Marcus Andrey Study
Ler em português Library

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.

1Name, status

Name, status and version, with links to Figma, code and Storybook.

"Stable 3.0.0"
2Purpose

One sentence of what it does, and what to use instead.

"To go to a page, use a link"
3Example

A live example with default settings, in light and dark.

Real content, never Lorem ipsum
4When, when not

Where it fits, and where it doesn't, naming the alternative.

Most value is in "not"
5How it works

Variants and properties, linked from Storybook, not copied.

Same names as Figma and code
6Accessibility

Role, keyboard, what is announced and the measured contrast.

For designers and engineers
7Content

How to write the text inside it, with a real example.

What changed, what to do
8Research, log

What was tested and the changelog, then owner and review date.

"Last reviewed …"
The parts of a component page in the order people ask; the first four fill the first screen.

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

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. 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]
Source
Component page structure: GOV.UK Design System (when to use, how it works, research, recent changes) and IBM Carbon (Guidelines, Specifications, Code, Accessibility tabs). Alert pattern: W3C WAI-ARIA Authoring Practices Guide. Documentation survey question: Brad Frost, Atomic Design, chapter 5

"See on Amazon" links are affiliate links. As an Amazon Associate I earn from qualifying purchases, at no extra cost to you.

Saved only on this device.

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