What should component documentation include?
Explain purposes, options, states, and limits so users do not have to guess.
Component documentation is a part’s usage guidance. It helps designers, developers, and content staff choose correctly and recognise when another approach is needed.
Keep these basics in mind
- Explain purpose and suitable contexts first, then structure, adjustable options, states, and examples.
- A default is the choice used when no alternative is set. Make defaults clear and explain important differences.
- Record accessibility requirements such as keyboard use, names, and error feedback so implementers can check behaviour.
- Explain limits, differences from similar parts, a maintenance contact, and changes to reduce repeated questions.
See Figma’s asset-description guide for purpose and context and its component-management guidance for considerations before updates.
Write usage guidance
Illustrative documentation
These are hypothetical Save-button instructions.
| Question | Previous guidance | Added information |
|---|---|---|
| When should I use it? | Blue button | Submit current form edits |
| What happens while waiting? | Unspecified | Show processing and prevent duplicate submission |
| Where is it unsuitable? | Use anywhere | Use links for page navigation |
Walk through an example
A new colleague adds Save to a profile page. The guidance explains purpose, editable text, loading feedback, and error placement. They implement it and check keyboard use. If disabled conditions are unclear, the maintainer adds them so the next colleague does not need to guess.
Limits and common misunderstandings
Documentation need not begin as a large manual, but must support correct use. Screenshots are incomplete instructions, and code examples do not replace purpose explanations. Keep guidance aligned with changes; outdated instructions preserve unsuitable practices.