Design Systems · Step 6 · 6 min read
Component docs people use
Most design system docs are written for the people who built the system, not for the person with a deadline. What a component doc page should answer, in which order, where each part lives (doc site, Figma, Storybook), how the best public systems structure theirs, and how to keep docs true.
Nobody reads a doc page from the top. They arrive with one question and leave as soon as it's answered. "Can I use this here?" "Which one do I pick?" "Is this accessible?" A good doc page is organised around those questions, in the order people ask them. A page organised around how the component was built answers questions nobody asked, and hides the one that brought them there.
What you'll be able to do after reading:
- List the questions a component doc page must answer, in order
- Write "when to use" and "when not to use" that settle decisions
- Decide what lives on the doc site, in Figma and in Storybook
- Keep docs honest with an owner, a status and a review date
1. The questions people arrive with
Who reads the Button page, and why:
- A designer mid-flow: "Should this be a button or a link? Which variant?"
- A developer building it: "What are the props? What's the import? What does it do with a long label?"
- A reviewer or tester: "Is it accessible? What's the keyboard behaviour?"
- A product manager: "Is this stable, or will it change under us?"
So the page has to answer, in roughly this order: what is it, should I use it here, how do I use it well, how do I build it, is it accessible, and can I trust it. Everything else is optional.
2. A page, filled in
Harbour › Components › Button
Button Stable 3.0.0
Use a button to start an action: book, save, check in, cancel. To go to another page, use a link.
- Usage
- Design
- Code
- Accessibility
- Changelog
One primary per view. The second action is secondary.
Two primaries compete, and people stop at the button, not the decision.
Accessibility
- Built on the native
<button>: keyboard and screen readers work without extra code - At least 44 px tall in default size; compact is 32 px, for the desktop console only
- Contrast measured: primary 6.35:1 (light), 5.32:1 (dark); danger 5.14:1 (light)
- Disabled buttons can't be focused: say why the action isn't available, next to it
Owner: Harbour teamFigma: Harbour Components › ButtonStorybook: Button · 8 storiesCode Connect: connectedLast reviewed 6 Oct 2026
What each part does on Harbour's Button page:
- One sentence of purpose under the title, including what to use instead: "To go to another page, use a link."
- A status and a version, next to the title. "Stable 3.0.0" answers the product manager in two words.
- A live example at the top, in Harbour's real colours, in light and dark.
- When to use, when not to use. Most of the value is in the second list, because it points at the alternative.
- Do and don't, with real Tidewater content, not "Lorem ipsum". One picture of two competing primaries settles more arguments than a paragraph.
- Accessibility: what the component handles for you, what you still have to do, and the measured contrast.
- A footer of links to the same component in Figma, Storybook and code, with the owner and the last review date.
Writing this page yourself is the lab Write a component doc page.
3. How public systems do it
Two well-documented systems, two structures worth copying:
- GOV.UK Design System puts each component on one long page: "When to use this component", "How it works", then "Research on this component", "Recent changes" and "Help improve this component" (GOV.UK Design System, Button). The research section is rare and valuable: it tells you what was tested, with whom, so you know how much to trust the guidance.
- IBM Carbon splits each component into tabs: Guidelines, Specifications, Code and Accessibility (Carbon, Button). Tabs suit a big audience where designers and developers want different things from the same page.
Neither is right for everyone. A small system like Harbour starts with one page and adds tabs when the page gets too long to scan. What both have in common is the order: when and why first, how second, the details last.
4. Where each part lives
Docs don't have to live in one place, but each fact should live in one place, with links from the others:
| Where | What lives there | Why there |
|---|---|---|
| Doc site | Purpose, when to use, do and don't, content rules, accessibility, status | Everyone can read it, no tool or seat needed |
| Figma | A short component description and a link to the doc page | Designers see it in the assets panel, while choosing |
| Storybook | Every state, the props table, live examples | Generated from code, so it can't go out of date (Storybook and living documentation) |
| Dev Mode | The real code snippet, through Code Connect | Developers see it while inspecting (Code Connect and the design-code bridge) |
| Changelog | What changed, per version | One history for the whole system (Versioning and releases) |
The usual failure is the opposite: the same usage rule written in four places, each slightly different, and nobody knows which one is current.
5. Keeping docs true
- An owner per page, by name or by team, shown on the page.
- A "last reviewed" date. A page reviewed three years ago warns the reader to check.
- Docs change in the same release as the component. A new prop without its doc line isn't released.
- A way to ask and to complain, on the page. GOV.UK's "Help improve this component" is the model. Brad Frost's sample question for a system survey is worth borrowing too: "On a scale from one to five, how useful is the pattern documentation? Any suggestions?" (Brad Frost, Atomic Design, chapter 5).
- Look at what people search for on the doc site. A search with no result is a page you haven't written.
Motion and images need the same treatment: see Documenting motion in a design system and An image style guide in your design system.
6. Common mistakes
- Pages that start with anatomy and specs, and get to "when to use" at the bottom.
- "When not to use" missing, or without an alternative.
- Do and don't examples with placeholder text.
- The same rule in the doc site, Figma and a slide deck, all slightly different.
- No status, so people can't tell a stable component from an experiment.
- Docs written once at launch and never reviewed.
7. Vocabulary
| Term | Meaning |
|---|---|
| Doc page | The page that explains one component: purpose, usage, code, accessibility |
| Usage guidance | When to use, when not to, and how to use it well |
| Do and don't | A pair of examples that shows the right and the wrong use |
| Status | How settled a component is: experimental, stable, deprecated |
| Single source | Each fact written in one place, linked from the others |
8. Try it (no tools needed)
- Pick one component in your product and write the one question a designer would ask about it today.
- Open its doc page, or ask where it is. Time how long it takes to find the answer.
- Write the "when not to use" line that would have answered it, with the alternative.
Reflection questions: Which part of your team's docs is written in more than one place? Who would notice if a doc page was wrong?
9. If you already practise
- Reorder your most-visited doc pages so "when to use" comes before specs.
- Add a status, an owner and a last-reviewed date to every page.
- Add a research section to one component, even if it's two lines on what you tested.
- Review your doc site's searches with no results every month.
Checklist
Learn more
- GOV.UK Design System, Button
- Carbon Design System, Button
- Brad Frost, Atomic Design, chapter 5: Maintaining design systems
Books, courses and videos to go deeper
- Design SystemsAlla KholmatovaBook · Smashing Magazine, 2017 (Amazon)
- Expressive Design SystemsYesenia Perez-CruzBook · A Book Apart, 2019 (Amazon)
Book links go to Amazon. As an Amazon Associate I earn from qualifying purchases, at no extra cost to you.
Related
Write a component doc page · Storybook and living documentation · Content and voice in the system · Documenting motion in a design system · What a design system is · Component doc template