How to Write an AGENTS.md File for Design Projects

Overview

If you've used Codex, Cursor, or Claude Code and gotten UI that's technically correct but off-brand, the fix usually isn't a better prompt. It's a file. AGENTS.md is a plain-markdown file in your project root that agents read automatically before they touch anything, and it's where you encode the context you'd otherwise repeat in every prompt.

Most AGENTS.md examples are written by and for engineers, all build commands and test runners. This is the designer's version: what to put in it so the interface an agent produces actually looks like your product.

Why the file beats the prompt

A prompt is per-message; the agent forgets it the moment the task ends. AGENTS.md is per-project; the agent reads it every single time, on every task, without you asking. That's a fundamental difference. Anything you find yourself explaining twice belongs in the file, not the chat.

It also compounds. A prompt improves one screen. A good AGENTS.md improves every screen the agent ever builds in that project, and keeps a team's AI output consistent even when different people are driving.

The design-system section

This is the part most designers skip and shouldn't. Give the agent your actual system in plain language it can apply:

- Color: name your tokens and their roles ("--accent is the single brand color, used only for primary actions; never use raw hex"). - Type: your font families and a real scale, with weights. State the hierarchy rule: size and weight for emphasis, not color. - Spacing: your base unit and scale (4px base, 8/12/16/24/32). - Components: the ones that already exist and must be reused instead of reinvented ("use the existing Button and Card; do not create new primitives").

The goal is to make on-system the path of least resistance, so the agent reaches for your tokens and components by default.

Stack and conventions

Agents produce much better code when they know the ground rules, so state them once: the framework and version, the styling approach (Tailwind, CSS modules, styled-components), file and folder conventions, and anything that's a hard no ("no inline styles," "no new dependencies without asking").

Keep it concrete. "Follow best practices" tells the agent nothing. "Components live in src/components, one per file, named in PascalCase" tells it exactly what to do.

A starter you can copy

You don't need a long file. This skeleton covers the essentials, and you fill each line with your real values:

- # Project: what it is, in one sentence. - ## Stack: framework, styling, key libraries. - ## Design system: color tokens, type scale, spacing, existing components to reuse. - ## Conventions: file structure, naming, hard rules. - ## Avoid: the specific anti-patterns you keep seeing (decorative gradients, oversized headings, new components when one exists).

Start there, then add a line every time the agent gets something wrong. The file gets sharper the more you use it.

Keep it short and current

A bloated AGENTS.md is as bad as none; agents weight it heavily, so stale instructions actively steer them wrong. Treat it like a living doc: when your tokens change, update the file the same day. When a rule stops mattering, delete it.

This is the same context you'd hand a new designer on their first day, written for a teammate that starts fresh every task. For where AGENTS.md fits in a broader AI workflow, the tool guides go deeper: How to Use Codex as a Designer and How to Use Cursor as a Designer

FAQ