Design system documentation people actually use
A six-block component page template, the writing rules behind it, where the pages should live, and the signals that tell you whether anyone reads them.
In 1997, Jakob Nielsen found that 79% of test users always scanned a new web page and only 16% read it word by word. Your docs site is not the exception. Readers arrive mid-task with one question, scan for the answer, and leave.
Design system documentation is the set of pages that tells designers and engineers when to use a component, how to configure it, and what it must never do. Documentation people actually use is organized around decisions: every component page answers "should I use this, which variant, and what breaks" before it explains anything else.
Key takeaways
- A useful component page has six blocks in a fixed order: usage, do and don't, anatomy, props, accessibility notes, and code.
- Generate props tables and live examples, and spend human writing time on usage guidance, which no tool can infer.
- Storybook can carry the engineering half of your docs, while platforms such as zeroheight and Supernova add editorial pages and Figma content on top.
- Docs now have a second reader: AI coding agents, which read component guidance through MCP servers.
- The best evidence that docs work is behavioral: fewer repeat questions, fewer forked components, and faster first correct use.
What belongs on a component page?
Most docs sites are either a gallery with no guidance or a wall of prose. The fix is a fixed template, so readers learn where answers live and writers can see what is missing. Call it the six-block component page.
| Block | Answers | Primary reader | Written or generated |
|---|---|---|---|
| Usage | When should I use this, and what instead? | Designers, product leads | Written |
| Do and don't | What does correct use look like next to a common mistake? | Designers | Written, with real screenshots |
| Anatomy | What are the named parts, and which are optional? | Both | Drawn once, labeled with code names |
| Props | Which options exist, with types and defaults? | Engineers | Generated from types |
| Accessibility notes | What are the keyboard path, focus behavior, and screen reader output? | Both | Written, then tested |
| Code | What does a correct, copyable example look like? | Engineers | Rendered live from stories |
Usage goes first because it answers the question most readers arrive with. Do and don't pairs should show the same content both ways, so the mistake is the only thing that changes. Anatomy labels should use the part names from the code (CardHeader, not "top area"), because that is the vocabulary engineers search for.
The GOV.UK Design System is a good public reference. Its Button page includes sections called "Recent changes" and "Help improve this component". Copy both: a per-component change log, and a link that turns readers into contributors.
How do you write guidelines people follow?
Usage guidance is the one block no tool can generate, so it is where your writing hours belong. Nielsen's study also tested rewrites of one site: a concise version improved measured usability by 58%, and a version that was concise, scannable, and objective improved it by 124%.
- Lead with the decision. Write "Use a Dialog for actions that block the page" before explaining what a Dialog is.
- Name the alternative every time, and link to it.
- Put conditions before instructions: "If the action deletes data, use the
destructivevariant." - Spell prop and variant names in code formatting, exactly as they appear in Figma and React.
- Show real content. Placeholder text hides truncation and localization problems.
Usage guidance is the one block no tool can generate, so it is where your writing hours belong.
Where should design system docs live?
As of October 2026 there are two realistic homes, and many teams use both.
Storybook. In Storybook 10.6, Autodocs builds a docs page for any component whose stories carry the autodocs tag: description, primary story, an interactive controls table, and the remaining stories. The accessibility addon runs axe-core checks on every story, though Storybook's own docs say automated tools catch up to 57% of WCAG issues, so accessibility notes still need a person.
Dedicated platforms. zeroheight now calls itself a design systems management platform and syncs content from Figma, Storybook, and code repositories. Supernova builds pages from blocks that embed Storybook canvases, render React code, show Figma frames, and list tokens, and its Supernova Agent drafts guidelines for people to review. Knapsack has moved furthest from pure documentation: its site now describes a digital production platform for enterprise teams that checks AI-generated output against your standards.
The bigger change is the second reader. Storybook's MCP server, in preview, has a docs toolset that lets agents list and read component documentation, and zeroheight and Supernova both offer MCP access for coding agents. Write usage rules as if an agent will follow them literally, because one will.
How do you keep documentation current?
Docs go stale when updating them is a separate task, so make the update part of the change.
- Generate the props table from TypeScript types.
- Render code examples from stories, so a renamed prop breaks the example visibly.
- Add "docs updated" to the definition of done for any pull request that changes a component's API or behavior.
- Keep a short change log at the bottom of each page.
- Give every page an owner and a review date.
How do you know if your docs work?
Page views tell you people arrived, not that they succeeded. Track behavior instead:
- Repeat questions. Tag support questions by component. Two identical questions in a month means a page is missing an answer.
- Searches with no results. Each one is a missing page or a missing synonym.
- Forks and detaches. When a team rebuilds a component, its usage block often lacks their case.
- Time to first correct use. Ask a new hire to build a form from the docs alone, and note where they stop.
- Repeated review comments. Turn a misuse that review keeps catching into a do and don't pair.
Fix the page with the most repeat questions first. One rewritten usage block usually saves more time than a new section.
Where Pegasus fits
Pegasus ships documentation for each component in its Figma library, covering anatomy, properties, and layout and spacing, and its React code comes with Storybook stories and tests. That fills the anatomy, props, and code blocks of the six-block page from the first day.
Because Pegasus uses the same component names, variant structure, and tokens in Figma and in code, one page can describe one thing. The name a designer reads in the library is the name an engineer imports, with the same options.
Accessibility notes start ahead too: Pegasus is built to WCAG 2.1 AA, with keyboard paths, focus states, and contrast documented per component. The local MCP server exposes the component catalog (components, props, variants, and tokens) to MCP clients such as Claude Code and Cursor, so agents read the same structure your team reads.
What Pegasus can't write is usage guidance specific to your product: which of your flows use a dialog, which deserve a full page, and why. That block is yours.
FAQ
What should design system documentation include?
Each component page should include usage guidance (when to use it and what to use instead), do and don't examples, an anatomy diagram with named parts, a props table with types and defaults, accessibility notes covering keyboard, focus, and screen reader behavior, and a live code example. Foundation pages for tokens and typography sit alongside them.
Is Storybook enough for design system documentation?
Storybook covers the engineering half well. Autodocs generates props tables and live examples from your stories, and the accessibility addon runs automated checks. It is weaker at editorial guidance for designers, such as usage rules and do and don't pairs. Many teams pair Storybook with a written guidance layer or a platform that embeds stories next to that guidance.
How often should design system documentation be updated?
Update a component's docs in the same pull request that changes its API or behavior, so docs never lag a release. Beyond that, give every page an owner and a review date, and review the pages that generate repeat support questions first.
Who should write design system documentation?
The system team owns the template and the generated parts. Usage guidance works best when a designer and an engineer write it together, because each catches mistakes the other misses. Product teams should be able to suggest edits through a visible link on every page, the way the GOV.UK Design System invites feedback on each component.
Sources
- How Users Read on the Web, Nielsen Norman Group (1997)
- Button, GOV.UK Design System (2026)
- Automatic documentation and Storybook, Storybook docs (2026)
- Accessibility tests, Storybook docs (2026)
- Storybook MCP overview, Storybook docs (2026)
- zeroheight, design systems management platform (2026)
- Design system documentation, Supernova (2026)
- Knapsack, digital production platform (2026)
One system. In Figma and in code.
Pegasus ships 1,540 components, 470 tokens, matching React code, Storybook, and a local MCP server. $149, one-time.
Get the full system