Marcus Andrey Study
Ler em português Library

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.

An open ring binder lying on its covers, seven printed pages on three rings. Move the pointer across it and the pages turn with you, the one under the pointer lifting off the pile and standing up toward it. That's this step: documentation is only worth what people find in it, so it has to open at the page they need. This step has three lessons: component docs people use, bringing teams onto the system, and measuring adoption.Illustration: Marcus Andrey, drawn with Hairline (MIT, Lucas Marques).

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
Book sailingView timetableCancel booking

When to use

  • To submit a form or confirm a step
  • Primary: the one main action of a view
  • Danger: actions that can't be undone, always with a confirmation

When not to use

  • To navigate: use a link, even if it looks like a button
  • For more than three actions in a row: use a menu
  • To toggle a setting on and off: use a switch
Do
Book sailingView timetable

One primary per view. The second action is secondary.

Don't
Book sailingView timetable

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

A filled-in doc page for Harbour's Button, the Usage tab. It answers the questions people arrive with, in the order they ask them: what is this, should I use it here, how do I use it well, and is it safe. The footer links the same component in Figma, Storybook and code, so the page is the meeting point, not a fourth copy.

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)

  1. Pick one component in your product and write the one question a designer would ask about it today.
  2. Open its doc page, or ask where it is. Time how long it takes to find the answer.
  3. 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

Books, courses and videos to go deeper

Book links go to Amazon. As an Amazon Associate I earn from qualifying purchases, at no extra cost to you.

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

Saved only on this device.

↑ ↓ to move · Enter to open · Esc to close