Component Documentation
Date: 2026-08-16
The page that decides whether a component gets used correctly, used wrongly, or rebuilt from scratch. Its job is not to describe the component — it’s to answer the four questions someone has at the moment they reach for it.
Component documentation is the reference page for a single component: what it’s for, how to use it, every state rendered, and when not to use it.
The four questions, in the order people ask them:
1 is this the component I want?
2 what's the minimum code to use it?
3 what can I change about it?
4 what happens in <edge case>?
A page that answers 3 but not 1 is why components get rebuilt. Someone couldn’t tell whether Callout or Banner was theirs, gave up, and wrote a third.
What the page needs
A one-line purpose, and a “use this when”. The most-skipped and most-valuable section:
Banner page-level, dismissible, about
the whole page or session
Callout inline, permanent, about the
content beside it
Toast transient, triggered by an
action the user just took
Three similar components become unambiguous in nine lines. Without this, naming alone can’t distinguish them.
The smallest working example, copy-pasteable, that runs:
<Banner tone="info">Delivery is delayed.</Banner>A props table — name, type, default, description. Generated from types where possible, because a hand-written table drifts within two releases.
Every state, rendered. Not described — rendered, on the page, where a missing one is visible:
default · hover · focus · active
disabled · loading · error
empty · long content · no image
That grid is also the visual regression test, which is why generating it from the same source pays twice — Component States.
The variant matrix, rendered. Every combination of the axes, in a grid. Bugs live in the combinations nobody looks at, and the grid makes them a glance rather than an audit — Variants and Modifiers.
Accessibility notes. What the component handles, and what the consumer still must do:
HANDLED role, aria-expanded, focus
trap, Escape to close
YOURS an accessible name,
heading level, focus
return target
When not to use it. The section that prevents misuse most effectively, and the one almost nobody writes.
Co-locate it with the code
Documentation in a separate wiki is documentation that describes last quarter’s component.
/components/Banner/
Banner.tsx
Banner.test.tsx
Banner.stories.tsx ← the docs
Banner.mdx
In the same folder, in the same pull request, reviewed together. A prop added without a docs change should fail review the way an untested change does — Design System Governance.
Generate what can be generated
FROM TYPES prop names, types,
required/optional, defaults
FROM STORIES every state, rendered
the variant matrix
visual regression baselines
BY HAND purpose
when to use / when not to
accessibility caveats
the migration note
Hand-write only what carries judgement. Anything derivable should be derived, because the derived parts are exactly the ones that drift silently.
Where it goes wrong
- Describing instead of showing. “Supports several sizes” versus three rendered buttons. The second is shorter and cannot be wrong
- No search. A component library nobody can search is a library where everything is rebuilt. Tag by problem — “notification”, “warning”, “alert” should all reach
Banner - Documenting the ideal. If the component has a known bug or an unsupported combination, say so. Undocumented limitations are discovered in production, and the discoverer forks
- No changelog per component. “What changed in this component and when” is the question during an upgrade, and a repo-wide changelog answers it badly — Design System Versioning
- Writing it once. Docs written at build time and never revisited describe a component that no longer exists, which is worse than no docs — people trust them.