What good component documentation lets someone do
Component documentation should help a contributor choose the right component, configure it correctly, and recognize when it does not fit. The reader needs a decision, not just a screenshot or a list of properties. An AI agent needs those same boundaries in a form it can find alongside the implementation.
TDP’s agentic component-library article puts purpose, variants, relationships, tokens, examples, and anti-patterns beside working code. The Figma-to-Storybook walkthrough adds an essential first step: resolve disagreements between the design and implementation before documenting them as rules.
Start with one component that appears in a real flow. A button or field is manageable, but do not assume a simple appearance means simple behavior. The documentation is successful when a teammate can use the component without asking the same questions again.
Step 1. Start with the component’s job
Describe what the component helps someone do and when to choose another component. A button performs an action; a link navigates. Include product-specific distinctions, such as when a compact table action is appropriate. Purpose helps a reader choose correctly before they inspect a list of props.
Step 2. Define anatomy and configuration
Name the parts, allowed inputs, defaults, and content rules. Identify whether an icon is decorative or conveys meaning. Avoid documenting hypothetical variants that the implementation does not support. If a desired behavior is missing, track it as work instead of making the specification appear complete.
| Specification field | Example for a field component |
|---|---|
| Anatomy | Label, input, hint, error message |
| Required inputs | Label and value/change interface |
| Optional inputs | Hint, error, disabled state |
| Content | Hint explains expected format |
| Relationships | Label is associated with its input |
| Errors | Error text identifies the problem and recovery |
| Sources | Implementation file, story, design reference |
Step 3. Show meaningful states
Include default, populated, invalid, disabled, and focused examples where supported. Add long labels and realistic translations. Document invalid combinations, such as showing a success message and an error for the same submission. Examples should teach correct use instead of merely displaying every visual permutation.
Step 4. Connect the entry point
Keep shared principles in design.md and detailed rules beside the component. Link implementation, metadata, and stories so a reader can inspect the source. Ask an agent to locate the component and explain when it would use it before generating a new screen. If discovery fails, fix the path or naming rather than duplicating the whole specification elsewhere.
Step 5. Review documentation with changes
When behavior or supported properties change, update the specification and stories in the same review. Identify who approves breaking changes and how consumers learn about them. A document that accurately described last month’s component can still cause today’s implementation error.
Worked example: document a field beyond its props
A text field is a useful test of documentation quality. A props table might list value, placeholder, disabled, and error. The usage guidance must also explain the relationship between label, hint, error, and entered content. Otherwise each consumer can assemble a slightly different interaction from the same API.
For an illustrative invitation form, document the field’s purpose as “collect one teammate email address.” Show the visible label, an example value, the validation trigger, and the error presentation. Preserve entered content after a failed request. If client validation and server rejection use different messages, explain where each belongs.
| Documentation layer | Example content |
|---|---|
| Anatomy | Label, control, optional hint, error region |
| Supported API | Only the properties actually exported by the component |
| Behavior | When validation occurs and how the error is associated |
| Composition | How the field fits into a form and action group |
| Examples | Empty, completed, invalid, disabled, long hint |
| Alternatives | Use a combobox for a searchable controlled set of options |
This is an example specification, not a universal requirement. A different field can have different validation timing. The important part is making the choice explicit and keeping the example aligned with the implementation.
Separate defaults, options, and invalid combinations
A default describes what happens when a consumer makes no choice. An option describes a supported variation. An invalid combination describes a configuration the team has decided not to support. Mixing these together creates ambiguity for both people and agents.
For example, “compact” might reduce padding but retain the same label treatment. An icon-only variation needs a naming strategy. A button configured as navigation needs the correct underlying semantics or a documented alternative. Describe these relationships instead of presenting every property as an independent toggle.
When the implementation permits something the guidelines forbid, decide how to handle that gap. The team might strengthen the API, add a check, or document the restriction while planning a change. Do not pretend prose alone makes an invalid configuration impossible.
Make anti-patterns actionable
Write anti-patterns as a visible problem and an alternative. “Do not misuse the primary variant” is vague. “When two actions compete in the same decision group, choose the main action and give the alternative secondary emphasis” is easier to apply and review.
Use an example from your actual product, then explain the decision. If a pattern is allowed in one context but not another, name the boundary. Avoid absolute rules that the next legitimate use case will immediately contradict.
Keep source references and ownership close
A useful component page names the implementation, its design reference, its stories, and the owner of unresolved decisions. Record a review date when the behavior changes. Avoid scattering copies across a design file, a wiki, and a repository with no indication of which one is current.
The document should preserve unknowns as unknowns. During an audit, tag each finding as observed, proposed, or approved. In TDP’s component walkthrough, identifying the source of each answer helps prevent an agent’s suggestion from quietly becoming a product requirement.
Review documentation by using it
Give a teammate a task that requires the component and ask them to work from the documentation. Watch where they hesitate: choosing a variant, finding a prop, understanding a slot, or handling an error. Those gaps are better evidence than asking whether the page “looks complete.”
Then run the same bounded task with your agent. Compare imports, supported configurations, and the final UI. Update the missing guidance or implementation, and keep the test task as a repeatable check for future changes.
For a library-wide rollout, use the AI-ready system guide. For the short index that points agents toward these contracts, use write a design.md.
Completion checklist
- Purpose and alternatives are clear.
- Properties and defaults match the implementation.
- States include realistic content and failure cases.
- Accessibility relationships and keyboard behavior are described.
- Sources, owner, and change process are discoverable.
Common questions
Should metadata replace human-readable documentation?
Use a concise human-readable explanation with structured details where they help tooling. Both should point to the same implementation and decisions.
Should every component have its own long document?
Scale the detail to the behavior. A simple divider needs less explanation than a modal with focus handling and destructive actions.