Skip to main content

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.

CatalEx Engineering · Published October 16, 2026 · 09:00 UTC

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:

  1. What it reads, at the right moment. Short, imperative, in the file the agent is guaranteed to load when it touches UI code.
  2. 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:

dashboard/web/AGENTS.md · ASTRYX block (paraphrased)
PartWhat it tells the agent
HeaderThe version and size: v0.6.7, 168 components. Run every command through the CLI.
WorkflowStart 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.
RulesNo <div>: components handle layout and spacing. Dense data goes in rows (Table, List), not Card-wrapped lists. Badge is for counts only.
StylingComponent props first, then tokens (--color-*, --spacing-*, --radius-*). No raw hex, no raw px. Palettes go through the theme, never :root overrides.
Self-checkRe-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 fileProduced fromWhat fails when it drifts
Built theme (relay.css, relay.js)relayTheme.tsmake web-lint
Layer-positioning rulesThe installed design systemA Vitest suite (the page CSP blocks the runtime injection, so these ship static)
Card schema for agent-rendered UIThe protocol's JSON schema in another moduleA Vitest suite
Emoji catalogA generator script at the repository rootA protocol suite runs it with --check
FaviconsThe SVG logo, rendered with a pinned rasteriserA 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.

RuleEnforced byStrength
Theme changes go through the sourceStale-theme check in lintWall
Generated files are not hand-editedDrift testsWall
Agent chart colours match the guidePalette testWall
No raw hex in componentsInstruction, self-check, reviewAdvice
No raw pxInstruction, self-check, reviewAdvice
No raw <div>Instruction, self-check, reviewAdvice
Read props before using a componentInstruction; type checker catches some invented propsPartial
Badge only for counts; rows for dense dataInstruction, reviewAdvice

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:

71 of 75non-test .tsx files import the design system
0colour literals in hand-written CSS
13colour literals in TypeScript, all in chart code

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.

MetricHow to compute itOurs on October 15
Literal colours in hand-written sourceGrep hex and rgb( in non-test, non-generated files13, all in chart code
Literals not covered by an exception testThe above, minus what a test pins3
Component adoptionShare of non-test component files importing the design system71 of 75
Generated files without a drift checkCount generators with no --check in CI0
Stale-theme failuresLint failures from the theme check, per weekNot 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​

LayerQuestion it answersMechanismStrength
1. Instruction blockWhat should the agent read before writing UI?Generated by the design system CLI, scoped to the UI directory, ending in a self-checkAdvice
2. Single theme sourceWhere can a colour role change?One source file, a build command, and a stale check in lintWall
3. Drift testsWhich files are output, not source?Every generator has --check, run by the test suiteWall
4. Checked exceptionWhat is allowed to be literal, and who agrees?One file, a test against the documented table, a decision to amendWall
Measured gapHow much is still only advice?Literal count outside exception tests, per commitMetric

Adopt it in this order:

  1. 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.
  2. 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.
  3. Add --check to every generator and run them all in the test suite.
  4. Name your exceptions in the design-system guide and pin each one with a test against that table.
  5. 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.