Part 7 · 2 chapters · ~20 min
Documenting and Tooling
Stories as the source of truth for a component, the docs page and site as the system's front door, Figma built from the same tokens and mirroring the code API with a sync process, and docs with metrics; then design lint for tokens, components and accessibility, story coverage checks, the suite on every change, and the same rules in every consumer's CI. Then the course in one page.
14
Storybook, the docs site, and Figma to code
a component nobody can find is a component nobody uses
- Stories as the source: one per state and variant with the real API, controls, and a canvas per theme; the fixture for visual regression, the target for axe, the playground for a consumer. No stories means undocumented and untested.
- The component page: purpose in a sentence; when to use and when not, with the alternative named; the API table generated from the types (the TypeScript course part 4); the states with stories embedded; accessibility notes (keyboard, the name requirement, what the primitive guarantees); do and do-not pairs; related patterns and guidelines. Generated where possible; written where it must be.
- The docs site: searchable so "dropdown" finds Select and Menu with the difference explained; versioned with the system; a five-minute getting-started path; the guidelines (parts 4 and 5) and governance pages (part 3) linked. The front door; a repo without one is invisible to most users.
- Figma to code: Figma variables generated from the tokens source (part 1); Figma components mirroring the code's API (the same variants as properties, the same states, the same names) so a handoff names the component and variant; Code Connect showing the snippet in Dev Mode. The gap between the file and the code is where every "it does not look like the design" comes from.
- Keeping them in sync is a process: tokens published to Figma in the same CI step as the CSS; a code component requires its Figma twin before release (a governance rule); frame-versus-story diffs catch drift; a quarterly audit lists orphans on each side.
- Measuring the docs: no-result searches (the vocabulary gap), page visits, first visit to first PR, support questions the docs should have answered (each a docs bug), Figma library usage by team. The docs have a dashboard because they are the product's interface.
STORYBOOK, THE DOCS SITE, AND FIGMA TO CODE
the component in every state, the documentation a consumer can find, and the design file that matches the code
swipe the figure sideways, or tap expand for full screen
1/6
stories
Stories as the source: one story per state and variant (Button: every intent × size, plus disabled, loading, focus, icon-only), written with the component's real API (args), with controls for exploration and a canvas per theme (the theme matrix from part 1). Stories are the fixture for the visual regression suite, the target for axe (part 2), and the thing a consumer opens to see what a component can do. A component without stories is undocumented and untested.
15
Design lint and the tests that keep the system honest
deviation caught at the PR, regression caught at the component
- Token lint: no hex, rgb or named colours, no primitive tokens, no spacing, font-size, z-index or shadow literals in component CSS; auto-fix where the mapping is unambiguous. Part 1's direction rule and dark-mode shortcuts as CI failures.
- Component lint: no raw button, input, select, link-as-button or dialog outside the system (the rule names the component to use); className on a system component only for layout classes; no deep imports past the index. The deviation count per surface feeds the governance dashboard (part 3).
- Accessibility lint: alt on every image, names on icon-only interactives, no positive tabIndex, no outline: none, heading order, labelled form controls, no click handlers on non-interactive elements without a role and key handler. The Disciplines course's mechanisable rules, mechanised; the human pass remains for sense.
- Story coverage: every exported component has stories; the stories cover the states the component declares (a state map per component the check reads); every story renders in every theme; the docs page exists. Missing coverage fails the system's CI.
- The suite on every change: visual regression over every story in every theme with a one-click accept for intended diffs; axe on every story with listed, dated exceptions; keyboard scripts per primitive with focus assertions; the token contrast matrix; type tests on the public API (the TypeScript course part 4). A change that fails any does not merge.
- In the consumer's CI: the lint config shipped and extended so a feature PR fails on a hex colour the same way; the deviation report on the PR; the consumer's own visual regression suite as the safety net for a system upgrade (the Architecture course part 2). The system is honest in its own repo and every consumer's, or honest nowhere.
the course, in one page
| part | the idea | the one thing to do |
|---|---|---|
| 0 what it is for | A product for engineers; pays past a number of screens; six layers | Count screens per quarter and list the layers you have |
| 1 tokens | Decisions with names in three tiers; dark mode is a semantic remap | Flip a dark attribute and list every shortcut |
| 2 components | Behaviour once in a primitive, appearance on top; accessibility the only compiling use | Try to use your top component inaccessibly |
| 3 governance | A proposal path, a written bar, semver with codemods, adoption measured, a weekly ritual | Measure the last three unmet needs' latency |
| 4 UI patterns | Hierarchy, type, space, colour, alignment; motion with jobs; every state designed | Screenshot every content state of one screen |
| 5 UX patterns | Friction where consequence is; defaults and disclosure; prevent errors; trust signals; name dark patterns | Instrument one flow and redesign its biggest drop |
| 6 the triad | Three questions, three overlaps, a review before build; four grounds to push back | Name the ground of your last pushback |
| 7 tooling | Stories, docs, Figma in sync; lint and a suite that keep it true | Ship the token lint to one consumer |
DESIGN LINT AND THE TESTS THAT KEEP THE SYSTEM HONEST
rules in CI for tokens, components and accessibility, and the suite that runs on every change
swipe the figure sideways, or tap expand for full screen
1/6
token lint
Token lint (stylelint, or a custom rule): no hex, rgb or named colours in component CSS (use var(--color-…)); no primitive tokens in components (only semantic or component tier: part 1's direction rule); no spacing literals (padding: 12px fails; var(--space-inset-sm) passes); no font-size literals (use the type role tokens); no z-index literals (a z-index scale); no box-shadow literals (elevation tokens). Each with an auto-fix where the mapping is unambiguous.