A good design brief for an AI coding agent answers the questions the agent would otherwise answer with defaults: who uses this, what they need to do, what matters most on the screen, what it should feel like, what it must reuse, and how you’ll judge it done. It fits on one screen and ends with acceptance criteria the agent can check. Below is a method for writing one, then three templates you can copy: a SaaS dashboard, a marketing website and a mobile app.
From vague idea to buildable spec
Most briefs start as one line: “a better onboarding flow”, “a pricing page”, “make the dashboard nicer”. Each hides decisions. Work through these in order; each one narrows the next.
1. Users and situation
Name who uses it and when. “Workspace admins, on desktop, at month end” leads to a different design than “new users on their phone during a free trial”.
2. Goals and tasks
What does the person need to get done? List the tasks in priority order. The first task determines the layout.
3. Information hierarchy
Rank the content: what must be seen first, second, third, and what can be one click away. This is the single most useful thing in a brief, because it’s what generic output gets wrong.
4. Visual direction
Describe a character in concrete terms and list what to avoid. “Calm, dense, utilitarian; no gradients, no cards inside cards” gives the agent something to act on. “Modern and clean” doesn’t.
5. References
Two to four, each with what to take and what to ignore. See how to give Claude Code visual design references.
6. Functional constraints
Data sources, real content, edge cases, permissions, performance limits. These prevent invented fields and happy-path-only screens.
7. Design system requirements
Which components and tokens to use, and what to do if something is missing (usually: propose it, don’t create it).
8. Acceptance criteria
How you’ll judge it: widths to check, states to show, accessibility floor, and the evidence you want back. Claude Code’s best practices describe the most useful specs as self-contained, ending “with an end-to-end verification step”.
Template 1: SaaS dashboard
# Brief: [dashboard name]
## Users and situation
- Who: [role], [company size or context]
- When: [how often, on what device, in what state of mind]
## Primary question
"[The one question this page answers]"
Secondary: "[...]", "[...]"
## Tasks, in priority order
1. [See X at a glance]
2. [Investigate Y]
3. [Act on Z]
## Hierarchy
1. [Answer to the primary question, in plain language, with its number]
2. [Supporting metrics, inline, not as a card grid]
3. [Main table or list]
4. [Secondary detail, one click away]
## Data (don't invent fields)
- Source: [file or API]
- Fields: [name: type], [name: type]
- Volumes: typical [n] rows, worst case [n]
## Visual direction
- Character: [e.g. calm, dense, utilitarian]
- Density: [row height], [base text size]
- Avoid: [e.g. stat cards, decorative charts, gradients]
## References
- [file]: take [quality]. Ignore [quality].
## Design system
- Components: [path]. Tokens: [path].
- Missing component? Propose it; don't create it.
## Acceptance criteria
- States: empty (new account), loading, partial, error, extreme values
- Tables: numbers right-aligned, tabular figures, sortable [columns]
- Works at [widths]; no page-level horizontal scroll
- WCAG 2.2 AA contrast, visible focus, labelled controls
- Evidence: screenshots at each width and of each stateFor what goes wrong in dashboards specifically, see how to build better SaaS dashboards with AI.
Template 2: marketing website
# Brief: [page name]
## The argument
- Audience: [specific reader]
- Claim: "[what changes for them, in their words]"
- Proof we genuinely have: [demo, screenshot, numbers we can stand behind]
- Action: [primary] / [secondary]
## Sections (each has one job)
1. [Section]: [its job in the argument]
2. [...]
Leave out: [sections we don't have proof or content for]
## Copy
- Source: [file]. Use it exactly. Don't write new claims.
- Facts only from: [file]
## Visual direction
- Character: [concrete description]
- Type: [display], [text], hero size [desktop / mobile]
- Colour: [base], [accent and its only uses]
- Imagery: [real screenshots / diagrams / none]
- Avoid: [the defaults you don't want]
## References
- [file]: take [quality]. Ignore [quality].
## Build
- Stack: [framework, styling, component path]
- Responsive from [smallest width]; [how images and columns stack]
## Acceptance criteria
- Who it's for and what it claims is clear within five seconds
- One primary action per section
- Every claim is true and sourced
- Hero holds up at [smallest width]
- Evidence: full-page screenshots at [widths]There’s a filled-in version of this brief in how to build a SaaS landing page with Claude Code.
Template 3: mobile application screen
# Brief: [screen or flow name]
## Users and situation
- Who: [user]
- Context: [one-handed? on the move? interrupted often?]
## Task
- Main task: [what they complete here]
- Entry points: [where they arrive from]
- Exit: [where they go when done or cancelled]
## Hierarchy
1. [Primary content or input]
2. [Primary action, reachable with a thumb]
3. [Secondary actions, in a menu or sheet]
## Platform and constraints
- Platform: [iOS / Android / both / responsive web]
- Follow platform conventions for navigation and back behaviour
- Safe areas respected; keyboard never hides the active input
- Touch targets at least [size]; no hover-only actions
- Offline or slow network: [expected behaviour]
## Visual direction
- Character: [description]
- Type: [sizes]; supports larger system text sizes
- Avoid: [e.g. dense tables, tiny icon-only buttons]
## Design system
- Components: [path]. Tokens: [path].
## Acceptance criteria
- States: first use, loading, empty, error, success
- Works at [smallest] and [largest] supported screen sizes
- Screen reader labels on every control
- Evidence: screenshots of each state at [sizes]Common brief mistakes
- Describing the layout instead of the job. “Three cards across the top” locks in a solution. “The first thing they need is X” lets the agent find a better one.
- Adjectives as direction. Replace each adjective with a decision or a reference.
- No data or content. Placeholder content produces placeholder design.
- No acceptance criteria. Without them, “done” means “it compiles”.
- Too long. A brief that needs scrolling to find the hierarchy has buried it.
Where briefs live
Keep briefs as files in the project (for example docs/briefs/) and reference them with @, so they’re versioned and reusable. Rules that apply to every brief belong in CLAUDE.md instead. The brief is the step before the build workflow in how to make Claude Code build better UI.
Attuna is built around the same idea. A project starts from a name and a short brief, Attuna suggests a starting creative direction from it, and you add project rules, preferences and references. Your agent then reads that context over MCP. Attuna is in development.