How to document a design system so an AI actually follows it

The instinct is to point the agent at the design system site. It rarely helps, for four structural reasons that have nothing to do with the quality of the site.

The organisation row is the one people miss. A site organised by component is perfect for someone who already knows they need a Button. An agent about to build a screen has not decided which components to use yet — its first decisions are about density, hierarchy and layout, and those are exactly what a component-organised site never covers.

The completeness row is the most consequential. Documentation describes what exists because that is what documentation is for. But the difference between your interface and a generic one is mostly a set of things you never do, and no component page will ever mention them.

We sampled 299 DESIGN.md files published across public repositories and directories — files written deliberately to give AI agents design guidance — and measured their contents. 72 were specifically visual-design files. The pattern is consistent enough to use as a checklist of what to avoid.

Set the last two rows against each other. Typography is mentioned in 83% of files and 44% contain no concrete size value anywhere. That gap is the whole problem in one statistic: the files are talking about type without ever saying how big anything is.

The adjective figure is the other half. "Clean" appears in 39% of these files, "modern" in 36%. Both are words a model satisfies by producing the centre of its training distribution, which is precisely the generic look the file was written to prevent.

Each of these maps to a measured failure above. Applied together they turn a description into something executable.

1. 1

   Give every colour a role, not just a value

   #6b7280 is a value a model will use for body text, borders, icons, placeholders and disabled states alike. --text-muted, described as secondary and supporting text only, is one job. Five roles beat one hex, and they let you change borders later without changing captions.

   Copy

   --text-muted: #6b7280   /* secondary and supporting text only */
   --border-subtle: #e5e7eb /* structural edges, dividers */
   --text-disabled: #9ca3af /* disabled controls only */

2. 2

   Replace every adjective with a number or a rule

   "Generous spacing" becomes "section gap 64px, card padding 24px". "Clean typography" becomes a scale. If a sentence cannot be checked against a rendered screen, it is decoration.

3. 3

   Write the prohibitions

   The single highest-impact section, and the one 76% of files omit entirely. Five lines is enough to start.

   Copy

   ## Never
   
   - No gradients
   - No drop shadows — elevation is a surface step plus a 1px border
   - No font-weight above 600
   - No colour value outside the token set
   - No border-radius above 12px

4. 4

   Define dark mode, do not let it be derived

   Left undefined, a model inverts light mode, and the result fails predictably: shadows stop reading, mid-greys lose contrast at both ends, and a saturated accent that looked confident on white glares on near-black. A second token set costs an hour and removes a category of rework.

5. 5

   State the density decision explicitly

   Whether this is a dense tool or a spacious marketing surface changes every subsequent choice, and it is the decision most files never make. If your product has both kinds of surface, that is two files, not one hedged file.

6. 6

   Name at least two motifs

   The recurring specific things that make the design yours: a 2px accent rule on the left of section headings, numeric columns always tabular and right-aligned, a particular way empty states are drawn. 57% of files have none, which is why their output is correct and characterless.

7. 7

   Point at the token file; never restate it

   Once a hex value exists in both the design file and the token file, one will be updated and the other will not, and the model will confidently use the stale one. Reference, do not copy.

What the seven changes produce, at the end, is a file whose values an agent can resolve without inventing anything. This is the same information rendered rather than written — useful here as a checklist of what your own file has to be able to answer:

Not all prohibitions work equally. Three properties separate the ones that change output from the ones that get ignored.

The third row is the one that gets missed. A prohibition with no alternative creates a gap the model has to fill, and it fills it from the same training distribution you were trying to escape. Every "never X" should be followed by "instead, Y".

The file has to fit in context alongside the actual task, which puts a real ceiling on it. Roughly 400 lines is a workable target; past that, individual rules start losing to the task for attention.

Order matters too. Put the intent and the prohibitions early. A model reading top to bottom encounters the general rule before the special case, which is the same ordering Stripe uses in its Appearance API — theme first, then variables, then specific rules.

# DESIGN.md

## Intent            <- who reads this product, and what it is for
## Never             <- the prohibitions, early and unmissable
## Colour            <- roles for light and dark, referencing tokens
## Type              <- scale with real numbers, weight band, tracking
## Spacing & density <- the scale, and which surface uses which step
## Elevation         <- the strategy, stated once
## Composition       <- how components sit together
## Motifs            <- what makes this design specifically ours

Not everything should be in the file, and trying to fit everything is how it grows past useful. The dividing line is whether the agent needs it before deciding or only on demand.

IBM's Carbon MCP server is a good model for the first column: it exposes documentation search, component code examples, charts and experimental components as tools. Notably, none of those are prohibitions — because a retrieval tool only surfaces what the agent thought to query. More on the split.

Writing the file and assuming it worked is how teams discover the problem three weeks later. Four checks, in increasing order of effort.

1. 1

   Grep for literal colour values

   If the agent is following semantic roles, there should be no hex outside your token file.

   Copy

   grep -rn --include='*.tsx' --include='*.css' -E '#[0-9a-fA-F]{3,8}\b' src \
     | grep -v 'tokens\|globals.css'

2. 2

   Grep for the weights you forbade

   Weight is where hierarchy quietly reverts to the default, and it is the fastest signal that a prohibition is not landing.

   Copy

   grep -rn --include='*.tsx' -E 'font-(bold|extrabold|black)' src | head -30

3. 3

   Ask for the same screen twice, in separate sessions

   Cross-session consistency is the real test. If two runs differ meaningfully on spacing, radius or hierarchy, the file is not constraining what it needs to — and the diff tells you exactly which section is missing.

4. 4

   Build one screen in dark mode first

   If dark mode was derived rather than defined, this is where it surfaces. Much cheaper to find on screen one than on screen twenty.

The first two belong in CI. A check that fails a pull request containing a raw hex value does more for long-term consistency than any documentation, which is the conclusion Salesforce reached with the SLDS linter and Stripe reached by removing the capability entirely.