Design Systems · Labs · 4 min read
Write a component doc page
A guided lab: write the doc page for one component, in the order people ask their questions. Collect the real questions, fill in a template, write usage rules with reasons, and test the page with a designer and an engineer who have never used the component. About two hours.
A doc page is read by someone in a hurry, halfway through a screen, with one question. If the answer is in the first screen, they use the component correctly. If it's in paragraph six, they guess, or ask in chat, or build their own. You'll write one page for one component, starting from the questions people really ask, and test it on two people who've never used it.
What you'll do:
- Collect the real questions people ask about one component
- Fill in a doc page template, top to bottom
- Write usage rules with a reason and an example
- Test the page with a designer and an engineer
You'll need: one component from your system (or Harbour's Notice, as in the example), a place to write (your docs tool, a Markdown file or a Figma page), a chat or ticket history to search, about two hours.
1. Collect the questions
Before writing, search your team chat, tickets and design reviews for the component's name. Write down every question you find, word for word. For a notice, they sound like:
- "Can I use this for a form error?"
- "Can it have a button?"
- "Which one do I use for 'sailing cancelled'?"
- "Does a screen reader read it out?"
Sort them by how often they come up. The top three go in the first screen of the page.
2. Use a template, in the order people ask
- Notice
- Usage
- Properties
- Accessibility
- Content
- Changelog
NoticeStable · since 3.2.0Figma · React · Storybook
Tells people about something that affects the whole page or task, without stopping them.
When to use it, and when not
Dialog).Properties
tone: info, success, warning, danger · title: text · dismissible: boolean · action: slot, one link or button at most.
Accessibility
- Rendered with
role="status";dangernotices that appear after an action userole="alert". - The tone is in words as well as colour: the title says what happened.
- Text 15.58:1 on
sand.50; the coral edge is decoration, not the message.
The GOV.UK Design System's component pages open with when to use the component, then how it works, then the research behind it (GOV.UK Design System, Button). The order matters more than the exact headings. Copy this template:
# Component name [status · since version] [Figma] [Code] [Storybook]
One sentence: what it does for the person using the product.
[Live example, default settings]
## When to use it
## When not to use it (and what to use instead)
## How it works
Variants and properties, each with an example
## Accessibility
Role, keyboard, what is announced, contrast
## Content
How to write the text inside it
## Research and decisions
## Changelog
Keep the first screen to the name, the status, the one sentence, the example and "when to use / when not". That's what most visitors need.
3. Write usage rules people follow
Each rule needs three things:
- The rule, as something checkable: "One notice per page", not "use sparingly".
- The reason, in one line: "Two notices compete, and people read neither."
- An example: a do and a don't, as images or live examples.
For "when not to use it", always name the alternative. "Don't use for errors in one field: use the field's error message" is useful. "Don't use for errors" leaves the reader stuck.
4. Write the accessibility section for both readers
Designers need to know what they must provide; engineers need to know what the component does. For a notice:
- Role:
role="status"for information that arrives without interrupting,role="alert"only for important, time-sensitive messages. The APG alert pattern describes alerts as important and potentially time-sensitive, and warns that frequent interruptions inhibit usability for people with visual and cognitive disabilities (WAI-ARIA APG, Alert). - Not colour alone: the tone has to be clear from the words too (W3C, Understanding 1.4.1).
- Contrast: the measured ratio of the text on its background, written down. Harbour's
ink.900onsand.50is 15.58:1.
5. Write the properties and the changelog
List every property with its values and default, the same names as in Figma and in code (see Design a component with variants in Figma). If you have Storybook, link the story or embed its controls instead of copying the table by hand, so it can't drift (see Storybook and living documentation).
The changelog at the bottom answers "did this change since I last used it?" A version, a date, a line each.
6. Test the page
Give the page to one designer and one engineer who haven't used the component. Give each a task:
- Designer: "Add a notice to this screen saying the 08:40 sailing is delayed."
- Engineer: "Implement it, and tell me what a screen reader will say."
Watch, don't help. Every time they scroll looking for something, or ask you, note the question. That question is a missing line, or a line in the wrong place.
7. Check your work
Reflection questions: Which question was asked most, and was it already answered somewhere nobody looked? What would you remove from the page if it could only be half as long?
Related
Component docs people use · Storybook and living documentation · Content and voice in the system · Documenting motion in a design system · Accessible components · Component doc template