Design Systems · Lesson 11 / 13
Documentation
How to write design system documentation people actually use: audiences, site structure, a complete component page template, writing guidelines, content standards, tools, and measuring whether docs work.
4 min read · 5 quiz questions
Why documentation makes or breaks a system
A component without documentation is a guess. People will use it in the wrong places, combine it in odd ways, or rebuild it because they didn't know it existed. Documentation turns a library of parts into a shared language and a set of decisions everyone can follow.
Good documentation answers questions before they're asked — so the design system team isn't answering the same Slack message twenty times a week.
Know your audiences
| Audience | What they need |
|---|---|
| Designers | When to use what, visual examples, do's and don'ts, Figma usage |
| Developers | Install instructions, code examples, props/API, accessibility behaviour |
| Product managers | What exists, what's planned, how to request something |
| Content writers | Voice and tone, terminology, how to write labels and errors |
| New team members | Getting started, principles, where to find help |
Structure of a documentation site
- Getting started — for designers and for developers.
- Principles — the system's design principles.
- Foundations — colour, typography, spacing, layout, elevation, motion, iconography — with tokens.
- Components — one page each.
- Patterns — forms, empty states, errors, navigation…
- Content — voice and tone, grammar, terminology.
- Resources — Figma library links, code packages, templates.
- Contributing, roadmap and changelog — how the system evolves.
- Search — essential once there are more than a few pages.
A component page template
Using the same structure on every component page makes docs predictable and easy to scan:
- 1Name and one-line description — what it is and its main purpose.
- 2Live example — interactive, with real content.
- 3When to use / when not to use — and what to use instead.
- 4Anatomy — numbered diagram of the parts.
- 5Variants, sizes and states — each with a short explanation.
- 6Behaviour — interactions, responsive behaviour, content limits (wrapping, truncation).
- 7Content guidelines — how to write labels and messages for this component.
- 8Do's and don'ts — paired visual examples.
- 9Accessibility — keyboard behaviour, focus, ARIA, what product teams must provide.
- 10Code — import, usage example, props table.
- 11Related components and patterns.
- 12Status and changelog — e.g. Stable, Beta, Deprecated.
Button
Buttons let people take actions with a single click or tap.
When to use
✓ To submit a form, start a task, or confirm a decision.
✗ To navigate to another page — use a Link instead.
Props
| Prop | Type | Default |
|----------|---------------------------------------|-----------|
| variant | "primary" | "secondary" | "danger" | "primary" |
| size | "sm" | "md" | "lg" | "md" |
| loading | boolean | false |Writing guidelines for docs
Do
- Write for scanning: short headings, short paragraphs, lists.
- Lead with the most important guidance.
- Use real content in examples, not lorem ipsum.
- Explain the why behind rules so people can apply them to new cases.
- Use consistent terms — the same names as in Figma and code.
Don't
- Write long essays nobody reads.
- Show only perfect examples — show edge cases and limits.
- Use internal jargon without explanation.
- Let docs go out of date — wrong docs are worse than none.
- Hide docs in many places (some in Notion, some in Figma, some in a wiki).
Content standards
Many design systems include guidelines for the words in the interface, because inconsistent language is as confusing as inconsistent visuals:
- Voice and tone — e.g. clear, friendly, confident; more serious in errors and payment flows.
- Capitalisation — sentence case for buttons and headings is common and easier to read.
- Terminology — a word list: "Sign in" not "Log in"; "Delete" vs "Remove" (delete = gone, remove = taken out of a group).
- Formats — dates, times, numbers, currency, phone numbers per locale.
- Patterns for messages — error, success, empty state, confirmation templates.
- Inclusive language — avoid idioms, gendered terms and ableist language.
Tools for documentation
| Tool | Typical use |
|---|---|
| Storybook | Interactive code component examples and props; often the developer side of the docs |
| Zeroheight, Supernova, Knapsack | Design system documentation sites that connect Figma and code |
| Custom site (e.g. Next.js, Docusaurus) | Full control; live components; good for public systems |
| Notion / Confluence | Quick start for small teams; harder to keep in sync with components |
| Figma | Component descriptions and annotated pages inside the library |
The best tool is the one your team will keep updated. Linking docs from the Figma component description and from the code component's comments puts guidance where people already are.
Is the documentation working?
- Track the questions people ask the system team — repeated questions point to missing docs.
- Look at search terms with no results.
- Check page analytics for the most and least viewed pages.
- Watch misuse in products — a component used against guidance means the guidance isn't clear or isn't found.
- Run short usability tests of the docs with new team members.
Key takeaways
- Documentation turns components into shared decisions and reduces repeated questions.
- Write for different audiences: designers, developers, PMs, writers and newcomers.
- Use one consistent template for every component page, including when not to use it and accessibility.
- Include content standards: voice, capitalisation, terminology and message patterns.
- Measure doc usefulness through questions, search, analytics and misuse — and keep docs current.
Exercise
Write a component page
- Choose a component you designed earlier (e.g. a text field).
- Write the page using the 12-part template.
- Create two pairs of do/don't examples.
- Write the accessibility section with keyboard behaviour.
- Ask a colleague to use only your page to design a form, and note what they ask you.
Test yourself
Documentation quiz
5 questions. Score 70% or more to complete the lesson.
