Why AI-generated UI drifts from your design system
An assistant like Claude Code, Cursor, or GitHub Copilot writes structurally sound React all day. Ask for a settings panel and you get sensible state handling, reasonable accessibility attributes, and a component that compiles on the first try. Then you put it next to the rest of your product and it is unmistakably foreign. The radius is 8px where yours is 4px. Muted text is #6b7280 where yours is #71717a. Vertical rhythm lands on 16px increments where your grid steps in 12s.
This is not a reasoning failure, and prompting harder will not fix it. It is a context failure. The model cannot see your rendered interface. Unless you tell it, it has no access to your CSS custom properties, your Tailwind theme extension, or the component conventions that define what your product looks like. Given no constraints, it falls back on the statistical centre of everything it has ever read, which is roughly Tailwind defaults filtered through Bootstrap-era instincts.
The durable fix is to give the assistant a machine-readable description of your design system and reference it in every session.
---
What "design context" actually needs to contain
Most people paste a few hex codes and wonder why the drift continues. A colour list is the smallest and least useful part of a design system. What a model needs is four layers:
Primitives are the raw values: the full colour ramp, the type scale, the spacing steps, radii, shadow definitions, and border widths. These are facts, and they are the easy part.
Semantics map primitives to roles. --color-slate-600 is a primitive; --color-text-muted is a semantic. Models reason far better about roles than about hex codes, because a role tells them *when* to reach for the value. Without this layer, an assistant will pick a plausible grey from your ramp for a disabled label and a different plausible grey for helper text.
Composition rules describe how the pieces combine. Which spacing steps are legal between a label and its input. Whether cards nest. Whether you use shadows at all, or rely on borders. This is the layer people leave out most often, and it is the one that produces the "technically on-brand but subtly wrong" output.
Negative constraints are what not to do. "Never introduce a new hex value", "no border radius above 4px", "do not use gap-5, our scale skips it". Explicit prohibitions are unusually effective with coding models, because they collapse the space of plausible guesses.
---
Four ways to hand over a design system
| Method | What the model actually receives | Survives a long session? | Setup effort |
|---|---|---|---|
| Pasting raw CSS | Thousands of tokens of noise, most irrelevant | Poor - gets truncated or falls out of context | Low |
| Screenshots of the UI | Visual impression, no exact values | Poor - values are guessed from pixels | Low |
| `design-tokens.json` | Precise primitives, no roles or rules | Moderate - accurate but under-specified | Medium |
| A `DESIGN.md` spec file | Primitives, semantics, rules and prohibitions | Strong - written to be re-read each session | Medium |
Pasting CSS is the most common approach and the weakest. A production stylesheet is mostly layout plumbing, vendor prefixes, and utility classes. Burying twelve meaningful values inside eight thousand tokens of noise is worse than sending nothing, because it consumes the context window that your actual task needs.
Screenshots feel intuitive and are surprisingly bad for this. A model reading an image can tell you the button looks blue-purple. It cannot tell you it is #635bff, and it will not notice that your spacing scale is a 4px grid.
A tokens JSON file is precise and machine-readable, which is why the W3C Design Tokens Community Group format exists. It is the right transport for primitives. On its own, though, it carries no roles and no rules, so the model still has to guess which token belongs where.
A written spec file is the format that holds up. It is prose plus tables, so it carries rules and prohibitions that JSON cannot express, and it is short enough to re-read at the start of every session.
---
Extracting tokens from a site you already built
If your design system exists only as shipped CSS, you have to recover it. There are two ways, and they are not equivalent.
Reading source files seems obvious and is misleading. Source contains everything that was ever declared, including dead variables, overridden values, and three generations of colour naming. You will faithfully document values that no longer render anywhere.
Reading computed styles on a live page tells you what the browser actually resolves after the cascade, media queries, and every override. That is the real design system. This is what browser tooling is for, and it is the approach DESIGN.md Style Generator takes: it scans the rendered page, reads resolved custom properties, typography, colours and layout values, then classifies them into semantic groups rather than dumping a flat list.
Whichever route you take, the extraction step is worth doing properly once. Everything downstream inherits its accuracy.
---
Writing a DESIGN.md the assistant will follow
Structure matters more than length. A model scanning for constraints does better with tables and short imperative lines than with paragraphs of design philosophy.
# Design System
## Colour - semantic roles
| Role | Token | Value |
|-----------------|-----------------------|----------|
| surface | --color-surface | #0c0c0c |
| surface-raised | --color-surface-2 | #141414 |
| text-primary | --color-text | #fafafa |
| text-muted | --color-text-muted | #9a9a9a |
| accent | --color-accent | #adff2f |
## Spacing
4px base grid. Legal steps: 4, 8, 12, 16, 24, 32, 48, 64.
Never use 20, 28, or 40.
## Radius
4px on inputs and buttons. 0 on cards and panels. Never above 8px.
## Rules
- Every colour MUST reference a token. Never emit a raw hex value.
- Elevation is expressed with borders, not shadows.
- Body copy is 14px/1.6. Never smaller than 12px.Two details do most of the work here. The semantic column lets the model pick by role rather than by eye. The explicit prohibitions ("never use 20, 28, or 40") shrink the guess space far more than an equivalent positive instruction would.
Reference the file at the start of a session rather than pasting its contents: Read DESIGN.md and follow it for all styling in this task. Assistants with file access will re-read it as needed, which keeps the constraints alive deep into a long conversation instead of falling out of the context window.
---
Keeping tokens in sync when the design changes
A spec file that describes last quarter's design is worse than none, because it is confidently wrong. Three habits keep it honest:
Regenerate after any theme change, and treat the regeneration as part of the design change rather than a follow-up chore. Commit DESIGN.md to the repository so it versions alongside the code it governs and shows up in review when it drifts. And if you maintain a Tailwind theme, generate the theme.extend block from the same extraction rather than hand-maintaining two sources of truth that will diverge within a month.
---
Mistakes that quietly undo the whole thing
Documenting aspiration instead of reality. If the spec says radii are 4px but half the shipped components use 6px, the assistant produces output that matches neither. Document what renders today, then fix the drift as a separate piece of work.
Omitting the dark theme. If both themes exist, both belong in the spec with their semantic roles mapped. A model given one palette will invent the other.
Leaving out anti-patterns. "We do not use drop shadows" is worth more than three paragraphs describing the shadows you do use.
Making it enormous. A 400-line spec competes with the actual task for context. Primitives, semantics, rules, prohibitions - if it runs much past a hundred lines, it is documentation for humans, not context for a model.
---
Frequently Asked Questions (FAQ)
Does this work with Copilot, or only Claude Code and Cursor?
It works with any assistant that can read files from the repository, which includes Claude Code, Cursor, Windsurf, and Copilot's agent modes. Older inline-completion tools that only see the current buffer cannot use a spec file; for those, a comment block at the top of the file is the closest equivalent.
Should I use DESIGN.md or design-tokens.json?
Both, for different jobs. JSON is the machine-readable transport for primitives and is what build tooling should consume. The Markdown spec carries the roles, rules and prohibitions that JSON has no way to express. If you only maintain one, maintain the Markdown - it is the one that changes model behaviour.
How is this different from just having a Tailwind config?
A Tailwind config declares which values are available. It says nothing about which value belongs in which situation, and nothing about what you have deliberately excluded. An assistant reading only the config will happily use rounded-3xl because the scale exists, even if nothing in your product has ever used it.
Can I extract a design system from a site I do not own?
You can read any page's computed styles - that is what browser developer tools do, and it is how designers have always inspected the web. Whether you should reproduce another product's visual identity is a trademark and design-ownership question, not a technical one. Competitive analysis is normal practice; cloning a brand is not.
How often should the spec be regenerated?
Whenever the theme changes, and not on a schedule otherwise. A spec regenerated weekly against a stable design just produces noisy diffs. Tie it to the design change, not to the calendar.
Does any of this leave my code exposed?
It depends on the tool. Extraction that runs locally in the browser never transmits your styles anywhere - DESIGN.md Style Generator processes everything in the tab sandbox with no server calls. Cloud-based extractors upload the page they are analysing, which matters if the page is a staging environment or an internal tool.
---
Where to go from here
If you are building your spec by hand, start with the semantic colour table and the spacing rules - those two sections alone eliminate most visible drift. If you would rather not hand-audit a live product, DESIGN.md Style Generator reads the rendered page and writes the spec, the Tailwind extension block, and the JSON tokens in one pass.
For the wider question of getting AI tooling to behave predictably across a whole workflow rather than a single file, see our guide to Grok workflow automation for developers.