Framework · Design systems · 4 min read
Component doc template
A component page in the order people ask: name and status, one sentence, a live example, when to use and when not, how it works, accessibility, content, research and changelog, with each fact kept in one place and linked from the others.
Name, status and version, with links to Figma, code and Storybook.
"Stable 3.0.0"One sentence of what it does, and what to use instead.
"To go to a page, use a link"A live example with default settings, in light and dark.
Real content, never Lorem ipsumWhere it fits, and where it doesn't, naming the alternative.
Most value is in "not"Variants and properties, linked from Storybook, not copied.
Same names as Figma and codeRole, keyboard, what is announced and the measured contrast.
For designers and engineersHow to write the text inside it, with a real example.
What changed, what to doWhat was tested and the changelog, then owner and review date.
"Last reviewed …"Use it when
- You're writing the page for a new component, or rewriting one nobody reads.
- The same question about a component keeps coming up in chat.
- A usage rule lives in four places, each slightly different, and nobody knows which is current.
How to use it
- Collect the real questions first. Search chat, tickets and design reviews for the component's name and write every question down word for word. Sort them by how often they come up. Output: the three questions the first screen must answer.
- Fill the first screen. Name, status and version, one sentence of purpose that names the alternative, a live example, then "when to use" and "when not to use". Output: a first screen a designer can act on without scrolling.
- Write every rule with a reason and an example. A checkable rule ("one notice per page"), one line of why, a do and a don't with real content. Every "don't" names what to use instead. Output: usage rules people follow.
- Write accessibility for both readers. Role, keyboard, what is announced, and the measured contrast: what the component does for you, and what you still have to do. Output: an accessibility section a tester can check against.
- Link the details instead of copying them. Properties come from Storybook or code, the snippet from Dev Mode, the history from the changelog. One fact, one home. Output: a page that can't drift from the component.
- Test the page with two people. Give one designer and one engineer who haven't used the component a task each. Every time they scroll looking for something, a line is missing or in the wrong place. Output: at least one line changed.
Worked example
Harbour's Notice page, after the team collected questions from chat. The top three were "Can I use this for a form error?", "Which one do I use for 'sailing cancelled'?" and "Does a screen reader read it out?".
| Part | What Harbour wrote |
|---|---|
| Title line | Notice · Stable 2.1.0 · links to Figma, code and Storybook |
| One sentence | Tells people about something on this page without stopping them. For an error in one field, use the field's error message |
| When to use | Information that affects the whole page: a delayed sailing, a changed timetable |
| When not to use | Errors in one field (field error message); actions that need an answer (dialog) |
| Accessibility | role="status"; role="alert" only for urgent, time-sensitive messages; tone clear from the words, not only the colour; text 15.58:1 on its background |
| Content | Lead with what changed and what to do: "The 08:40 sailing leaves at 09:10. Your booking still holds." |
| Footer | Owner, last reviewed date, "Help improve this component" link |
The engineer in the test found the role in under a minute. The designer asked where the cancelled-sailing example was, so it moved up into "when to use".
Watch out for
- Anatomy first. Pages that open with specs and get to "when to use" at the bottom answer the questions nobody asked first.
- "When not to use" without an alternative. "Don't use for errors" leaves the reader stuck. Say what to use.
- Placeholder examples. Do and don't with "Lorem ipsum" don't settle arguments. Use real product content.
- No owner, no date. A page with no owner and no review date ages silently. Show both, and update the page in the same release as the component.
Template
Copy this into your docs tool or a Markdown file and fill it in, top to bottom.
# Component name [status · since version] [Figma] [Code] [Storybook]
One sentence: what it does for the person using the product.
For ..., use ... instead.
[Live example, default settings, light and dark]
## When to use it
- ...
## When not to use it (and what to use instead)
- ... → use ...
## How it works
Variants and properties, each with an example (from Storybook, not copied)
## Accessibility
Role: ... Keyboard: ... Announced: ... Contrast: ...:1
The component handles: ... You still have to: ...
## Content
How to write the text inside it, with a real example
## Research and decisions
What was tested, with whom, and what changed
## Changelog
version · date · one line
Owner: ... Last reviewed: ... [Ask or report a problem]
- Design SystemsAlla KholmatovaBook · 2017 (Amazon)
- Expressive Design SystemsYesenia Perez-CruzBook · 2019 (Amazon)
- Atomic DesignBrad FrostBook · 2016 (Amazon)
- ButtonGOV.UK Design System (external site)
- ButtonCarbon (external site)
- Alert patternWAI-ARIA APG (external site)
- Maintaining design systemsAtomic Design, chapter 5 (external site)
"See on Amazon" links are affiliate links. As an Amazon Associate I earn from qualifying purchases, at no extra cost to you.