On this page
Everything an agent needs is inside one repository, 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.
1Start
README.md, then AGENTS.md.The map and the five rules that are not the agent's to break. It says which file to open next and not to load everything at once.
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 five rules
├── CONVENTIONS.md fourteen rules, each naming its gate or admitting judgement
├── 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/
│ ├── CATALOG.md which component: for and not-for, grouped by purpose
│ ├── COMPOSITION.md how components sit together: eleven rules, six questions
│ ├── .storybook/ rendered, inside the repository
│ └── 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 and the instrument
└── undrift.config.json what the gate checks, per profile
3Storybook and the product
Both are inside the line.
3.1Storybook
In the repository, not beside it.The stories are source files next to each component; the Storybook build and its test runner live in the components package. An agent reading the repository reads the stories. An MCP server over Storybook, when one is added, serves the same repository through a tool, and the claim on the home page holds: the agent builds from the repository and nothing else.
3.2The product
Here, a consumer in the same tree. For a client, a separate repository.In the reference, apps/web consumes the components and is gated as a consumer. In an engagement the product is its own repository: the agent reads the design system's repository and writes into the product's, 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.
4Skills
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.
| Skill | Does | State |
|---|---|---|
| pick-a-page-template | What page type is this, then the shape, then the not-built list. | built |
| use-a-token | The token for the job and the utility that carries it, never a raw value. | built |
| add-a-component | The five files, the catalogue row, the barrel export, the gates. | built |
| check-adherence | Run the gate, read the triage, resolve a gap honestly. | built |
| compose-a-screen | Page, header, sections, stacks, grids, then the six questions. | built |
| review-a-screen | answer the six composition questions against a render | pending |
| add-a-token | propose a token, get the ruling, wire the utility | pending |
| write-a-component-doc | the COMPONENT.md shape, for and not-for first | pending |
| choose-a-status-role | success, warning, danger, info, and what each means | pending |
| handle-a-gap | render Missing, declare it, let triage rank it | pending |
| run-the-gate | undrift gate before a commit, read the fix it names | pending |
| theme-a-screen | light and dark from one source, never a dark: utility | pending |
| build-a-list-page | the list template when its kit exists | pending |
5Read next
The index measures ten public systems against this shape. The thesis says why the shape is the one that holds.