How to brief Codex for design

Goal

One or two sentences: what is being built, for whom, and what the person using it should be able to do. "Build a pricing section" is a topic. "Add a pricing section to the home page with two plans and a monthly or yearly switch, so a visitor can compare and click Start" is a goal. The agent uses it to settle every question the rest of the brief didn't answer.

Constraints

What the work must stay inside: the stack, no new dependencies, browser support, existing components to reuse, things not to add. Constraints that hold for every task belong in AGENTS.md, so the brief only carries the ones specific to this task. See design rules in AGENTS.md.

Design values

This is the part most briefs leave out. Give the type, colours, spacing, radius and motion as numbers, or point to the tokens file and say which tokens apply. Describe each state, not only the resting one. Give the real copy.

If you don't have the values, that is a design problem and no brief wording will fix it. Either make the decisions first, or start from a design where they are already made and written down.

Files it may touch

Name the folders and files in scope, and the ones that are off limits. Scope keeps the diff reviewable and stops a styling task from wandering into your data layer. It also tells the agent where to look for existing patterns.

Definition of done

• Commands that must pass: build, type check, lint, tests. Use the exact script names from your package.json.
• Conditions with a yes or no answer: no horizontal scroll at 390px, one h1, focus ring visible on every control.
• A report: what was built, which checks passed, what could not be verified, and anything it chose that the brief didn't decide.

What to leave out

Leave out adjectives, long explanations of why, and instructions for how to write the code unless the how matters. A brief gets better by being more exact, not longer. If a sentence wouldn't change what the agent builds, cut it.

A task brief skeleton

Goal
[What is being built, for whom, and what the person using it can do when it's finished. Two sentences.]

Constraints
- Stack: Vite + React + TypeScript, plain CSS with custom properties. No new dependencies.
- Reuse: [existing components to use, by path].
- Do not add: [sections, libraries, sample content].
- Follow AGENTS.md for everything not stated here.

Design values
- Colour: ground [#hex], text [#hex], accent [#hex].
- Type: [typeface]; headline [72]px desktop / [40]px phone; body [17]px.
- Space: [160]px between sections; [24]px gutters. Radius [12]px.
- States: hover [what changes, 0.15s]; focus-visible [2px ring #hex]; disabled [opacity 0.4].
- Motion: only [thing] moves, on [trigger], over [0.6]s, ease-out. With prefers-reduced-motion: [what happens instead].
- Phones (below [720]px): [what stacks, what hides, what stays].
- Copy: "[headline]", "[subline]", "[button label]".

Files
- May edit: [paths].
- Must not edit: [paths].

Done when
1. [npm run build], [npm run typecheck] and [npm run lint] pass.
2. [Condition with a yes or no answer.]
3. [Condition with a yes or no answer.]
Run it and check at 390px and 1440px. Then report: what you built, which checks passed, what you could not verify, and any decision you made that this brief did not cover.

Written for this page as a starting point; swap the parts in [brackets] for your own. The full prompt of each uberdesigner template is longer and specific to one finished design, and it is tested by rebuilding the template from the prompt alone.

Keep reading

• Design rules in AGENTS.mdAn AGENTS.md example for front-end work: where design rules go, what to include, and a rules block to copy so every Codex task follows the same system.
• Using the uberdesigner MCP server in CodexHow to connect the uberdesigner template library to Codex over MCP with two terminal commands, and what to ask the agent once it's connected.
• Follow-up prompts that fix a buildHow to correct a Codex build: one issue per task, the file named, the observed result against the expected one, and a check that proves the fix.

• Whole websites
• Landing pages
• UI components