Component documentation

Component Documentation & Examples

A design system component that only exists as source code forces every developer to read its implementation to guess which props to pass, when to use it versus a sibling component, and what edge cases it supports. Write concise, accurate documentation that helps developers choose and use the component correctly on the first try.

1. Anatomy of Actionable Component Documentation

For every shared component or token group, document:

1. Purpose & When to Use (vs. Alternatives):
   • State in 1–2 sentences what user problem the component solves and when to use a related component instead (e.g., "Use Dialog for focused tasks requiring user confirmation; use Drawer for inspecting details alongside context; use Popover for lightweight non-modal controls").
2. Public API Reference (Props, Slots, Events & Tokens):
   • List supported props/inputs, types, default values and whether required.
   • Document named slots / compound subcomponents and semantic CSS tokens that apply to the component.
   • Explicitly distinguish public contract from internal implementation details.
3. Interactive States & Variants Showcase:
   • Provide copy-pasteable, realistic code examples covering primary variants, sizes, loading/disabled/error states and composition patterns.
4. Accessibility & Keyboard Contract:
   • Document the expected keyboard interactions (Tab, Enter, Space, Escape, Arrow keys) and any required accessibility props (such as providing aria-label when a visible title is omitted).
5. Do / Don't Guidelines & Known Limits:
   • Show concrete usage boundaries (e.g., "Do: keep button labels to 1–3 action verbs. Don't: place two Primary buttons side-by-side in the same dialog footer").
   • State clearly which edge cases are verified and which capabilities are intentionally unsupported.

2. Realistic Content in Examples (No foo / Lorem ipsum)

• Write every documentation example and workbench story using realistic product copy and representative domain data (real project names, realistic statuses, localized strings, empty states and error messages).
• Include stress-test examples alongside happy-path examples:
  • Very long labels, overflowing titles and multi-line descriptions.
  • Missing optional fields (no avatar image, empty subtitle, zero items).
  • Narrow mobile viewport (320px) and dark/high-contrast themes.
• When the project uses an i18n catalog (@orqestria/i18n, data-i18n, framework translation helpers), show how translated labels plug into the component API cleanly.

3. Keeping Documentation Synchronized With Code

• Update component documentation, prop tables and usage examples in the same change that modifies a component's API, tokens or behavior.
• When deprecating a prop or component, mark it clearly in both code types (@deprecated) and documentation with the exact replacement example and removal condition, and coordinate broader developer guides with the technical writer.