Framework · AI & design · 3 min read
Context files
Files that AI agents read automatically (CLAUDE.md, AGENTS.md, DESIGN.md) that hold your principles, design-system rules and conventions, so every session starts from your standards instead of generic defaults.
Stable rules every session reads: users, principles, tokens, components, "never" rules.
Typically: CLAUDE.md, AGENTS.md, DESIGN.mdWhat this feature must do: problem, users, flows, states, rules, acceptance criteria.
Typically: a spec in the wiki or repoThe request for this one iteration, inside the conversation with the tool.
Typically: "Show three options"Changes rarely → changes per feature → changes per iteration
Use it when
- Designers keep repeating the same instructions ("use our components", "no raw colours") in every prompt.
- AI-generated prototypes look generic or off-system, even with good feature specs.
- You are setting up a prototype repository or a shared agent setup for the team.
How to use it
- Know which file your tools read. Agents read a project instructions file at the start of every session:
CLAUDE.mdfor Claude Code,AGENTS.mdas an open format many agents support, andDESIGN.md(a Google Labs format: tokens plus written rationale) for the design system. As of late 2026 these conventions still change, so check your tool's docs. Output: the file names your team's tools use. - Write only the stable rules. Who the users are, design principles, tokens, the component inventory, tone of voice, the accessibility baseline. Feature details belong in the feature spec, and one-off requests in the prompt. Output: a first draft, ideally under one or two screens long.
- Write the "never" rules explicitly. "Never hard-code colours, spacing or font sizes." "Never create lookalike components." "If a component doesn't exist, stop and list it as an open question." Output: a short "never" list.
- Point to the source, don't copy it. Reference the token names and the component library instead of pasting values that will go out of date. See Design tokens. Output: links and names instead of duplicated values.
- Version and review it like code. Keep the file in the repository, change it through review, and name an owner (often the design-system team). When an agent makes the same mistake twice, add a rule. Output: a versioned file with an owner and a change history.
Worked example
An internal operations platform with 6 product teams. Designers build code prototypes with an agent, and every prototype comes back with custom grey buttons and no empty states. The design-system designer adds a short CLAUDE.md to the prototype repository:
## Design rules
- Users are expert operators; prefer density and keyboard support.
- Use only components from @acme/design-system; never create lookalike components.
- Use design tokens (var(--ds-*)); never hard-code colours, spacing or font sizes.
- Every list view needs empty, loading, error and large-data states.
- Accessibility baseline: WCAG 2.2 AA; visible focus; no colour-only status.
- If a needed component doesn't exist, stop and list it as an open question.
The next prototypes use library components and include all four list states. When an agent later invents a "chip" component, the team adds one more line instead of correcting it by hand each time.
Watch out for
- A context file that tries to hold everything. Long files bury the rules that matter. Keep feature details in specs and link to deeper docs.
- Vague rules. "Follow our design system" gives the agent nothing to check. Name the library, the token prefix and the exact rule.
- Copied values that drift. Hex codes pasted into the file go stale when the tokens change. Reference the token names instead.
- Nobody owns it. An unowned file slowly fills with conflicting rules. Review changes like code.
Template
Copy this into CLAUDE.md, AGENTS.md or DESIGN.md and fill it in for your product.
# Design context: <product name>
## Users
- Who they are, what they do all day, what they need (e.g. density, keyboard use)
## Principles
- <principle 1>
- <principle 2>
## Design system
- Components: only from <library name>
- Tokens: use <token prefix>, see <link to token docs>
- Patterns: <link to pattern tiers / usage rules>
## Accessibility baseline
- WCAG 2.2 AA; visible focus; no colour-only status
## Never
- Never hard-code colours, spacing or font sizes
- Never create lookalike components
- Never use real customer or personal data in mock data
## When unsure
- Stop and list the open question instead of inventing a solution
Owner: Last reviewed: