Developer Tools
How to document a button component clearly
A button looks simple, yet teams repeatedly reinterpret it. This guide shows how to document one so designers and developers can use it correctly without asking, with a worked example.
01
Step one: define purpose and variants
Begin by stating what the button is for and what it is not for. Example: a primary button triggers the single most important action on a screen, such as Save changes, while a secondary button handles supporting actions like Cancel. List each variant with a short rule for when to use it, and limit one primary button per view. Include the label guidance too: start with a verb, keep it under three words, avoid vague text like Submit. This opening section prevents most misuse because people see the intent before they see the code.
02
Step two: show states and usage examples
Next, display every state a person may encounter: default, hover, focus, pressed, disabled and loading. For the Save changes example, show the loading state replacing the label with a spinner while keeping the width fixed so the layout does not jump. Pair each state with a minimal code snippet and a one-line note, such as disabled buttons should explain why through nearby text. Add two or three realistic placements, like a form footer or a dialog, so readers see spacing and alignment in context rather than isolated on a blank canvas.
03
Step three: record accessibility and change notes
Finish with the requirements that keep the component dependable. Note that the element should be a real button, reachable by keyboard, with a visible focus ring and sufficient contrast against its background. For the Save changes example, state that the loading version announces its status to assistive technology and ignores repeat clicks. Then add a short change log listing what altered and why, so downstream teams can update screens confidently. Review the page by handing it to someone unfamiliar with the project and asking them to build the button; where they hesitate, the documentation needs another sentence.