Marcus Andrey Study
Ler em português Library

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.

The 08:40 sailing is delayed by 30 minutesCheck in closes at 09:00. Your seat is kept.

When to use it, and when not

Use itFor news about a booking or a sailing that people should see before they act.
Don'tFor errors in one field (use the field's error text) or for confirmations that need an answer (use Dialog).

Properties

tone: info, success, warning, danger · title: text · dismissible: boolean · action: slot, one link or button at most.

Accessibility

  • Rendered with role="status"; danger notices that appear after an action use role="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.

Content

Title: what happened, in under 60 characters. Body: what it means for them and what to do. No "Oops".

Changelog

3.6.0 · action slot added · 3.2.0 · first release, replaces Banner.

A filled-in doc page for one Harbour component, top to bottom in the order people ask: what is it, can I use it here, how do I set it, is it accessible, what do I write, what changed. Everything a designer needs in the first screen, the detail below.Example: Marcus Andrey, CC BY 4.0. Section order inspired by the GOV.UK Design System component pages.

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.900 on sand.50 is 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?

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

Saved only on this device.

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