DESIGN.md and Machine-Readable Systems

Open by connecting back to Module 1. Tokens answer the question which value do I use here, but they cannot answer why this system looks the way it does, which component to reach for, or what the system refuses to do. That connective tissue is what DESIGN.md carries. Without it, an agent with a perfect token set still assembles those tokens into something generic.

Name the two audiences explicitly, because the document fails if it serves only one. The agent reads it at the start of every session — it has to be parseable, specific, and short enough to fit in context without crowding out the actual task. The human reads it when onboarding, reviewing, or arguing about a decision — it has to be skimmable in ten minutes and written in plain language, not a token dump. Most design system documentation today fails both tests: too long and too vague for the agent, too scattered across wiki pages for the human.

Set the scope of the module honestly. This is not a documentation-tooling module and it is not about publishing a public design system site. It is about one Markdown file in the repository, what goes in it, what stays out of it, and the habit that stops it from rotting.

The distinction to land is between documentation that explains and documentation that governs. A public design system site exists to persuade and orient: principles, photography, long usage essays, brand storytelling. It is valuable, but an agent given that material extracts very little it can act on. DESIGN.md is the governing version: the decisions themselves, written so they can be applied without interpretation. Exact colour values mapped to semantic roles, the actual font stacks, the spacing scale, the names of the components that exist and the rules for using them.

Location matters as much as content. The document lives in the repository, version-controlled next to the code it describes. That is what makes it machine-readable in practice: the agent does not need a link, an export, or a vendor API — it reads the file the same way it reads any other file, and changes to it show up as diffs that go through review like everything else.

The last bullet is the behavioural argument from Module 1, restated for documents. Agents fill gaps with the centre of their training distribution. If your document does not say what the system does about radius, density, or empty states, the agent will produce the most common answer on the public web — competent, polished, and not yours. The contract exists to pre-empt that fallback, decision by decision.

The point of this slide is to remove the am I inventing something weird hesitation. The pattern of a Markdown design system that an agent loads before generating anything is already an ecosystem convention. A nine-section schema — colour, typography, spacing, layout, components, motion, voice, brand, anti-patterns — circulates through open-source projects, and public libraries ship large collections of well-known product design systems expressed exactly this way, as of mid-2026. Keep the claim conservative: the specific counts and project names change quickly, so what matters is the direction, not the catalogue.

Two properties of the convention are worth calling out. First, switchability: tools built around these files can swap the active system and the very next generation respects the new rules, because the system is an input the agent reads rather than a theme baked into a template. Second, the insight that portable Markdown beats theme JSON for this job: a JSON theme carries values but not reasoning, usage rules, or refusals, and a human cannot skim it. Markdown carries all of it and stays diffable.

The same idea shows up under other names — brand-spec files frozen for agents in HTML-canvas tools, design-system sections inside skills. The names differ; the move is the same: write the system down once, in text, where the agent reads before it writes.

Walk the grid by groups rather than card by card. The token-backed sections — colour, typography, spacing, layout, motion — should not duplicate the token files; they name the semantic roles, the scales, and the rules for choosing between them, and they point at where the tokens live. The agent behaviour for all of them is the same shape: choose from the named set, never invent a value. If Module 1 was done well, these sections are short.

The usage and asset sections carry what tokens cannot. Components lists the primitives and composites that exist, where they live, and the reuse-before-build rule — for an agent this is the single highest-leverage section, because the most common agent failure in a real codebase is rebuilding something that already exists. Voice covers tone and copy patterns, which matter because agents write a surprising amount of interface copy: labels, empty states, error messages. Brand freezes the assets — logo paths, imagery rules — so the agent references them rather than redrawing them.

Anti-patterns is deliberately drawn in ink as the refusal list; it gets its own slide next. Note that your own document does not have to use exactly nine headings — this school's adds identity, radius, shadows, and icons — but every heading should pass the same test: it declares something, and there is a behaviour you expect from the agent because of it. A section with no expected behaviour is prose that belongs on the public site, not in the contract.

This slide is about the writing standard inside each section. The recurring failure in design documentation is adjectives where values should be: generous spacing, a warm and approachable palette, clean typography. A human designer fills in those adjectives from taste and context; an agent fills them in from the average of the public web. The fix is mechanical: exact values with their semantic role attached, font stacks with fallbacks, a numeric scale, pixel limits where limits exist.

The excerpt shows three habits worth copying. First, every colour line carries both the value and the role — the agent needs the role to choose correctly, the human needs it to review. Second, component entries point at the actual file path. An agent told Button: primary and outline variants will often write a new button; an agent told the variants live in components/ui/button.tsx imports the existing one. Third, forbidden values sit next to allowed ones in the same section, so the constraint is visible at the moment of choice rather than buried at the end.

Also make the pairing with tokens explicit: every value in the document should have a CSS-variable or code counterpart, and the document should say where those live. DESIGN.md states the decision and the role; the token file is the runtime. When the two disagree, that is drift, and a later slide deals with it.

Most design documentation only says what to do. For agents, what not to do carries unusual weight, because the agent's default behaviour is to produce the centre of its training distribution: gradient hero bands, decorative blobs, card grids inside card grids, an invented call-to-action on every section. Those defaults are exactly what an anti-patterns section exists to block. This is the same anti-slop idea that appears across the ecosystem — never invent colours outside the system, never use display fonts not in the spec, never add decoration the content does not justify.

The writing standard is the same as the rest of the document: concrete and checkable. No purple gradients is checkable. Avoid visual clutter is not. The best source of entries is your own review history — anything you have corrected twice in agent output is a candidate, because it will recur until it is written down. This is also where the document earns its keep over time: the refusal list is the accumulated taste of the team, expressed in a form the agent can apply before you ever see the work.

Two cautions. Refusals double as self-review criteria — you can and should ask the agent to check its output against the anti-patterns section before reporting done, which turns the list into a cheap automated gate. And keep it short. A refusal list that tries to enumerate everything bad becomes noise; ten sharp entries that reflect your actual failure modes outperform fifty generic ones.

This table answers the question every team asks within a week of adopting the pattern: we already have a CLAUDE.md and a token file — why do we need another document? The answer is separation of concerns, and it matters because duplicated rules drift apart and the agent has no way to know which copy is current.

Walk the rows. The agent instruction file — CLAUDE.md, AGENTS.md, GEMINI.md depending on platform — owns how to work in the repository: commands, test conventions, branch rules, and one line that matters here: read DESIGN.md before any UI work. It should not restate the palette. DESIGN.md owns the design decisions: roles, scales, component rules, voice, anti-patterns. Token files own the runtime values the code actually consumes; DESIGN.md names the roles and points at these files rather than copying every value, because copied values are the first thing to drift. Skills own procedures — run the token audit, scaffold a component with our states, produce a review checklist — and they consume DESIGN.md rather than re-declaring it.

The practical test for any new rule: where would the agent need it, and where would a human look for it? Workflow rules go in the instruction file, design decisions in DESIGN.md, values in tokens, procedures in skills. When you find the same rule in two places, pick the owner and replace the other copy with a pointer.

The pressure on this document is always to grow. Every incident produces a candidate rule, every stakeholder has a paragraph they want included, and the document quietly becomes a wiki. The cost is real on both sides: for the human, a long document stops being read; for the agent, every additional line competes for attention with the rules that actually prevent bad output, and the document starts crowding out the task context it is meant to support.

Go through the exclusions. Raw token values are the most tempting duplication — resist mirroring the whole token file, because the mirror will be wrong within a month; name the roles, give the handful of values that anchor identity, and point at the files. Brand storytelling and principle essays persuade humans and give agents almost nothing actionable. Per-feature specs and page briefs describe a moment in time, not the system; they belong in the brief for that work. Workflow rules — how to run checks, how to branch — belong in the instruction file from the previous slide.

The last bullet is the honest one: do not write down anything you are not willing to maintain. A stale rule is worse than a missing one, because the agent will follow it confidently and the human will assume the document is wrong about everything else too. Keeping the document small is what makes keeping it true achievable.

The document and the code drift apart for ordinary reasons: a new component family lands without a documentation pass, a token is renamed during a refactor, a one-off exception ships under deadline and quietly becomes the pattern everyone copies. None of these is negligence; they are what happens when documentation is a separate activity from making changes.

The consequence is specific to agents. A human reader treats documentation with healthy suspicion and checks the code when something looks off. An agent treats the document as authoritative — that is the entire point of the document — so a stale entry does not just mislead, it gets faithfully reproduced in new work. A document that is eighty per cent right produces output that is confidently wrong in the other twenty.

Two habits keep it true without a documentation project. First, the document changes in the same pull request as the change it describes: a new component, a renamed token, a revised rule — same diff, reviewed together. Second, run a periodic verification pass where the agent itself diffs the document against the codebase: do these components still exist at these paths, do these tokens still carry these values, are there token families or components in the code the document never mentions. That is a small, well-scoped agent task, and Module 4 turns it into a full audit practice. A visible last-verified date completes the loop — it tells both audiences how much to trust what they are reading.

Most teams adopting this pattern are not starting from nothing — the system already exists, scattered across a globals file, a Tailwind theme, a components directory, and habits nobody wrote down. Drafting the document by hand from memory is slow and produces a document about the system you think you have. Having the agent extract a first draft from the code produces a document about the system you actually have, which is more useful and occasionally more embarrassing.

Walk the prompt. Scoping the read matters: point at the token files, the component directories, and the shared shell components rather than the whole repository. The only-document-what-the-code-shows rule plus the [UNVERIFIED] marker is what makes the draft reviewable — without it, the agent will confidently describe conventions it inferred from one example. Asking for a section outline first is the same plan-before-build gate as any other agent task.

Be clear about what extraction cannot produce. The code can tell the agent what values exist and which components are used where; it cannot say why, what the identity is, or what the system refuses to do. Identity, voice, and anti-patterns stay human-written. And the first draft will be wrong in places — it will elevate accidents into rules and miss rules that live only in review comments. That correction pass is not overhead; it is the moment the team actually decides what its system is.

This example is first-party: the document being described is the DESIGN.md in this site's own repository, and the agent-built pages of the school are the evidence of what it does. Walk the mapping column by column: the declaration is only as useful as the behaviour change it produces.

A few specifics worth narrating. The identity section is two lines of mood and metaphor — clear, instructional, bookish — and it is what stopped early drafts from defaulting to generic SaaS landing-page styling; identity is the cheapest section to write and the one most teams omit. The colour section maps oklch values to the shadcn semantic variables in globals.css rather than duplicating them, which is the point-at-the-tokens pattern from earlier. The anti-slop rules sit inside the layout section rather than as a separate ninth heading — a reminder that the nine-section schema is a convention, not a law; this document uses ten headings including radius, shadows, and icons, and adds a canvas contract section covering the Figma and OpenPencil snapshots, which is deliberately out of scope for this module.

The component system section is the longest in the file and earns it: every component family is named with its file path and a usage rule, which is why agent-built pages assemble SectionBand, AccentCard, and ArticleCard instead of inventing layout divs. The honest caveat: the document still requires the verification habit from earlier in the module — it has needed corrections as components evolved, and the last-verified discipline is what keeps it trustworthy.

This exercise produces the artefact the rest of the course builds on, so encourage people to actually run it rather than file it away. If a document already exists, the same steps work as a refresh: run the extraction, diff the result against the existing document, and treat every mismatch as either drift to fix or a rule to delete.

The sequencing matters. Extraction first, because the agent is faster and more honest about what the code contains than memory is. Correction second, and warn people that this step takes longer than they expect — the draft will contain accidental conventions, things that appear three times in the code without ever having been decided. Deciding whether each one is a rule or an accident is the actual design-system work. The hand-written sections come third: identity in a few lines, and at least five anti-pattern entries drawn from real review history rather than imagination.

The final step is the one that distinguishes this from a documentation exercise: give the document to the agent and have it build one small, low-stakes component using only what the document says. Every mistake in the output is diagnostic — either a missing rule, a vague rule, or a rule that no longer matches the code. Keep the notes from that test run; Module 3 uses the same component as the input to its review-gate exercise.

Recap by tracing the through-line rather than re-listing the slides. The contract framing explains the writing standard — values, paths, and refusals instead of adjectives — and the anatomy is just that standard applied section by section. The who-owns-what table prevents the duplication that breeds contradictions, and the drift slide is the maintenance cost you accept by writing anything down at all. The extraction workflow makes the first draft cheap; the correction pass and the hand-written sections are where the actual decisions get made.

If participants did the exercise, the test-build notes are the bridge to the next module: most of what the agent got wrong will not be token or rule violations, it will be judgement — density that feels off, hierarchy that is technically compliant and still wrong, copy that is grammatical and not yours. That is precisely the territory DESIGN.md cannot fully capture.

Preview Module 3 concretely: what taste means operationally, which checks an agent can run on its own output, and how a review gate works when the contributor is an agent — including what evidence a component has to bring before a human spends attention on it.