Design system
documentation.

Design system documentation is the written reference that tells a team how to use its shared design language: the design tokens, components, usage guidelines, do and don’t examples, and accessibility rules that turn a Figma library and a component package into something people can build with. Good docs answer when to reach for a thing, not just what it looks like.

Most design systems do not fail because the components are bad. They fail because nobody can tell, six months in, whether to use Banner or Toast, whether the new spacing token shipped, or why the old button still exists. That is a documentation problem, and it is the one most teams underinvest in. This playbook covers what to document, how to structure it, how to keep it current as the system changes, and how to make it findable so the work you did actually gets used.

What goes into design system documentation?

Treat the docs as layers, from the smallest decision to the largest. Each layer answers a different question, and skipping a layer is what produces the “the component exists but nobody knows the rules” gap. The five that matter:

The layer teams skip most is usage guidelines. Anatomy and props are easy to auto-generate; the judgment — “use a destructive button only for irreversible actions, never for a cancel” — has to be written by a human and is exactly what stops the system from drifting. If you only have time for one prose section per component, write the do and don’t.

How should you structure the docs?

Pick one shape for a component page and use it for every component. Predictability is the whole point: a teammate should be able to guess where the accessibility notes live before the page loads. A structure that holds up:

1. Overview. One sentence on what the component is for, and a single live example above the fold.
2. When to use / when not. The decision, including the nearest neighbour it gets confused with (Banner vs Toast).
3. Anatomy. A labelled diagram of the parts, so the vocabulary is shared.
4. Props / API. The full table — generated from types where you can so it cannot rot.
5. States and variants. Default, hover, focus, disabled, loading, error, plus every size and intent.
6. Do / don’t. Paired examples, ideally rendered, not described.
7. Accessibility. Roles, keyboard behaviour, focus management, and anything a consumer must not break.
8. Code and design links. A direct link to the source, the package, and the Figma component, so design and code never drift apart silently.

Above the component pages, you need a short getting-started path: how to install the package, how to pull the tokens, how to find the Figma library, and how to propose a change. Below them, a foundations section for the tokens themselves — the color ramp, the type scale, the spacing system — documented as values with their names, because that is what people copy.

A copy-paste checklist for documenting a component

When a new component is ready to ship, run it through the same list every time. Paste this into your contribution template or the component’s pull-request description so nothing gets forgotten under deadline pressure:

• Name and status. Final name agreed, status set (draft / beta / stable / deprecated).
• Overview + one live example rendered at the top of the page.
• When to use / when not written, including the component it is most confused with.
• Anatomy diagram with every part labelled.
• Props table complete, with defaults and required flags marked.
• Every state shown — default, hover, focus, active, disabled, loading, error, empty.
• All variants shown — sizes, intents, and density options.
• At least two do / don’t pairs, rendered rather than described.
• Accessibility notes — role, keyboard map, focus behaviour, contrast on every variant, reduced-motion handling.
• Content guidance — label length, casing, and what good copy looks like.
• Links out — source file, package export, Figma component, and the related pattern pages.
• Changelog entry added, and the owner named for future questions.

It looks like a lot. In practice most rows take a sentence, and the ones that take longer — accessibility and the do/don’t pairs — are the rows that save you the most support questions later.

How do you document accessibility and do/don’t?

Accessibility belongs in two places: a system-wide baseline and a per-component note. The baseline states the rules that are always true — minimum contrast ratios, that focus is always visible, that nothing relies on color alone, that motion respects prefers-reduced-motion. The per-component note covers what is specific: the keyboard map for a menu, the focus-trap behaviour of a dialog, the live-region behaviour of a toast. Writing the baseline once means each component page only has to document its exceptions, which keeps the notes short enough that people actually read them.

Do and don’t examples are the highest-leverage prose in the whole system, and the most commonly done badly. Two rules keep them useful: render them, do not describe them — a wrong button next to a right button teaches more than a paragraph — and pair them so the contrast is explicit. A lone “don’t” with no matching “do” leaves the reader knowing what to avoid but not what to reach for instead.

How do you keep the docs current as the system evolves?

Documentation is only trusted if it is right, and it is only right if updating it is part of the change, not a chore that comes after. A few practices keep the gap from opening:

• Docs in the same pull request. A component change that does not touch its docs should fail review. Bundle them so they cannot drift.
• Status labels on everything. Mark each component draft, beta, stable, or deprecated. A deprecated component stays documented — with its replacement and a migration note — until it is actually removed.
• A real changelog. Record what changed, when, and whether it is a breaking change, so a consumer can decide whether to upgrade.
• A named owner per component. “The design system” owns nothing; a person owns the button. Put the name on the page.
• A standing review cadence. Once a quarter, walk the component list, retire what is dead, and reconcile the docs against what actually shipped.

Generate what you can — props tables from types, token values from the source — so the machine-checkable parts never disagree with the code. Reserve human writing for the judgment: usage, do/don’t, and the migration story. The split keeps the maintenance burden on the parts that genuinely need a person.

How do you make the documentation findable?

The best-written design system docs are worthless if a developer cannot find them at the moment they are choosing a component. Discoverability is a documentation feature, not an afterthought. The cheapest fix is a memorable shortcut everyone can type from the address bar: a go link that always points at the docs home, no matter how often the underlying URL moves.

In practice that means claiming a couple of b/ slugs for the system and putting them in your onboarding doc: b/design for the documentation home, b/tokens for the token reference, b/figma for the source library. When the docs site gets re-platformed or the Figma file is reorganised, you update the slug once and every link in every old Slack thread keeps working — the shortcut your team has in muscle memory never breaks.

The other half of findability is the working state — the things that are not stable docs yet: proposed components, open token questions, the deprecation backlog, the migration tracker. That does not belong in the polished reference, but it does need a home. A board behind a slug like b/design-wip works well here: a kanban of in-flight components, a notes panel for decisions, and live embeds of the Figma file, all on one canvas next to the design source. It sits beside the formal docs rather than replacing them — the board is where the system is being decided, the docs are where the decisions land.

Match the surface to the reader

Engineers want the props table and a copyable import. Designers want the Figma component and the anatomy. Product and content people want the usage and content guidance. You do not need separate sites for each, but a clear path from the slug to the right section for each reader means nobody has to scroll past the parts that are not theirs. The slug gets them to the door; the page structure gets them to the room.

Where to start

You do not need the whole system documented before any of it is useful. Ship a thin slice and widen it:

1. Document the foundations first — tokens, type scale, color — because every component references them.
2. Document your ten most-used components with the full per-component checklist. Leave the long tail as stubs with a status label.
3. Write the getting-started and contribution pages so new work follows the same shape.
4. Claim the b/design and b/tokens slugs and stand up a board for the work in progress.
5. Put the slugs in onboarding and set a quarterly review so the docs stay honest.

Documentation is what makes a design system a shared asset rather than a folder of components only its authors understand. For how teams run the whole system — the library, the slugs, and the working board together — see the design systems use case, and read what go links are if the shortcut idea is new to your team.