A Design Stack That Produces Repeatable Results

The mental-model article established the core fact about this material: model output is a draw from a distribution. You can’t hand-craft the variance away, not with better prompts typed fresh each morning and not with your most talented designer at the keyboard. Every element you don’t standardize widens the distribution. A different model version. A context dump worded differently each time. A workflow retold from memory. A personal account with different settings.

A harness is everything around the model that you can hold constant:

• which model runs
• what context it’s given
• what instructions encode the workflow
• what environment and tools it has access to
• what the output must pass before anyone calls it done

Hold those constant and the distribution narrows to something a team can rely on. The variance that remains belongs to the material, and now it’s visible instead of buried under setup noise. The jig doesn’t make the router deterministic. It makes everything around the cut deterministic, so the cut is the only thing left to judge.

Anthropic’s engineering team gave this discipline a name in 2025, context engineering, and their guiding principle is a good one to tape to the wall:

Most of the harness is generic. Any team running agents needs a sanctioned model, written instructions, and a review gate. But one part of it is specific to design, and it matters more than the rest combined.

When an agent generates interface code, every decision it makes is a design-system decision, whether intended or not.

Which button.
Which spacing value.
Which color for an error state.
Which layout for a settings page.

An agent with no access to your system makes those decisions anyway, fluently and differently each time. This results in the drift that befuddles designers who strive to keep high craft standards, but can’t figure out why it isn’t working.

The teams that have tried it report the same failure pattern. Atlassian found agents surfacing outdated patterns, missing accessibility requirements, and inventing components. 1Password watched a general-purpose agent put tokens at the wrong tier and reach for raw HTML instead of the library’s primitives, leaving reviewers to clean up after it.

Give the agent the system, and the same decisions come out the same way every time. That’s the jig.

It’s also the only jig that runs the full length of the path from idea to production. A designer prototyping in Figma Make or Claude Code, an engineer building the feature in Cursor, and the code that finally ships can all draw from the same components and the same tokens. When they do, the prototype stops being a throwaway. It’s built from the parts production is built from, so handoff becomes a code review.

The design system is the source of truth that code generation builds on. Treat it that way, and every other layer of the harness gets easier.

Murphy Trueman put the shift well:

First, some context on the formats, because the past year changed what’s possible.

After World War II, European cabinetmakers converged on drilling every hole on a 32-millimeter grid. The number came from the machinery: 32mm was the closest that drill bits could sit side by side on a line-boring machine. Hinge, drawer-slide, and shelf-pin makers designed their hardware to the same grid. The payoff was interchangeability. A hinge from one manufacturer fit a cabinet from another, and a shop could change suppliers without rebuilding its fixtures.

The striking part is how the 32mm system got there:

There’s now enough public work to see the pattern. A sample:

Read across the rows and the convergence is obvious. Every one of these teams broke the system into the same handful of parts, made each part machine-readable, delivered it on demand, and gave the agent a way to check its work.

I’ve divided this into six parts. The first four are content: what your system knows. The last two are infrastructure: how agents get it and how you know they used it correctly.

1. Tokens: the only legal values

Tokens are what make generated code clean. An agent that styles with color.border.critical produces something that themes, flips to dark mode, and survives a rebrand. An agent that styles with red-500 produces a liability. Every other part of the system references tokens, so they come first.

• Use the DTCG format. It’s stable, vendor-neutral, and exports to everything else (CSS variables, Tailwind, platform code, DESIGN.md).
• Separate primitives from semantics. Primitives hold the raw palette and scale. Semantic tokens hold decisions (color.text.subtle, space.inset.card). Components reference semantic tokens only. That one rule is what makes theming work without the agent thinking about it.
• Name by purpose. color.border.critical tells an agent when to use it. red-500 tells it nothing.
• Mark status. Introduced, deprecated, replaced-by. Agents can’t tell a legacy token from a current one unless you say so.
• Make raw values a lint error. Then “use tokens” is enforced on every build.

2. Component metadata: the contract, as data

Prose docs tell a person what a component is. Metadata tells an agent what it’s allowed to do. Every component needs a structured record:

• props with types, defaults, allowed values, and constraints
• variants, sizes, and states
• composition rules: what it can contain, what it can sit inside
• the tokens it binds to
• an accessibility contract
• status (stable, beta, deprecated) with the replacement named
• import path and version

Generate it from source wherever you can. This is the single most important practice. Atlassian keeps its schemas in TypeScript beside the components. Astryx’s doctor command checks documented props against the actual TypeScript props. SmartHR generates guidelines from metadata and lint rules. Hand-maintained metadata drifts, and an agent will trust drifted metadata completely.

Name components by purpose, too. ConfirmDestructiveAction carries intent an agent can pattern-match to. ModalAlt2 doesn’t.

3. Usage guidance: judgment, written as rules

This is the part most systems are weakest on, and the part agents need most. Metadata says what a component can do. Usage guidance says when it should.

• Use when / use instead. “Use Button for actions in the current view. For navigation, use Link. For on/off settings, use Switch.” Agents are constantly choosing between near neighbors. Tell them how.
• Do’s and don’ts that are checkable. “One primary button per view” is a rule an agent can follow and a reviewer can verify. “Use primary buttons thoughtfully” isn’t.
• Content standards. Label length, casing, verb-first, error-message structure. Atlassian’s agent-facing content was written with content designers, which is the right call: the words in a component are part of its contract.
• Chunked per component. Retrieval works on small pieces. A forty-page “Buttons and Actions” doc gets loaded whole or not at all.

4. Example patterns: what the agent will actually imitate

Models learn more from one good example than from a page of rules. Examples are your highest-leverage content and the easiest to neglect.

• Canonical examples per component. Three is a reasonable floor: the common case, a tricky state, and a composition with neighbors. Storybook’s MCP returns a component’s first three stories for exactly this reason.
• Page-level patterns. Most real requests are bigger than a component: a settings page, a data table with filters, an empty state, a destructive confirmation flow. Primer exposes patterns as their own tools. Astryx ships templates. SmartHR has 22 pattern guides. This is where your system’s taste lives.
• Keep examples compiling. An example that references a removed prop teaches the agent to use a removed prop. Test examples like code, because they are code.

Here’s what parts 1 through 4 look like together for a single component. The format is illustrative: the metadata is the point.

component: Button
status: stable                 # stable | beta | deprecated
since: 4.2.0
import: "@acme/ds/Button"
purpose: Triggers an action in the current view.

props:
  variant:
    type: enum
    values: [primary, secondary, subtle, danger]
    default: secondary
    rule: One primary per view. Danger only for destructive, irreversible actions.
  label:
    type: string
    required: true
    rule: Verb first, sentence case, three words or fewer.
  size:
    type: enum
    values: [sm, md, lg]
    default: md
  icon:
    type: IconName
    required: false

tokens:
  background: color.action.primary.bg
  text: color.action.primary.text
  radius: radius.control

accessibility:
  - Icon-only buttons require an aria-label.
  - Touch targets are at least 44×44 px.

use_when: The user commits or triggers something in the current view.
use_instead:
  navigate to another page: Link
  toggle a setting: Switch
  confirm a destructive action: patterns/destructive-confirmation

examples:
  - stories/button--default
  - stories/button--loading
  - patterns/form-footer

5. Delivery: the MCP server, plus a few signposts

Content in a repo doesn’t help an agent that can’t reach it. Delivery has a primary channel and several supporting ones:

• An MCP server for on-demand retrieval. This is the main channel, and the next section covers how to design one.
• Skills for procedures that span many components: build a page from a pattern, scaffold a new component, migrate a legacy screen. 1Password wrote eight narrow skills for exactly these jobs. Knowledge comes from the server; procedure comes from the skill.
• An AGENTS.md section in every consuming repo that says, in effect: for any UI work, use the design-system server; never use raw values; report gaps instead of inventing components. Astryx writes this section for you on install.
• DESIGN.md as an export for tools that can’t use MCP or skills.
• llms.txt on your docs site, which is cheap to add and low-value (more on that below).

6. Enforcement and feedback: how you know it worked

• A review tool the agent can call. Primer’s Brand server checks generated JSX and CSS for unknown components, invalid props, and hardcoded values. The agent runs it before handing work back, and catches its own mistakes.
• Lint in CI. The same rules, enforced on every pull request regardless of who or what wrote the code.
• Accessibility tests wired into the loop, as Storybook does with its test runner.
• Gap reporting. When the agent needs something the system doesn’t have, it should say so rather than improvise. Astryx’s gap-report does this. Every report is design-system intake, which is a better signal of what to build next than most roadmaps.
• Evals. Astryx’s vibe tests run the same prompts against the system and against baselines, then score the output. That’s how you measure “agent-ready.”

If you’re building one, as my team is, here’s what the public work suggests.

Build your tools around the questions agents ask. Your docs site is organized for browsing. Agents work by asking: “what components exist?”, then “what are this one’s props?”, then “show me an example.” Expose that sequence directly, with small responses at each step. This is progressive disclosure, the same principle that makes Agent Skills efficient: load the index first, the detail only when needed.

A starter tool set, modeled on Primer and Astryx:

Keep responses small and structured. Context isn’t free. Storybook’s docs warn that excessive or misleading context degrades agent performance, and they let you tag components out of the manifest. Return the smallest useful record.

Make it version-aware. An agent working in a repo pinned to v4 should get v4’s API. Primer’s Brand server reads the docs of the installed package version for exactly this reason.

Pair it with a skill. The server knows what’s in the system. A skill knows how your team builds with it: start from a pattern, check usage before choosing a variant, run review before finishing. This isn’t a one or the other choice. Atlassian uses both.

Then measure it, because the delivery method matters more than you’d expect. Recall the foreshadowing above: Atlassian ran a production-style task (build a login screen) four ways and published the averages:

The MCP server was the cheapest and fastest. DESIGN.md alone used about 92% more tokens than MCP, took longer than having no context at all, and led agents to re-create existing components instead of importing them, because a single file describes what components look like rather than pointing to the real ones. It also had to be cut to fit: Atlassian’s full guidance runs about 2.5 MB, and the DESIGN.md came in around 80 KB. In a separate benchmark, structured content behind the MCP server produced more accurate code with fewer errors, tokens, and tool calls than agents working without it.

Atlassian is careful to say these results aren’t conclusive; different models, prompts, and systems will vary. Their conclusion is still the right one: DESIGN.md is “not a replacement for richer design system tooling.” It’s genuinely useful for visual direction, quick prototypes in unfamiliar tools, and theming. Generate one. Just generate it from your source, as an export.

The practice that ties all of this together is what Atlassian advises: avoid creating another source of truth.

Your design system already has too many copies of itself: the Figma library, the code package, the docs site, the Storybook, the Confluence pages nobody has updated since the last rebrand. Adding agent-facing content as another copy guarantees drift, and agents trust drifted content completely. Instead:

• One structured source, ideally beside the component code, holds tokens, metadata, usage, and examples.
• Everything else is generated from it: the MCP server’s responses, the skill, the DESIGN.md, the docs site, the lint rules’ documentation.
• Figma connects through Code Connect, so a designer’s frame maps to real code components, and design-to-code generation uses your library instead of approximating it.
• Agent-facing content updates in the same pull request as the component. Atlassian goes further: when a component changes, agents update the structured content and run evals and code-health checks.

Get this right and the prototype-to-production path collapses. A designer prototyping in v0, Figma Make, or Claude Code queries the same server an engineer queries from Cursor. The prototype is made of production components with production tokens. What reaches engineering is code engineering can keep.

It also changes what the design-system team is. They’re now shipping an API with real consumers, and it needs API-grade ownership: versioning, changelogs, deprecation policy, and evals. Atlassian’s bylines on this work are telling: content designers, a design technologist, and a prompt engineer, working together. Staff accordingly.

Each layer is something held constant so the layer above it can be trusted. Ownership maps to the three roles. The design system now runs through three of the five layers, which is why it deserves to be treated as the center of the harness.

Packaging: MCP config + skills, shipped as one plugin.
Sidecar: a tool registry & evals — what’s approved, what’s measured, what triggers a re-check.

Three observations

• Context and Output Gate are still the ones orgs skip. Everyone has a model. The enthusiastic have skills. Without a shared context layer, every skill runs against a different private retelling of your product, and without an output gate, “done” means whatever the last person felt like. For design orgs, the design system fills most of both, if it’s been made agent-ready.
• The design-system team now owns infrastructure. Layer 4 used to be purely agent-ops territory. A design-system MCP server puts design systems in the runtime path of every agent that touches UI. Plan for uptime, versioning, and access the way you would for any internal API.
• Standard formats don’t come with standard content. The 32mm grid tells you where to drill the holes. It doesn’t tell you what cabinet to build. Every layer in this stack is empty until your team writes down how you design, and that writing is the actual job.

Two repos matter. The design system’s repo is the source; every product repo consumes it.

design-system/                     # the source of truth
├── tokens/                        # DTCG; primitives + semantic tiers
├── components/
│   └── button/
│       ├── Button.tsx
│       ├── button.meta.ts         # metadata record, beside the code
│       ├── button.usage.md        # use when / use instead / do's and don'ts
│       └── button.stories.tsx     # canonical examples, tested
├── patterns/                      # page-level compositions
├── mcp-server/                    # serves all of the above on demand
├── skills/
│   └── build-from-pattern/SKILL.md
├── evals/                         # benchmark tasks, run on release + model change
└── dist/
    └── DESIGN.md                  # generated export, never hand-edited

And the section every product repo’s AGENTS.md should carry:

## UI and the design system
- For any UI work, use the `acme-ds` MCP server. Check `get_usage`
  before choosing a component or variant.
- Style only with design tokens. Raw color, spacing, or type values
  fail CI.
- Start page-level work from a pattern (`list_patterns`).
- If the system doesn't have what you need, call `report_gap`
  and build the closest compliant alternative. Don't invent components.
- Run `review` before handing work back.
- No MCP access? Fall back to /design-system/dist/DESIGN.md.

This is design-systems work more than platform work: the same discipline that built your system, aimed at a new reader.

Below the stable layer, a second wave of standards is arriving. Most design teams haven’t heard of them yet, and a couple will matter a lot to design systems specifically.

Agent Plugins 1.0

• What it is: A packaging format, published August 2026, that bundles Agent Skills and MCP server configuration into one directory with a plugin.json manifest. Developed by representatives from Amazon, Cursor, Microsoft, OpenAI, and Vercel; supported in VS Code, Cursor, GitHub Copilot, Codex, and Kiro. Independently governed and not an AAIF project.
• Why design cares: This is how a design system ships to every team in one install: server config plus skills, together. SmartHR and Mitsubishi Electric’s Serendie already distribute their systems as installable Claude Code plugins. Agent Plugins is the attempt to make that package portable across tools.
• Call: Pilot. Hooks were left out of v1 because tools disagree on how they work, so expect some tool-specific glue to remain.

A2UI (Agent-to-UI)

• What it is: Google’s open spec for agents to describe an interface declaratively, which the client app then renders with its own native components. v0.9 shipped in April 2026; a v1.0 release candidate is out, with official React, Flutter, Lit, and Angular renderers.
• Why design cares: The agent picks from a catalog of components the client already owns. Your design system becomes the agent’s vocabulary at the protocol level, including for agents that generate UI at runtime inside your product.
• Call: Watch closely if you design agent-facing products. Pilot it if you’re already building generative UI.

MCP Apps

• What it is: An official MCP extension, built by Anthropic, OpenAI, and the MCP-UI project, that lets a tool return interactive UI rendered in a sandboxed frame inside a chat host. Stable spec dated January 2026.
• Why design cares: Your product can now show up as an interface inside someone else’s agent. That surface needs your design system, your states, and your error handling, in a frame you don’t control.
• Call: Pilot if your company exposes an MCP server. Otherwise, watch.

llms.txt

• What it is: A community proposal (Jeremy Howard, 2024) for a Markdown file at a site’s root summarizing its content for language models.
• Why design cares: Design-system docs sites are a natural fit, and some (Carbon among them) publish one.
• Call: Cheap, but don’t count on it. No major model provider has confirmed reading it, and one 2026 server-log study found the vast majority of files received no AI requests at all. Your MCP server does this job properly.

For those that don’t like to read, here’s the article in a handy checklist:

Shipping an agent-ready design system

1. Tokens are in DTCG format, split into primitive and semantic tiers, named by purpose.
2. Components reference semantic tokens only, and raw values fail lint.
3. Every component has a structured metadata record, generated from source, not hand-maintained.
4. Status is machine-readable. Deprecated components and tokens name their replacements.
5. Every component has usage guidance: use when, use instead, checkable do’s and don’ts, content rules.
6. Every component has an accessibility contract the agent can read and a test can verify.
7. Every component has at least three canonical examples, and they compile and pass tests.
8. Your top flows exist as page-level patterns.
9. An MCP server delivers all of it with progressive disclosure, small structured responses, and version awareness.
10. Agents can check their work and report gaps: a review tool and a gap-report tool, both live.
11. There’s one source. DESIGN.md, docs, skills, and Figma mappings are generated or connected, never hand-copied.
12. It’s benchmarked. The same tasks run with and without the system, scored on accuracy, tokens, and turns, re-run on every major release and model change.

Making a workflow repeatable

A workflow doesn’t get called standard (it doesn’t enter the library or count toward the Pod Score’s workflow-integration dimension) until it passes all ten. Think of it as the woodworker’s careful jig inspection before entering full production.

1. Model recorded. The skill names the model and version it was validated against. “Whatever I had open” is the first source of phantom variance.
2. AGENTS.md covers it. Rules, file locations, and hand-back checks live in the repo’s AGENTS.md, not in the author’s personal notes or chat history.
3. UI work runs through the design system. Components, tokens, and patterns come from the design-system server (or its DESIGN.md export where MCP isn’t available), and output passes the system’s review tool.
4. The workflow is a SKILL.md. The description reads like a matching rule, the human review points are marked, and a “bad for” section documents where it fails. The file, not its author, is the source of truth.
5. Clean-start test passed. From a fresh environment with only the repo, the workflow runs. No “oh, you also need to…”
6. Second-designer test passed. Someone who didn’t build it gets acceptable output on the first attempt, with no verbal coaching. If they don’t, the gap is in the file. Fix the file and retest.
7. Second-tool test passed. The same skill and the same design-system server work in a second agent tool with no edits. This proves you built to the standard instead of to one vendor’s quirks.
8. Reference set stored. Three sample inputs, their known-good outputs, and the eval owner’s rubric sit beside the skill, graduated from the pile-sorting exercise in the twenty-runs piece, so “acceptable” is something you can show.
9. Output gate defined. One sentence at the top of the skill states what the deliverable passes before it leaves the harness: design-system review, lint, rubric score, human sign-off.
10. Owner and drift trigger named. A named owner, plus a rule to re-run the reference set when the model underneath or the design system changes. Re-validation is what keeps the library from becoming a museum, because a jig that’s drifted out of square is worse than no jig: it produces confident wrong cuts.

A pod that can tick all ten for even two workflows, on top of a system that passes the first list, will out-produce a pod holding every design tool license on the market, and do it repeatably, which is the whole point.

Back to the second woodworker, and the moment that pays for the jig: the customer who orders forty chairs. Freehand craft, however good, can’t say yes to forty chairs. The jig can, in a form that freelance woodworkers can use to fill the order after its designer goes home.

That’s what your org is being asked for: a strong prototype per pod, per sprint, at a quality bar someone wrote down, built from the same parts that engineers use. You already own the jig that makes that possible. It’s been sitting in your design system the whole time, written for a reader who skims.

Rewrite it for the one that doesn’t.

Agent-ready design systems to study

• Meta Astryx (GitHub, CLI docs): the most complete open example of a system built for agents from the start, including its evaluation approach.
• Primer MCP and Primer Brand MCP: the clearest public tool taxonomy for a design-system server.
• Atlassian, Teaching AI to speak our design language and Atlassian’s DESIGN.md is here: the best published evidence on structured content and delivery methods.
• Carbon MCP, Storybook MCP, and Figma’s MCP server with Code Connect.
• SmartHR Design System and Serendie: two systems distributing skills and servers as plugins. Classmethod’s roundup compares them with Astryx and v0.
• 1Password, Agent-driven design system: narrow skills, an MCP server, and honest lessons about where agents still need humans.
• Murphy Trueman, Your next design system user is an agent: the case for treating your system as an API.

Standards

• Model Context Protocol and the MCP Apps announcement.
• W3C Design Tokens specification.
• Agent Skills and AGENTS.md.
• DESIGN.md and Google’s announcement.
• Agent Plugins 1.0.
• Anthropic, Effective Context Engineering for AI Agents: why the context layer matters.