Set Up Codex for Designers

What Codex is

Codex is OpenAI’s software engineering agent. That phrase sounds like it belongs to engineers, but the useful part for designers is simpler:

Codex can read a project, understand the files, make changes, run commands, test in a browser, and explain what it did.

That makes it useful for design work that has escaped the canvas:

• auditing a component library
• generating design-system docs from code
• checking token usage
• building a prototype from a brief
• reviewing a PR for design-system drift
• turning research or spreadsheets into a small internal tool

If you are only asking for ideas, copy, critique, or a quick explanation, ChatGPT is enough. If you want an agent to touch a folder, inspect a repo, run a dev server, open a browser, and come back with a diff, use Codex.

Delegate or collaborate

Codex work usually falls into two modes.

Delegate when the task is clear, repeatable, and low-risk: summarize a folder, audit token usage, draft release notes, collect unanswered comments, or update one documented pattern.

Collaborate when the work needs judgment: choosing a component API, deciding whether a design-system rule is worth enforcing, reviewing a messy prototype, or turning research into a product recommendation.

For designers, this is the practical shift: do not ask “Can Codex do my job?” Ask “Which parts of this workflow can Codex run while I keep the design judgment?”

The Codex work loop

A useful Codex workflow has five parts:

1. 01

   Connect

2. 02

   Contextualize

3. 03

   Run

4. 04

   Review

5. 05

   Compound

Connect the files, repo, docs, screenshots, browser session, or app integrations Codex needs. Contextualize the work with project rules, source links, acceptance criteria, and review standards. Then decide whether you are delegating a bounded task or collaborating through an ambiguous one.

Review the result where it will actually be used. If Codex edits UI, inspect the page in a browser. If it drafts documentation, read the rendered page. If it writes a PR, review the diff in GitHub. The output can look fine inside the Codex thread and still feel wrong in its real home.

Then compound the useful part. Save the prompt, add the miss to your checklist, update AGENTS.md, or turn the workflow into a skill. A good Codex session should make the next session slightly easier.

One project context, several ways in

Codex is easiest to understand as a shared project context with multiple surfaces: app, IDE, CLI, cloud, and mobile.

Shared context Project folder

Files Rules Browser Diffs

Agent Read, edit, run, report

App Project hub

IDE Edit in place

CLI Fast local tasks

Cloud Background work

Mobile Check in

The surfaces

Codex is not one screen. It is a set of ways to work with the same agent.

1. APP

   Project hub

2. IDE

   Editor pair

3. CLI

   Terminal agent

4. CLOUD

   Background work

5. MOBILE

   Remote control

Surface	Use it when	Designer example
Codex app	You want a visual command center for multiple projects or tasks	Run a design QA task while another thread writes docs
IDE extension	You are inside VS Code, Cursor, or Windsurf and want file-level diffs	Edit a component and review the patch inline
CLI	You want fast local repo work from the terminal	Audit all token files and write a report
Cloud	You want to delegate a longer task in an isolated environment	Ask Codex to explore three implementation approaches
Mobile	You want to check progress or start a low-risk task away from the desk	Voice-prompt a research summary or review queue

Criterion	App Best pick Best first surface	IDE Best while editing	CLI Best for terminal work	Cloud Best for delegation	Mobile Best for check-ins
No terminal comfort	Best	Okay	Harder	Okay	Okay
Visual project work	Best	Good	Okay	Good	Limited
Code diff review	Good	Best	Good	Good	Limited
Parallel tasks	Best	Okay	Okay	Best	Limited
Quick away-from-desk check-in	Okay	No	No	Okay	Best

Start in the app. It gives you projects, chats, diffs, automations, and parallel work without forcing you to become a terminal person on day one.

What to try first

A task is a good Codex candidate when at least two of these are true:

• It pulls from several files, pages, docs, screenshots, or tools.
• It has steps you repeat often enough to resent them.
• It can be checked against visible, factual, or testable criteria.
• It produces a durable artifact: report, checklist, doc, diff, script, prototype, or PR.
• It benefits from synthesis across more context than you want to hold in your head.

For design-system work, that means Codex is especially useful for audits, documentation passes, component inventories, token drift reports, screenshot reviews, small content edits, and PR prep. It is weaker when the source material is missing, success is purely subjective, or the cost of a wrong action is high.

Step 1: Create a safe project

Do not start Codex inside your most important production repo with full permissions. Start with one of these:

• a copy of your design-system repo
• a folder of markdown docs
• a prototype folder
• a token export folder
• a small test repo

Name the folder clearly:

codex-first-run/
  README.md
  tokens.json
  screenshots/
  notes/

If the folder is a Git repo, make sure the current state is committed before you ask Codex to edit anything. The diff is your safety net.

Step 2: Ask a read-only question first

Your first task should not modify files. Make Codex orient itself.

Paste this:

Read this project but do not edit files yet.

Tell me:
1. What kind of project this is
2. Which files matter most for design-system work
3. What commands you would run to verify changes
4. What you would avoid touching without permission

Return a short onboarding note for a designer.

This gives you two things at once: a project summary and a trust check. If Codex misunderstands the project, fix the context before asking it to write.

Step 3: Add project instructions

Codex performs better when the project has a small instruction file. In many Codex workflows, this is an AGENTS.md-style file: a short, repo-readable brief that tells agents how to behave.

Create one at the project root:

# AGENTS.md

## Project
This is a design-system project for [team/product].

## Designer priorities
- Preserve existing components before creating new ones.
- Use semantic tokens, not raw hex values.
- Keep UI dense, scannable, and practical.
- Do not introduce new dependencies without asking.

## Verification
- Run the existing build command before finalizing.
- If a browser is available, inspect the changed page at desktop and mobile widths.
- Summarize risks and files changed at the end.

## Off limits
- Do not edit billing, auth, or production config without explicit approval.
- Do not delete files unless I ask.

Then ask Codex:

Read AGENTS.md. Tell me which rules are clear, which are ambiguous, and what you would add before doing design-system work in this repo.

If you use Codex for more than one project, keep AGENTS.md short and point it at deeper context files:

• context.md for the project, team, current priorities, and source links
• preferences.md for tone, review style, naming preferences, and communication habits
• rules.md for what Codex can do alone, what needs approval, and what is off limits

Step 4: Run one low-risk design task

Pick a task where Codex can help but cannot ruin your week.

Good first tasks:

• “Find all raw hex colors outside token files. Write a report only.”
• “Review the Button docs and list missing usage examples.”
• “Compare these two token exports and summarize naming drift.”
• “Open the prototype page and list visible responsive issues. Do not edit yet.”
• “Write a component inventory from the files in src/components.”

Avoid these on day one:

• “Redesign the whole app.”
• “Fix all accessibility issues.”
• “Refactor the design system.”
• “Delete unused components.”
• “Ship this to production.”

Your first useful prompt:

Audit this project for design-system drift.

Scope:
- Read component files and token files.
- Look for raw colors, one-off spacing, duplicated components, and missing docs.
- Do not edit files.

Output:
- Top 10 findings
- Severity: Blocking, High, Medium, Low
- File path or folder
- Suggested next action

Step 5: Let Codex edit one file

Once the read-only audit looks sane, choose one contained fix.

Take finding #3 only.

Make the smallest possible change to fix it.
Do not touch unrelated files.
After editing, show me:
1. Files changed
2. Why the change fixes the issue
3. How to verify it

Review the diff. If the change is good, keep it. If it is weird, reject it and tighten the instruction.

Step 6: Decide your permission level

Codex can work with different levels of autonomy depending on the surface you use. Keep the first week conservative.

Full autonomy is not a personality trait. It is a permission you grant after the agent has a track record.

Before approving any significant output, ask:

What was the hardest judgment call in this work?
What alternatives did you consider and reject?
Where are you least confident?

Those questions are boring in the best way. They expose assumptions before they quietly become product decisions.

The first week plan

Day 1: Orientation

Open one safe folder. Ask Codex to explain it. Create or improve AGENTS.md.

Day 2: Read-only audit

Run a design-system drift audit. Do not edit. Save the report.

Day 3: One tiny fix

Ask Codex to fix one low-risk issue. Review the diff. Run the verification command.

Day 4: Browser check

If your project has a UI, ask Codex to open it in a browser and inspect one page at desktop and mobile widths.

Day 5: Turn the repeated workflow into a skill

If you ran the same audit twice, that is a skill candidate. The next guide shows how.

Day 6: Add review rules

Create a short review checklist for the mistakes Codex made this week: data checks, UI checks, copy checks, or design-system checks.

Day 7: Compound

Ask Codex what should become reusable:

Based on what we did this week, what should become a reusable skill, automation, workflow file, or small tool? What context should I add so future sessions start from a better baseline?

Exercise

Your first Codex run

1. Create a disposable project folder

2. Ask for orientation only

3. Create AGENTS.md

4. Run one audit

You are done when Codex can describe the project, name the safe verification command, and produce one useful read-only design-system finding.