Say hola0404 764 825

Showing the site for Tradies

Showing the site for Service businesses

Showing the site for Small business

Showing the site for Medium business

Showing the site for Enterprise

How we helpHow we helpHow we helpHow we helpHow we help

← InsightsUX/UI & Design Systems Guides · Guide · 2 min read

Design system documentation: how to write it

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

Cover image for the article: Design system documentation: how to write it

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?

Request a call

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

Component documentation pageTemplate
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.

Your answers stay in this browser only.

Where docs live

Documentation optionsInfographic
  • Ease to maintain
  • Developer friendliness
Figma pages only
42
Storybook
35
Zeroheight or Supernova
44
Custom docs website
25
Notion or Confluence
43

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

Get your copy

Tell us who it is for and your copy starts straight away.

We record your name, email and which guide you downloaded so Nella can follow up about it. This device also remembers your details so we don’t ask again; ‘Not you?’ clears them. See our privacy policy.

Let’s figure it out together.

Request a call