How to Document UI Components: A Practical Guide

Undocumented components get used incorrectly. Developers implement them with wrong spacing. Designers create one-off variants instead of using the existing component. New team members invent patterns that already exist.

Good documentation prevents all of that. Here's what it should include and how to write it.

What good component documentation includes

For every component, document these elements:

Purpose. One to two sentences explaining what the component is for and the problem it solves. "The Toast component displays brief, non-disruptive notifications for status updates, confirmations, and error messages that don't require user action."

Variants. All available variants with screenshots and the conditions under which each is used. Don't just list them — explain when to use which. "Use the Error variant when an action the user took has failed. Use the Warning variant when a recoverable issue exists that the user should know about."

Usage guidelines. Concrete guidance on how and when to use the component. Include dos and don'ts with visual examples. "Do: use Toasts for transient system messages. Don't: use Toasts for critical errors that require user action — use a Dialog instead."

Props/properties. The API for the component. For design docs: the component properties exposed (variants, text properties, boolean toggles). For code docs: the full props interface with types and defaults.

Accessibility notes. Any accessibility considerations the implementer needs to know. "This component uses role='status' for informational toasts and role='alert' for error toasts. It auto-dismisses after 5 seconds but must have a manual dismiss option."

Related components. Links to components that are often confused with this one or commonly used alongside it.

Where to document: Figma, Storybook, or Zeroheight

These tools serve different audiences and different purposes. You probably need more than one.

Figma annotations are the right place for design-side documentation — the decisions that designers and product managers need to reference. Add annotations directly on Figma frames showing:

• Component states with labels
• Spacing values and layout rules
• Usage context (when to use this, when not to)
• Edge case behavior

Figma annotations are visible to everyone with file access and don't require a separate documentation site. They're good for design specifications, but they're not accessible to developers who want to understand a component's behavior and code interface.

Storybook is the developer's documentation tool. Each component gets a "story" — an isolated render of the component in a specific state, with controls for toggling props. Storybook serves as a living component playground and documents the code API automatically.

Try Storybook Free

Storybook is where you write: code examples, prop documentation, accessibility checks (via the a11y addon), and interaction tests. For design system teams, Storybook is the code side of the documentation equation.

Zeroheight sits between Figma and Storybook — it's a documentation site builder that pulls from both. You write prose guidelines in Zeroheight, embed Figma frames for design specs, and embed Storybook stories for code examples. The result is a single documentation site that serves designers, developers, and product managers.

Try Zeroheight Free

Zeroheight is most valuable when you have a team large enough that people regularly fail to find or correctly use components without documentation. It starts at $149/month for teams.

Writing useful usage guidelines

The most common documentation failure is guidelines that describe what a component looks like instead of telling users how to use it.

Bad: "The Button component has four size variants: small, medium, large, and extra-large."

Better: "Use the medium button for most actions. Use small buttons in compact UI contexts like tables, inline forms, or toolbars where vertical space is limited. Large buttons are for primary CTAs on marketing pages or standalone action screens — they draw more attention and work best with whitespace around them."

The test for a useful usage guideline: could someone who's never seen the component before read this and know when to use it and when not to? If not, add more specificity.

Write your dos and don'ts with actual visual examples, not just text. A screenshot of correct use and incorrect use together makes the guideline immediately clear.

Minimum viable documentation by team size

Solo designer or very small team (1-3 designers):

• Figma annotations on all major components
• A single Notion page listing components and their primary usage guidelines

Small-to-medium product team (4-15 designers/engineers):

• Figma with detailed component annotations
• Storybook for the component code library
• A simple Zeroheight or Notion-based documentation site linking everything together

Large team or multi-brand system:

• Full Zeroheight documentation site
• Storybook per product/brand
• Documented contribution guidelines and governance
• Versioned release notes

Don't build enterprise-scale documentation for a three-person team. The overhead of maintaining documentation you don't need is real.

Keeping documentation up to date

Documentation that's out of date is worse than no documentation — it actively misleads. Establish a simple rule: a component isn't done until it's documented. Not shipped to the library, not handed off to engineering. Done.

When a component changes — new variant, changed behavior, updated accessibility notes — documentation is updated in the same PR or Figma file version.

Assign documentation ownership. Someone is responsible for each component's documentation. Without ownership, documentation drifts.

Do a documentation audit every quarter: check that existing docs still match the actual components. Add a "last reviewed" date to each component page. If a page hasn't been reviewed in six months, flag it.

Good documentation is a first-class design deliverable. Treat it that way.