Documenting a single UI component

WHAT THIS TESTS This checks whether you understand documentation as a product for two audiences, engineers and designers, and what content actually reduces misuse and support questions for a component.

A GOOD ANSWER COVERS Start with purpose: a short statement of what the component is for and, importantly, when to use it versus an alternative, so people pick the right component. Provide a complete API reference: every prop with its type, default value, whether it is required, and a one-line description, ideally generated from the source or types so it stays accurate. Show live, interactive examples covering the main variants and every meaningful state, including default, hover, focus, disabled, loading, and error. Include copyable code snippets so consumers can paste working usage. Document accessibility: the role, keyboard interactions, required labels, and any constraints. Add do and don't guidance with visual examples to steer correct usage, and note relevant design tokens. Mention version or changelog links so consumers see what changed.

COMMON WRONG ANSWERS Documenting only the prop table with no usage intent leaves people misusing the component. Omitting states like disabled and loading hides important behavior. Skipping accessibility guidance leads to inaccessible implementations. Static screenshots that drift from the real component are worse than live examples. Writing for engineers only ignores designers who also consume the docs.

LIKELY FOLLOW-UPS How do you keep the props table from going stale? Tools like Storybook autodocs or TypeScript-driven generation. How do you document composition and slots? Where do design and code docs converge? How do you show accessibility behavior interactively? What belongs in a do versus a don't example?

ONE CONCRETE EXAMPLE The Button page opens with when to use a primary versus secondary button, then an auto-generated props table listing intent, size, loading, and disabled with defaults, followed by live examples of each variant and state, a snippet to copy, a note that it renders a real button element and supports Enter and Space, and a don't example warning against using a Button for navigation when a link is correct.