CorrectByDesign
A standard for agent-ready design systems Text and diagrams CC BY 4.0
Structure
The reference repository
5 skills built · 8 pending

How an agent moves through it.

The thesis says what a design system must hold. This page is the mechanics: the files, the order they are read, where Storybook and the product sit, and what is checked at every step.

On this page

Everything an agent needs reaches the repository it works in, and each file points to the next.

1The traversal

Five reads, then a screen.

Map, rules, catalogue, one component, compose. Nothing is shown before it is needed; nothing needed is left unsaid.

Each file opens onto the next
1README.md → AGENTS.md the map and the rules
2CONVENTIONS · COMPOSITION · FOUNDATIONS
3CATALOG.md for and not-for
4COMPONENT.md beside the source
5 · The screen
apps/web/app/…
inside Page
The repository
Depth is disclosure: the deeper the room, the less of the repository is in view.Beside the path: skills route to 3, Storybook renders 4, Undrift checks every write.
1Start
The product's AGENTS.md, then the package's.The product's file points in with one line; the package's own AGENTS.md gives the rules and the read order for building with it, and ships with the package.
2The rules
CONVENTIONS.md, COMPOSITION.md, FOUNDATIONS.md.What has already been decided, how components sit together, and the token layer at a glance. Each rule names its gate, or says it has none.
3Which one
CATALOG.md.Every component with a for and a not-for, grouped by purpose. The not-for is the line that matters: it names the neighbour to use instead.
4One component
COMPONENT.md beside the source.Props, best practices, accessibility, the quality checklist, next to the code and the stories, so it cannot drift from them.
5The screen
Inside Page, from the primitives.The inset cannot be zeroed, the gaps come from the scale, the columns collapse at a token. The gate checks every file as it is written.
2The files

What is actually there.

sample/ ├── README.md start here ├── AGENTS.md the map, and the rules for working on the system ├── CONTRIBUTING.md the build manual ├── .agents/skills/ 5 skills, each checked against the files it names │ ├── add-a-component/SKILL.md │ ├── check-adherence/SKILL.md │ ├── compose-a-screen/SKILL.md │ ├── pick-a-page-template/SKILL.md │ └── use-a-token/SKILL.md ├── packages/tokens/ │ ├── src/ primitive, semantic (layout), theme: DTCG, one source │ └── FOUNDATIONS.md generated on every build; a hand edit fails the test ├── packages/components/ │ ├── package.json files: what ships, and a test proves it │ ├── AGENTS.md the rules for building with it, shipped in the package │ ├── CATALOG.md which component: for and not-for, grouped by purpose │ ├── COMPOSITION.md how components sit together: eleven rules, six questions │ ├── CONVENTIONS.md fourteen rules, each naming its gate or admitting judgement │ ├── .storybook/ rendered, inside the repository │ ├── tests/package-ships-its-rules.test.ts packs the package; fails if a rule or story is missing │ └── src/components/<name>/ │ ├── COMPONENT.md the colocated doc │ ├── <name>.tsx │ ├── <name>.stories.tsx the living examples │ └── <name>.test.tsx, test-d.ts ├── apps/web/ the product, gated as a consumer ├── packages/undrift/ the gate └── undrift.config.json what the gate checks, per profile
3Storybook, the product and the gate

Storybook, the product and the gate.

3.1Storybook
Two things with one name.The stories are source files beside each component, checked by the build, and they ship in the package as examples, so an agent in the product reads them. The rendered Storybook, with its visual, interaction and accessibility tests, stays with the system, for people and for CI. An MCP server over it is a second channel, never the first.
3.2The product
Here, a consumer in the same tree. For a client, a separate repository that installs the system as a package.The agent reads the installed package and writes into the product, and the same gate runs there. The design file and the designer are on neither path.
3.3The gate
Checks every file the moment it is written.A PostToolUse hook runs Undrift on each write. A raw colour, an arbitrary value, a raw element where a component exists, a foreign UI import: each comes back as an error naming the fix. After three attempts on one file it asks for a decision, a declared gap or an explained exemption, never a workaround.
4How it reaches the product

Shipped as a package.

One system, many products, each reading the rules of the version it installed.

4.1One source
The design system is its own repository and publishes a versioned package.A product installs it the way it installs any other dependency. A system that lives inside its only product is already in the repository the agent works in, and needs no package.
4.2The rules travel with the code
Source, types and stories are read first, because that is what an agent opens.In the first draw of the trial, none of the eight cold runs opened the documentation unprompted, and all eight read the package's source or types instead. The map, the conventions, the composition rules, the catalogue and each component's document are in the package too. A product on version 3 reads version 3's rules.
4.3One line in the product
The product's AGENTS.md names the rules in the installed package.Without it, the rules are present and unread.
4.4The gate runs in the product
It checks every file the agent writes.It checks against the tokens and components of the version installed, so an upgrade changes what it checks against. In the reference, one tree, it reads them in place.
4.5MCP is a second channel
An MCP server serves the same package version through a tool.It suits work with no repository open, such as a prototype built in a chat. It is not the primary channel: an agent has to choose to call it, and cold agents did not go looking for documentation.
4.6The reference is one tree
It is a monorepo, so the gate can be shown running in one place.What it would ship is tested: the package declares its contents, and the build fails if a rule document, a story or a component is left out of it.
5Skills

5 built, 8 pending.

A skill routes a recurring job to the right files. Six of the ten indexed systems ship them; the top-scoring one ships a skill that sends the agent to a page template instead of inventing chrome. Every skill here is checked against the files, tokens, exports and scripts it names, so one that goes stale fails the build.

SkillDoesState
pick-a-page-templateWhat page type is this, then the shape, then the not-built list.built
use-a-tokenThe token for the job and the utility that carries it, never a raw value.built
add-a-componentThe five files, the catalogue row, the barrel export, the gates.built
check-adherenceRun the gate, read the triage, resolve a gap honestly.built
compose-a-screenPage, header, sections, stacks, grids, then the six questions.built
review-a-screenanswer the six composition questions against a renderpending
add-a-tokenpropose a token, get the ruling, wire the utilitypending
write-a-component-docthe COMPONENT.md shape, for and not-for firstpending
choose-a-status-rolesuccess, warning, danger, info, and what each meanspending
handle-a-gaprender Missing, declare it, let triage rank itpending
run-the-gateundrift gate before a commit, read the fix it namespending
theme-a-screenlight and dark from one source, never a dark: utilitypending
build-a-list-pagethe list template when its kit existspending
6Read next

The index measures ten public systems against this shape. The thesis says why the shape is the one that holds.