Design Systems and Component Libraries

Modules 3 and 4 were about producing artifacts: a converted section, a working prototype. This module turns the agent on the thing those artifacts are made of — the design system itself. The leverage argument is straightforward: a fix to one screen helps one screen, while a fix to a token, a shared component, or its documentation propagates to everything built on top of it.

It is also the place where the failure cost is highest. A bad one-off screen embarrasses one review. A bad change to a shared component or a token file quietly breaks surfaces nobody was looking at. That asymmetry is why this module spends as much time on review gates and evidence as it does on generation.

Set expectations about prerequisites. The module assumes the project has some form of system to work against — token files or CSS variables, a set of shared components, and ideally a CLAUDE.md with conventions in it. If a participant's project has none of these, the exercise at the end still works: an audit is exactly how you find out what the de facto system actually is.

The single most common failure in agent-assisted system work is skipping this step. Asked to build a card, an agent that has not read the project will produce a perfectly competent generic card — its own colours, its own radius, its own spacing — and the system gains a duplicate instead of a member. The fix is procedural: the first instruction in any system task is to read the token files, the shared component directory, and the conventions, and to restate what it found before building.

Distinguish the layers of the token stack, because they answer different questions. Primitive tokens are the raw values; semantic tokens carry product meaning, like a status colour or a surface level; component tokens carry local rules, like a chip's radius. Generated output — the CSS variables or theme file the application actually consumes — is what the agent should check implementations against. The school's article on design tokens covers this structure in depth; the working summary is that an agent needs the names and meanings, not just the hex values.

CLAUDE.md is where the conventions that cannot be inferred from code belong: the spacing scale, the naming pattern, the rule that components never use raw palette values. Anthropic's guidance, as of mid-2026, is to keep that file under roughly 200 lines and to push large reference material — full brand guidelines, icon inventories — into skills that load on demand. Module 6 picks up the skills half of that split.

This table comes from the school's article on design tokens as agent instructions, and it is the practical heart of the reading step. The left column is how design intent is usually communicated to humans, who fill the gaps with shared context. An agent fills the same gaps with the most statistically common interpretation, which is how you get a soft blue used for every state and a pill radius on a dense table chip.

The right column has three properties worth naming. Each instruction points at a token by name, so the agent can find it and a script can verify it was used. Each explains the meaning behind the value — warning versus escalated is a product decision, not a colour preference. And the last row builds verification into the instruction itself: evidence is requested up front rather than hoped for later.

The place these instructions live matters as much as their wording. Token meanings and the most important rules belong in DESIGN.md or CLAUDE.md so every session gets them; the full token files stay the source of truth that the agent reads directly. Do not paste an entire token export into the instruction file — reference the files and write only the judgment the agent needs when choosing between valid options.

Walk the loop and name the owner of each step. Reading the system and building inside its rules are agent-run, but the build happens on a scratch branch — shared component code never changes directly on main. The design review gate is human and sits before documentation deliberately: there is no point documenting a component the system designer is about to reject or reshape.

The two steps after the gate are the ones teams habitually skip when humans do this work by hand, which is exactly why they belong to the agent. Documentation is generated in the same run, from the same sources — props from the type definitions, usage guidance from real usages, the Storybook story or MDX page updated alongside the source. Verification produces evidence rather than assurance: the token audit and type check pass, and screenshots of every variant and state are attached so the human review has something concrete to look at.

The dashed feedback line is the part that compounds. When verification finds drift — a missing semantic token, a convention the agent had to guess — the finding goes back into the token files or CLAUDE.md, not just into the conversation. Each pass through the loop should leave the system slightly better documented and slightly harder to drift from. That is the same harness principle from the brief-and-loop modules, applied to the system itself.

A component brief against an existing system reads differently from a mockup-to-code brief. Less of it describes what to build and more of it describes what already exists and must be respected: the components to compose or extend, the semantic tokens to consume, the naming convention, the file location, the states that the system treats as mandatory. The visual description can be short because the system carries most of the visual decisions already.

The plan-first requirement earns its keep on system work specifically. Asking for the proposed anatomy, the prop API, and the variant list before any code exists lets you catch the expensive mistakes — a duplicate of an existing component under a new name, a prop API that fights the rest of the library, a variant explosion nobody asked for — at the point where they cost a sentence to fix.

The highlight line is a rule worth putting verbatim into CLAUDE.md: when the system cannot express something the component genuinely needs, the agent proposes the new token or variant and waits, rather than hard-coding a local value. Most drift enters systems exactly there — a reasonable local exception that never made it back into the system. Making the proposal explicit turns that moment into a design decision instead of an accident.

Documentation debt is the most universal design system complaint, and it exists for a structural reason: docs are written by hand, after the fact, from memory, and the system keeps moving. The component gains a prop or loses a variant and the page describing it quietly becomes a description of the component as it was a year ago. The agent changes the economics because the honest sources — the component source, the type definitions, the token references, and the real usages across the product — are all things it can read at scale.

The per-section sourcing is what makes generated docs trustworthy. Props tables come from the types, so they cannot disagree with the code. Usage guidance comes from how teams actually use the component — the patterns they repeat, the props they consistently misuse, the workarounds that signal a missing variant. Accessibility notes come from what the source actually does, with gaps flagged rather than papered over. The school's component documentation generation workflow scales this to a whole library with one agent per component and a consistency pass over the drafts; in this module the unit is one component, in the same run as the change that touched it.

Two cautions. First, write the doc template before generating anything — it is the contract that keeps fifty pages from reading like fifty authors. Second, generated docs that nobody reviews are just stale docs with a newer date. The human read-through before publishing is part of the workflow, not an optional extra.

Drift rarely starts as a dramatic redesign. It starts as a one-off colour, a copied component, a missing focus state, a density decision that never made it back into the system. An agent is well suited to finding it because the work is mostly patient reading: scanning files for raw values, comparing the same component across routes, checking which states exist where. But without a frame, the output collapses into vague commentary — buttons are inconsistent, spacing needs polish — which is not an audit.

The four layers come from the school's design system audit article and they matter because the same visible inconsistency can have different causes and different owners. Meaning drift — a warning badge that is orange on one page and red on another — teaches users two different languages and is a design decision to resolve. Behaviour drift is usually an engineering fix. Implementation drift, the copied local component, is a consolidation refactor. Presentation drift is polish debt. Severity stops the team spending a day on radius while a warning state is unreadable on mobile.

Scope the audit narrowly: one component family across the routes where it appears, not the whole product. And distinguish intentional variation from accidental drift — a compact table chip legitimately differs from a detail-page chip, but the semantic state, the colour token, and the accessible name should still come from the system. Known exceptions belong in the audit packet so the agent does not try to normalise a useful difference.

Three properties of this prompt do most of the work. It names its inputs — the source of truth, the token files, the shared component, the routes, and the screenshots — so the agent is judging against the actual system rather than a general sense of good practice. It asks for findings with evidence, severity, and a recommended owner, which is the difference between an audit and a list of complaints. And it forbids fixing during the audit, because an agent that quietly rewrites the system while auditing it has just created a new round of undocumented change.

Contrast finding quality explicitly. 'Status chips are inconsistent' invites subjective rework. 'The escalated chip on the project detail route uses raw red while the dashboard uses the semantic warning token' names the file, the token, the meaning at stake, and a mechanical fix. The same applies to the supporting checks: a small verification script that flags raw hex values, arbitrary spacing, and one-off shadows in component code gives the agent something objective to report against, and gives the next run immediate feedback before a human spends attention on it.

Screenshots belong in the inputs because plenty of drift is invisible to a code search: mobile wrapping, disabled-state contrast, focus rings, density inside data tables. Capture desktop and mobile, and the states that matter, and ask the agent to describe observable differences before it recommends anything. Findings then become a fix plan — quick fixes, consolidation refactors, token changes, documentation updates, and the conflicts that need a human decision — which is the bridge to the next slide on refactors.

Every design system carries a backlog of known, unglamorous work: the three local copies of the badge component, the legacy colour variables still referenced in older routes, the components that never got a loading state, the Storybook pages describing last year's API. Teams do not skip this work because it is hard; they skip it because it is tedious and never urgent. That profile — mechanical, repetitive, verifiable — is precisely what an agent handles well, and the audit findings from the previous step are the natural work list.

The discipline that keeps it safe is pass size. A migration run that touches four hundred files in one diff cannot be reviewed honestly; it gets skimmed and approved, which defeats the purpose of having a gate. Decompose by component family, by route group, or by token category, keep each pass on its own branch, and let the verification evidence — the token check, the type check, before-and-after screenshots — accompany every pass. The agent does not get bored on pass nine, which is the actual advantage over doing this by hand.

Be explicit about what the agent must not decide on its own: deleting a token, renaming a semantic token, or changing what a status colour means are system decisions with product-wide consequences. The agent can propose them, with the usage data to support the proposal, and the system owner decides. That boundary is the subject of the next slide.

Review gates exist because the blast radius of system changes is larger and less visible than the diff suggests. A token rename touches every surface that consumes it; a prop change breaks usages the agent may not have found; a new variant becomes something other teams build against the day it ships. The gate question is not whether to review but who is accountable for each kind of change, and writing that down once — in CLAUDE.md or the system's contributing notes — is what keeps approvals consistent when the volume of agent-prepared changes goes up.

The pattern across every row is the same: the agent prepares, a human decides. For token changes the agent can supply the usage counts and the proposed name; the system owner decides whether the system needs the token at all. For API changes the agent can list every affected usage; design and engineering decide whether the trade-off is worth it. For bulk migrations the plan is approved before any pass runs, and each pass is still reviewed, because plan approval is not a blank cheque.

There is a volume effect worth naming honestly: agents make system changes cheap to produce, which means more of them arrive at the gates. If the gates are vague, they become a bottleneck or get skipped, and either failure undoes the benefit. Tight scopes, evidence attached to every change, and clear ownership per change type are what keep review fast enough to sustain.

This trace is a representative composite of the runs behind the book and the school's workflows rather than a benchmark, and it is worth saying that to the room. The task was deliberately ordinary: a segmented control for a dashboard filter bar, in a project that already had a token set, a component library, and conventions in CLAUDE.md.

The two most valuable moments both happened before any code existed. The plan surfaced a genuine gap — there was no semantic token for a selected control surface — and proposed one instead of hard-coding a value, which is the behaviour the brief explicitly asked for. The review gate then did its job in both directions: it accepted the token proposal, cut a 'pill' variant the agent had added speculatively, and corrected the component name to match the library's conventions. Each of those corrections cost a sentence at that point and would have cost a rework round after generation.

The verification step is the other half to dwell on. The token and type checks passed, but the screenshot review caught a focus-ring contrast problem on the selected state — a reminder that mechanical checks do not cover everything and that the evidence exists so a human can look at the right things quickly. Total elapsed time was about an hour of designer attention spread across the gates, which is roughly what writing the documentation alone used to take.

This exercise is scoped to stay honest within an hour: one component family, findings only, no fixes. The most common mistake is choosing too broad a surface — 'audit our design system' produces vague output and an unreviewable wall of text. Status chips, buttons, cards, or form fields across three or four routes is the right size; participants without a formal design system should pick whatever pattern is most repeated in their product, because the audit will reveal the de facto system they actually have.

The packet-assembly step is half the learning. Collecting the token files, the shared source, the usage routes, and the screenshots forces participants to discover what their system does and does not make available to an agent — missing token files, undocumented exceptions, components that exist only as copies. Those discoveries are findings in their own right even before the agent runs.

The classification and prioritisation steps keep the output anchored in the four-layer frame from earlier in the module, and the final step — naming the gate the first fix would pass through — connects the audit back to the governance slide. The findings file is deliberately kept: Module 6 uses it as the seed for a SKILL.md, turning this one-off audit into a procedure that runs on a schedule.

Recap by walking the loop rather than the bullets in isolation: read the system, build inside its rules, gate the change, document and verify in the same run, release deliberately, and feed what you learned back into the tokens and CLAUDE.md. The compounding effect is the real argument for doing system work this way — every pass leaves the system better specified and harder to drift from, which makes the next pass cheaper.

Be honest about the constraint that runs through the whole module: agents make system changes cheap to produce, and the only thing that keeps that from becoming cheap chaos is the combination of narrow scopes, evidence attached to every change, and named owners at every gate. Teams that adopt the generation without the governance end up with a faster-moving mess.

Preview Module 6 concretely. The audit packet and prompt from the exercise are exactly the kind of procedure that belongs in a SKILL.md: written once, loaded on demand, run on a schedule, with the report and evidence format already agreed. Documentation refreshes and asset production runs follow the same pattern. The shift in the next module is from doing the work well once to making the work repeatable.