Design systems for AI coding agents

Ask any coding agent to "build a landing page" and you get the same thing: a near-black hero, a violet gradient, Inter, three feature cards with rounded corners. It is competent and completely generic, because the model has no memory of your brand between prompts. Add a second page and the styling drifts: different spacing, a slightly different blue, a new button shape. There is no source of truth for the look, so there is no consistency.

It is worth being precise about why, because the reason determines the fix. The model is not failing at design. It is doing exactly what it was asked: producing the most probable interface given the request. Absent a constraint, the most probable interface is the centre of everything it has seen, and everyone else prompting without constraints lands on the same centre.

That reframes the fix. You are not trying to make the agent more creative. You are trying to move it off the centre and hold it somewhere specific, which requires stating what that place is and what is outside it.

We sampled 299 DESIGN.md files published across public repositories and directories (real files, written by real teams to give agents design guidance) and measured what they contain rather than what they claim to. 72 were specifically visual-design files. The pattern is consistent enough to be diagnostic.

The last row is the giveaway. Typography gets mentioned in 83% of files, and 44% of those same files contain no concrete size value. "Use a clear typographic hierarchy" is a mention. It is not an instruction, and a model satisfies it with whatever hierarchy is most common in its training data.

The two numbers that matter most are the prohibition figure and the semantic-role figure, and they fail in the same way. A file listing #3b82f6 as "primary" with nothing forbidden has told the model that a specific blue exists and left every decision about where to use it wide open. The agent then uses it on headings, links, icon fills, a border and a gradient, because all of those are plausible uses of a primary colour.

A design system that survives being read by a model, applied across twenty files and picked up again next session needs six parts. Each one closes a specific failure.

The dark mode row is the one teams underestimate. Deriving dark mode by inverting light mode is what a model does when nothing tells it otherwise, and it goes wrong in predictable ways: shadows stop reading against dark surfaces, mid-greys lose contrast against both text and background, and a saturated accent that looked confident on white becomes glaring on near-black. Defining it costs a second token set and removes an entire class of rework.

A kit is a whole system, not a palette. Below is a live preview of the free ambient-sage kit: the same tokens, fonts, and treatments an agent receives when it applies it. Everything on this page could be repainted by swapping the kit.

However you install it, the payload is the same three things:

1. A DESIGN.md: the written brief: the design's intent, the type system, spacing and layout rules, component treatments, distinctive motifs, and do's & don'ts. This is what stops the agent defaulting to generic. What a DESIGN.md is, and how to generate one.
2. Semantic color tokens: 28 roles (background, foreground, primary, muted, card, border, chart-1…5, and more) in both light and dark. The agent styles against role names, not raw hex, so themes stay coherent. Semantic color tokens explained.
3. Framework exports: the same system as CSS variables, Tailwind v3/v4 @theme, a shadcn registry item, or DTCG/W3C JSON. The agent wires whichever matches your stack.

The role names in the second item are doing more work than they appear to. --color-muted-foreground tells a model both what the value is and where it belongs; --gray-400 tells it only the value, and the agent then decides for itself which grey a caption should be. That decision is where consistency leaks out, one file at a time.

The mechanics differ by tool: coding agents run a local MCP server, web builders take the shadcn registry or the exported DESIGN.md. Pick your tool:

• Give Claude Code a design system: MCP via .mcp.json, or identityforge apply.
• Give Cursor a design system: MCP via .cursor/mcp.json, plus how to structure the rules files.
• Give Windsurf a design system: manual MCP config for Cascade, plus the CLI path.
• Give v0 a design system: the shadcn registry + DESIGN.md as the brief.
• Give Lovable a design system: project knowledge + shadcn add in the repo.
• Give Bolt a design system: run shadcn add right in Bolt's terminal.

Both, and for different reasons. The distinction is worth getting right because installing an MCP server and expecting better-looking output is a common disappointment.

Prohibitions are the clearest case for the file. An agent about to add a drop shadow has no reason to query "are drop shadows allowed", so a constraint that lives behind a tool call is a constraint that never fires. Constraints have to be present before the decision. More on where each belongs.

Browse kits by visual style to see complete systems in context: type, color, surfaces, and build rules. Every kit has a permanent id and a readable slug; once you know either, the agent can skip search and apply it directly. Slugs can be renamed, but the old one keeps resolving, so a stored handle does not go stale. If you have brand colors already, the match_palette MCP tool finds the closest-fitting kits perceptually.

Installing a design system and assuming it worked is how teams end up surprised three weeks later. Four checks, in increasing order of effort:

1. 1

   Grep for literal colour values

   The fastest possible signal. If the agent is following semantic tokens, there should be no hex outside your token file.

   Copy

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

2. 2

   Check the font weights

   Weight is where hierarchy quietly reverts to the default. If your system says 400 and 600 only, anything else is drift.

   Copy

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

3. 3

   Ask for the same screen twice, in separate sessions

   Consistency between sessions is the actual test. If two runs produce meaningfully different spacing, radius or hierarchy, the system is not constraining what it needs to.

4. 4

   Build one screen in dark mode first

   If dark mode was derived rather than defined, this is where it shows: dead shadows, muddy mid-greys, an accent that glares. Cheaper to find now than after twenty screens.

The first two are worth running in CI. A rule that catches a raw hex value in a pull request does more for long-term consistency than any amount of documentation, which is the same conclusion Salesforce reached with the SLDS linter.