Design system documentation: how to write it
Design system documentation that designers and developers use: what, when and how for every component.

Many design systems fail not because the components are poor but because nobody can find, understand or trust them. Documentation is the bridge between the system and the people using it.
Good documentation answers three questions for every component: what is it, when do I use it, and how do I use it correctly?
What to document
- Foundations: colour, type, spacing, grid, icons, motion
- Design tokens: names, values and usage
- Components: purpose, anatomy, variants, states, do and don’t
- Patterns: forms, navigation, tables, empty states
- Content: voice, tone and writing guidelines
- Accessibility: requirements for each component
- Contribution: how to propose changes
Document every component the same way
- What it is and the problem it solves.
- Alternatives for other situations.
- The parts that make up the component.
- Sizes, styles, hover, focus, disabled, error, loading.
- Examples of correct and incorrect use.
- Keyboard, screen reader and contrast requirements.
- Figma component and code reference.
Spam check by Cloudflare
Where docs live
- Ease to maintain
- Developer friendliness
Our view, scored out of 5. Many teams combine a docs site with Storybook.
Keep it alive
- Assign an owner and a regular review
- Publish a changelog
- Collect questions and turn them into docs
- Show usage examples from real products
- Measure adoption across products
How this looks in your industry
Illustrative examples
Closest to you
B2B
A fintech product team
The problem: Developers kept asking which button to use.
What changed: Added “when to use” guidance for every component.
Result: Fewer questions and more consistent screens.
Closest to you
Education
A university digital team
The problem: Docs lived only in Figma.
What changed: Published a docs site linked to Storybook.
Result: Developers adopted the system.
Closest to you
Government
A state agency
The problem: Accessibility rules were inconsistent.
What changed: Added accessibility notes to every component page.
Result: Fewer accessibility issues in new work.
Common mistakes
- Documenting only how components look
- No guidance on when to use each component
- Docs out of sync with code
- No owner or changelog
- Hiding docs where developers don’t look
Key takeaways
- Document what, when and how
- Use one template for every component
- Keep design and code in sync
- Assign an owner and publish changes
Frequently asked questions
How much documentation is enough?
Enough that a new designer or developer can use a component correctly without asking.
Should developers write docs too?
Yes. Code usage, props and accessibility notes are best written with developers.
How long does documentation take?
Expect documentation to take as long as building many of the components themselves.
Your next step
Make your design system easy to use
We build and document design systems that product teams adopt and trust.
Explore design systems