Docs / Best practices
Writing for AI
DESIGN.md is read by AI agents on every session. The prose sections are as important as the token values — they give the agent context that numbers alone cannot provide.
The following principles consistently produce better AI output when applied to DESIGN.md files.
1. Be prescriptive, not aspirational
Write what your design system is, not what you hope it will become. An agent that reads “we aim for a clean, modern look” has learned almost nothing. An agent that reads “primary buttons are always pill-shaped and use the primary token as background color” can apply that rule immediately.
Avoid
We strive for a premium, modern aesthetic that feels both professional and approachable.
Better
Primary buttons are pill-shaped, use colors.primary as background, and appear once per screen.
2. State constraints as direct rules
AI agents respond well to direct, imperative statements. Use “Never”, “Always”, “Do”, and “Don’t” rather than softer language. The Do’s and Don’ts section exists precisely for this — use it for your hardest constraints.
Avoid
The accent color is generally best reserved for warning states.
Better
Never use accent (#B8422E) for CTAs. It signals danger — use it only for errors and destructive actions.
3. Explain the “why” briefly
A single sentence of rationale dramatically improves how an agent applies a rule. Without context, an agent may override a rule when it seems to conflict with another goal. With context, it understands the intent and resolves ambiguity correctly.
Example with rationale
Never use text-3 (#8C8884) for interactive elements — it fails WCAG AA on the neutral background and users may not perceive it as clickable.
4. Prefer short sections over long ones
Every section you write is loaded into the agent’s context window. A 3-sentence Colors section with precise rules outperforms a 20-sentence one that repeats itself. When in doubt, cut.
The linter does not enforce section length, but a useful heuristic: if your Overview section is longer than 5 sentences, it probably contains rules that belong in Colors, Typography, or Do’s and Don’ts.
5. Name tokens semantically
Token names appear in both the YAML front matter and the markdown body. Semantic names (primary, surface, error) give the agent immediate signal about intent. Descriptive names (dark-navy, light-grey-200) require the agent to infer intent from context — introducing unnecessary ambiguity.
6. Test with a prompt, then iterate
The fastest feedback loop for DESIGN.md quality is to ask your AI agent to generate a specific component, review whether it applied your tokens correctly, and then improve the section that failed. Treat your DESIGN.md as living documentation that improves with use.
A useful test prompt after any DESIGN.md edit: