By Mehdi HassanWhat should design system documentation include?
Design system documentation should include usage guidance, content guidance and technical reference for each component, plus a short set of foundations: tokens, typography, spacing, voice and accessibility. Usage guidance answers whether to use this component here. Content guidance answers what to write in it. Technical reference answers how to build it.
Most documentation gets the third part right and skips the first two. That's why teams with a full Storybook still ship three different confirmation dialogs with three different button labels. We approach docs copy-first, because the decisions people get wrong are usually about words and judgment, not padding values. For how documentation fits a startup's wider system, see our guide to design systems for startups.
Layer | Answers | Examples | Often missing? |
|---|---|---|---|
Usage | Should I use this here? | When to use, when not to, alternatives | Yes |
Content | What do I write in it? | Label rules, tone, error message patterns | Almost always |
Visual | What does it look like in each case? | Variants, states, do and don't images | Sometimes |
Technical | How do I build it? | Props, tokens, code examples | Rarely |
Accessibility | How does everyone use it? | Keyboard, focus, screen reader labels | Often |
What goes on a component documentation page?
A component documentation page should answer the questions people ask in order: what is it, should I use it, how do I configure it, what do I write in it, and what can go wrong. Keep the same structure on every page so readers know where to look.
- One-line definition. What the component is for, in plain words.
- When to use it. Two or three concrete situations.
- When not to use it, and what to use instead. This is the most valuable section on the page.
- Anatomy. A labelled image of its parts.
- Variants and states. Each option, with when to choose it.
- Content guidelines. Rules and examples for every piece of text in it.
- Do and don't. Paired visual examples.
- Accessibility. Keyboard behavior, focus, labels.
- Props and code. Linked from Storybook or the code docs, matching the Figma properties.
The props section should mirror the Figma component's properties exactly, as described in our guide to building a Figma component library. If the names match, you only need to document them once.
How do you write usage guidelines people follow?
Write usage guidelines as decisions, not descriptions. A description says a modal is an overlay that focuses attention. A decision says use a modal only when the user must respond before continuing, and use an inline message or a side panel otherwise. The second one changes what people build.
- Use imperatives. Use a toast for confirmations that need no action. Don't use a toast for errors.
- Always give the alternative. Every don't should point at the right component.
- Be specific about limits. Use no more than one primary button per view.
- Explain the reason in one clause. Because the user can't undo it, ask for confirmation.
- Show, then tell. A do and don't image pair beats a paragraph.
What are content guidelines in a design system?
Content guidelines are the rules for the words inside components: button labels, form labels and helper text, error messages, empty states, confirmations and notifications. They're part of the design system because inconsistent words make a product feel inconsistent even when every pixel matches.
Element | Rule | Do | Don't |
|---|---|---|---|
Button label | Verb plus object, sentence case | Save changes | Submit, OK |
Destructive button | Name what gets deleted | Delete project | Yes |
Error message | What happened, then how to fix it | Card declined. Try another card. | Error 402 |
Empty state | What goes here, then one action | No invoices yet. Create your first invoice. | Nothing to show |
Helper text | Answer the question before it's asked | We'll only use this for receipts. | Enter email |
Confirmation toast | Past tense, specific | Invite sent to Sam | Success |
Add a short voice section to your foundations: three or four traits, each with a this, not that example. Products with AI features need extra rules for how the assistant talks and admits uncertainty, which our guide to AI chat interface design covers. Where brand voice is already defined in brand guidelines, link to it rather than rewriting it; our comparison of brand guidelines vs a design system explains where each rule belongs.
Hypothetical example: documenting a confirmation dialog
For example, suppose a team keeps shipping delete dialogs that say Are you sure? with OK and Cancel buttons. A copy-first doc page for the dialog would say: use a confirmation dialog only for actions that can't be undone; for anything undoable, act immediately and show a toast with an Undo action.
Content rules would follow. The title names the action and object (Delete this project?). The body says what will be lost, in one sentence. The destructive button repeats the verb and object (Delete project), and the cancel button says Cancel. A do and don't pair shows the vague and specific versions side by side. After that page exists, the team stops debating each dialog, because the decisions are already written.
Where should design system documentation live?
Design system documentation should live as close to where people work as possible: short descriptions inside Figma components, usage and props in Storybook or a code docs page, and foundations on one shared page. Link each to the others so nobody maintains the same rule twice.
Location | Good for | Limitations |
|---|---|---|
Figma component descriptions | One-line usage notes designers see when inserting | Short, no rich examples |
Figma documentation pages | Do and don't visuals, anatomy | Engineers rarely open them |
Storybook docs | Props, live states, code examples | Designers and PMs rarely open it |
Notion or a wiki | Foundations, voice, process | Drifts from both design and code |
A dedicated docs site | Everything in one place, public or internal | Real effort to build and maintain |
For a small team, Figma descriptions plus Storybook docs plus one foundations page is enough. A dedicated docs site makes sense when several teams or external partners use the system, and the design principles in our guide to developer documentation site design apply to internal docs too.
How do you keep design system documentation up to date?
Keep documentation current by making doc updates part of the definition of done for any component change. If a pull request changes a component's props or behavior, it changes the docs in the same pull request. If a Figma library update changes a component, the change note says what to update.
Pros
- Fewer repeated questions in Slack about which component to use
- New designers and engineers ship consistent work in their first weeks
- Content rules make the product sound like one company
- Accessibility notes prevent the same keyboard bugs reappearing
Cons
- Docs written once and never updated become actively misleading
- Long docs don't get read, so every page needs editing down
- Someone has to own writing, not just design and code
- Visual examples need updating whenever the component changes
Start small: document the five components people get wrong most often, plus button labels and error messages. Expand only when real questions show a gap. Tokens deserve a short page of their own, linking to the full explanation of design tokens.
Who should write design system documentation?
The person who decided how a component should be used should write its usage and content guidance, ideally with a writer editing it. Engineers write the props and code examples. When one team owns words, design and code, as ours does, the three layers come out consistent because they come from the same decisions.
If you want your brand foundations and core screens rethought before you document them, our brand and design sprint is $3,000, fixed: a brand refresh or redesign plus 10 website or product explorations, delivered as Figma files. You can see what's included on our pricing.
