How to document a design system component
Learn

How to document a design system component

Author Avatar
Written by
Aug 21, 2026

When someone reaches for your design system, the page they actually open is a component page. They might also browse foundations, read principles, scan patterns. But the daily work, picking a component, configuring it, dropping it into a screen, runs through component pages. That makes component documentation the part of the system most people interact with most often.

It's also the part most often half-finished. The component is built, it's in the library, but the page documenting it is a sketch: a screenshot, a couple of variants, maybe a code snippet copy-pasted from Storybook. Readers fill in the gaps by asking the design system team directly, or by guessing.

This article is the practical template Article 02 promised. It walks through what a working component page contains, in what order, and how to write each section so it does the job. By the end you should have a structure you can apply to any component in your library.

The anatomy of a component page

A good component page answers the questions someone walking up to your design system actually has. Roughly in this order:

  • What is this component called?
  • What is it for, in one sentence?
  • When should I use it, and when shouldn't I?
  • What does it look like? What variants and states does it have?
  • How do I implement it? What props does it take?
  • What accessibility requirements does it carry?
  • Is it production-ready, or am I working with something experimental?
  • Where can I see it in context?

That's the spine. Every component page in your system should answer those questions, in the same order, with the same structure. Consistency between pages is doing more work than it looks like: when readers know where to find each piece of information, they spend less time hunting and more time using.

The order matters too. Designers tend to scan for what the component looks like and when to use it. Developers scan for props and code. Accessibility specialists scan for ARIA notes and keyboard behavior. A consistent layout lets each of those readers learn the page once and reuse the mental map across every component.

The sections below take each piece in turn and explain what to write, what to skip, and the mistakes that make these sections fail.

Name and purpose

Start with the name and a one-line description of what the component does.

The name does more work than it looks. The same component goes by different labels in different systems (a chip is a tag is a pill is a badge), so the name on the page has to be the canonical one for your team. If your component is named "Tag" in design and "Chip" in code, the documentation has to either reconcile the naming or surface both with a note. Either way, the reader should never have to guess which name to search for. Article 06 covers naming conventions in detail.

The one-line description should explain what the component does in language someone outside the design system team can parse. "A tag is a small, non-interactive label used to mark or categorize an item" is more useful than "A tag is a stateless presentational element." Don't write to impress. Write so a junior engineer who's never touched the system can decide in five seconds whether this is the component they're looking for.

A useful test: read the description out loud. If it sounds like it was edited by a committee, rewrite it. The clearest descriptions sound like a person explaining the component to a teammate.

You can add a longer paragraph below the one-liner if there's context that genuinely helps, but most components don't need it. The one-liner is the load-bearing line.

Usage guidance: when to use, when not to use

This is the most important section on a component page, and the one most often half-written.

Usage guidance answers the question "should I use this component for what I'm trying to do?" Without it, the reader has to guess, and guessing is how you end up with toasts being used as confirmations and modals being used for error messages. Once that happens, the system is no longer a system. It's a kit of parts being used inconsistently across the product.

A complete usage section has three parts.

When to use it. Describe the situations the component is designed for. Be specific. "Use a banner to surface a system-level message that doesn't require immediate action" carries more weight than "use a banner for messages."

When not to use it. This is the part most teams skip. If a banner shouldn't be used for an action that requires acknowledgment, say so. If it shouldn't be used for inline form errors, say so. Be explicit about the boundaries.

What to use instead. When you tell someone not to use a component, point them at the right alternative. Reach for a banner when the message is non-urgent and system-level. Use a modal when the message has to be acknowledged before continuing. For form-specific errors, inline validation does the job better.

The mistake to avoid is writing usage guidance abstractly. "Use this component to communicate information" isn't guidance, it's a definition. Real guidance names the scenario, the alternative, and the reason the choice matters. A reader should be able to take your usage guidance and use it to settle an actual disagreement with a teammate.

Anatomy, variants, and states

Once the reader knows what the component is and when to use it, they need to know what it looks like.

The anatomy of a component is a labeled visual showing the parts. For a button: the container, the label, the optional icon, the optional loading state. Label the parts and use those names consistently in the rest of the page. If the icon slot is called "leading icon" in the anatomy and "left icon" in the props table, you've made the reader work to bridge the gap. Pick one name and stick with it.

Variants are different versions of the component that share the same anatomy but vary in style or behavior: primary, secondary, tertiary; small, medium, large; outlined, filled, ghost. Show each variant with a clear label and a one-line note on when it applies.

States are how the component changes based on interaction or context: default, hover, focus, active, disabled, loading, error. For each state, show what it looks like and any specific rules. A hover state shouldn't fire on touch devices. A focus ring must remain visible at 2px minimum. A loading state blocks further interaction. Spell these out where they matter.

A few practical rules for this section.

Show each variant and state visually. A static screenshot will do, but a live component pulled from the actual library is better. A description without a visual won't get a designer where they need to be.

Don't list every theoretical combination. If your button has four variants, four sizes, three states, and a loading flag, the cross-product is 96 instances. Show the ones that matter (the default state for each variant in the default size, the states for the primary variant, the combinations with non-obvious behavior) and let the reader extrapolate.

Be explicit about combinations that are off-limits. If a ghost button shouldn't be used in a disabled state, document that as a rule rather than quietly leaving the variant out.

Props and API documentation

This is the developer-facing layer of the component page. It's also where automation can save a lot of writing.

A complete props section gives, for each prop:

  • Name
  • Type (or accepted values, for enums)
  • Default value
  • Required or optional
  • A short description of what the prop does

A props table is usually the right format. Keep it scannable. The description should be a phrase, not a paragraph. If a prop needs more explanation, link to a longer note below the table.

Where possible, generate the props table from the component code rather than maintaining it by hand. TypeScript types, JSDoc comments, or a tool like react-docgen can produce a props list that stays in sync with the implementation. Hand-maintained props tables go stale the moment someone adds a prop without updating the docs.

Beyond props, this section should include a code example showing the most common use case. Keep it minimal: the component import, the component call, the most common props set to typical values. A developer should be able to copy this snippet and have something working without additional changes.

A few additional examples are worth including. Variant usage, controlled vs uncontrolled patterns where relevant, and any non-obvious composition. Don't show every combination. Show the ones that aren't immediately clear from the props table.

Link out to the live component sandbox (Storybook, Stackblitz, or whatever your team uses) for developers who want to experiment before committing. Article 11 covers live code examples in depth.

The mistake to avoid is treating props as the only thing developers need. Developers also need usage guidance, accessibility notes, and visual references. The developer section is the entire component page, not just the props table.

Accessibility notes

Every component page should have an accessibility section. It should never be empty.

What goes here depends on the component, but typically covers:

  • ARIA roles and attributes the component sets automatically, and which ones the consumer is responsible for setting
  • Keyboard interaction: which keys do what, and how focus behaves
  • Screen reader behavior: what gets announced, in what order
  • Color contrast requirements, especially for non-default states and variants
  • Touch target sizing for interactive elements

Be specific. "This component is accessible" is not an accessibility note. "The button traps focus when activated, restores focus on close, and announces its label via aria-label" is.

The accessibility section also has to be honest about gaps. If a component doesn't meet a WCAG criterion in a particular configuration, document that. If there's a known issue with screen reader support in a specific browser, document that. Documentation that overstates accessibility actively harms the people relying on it.

Where to split responsibility between the component and the consumer matters too. A component might handle keyboard navigation internally but require the consumer to provide an accessible label via prop. Make the split explicit so consumers don't assume something is handled when it isn't.

Article 09 goes deeper on what developers need from documentation, including how accessibility hooks get surfaced.

Do and don't examples

Do and don't examples are the most visual part of the page and often the most copied. Done well, they shift behavior across the team. Done badly, they're decoration that nobody reads.

Three rules for writing them.

Specificity over abstraction. "Do use a button for primary actions / Don't use a button for navigation" is too general to change anyone's mind. "Do use a primary button for the main action in a form / Don't use a primary button for a tertiary action like 'cancel'" gives the reader something to apply.

Target real mistakes. Look at the questions your team actually gets asked, the patterns you see going wrong in code review, the misuse that keeps appearing in support tickets. Those are the do/don'ts that earn their place on the page. If you can't remember anyone making the mistake the pair is correcting, it probably isn't pulling its weight.

Show the mistake visually. A do/don't pair without images is a missed opportunity. A reader who skips the body text still sees the visuals. Making the wrong example visually wrong is the fastest way to get the point across.

Limit yourself to three or four pairs per component. More than that and the reader stops reading. Fewer and you're probably not surfacing the mistakes that matter. The goal isn't comprehensive rule coverage. It's preventing the specific mistakes that keep happening in your system.

Component status

Every component page should make its status visible. Without a status, the reader has to assume, and assumption erodes trust in the system.

A minimal status system has four labels.

Alpha. Under active development, expected to change, not yet ready for production use. Reach for an alpha component knowing the API or behavior may shift.

Beta. Stable enough for use but the team is still gathering feedback. Most APIs are settled, though edge cases may still be worked out. Safe to ship if you can accept small changes.

Stable. Production-ready, API committed, breaking changes only with proper deprecation. The default state for most of your library.

Deprecated. Still available but not recommended. The status should link to the replacement component and include a sunset date if there is one.

Show the status prominently. A small label at the top of the page is enough. It should be obvious without scrolling.

Status communication does two things at once. It tells consumers what level of risk they're taking on, and it gives the design system team room to ship components without committing to them permanently. An alpha label is permission to iterate. A stable label is a promise.

The mistake to avoid is treating every component as stable by default. Components in active development that aren't labeled appropriately make the entire library feel less trustworthy.

A complete component page in practice

To make the structure concrete, here's what a button component page might look like applying everything above.

Name and status. Button. Stable.

Purpose. A button is an interactive element that triggers an action when activated.

When to use. Use a button for actions that change state, submit data, or trigger an immediate response from the system. Use a primary button for the single most important action on a screen. Use a secondary button for supporting actions. Use a tertiary button for low-emphasis actions like dismissing a notification.

When not to use. Don't use a button for navigation between pages. Use a link instead. Don't use a button to surface information; use a banner or a card. Don't put more than one primary button on a screen.

Anatomy. Container, label, optional leading icon, optional trailing icon, optional loading spinner.

Variants. Primary, secondary, tertiary, ghost. Sizes small, medium, large.

States. Default, hover, focus, active, disabled, loading.

Props. A table generated from the TypeScript types: variant, size, leading-icon, trailing-icon, loading, disabled, on-click.

Code example. A minimal snippet showing a primary button with a click handler, copy-pasteable.

Accessibility. Renders as a native <button> element. Supports keyboard activation via Enter and Space. Sets aria-disabled when the disabled prop is true. Consumer is responsible for providing an accessible label (via children or aria-label) when no visible text is present.

Do and don't. Three pairs, each addressing a real mistake the team has seen: using primary for multiple actions on a screen, using a button for navigation, using a button without an accessible label.

That's the spine of a working component page. The exact content varies by component, but the structure repeats. Once you have it in place for the first component, the rest of the library follows the same pattern. Component documentation gets dramatically faster once the template exists.

Where to go next

The structure in this article gets you a complete component page. Several articles in this guide go deeper on specific parts of it.

Article 09 (Documenting design systems for developers) goes further on the developer-facing layer: API docs, code examples, integration with Storybook, and the parts of component documentation that live closest to the codebase.

Article 04 (The key sections of a design system) zooms out from individual components to the structure of the system around them. Useful if you're still figuring out what your overall documentation site needs to contain before drilling into component pages.

Article 13 (Keeping your design system documentation up to date) covers the maintenance side. Component pages are the part of your documentation that drifts fastest, because the underlying code changes most often. Article 13 is about how to stop that drift.

Article 08 (AI and design system documentation) covers the role AI can usefully play in writing component pages (drafting descriptions, generating prop tables, reviewing for consistency) and the places it's better left alone.

Author Avatar
Try zeroheight
The design systems platform that keeps teams and agents in sync
Start for free
Share this post