Design rules in AGENTS.md

What AGENTS.md is for

AGENTS.md is a plain Markdown file of instructions for coding agents working in a repository. It plays the part a contributor guide plays for a new developer: how this project is built, what to run, what never to do. For where Codex looks for the file and how it treats more than one, check Codex's documentation.

For front-end work it solves one problem above all. Without it, each task makes its own small design decisions, and after ten tasks you have three greys and four button heights.

What to put in it

• The stack and the commands: how to install, run, build, type check, lint and test.
• Where values live: the path to the tokens file, and the rule that components use tokens only.
• The scales: allowed type sizes, spacing steps, radii and durations, or a pointer to them.
• Component rules: where components go, what each must include, which existing ones to reuse.
• Accessibility rules: focus ring, contrast, target size, reduced motion.
• Banned habits: the specific defaults you don't want, by name.
• The stop rule: when to stop and ask in place of inventing a value.

Write rules, not prose

Each line should be something the agent can obey or break. "We care about quality" is neither. "Every interactive element has a visible focus-visible state" is a rule. Keep the file to what you would actually enforce in review. A long file full of preferences buries the five rules that matter.

Keep values in one place

Don't copy the whole palette into AGENTS.md if it already lives in a tokens file. Point to the file and state the rule. Two copies of the same values drift apart, and the agent then has to guess which is right.

The stop rule deserves its own line: if a design needs a value that isn't in the system, the agent stops and says so. This one line prevents most of the slow drift.

Update it when a correction repeats

When you send the same follow-up twice, such as "use the Button component, don't write a new one", it belongs in AGENTS.md. The file is the memory of the project's decisions. Treat a repeated correction as a missing rule.

An example design rules block for AGENTS.md

# Front-end rules

## Stack and commands
- Vite + React + TypeScript (strict). Plain CSS with custom properties. No UI library, no CSS framework.
- Run before reporting a task as done: npm run typecheck, npm run lint, npm run test, npm run build.
- No new dependencies without asking first.

## Design values
- Every colour, font size, space, radius, shadow and duration comes from src/styles/tokens.css. No raw hex, px or seconds in component CSS.
- Type sizes: 12, 14, 16, 20, 28, 40, 64px. Spacing: 4, 8, 12, 16, 24, 32, 48, 72, 120px. Radius: 6px controls, 12px cards.
- One accent colour. It is for primary actions, links and focus only.
- If a design needs a value that is not in tokens.css, stop and ask. Do not add one quietly.

## Components
- Components live in src/components/Name/ as Name.tsx, Name.css, Name.test.tsx.
- Reuse Button, Input, Card and Dialog. Do not write a second version of an existing component.
- Every interactive component defines hover, focus-visible, pressed and disabled states.

## Accessibility and motion
- Focus-visible ring: 2px accent, 2px offset, on every interactive element.
- Text contrast at least 4.5:1. Touch targets at least 44px.
- Motion: 0.15s for colour changes, 0.3s for movement, ease-out. Only animate transform and opacity.
- With prefers-reduced-motion, remove movement and keep colour changes.

## Layout
- Desktop first. Below 720px: one column, no hover-only behaviour, no horizontal scroll at 390px.

## Do not add
- Gradient text, emoji, decorative icons, drop shadows on text, invented copy, invented numbers or testimonials, sample pages.

## Reporting
- End each task with: files changed, commands run and their results, what you could not verify, and decisions you made that the task did not specify.

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

• How to brief Codex for designThe five parts of a front-end task brief for Codex: goal, constraints, design values, files it may touch and a definition of done. With a skeleton to copy.
• 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.

• Restyles
• Dashboards
• Whole websites