The Design System Is the Agent's Style Guide
A coding agent does not absorb a style guide the way a new hire does. It reads what is in its context and obeys what fails the build. Here is the four-layer framework we use to turn a design system into constraints an agent actually follows, and the honest gap where it is still only advice.
Picture a coding agent asked to add a status line to a settings screen in
our dashboard app. It opens the screen's file to read it. At that moment,
and not before, Claude Code loads the instruction file that lives in that
directory, and the first thing in the agent's context about styling is a
block that was not written by anyone on our team. It was generated by the
design system's own CLI. It says: start from a template, use no raw <div>,
style with component props first and tokens second, no raw hex, no raw
pixels. Then it says: re-read the file before you finish and replace
anything that breaks those rules.
If the agent writes the status line with a Text component and a colour
role, with no literal colour and no wrapper div, there is nothing left to
review for style. That is the outcome the whole arrangement is built for.
That is the good case. This post is about why it happens, which parts of it are guaranteed and which are only likely, and how to arrange a design system so more of it lands in the guaranteed column. We rebuilt two UIs on a design system a few days ago. Of the 44 commits that touched the new app's source from October 11 to 15, 31 carry a coding agent's co-author trailer. The design system has stopped being a document for people and become the agent's style guide.
A style guide is for people. Agents need two other things.
A human designer or engineer learns a style guide slowly. They read it once, then they absorb it through review comments, through copying the screen next door, through someone saying "we don't do that here". By month three they carry it in their head and the document is a reference.
An agent carries nothing between sessions. Each one starts with a fresh context. What it knows about your conventions is exactly what is in the context at the moment it writes the line, and its own general training, which knows the popular libraries well and yours not at all. Claude Code's documentation says it plainly about instruction files: Claude treats them as context, not enforced configuration.
So a style guide for an agent splits into two halves:
- What it reads, at the right moment. Short, imperative, in the file the agent is guaranteed to load when it touches UI code.
- What it cannot get past. Checks that fail the build when the rule is broken, whatever the agent read or ignored.
The first half makes the right output likely. The second makes the wrong output impossible to merge. A token constrains an agent only where something checks it. Everywhere else it is advice, and advice is followed most of the time, which is a different thing from always.
The four layers
Here is how the pieces sit, from the softest constraint to the hardest.
Layer 1 is advice. Layers 2 to 4 are walls. The last box is where everything that no wall covers ends up: review by a person or another agent, which is the most expensive and least reliable check in the chain.
Layer 1: a generated instruction block, loaded where it applies
The design system is Astryx, Meta's
open-source React system. Its CLI has a command, astryx init --agent claude, that writes a managed instruction block between ASTRYX:START and
ASTRYX:END markers. We keep that block verbatim in the web app's
AGENTS.md (with a CLAUDE.md symlink beside it) and refresh it by
re-running init, which rewrites only the marked block.
Placement is half the value. Claude Code loads a subdirectory's instruction file on demand, the first time the agent reads or edits a file in that directory. A Go change elsewhere in the repository never pays for the UI rules in its context, and a UI change always gets them.
The other half is the content. The block is short, and almost every line is an instruction that can be checked by reading the diff:
| Part | What it tells the agent |
|---|---|
| Header | The version and size: v0.6.7, 168 components. Run every command through the CLI. |
| Workflow | Start every page from a template: astryx build "<idea>" names the template to scaffold. Run astryx component <Name> to read the props before using a component. Changing an existing page? Keep its frame and add inside it. |
| Rules | No <div>: components handle layout and spacing. Dense data goes in rows (Table, List), not Card-wrapped lists. Badge is for counts only. |
| Styling | Component props first, then tokens (--color-*, --spacing-*, --radius-*). No raw hex, no raw px. Palettes go through the theme, never :root overrides. |
| Self-check | Re-read the file; replace any raw <div> or <span>, imported CSS, or hardcoded hex or px with the component or a token. |
Three things in it are designed for agents rather than people.
- "Read the props before using one." The most common agent failure with a young library is inventing a prop that sounds right. The CLI prints the real ones, so the instruction replaces recall with lookup. The design system's own anti-pattern list names it: "Inventing props. Read component docs first."
- The self-check step. It turns the rules into a final pass the agent runs on its own output. A rule the agent must remember while writing is a background preference. A step at the end is a task with a checklist, and it reads the finished file rather than the half-written one.
- The CLI path. The design system's docs recommend adding the CLI as an npm script "because agents often mistype the path". We did. A command an agent cannot type correctly is an instruction it cannot follow.
Why generated, and not written by us? Because a hand-written guide drifts from the library it describes. The block is versioned with the package, and refreshing it is one command. When the library adds a component or renames a prop, the guidance changes with it.
Layer 2: one theme source, and lint fails when the build is stale
The colour roles, type and spacing come from one file: a theme source,
relayTheme.ts, that extends the design system's neutral theme and adds
only what we need. npm run theme builds it into CSS and JavaScript. The
app's lint script runs the same build with --check, so make web-lint
fails while the built theme does not match its source.
This closes the shortcut an agent is most likely to take. Asked to "make the selected row more visible", the fastest edit is in the built CSS file, where the computed value sits in plain sight. That edit would work, pass every visual check, and be silently erased by the next theme build. With the check in lint, it cannot merge. The only edit that survives is the one in the source, which is the one you wanted.
Layer 3: every generated file has a drift test
The same pattern covers every artifact in the app that a script produces. Each generator has a check mode, and a Vitest suite runs it.
| Generated file | Produced from | What fails when it drifts |
|---|---|---|
Built theme (relay.css, relay.js) | relayTheme.ts | make web-lint |
| Layer-positioning rules | The installed design system | A Vitest suite (the page CSP blocks the runtime injection, so these ship static) |
| Card schema for agent-rendered UI | The protocol's JSON schema in another module | A Vitest suite |
| Emoji catalog | A generator script at the repository root | A protocol suite runs it with --check |
| Favicons | The SVG logo, rendered with a pinned rasteriser | A Vitest suite |
Every row says the same thing to an agent: this file is output, not source. Edit the input and regenerate, or the build goes red. The instruction file says it too ("generated; do not edit"), but the test is what makes it true.
Layer 4: the one fixed exception, checked against its documentation
The design-system guide sets "Tokens only" as the rule and names exactly one
exception. Agents can draw charts in chat, and they choose series colours
from nine names: blue, orange, red, teal, green, amber, purple, pink, slate.
Those names are part of a wire contract that agents write, not a theme
choice, and the design system has no token for amber or slate. So the nine
Tableau 10 values live as literal hex in one TypeScript file, palette.ts.
An exception that lives in two places will drift, so a test ties them together.
The test opens the guide's Markdown, parses the colour table with a regular expression, and asserts the table equals the palette in code. A second assertion pins how each colour's edge is derived: 65% toward black in light mode, the colour itself in dark mode. And the guide states the process rule: changing an agent chart colour amends the named-series decision record and the table in the same change.
Make the exception as expensive to change as the rule. If the one literal palette in your app can be edited in one file without touching anything else, an agent will edit it the first time a chart "looks off". A test that binds code to documentation forces the change to show up in both, in the same diff, where a reviewer sees it.
The gap: rules that nothing checks
Now the honest part. Line up every rule in the instruction block against the layer that enforces it.
| Rule | Enforced by | Strength |
|---|---|---|
| Theme changes go through the source | Stale-theme check in lint | Wall |
| Generated files are not hand-edited | Drift tests | Wall |
| Agent chart colours match the guide | Palette test | Wall |
| No raw hex in components | Instruction, self-check, review | Advice |
| No raw px | Instruction, self-check, review | Advice |
No raw <div> | Instruction, self-check, review | Advice |
| Read props before using a component | Instruction; type checker catches some invented props | Partial |
| Badge only for counts; rows for dense data | Instruction, review | Advice |
No lint rule bans a raw colour in our app. The ban is an instruction plus review. That is a choice we made for speed during the rebuild, and it is worth measuring rather than assuming. Here is the app's source at the end of October 15, with tests and generated theme files excluded:
Compare that with the roughly 670 literals in the two UIs it replaced. Of the 13, ten are covered by the palette test: the nine named colours and the black used to darken their edges. The other three are not. One is a dark ink for pie-slice labels, left over from the palette we superseded the day before the rebuild; its comment still says so. Two are a white background and a transparent value for exporting a chart as a PNG.
None of those three is a disaster, and the export fallback is arguably correct. But they are exactly the kind of literal the instruction block forbids, and nothing flagged them. They got in because the rule is advice. Today the count is low because the app is days old and every screen was composed from components. Advice holds up well in fresh code and erodes under pressure: a deadline, a third-party look to imitate, an agent asked to "match the screenshot".
How to measure where you stand
Treat the design system's grip on agent-written code as a metric with a number, not a feeling. These are cheap to compute on every commit.
| Metric | How to compute it | Ours on October 15 |
|---|---|---|
| Literal colours in hand-written source | Grep hex and rgb( in non-test, non-generated files | 13, all in chart code |
| Literals not covered by an exception test | The above, minus what a test pins | 3 |
| Component adoption | Share of non-test component files importing the design system | 71 of 75 |
| Generated files without a drift check | Count generators with no --check in CI | 0 |
| Stale-theme failures | Lint failures from the theme check, per week | Not yet tracked |
The second metric is the one to watch. It is the size of the advice-only zone, in units you can count. When it starts to grow, that is the signal to move a rule from layer 1 to a real check.
What this does not fix
- Raw values are still possible. Until a lint rule bans literal colours and pixel values outside an allowlist, an agent can write one and the build stays green. The obvious next step is a check whose allowlist is the exception file and nothing else.
- The block can go stale too. It names version 0.6.7. If someone bumps
the package and forgets to re-run
init, the agent follows guidance for the old version. Our upgrade steps name the codemod and the theme rebuild; the block refresh is documented in a separate section, and nothing fails if it is skipped. - A design system knows components, not judgement. It tells an agent how to build a dialog, not whether this flow should be a dialog. Questions of interaction design (when to confirm, where a setting belongs, what the smallest window should show) need their own short, cited principles, scoped to the UI directory the same way, and loaded beside the block.
- Compliance with the advice is not measured. We know the literal count is low. We do not know how often the self-check step ran, or how often an agent wrote a raw value and then removed it.
What it costs
- Generated files in the repository. The built theme, layer rules, schema, catalog and icons are committed, and each upgrade of the design system means regenerating several of them in one change.
- Lint time. The theme check rebuilds the theme on every lint run.
- Friction on the exception. Changing one chart colour means amending a decision record, the guide and the code together. That is the point, and it is still slower.
- Less freedom in styling. We use the plain CSS path, without the design system's StyleX compiler, so per-component style overrides are not available to agents. Most of the time that is a feature. Occasionally a layout needs a token-level workaround that a person would have written more directly.
The framework
| Layer | Question it answers | Mechanism | Strength |
|---|---|---|---|
| 1. Instruction block | What should the agent read before writing UI? | Generated by the design system CLI, scoped to the UI directory, ending in a self-check | Advice |
| 2. Single theme source | Where can a colour role change? | One source file, a build command, and a stale check in lint | Wall |
| 3. Drift tests | Which files are output, not source? | Every generator has --check, run by the test suite | Wall |
| 4. Checked exception | What is allowed to be literal, and who agrees? | One file, a test against the documented table, a decision to amend | Wall |
| Measured gap | How much is still only advice? | Literal count outside exception tests, per commit | Metric |
Adopt it in this order:
- Generate the instruction block and put it in the directory-scoped instruction file for your UI code. Keep it verbatim; refresh it with the CLI.
- Collapse the theme to one source and add the stale check to lint the same day. This is the cheapest wall and closes the most tempting shortcut.
- Add
--checkto every generator and run them all in the test suite. - Name your exceptions in the design-system guide and pin each one with a test against that table.
- Measure the advice-only zone and turn the rule into a check when the number moves.
Agents follow what they read most of the time. They follow what fails the build every time. Put the rules you care about in the second category.
Written by CatalEx Engineering. We build the AI operating layer for AI-native companies: one platform to build, deploy, and run AI agents in production. More at catalex.co.