Writing component docs teams actually use

Most component documentation is written like an API reference and then expected to solve product adoption. That is too much pressure for a props table.

Reference matters, but teams use documentation when it helps them make a decision faster than asking another person.

Start with when to use it

The first section of a component page should answer when to use the component and when not to use it.

A modal, drawer, popover, and inline panel may all be able to show extra content. The documentation should explain the product distinction. Use a drawer for a focused side task that preserves page context. Use a modal for a blocking decision. Use an inline panel when the surrounding content remains part of the task.

That guidance prevents design review from becoming pattern arbitration every week.

Show real states

Docs that show only the perfect state are almost decorative.

A component page should show loading, empty, error, disabled, focused, long content, narrow viewport, and permission-limited states when those states exist. The states are where product bugs hide.

Examples should use believable content. "Lorem ipsum" does not reveal truncation, hierarchy, or awkward product language. Realistic examples make the component's constraints obvious.

Explain the accessibility contract

Accessibility docs should be specific enough that an engineer knows what the component handles and what the product team still owes.

For example: the drawer traps focus, closes on Escape, restores focus to the opener, and requires an accessible title. The component can enforce some of that. The product team still needs to pass a useful title and avoid putting unrelated workflows inside.

That distinction matters. Otherwise teams assume the component makes every usage accessible automatically.

Include copy and behavior notes

Many component decisions are not visual. Empty state copy, destructive confirmation language, loading timing, validation placement, and keyboard behavior shape the user experience as much as spacing.

Good docs include those rules near the component. If the delete confirmation component requires a resource name, say so. If a toast should not contain irreversible errors, document the alternative.

Make contribution normal

Documentation should explain how to request a new variant or propose a pattern. Without that path, teams either fork locally or overload existing props.

I like docs that say:

• If this use case appears once, solve it locally.
• If it appears twice, document a candidate pattern.
• If it appears across product areas, propose a system primitive.

That turns documentation into a living operating model instead of a museum.

The docs test

Give the page to someone who did not build the component. Ask them to choose between two similar patterns, implement one realistic state, and explain what to do if their case is missing.

If they can do that without Slack archaeology, the docs are useful. If not, the docs may be accurate but they are not doing enough work.

Docs should reduce interpretation

Component docs fail when they describe the component but not the decision. A team does not only need to know that a button has variants. They need to know which variant belongs to which consequence, what happens when the button is loading, how destructive actions are confirmed, and when a link should not pretend to be a button.

Useful docs reduce interpretation at the moment of use. They answer the small questions that otherwise become Slack threads, inconsistent implementations, and local workarounds.

When I write component docs, I try to imagine a tired product team using them at 5:30 PM. The docs should still help.

UseWhen should I reach for it?

Product situation, not just visual category.

StateWhat can happen to it?

Loading, focus, disabled, invalid, selected, and empty.

ContentWhat should it say?

Labels, error copy, destructive language, and length limits.

Start with use and non-use

The most important section is often "Do not use when." It prevents the component from becoming a universal hammer.

For example, a toast component might say:

Use when:

• confirming a lightweight background action
• showing a non-blocking success
• giving a short retry path

Do not use when:

• the user must correct a form field
• an irreversible action failed
• the message contains more than two lines
• the user needs to compare details

That second list protects the product. It tells teams when to choose an inline error, alert, dialog, or full-page recovery instead.

Document states as behavior

Screenshots of states are helpful, but the docs should say what the state means.

Disabled is not just gray. It means the action cannot be taken yet, and the reason should be visible nearby. Loading is not just a spinner. It means the component is waiting for a result, and the layout should not jump. Invalid is not just red. It means the user can recover.

I like state tables:

State	Meaning	Required behavior
Loading	Action is in progress	Preserve width, prevent duplicate submit
Disabled	Requirement missing	Explain nearby when not obvious
Invalid	Input needs correction	Keep value, show message, focus field

Tables like this make implementation and QA easier.

Include the wrong examples

Good docs show mistakes. Not to shame teams, but to make judgment concrete.

For a modal:

• Wrong: using a modal for a full settings workflow.
• Better: use a page or drawer when the user needs to compare information.

For a badge:

• Wrong: using color alone to indicate critical account state.
• Better: pair text with color and keep labels stable.

Wrong examples are fast teachers because they match the moments where teams misuse components.

Docs and contribution should meet

Component docs should include a path for gaps. If the component does not support a needed case, the docs should say how to request or contribute a variant.

That path can be simple:

1. Describe the product surface.
2. Explain why the current component fails.
3. Include a screenshot or prototype.
4. List required states.
5. Say whether the need is one-off or reusable.

Without that path, teams work around the system quietly. Then the system team discovers drift months later and treats it as disobedience. Often it was just a missing contribution loop.

The maintenance pass

Docs need review just like code. I would rather have fewer docs that stay true than a museum of outdated examples.

A useful quarterly pass:

• Remove examples that no longer match production.
• Add common misuse cases from product work.
• Update content rules from support or UX writing.
• Link to new component variants.
• Close or promote documented escape hatches.

Component docs are not a deliverable. They are product infrastructure. They help teams make the same decision the same way, especially when nobody from the design system team is in the room.

The minimum useful example set

For important components, I want examples that match product pressure, not only ideal presentation.

A minimum set:

• Default use.
• Dense use.
• Long content.
• Loading state.
• Empty or unavailable state.
• Error or invalid state.
• Mobile layout.
• Wrong usage.

For a table row action, show a normal row and a row with a long name, missing metadata, disabled action, and failed action. For a modal, show the short confirmation and the case where the content should become a full page instead. For a form field, show helper text, validation, server error, and read-only mode.

These examples prevent the docs from becoming a gallery. They make the docs behave like QA training.

I also like including implementation notes beside examples:

• Keep button width stable during loading.
• Do not truncate the status label below 320px.
• Put destructive confirmation copy in the body, not only the title.
• Use inline errors for field validation, not toast messages.

Those notes are small, but they save repeated interpretation.

The final thing I want is ownership. Every doc page should have a path for questions and a last-reviewed date. If nobody owns the page, teams eventually stop trusting it. Outdated docs are worse than sparse docs because they create false confidence.

The goal is not to document every possible use. It is to document enough real product pressure that teams can make good choices without waiting for a design-system reviewer.

What I would not document

I would not document internal implementation trivia unless it changes how teams use the component. I would not add a dozen variants that exist only in old screenshots. I would not write long philosophy sections that hide the practical rules. I would not publish examples that have not been checked against production behavior.

Docs should be opinionated because teams need help deciding. If every variant is presented as equally valid, the docs are not guiding anyone.

The hardest part is cutting. A good docs page leaves out enough that the important decisions are visible. It gives teams confidence without making them read a manual every time they need a component.

That is why I treat component docs as a product surface. They have users, tasks, failure modes, and maintenance cost. If the docs help a team ship the right thing with fewer questions, they are doing their job.

One practical metric is question reduction. If the same question appears in three implementation threads, the docs should answer it. If a component is misused twice in production, the docs should show the wrong usage explicitly. Documentation gets better when it listens to the mistakes teams are already making and turns them into clearer guidance for the next project cycle. That is maintenance, not paperwork, and teams feel the difference daily.