Building a component library, one Button at a time

A good component is more than the right look: its anatomy, states, API, behaviour and documentation are all complete. A button that looks right but has no focus style, no loading state and a different prop name in code is a source of bugs, not a shared part.

This part follows one component, the Button, from audit to release. The same process works for any component.

The process

1. 01Audit. Collect every version of the component that already exists in the product, as screenshots on one page. Brad Frost calls this an interface inventory. It often turns up many more button styles than anyone expected.
2. 02Requirements. Agree with engineers and product managers which use cases the component has to cover.
3. 03Anatomy. Name each part of the component.
4. 04Variants and states. Design every form and every state.
5. 05Accessibility check. Contrast, focus, keyboard use and screen reader labels.
6. 06API alignment. Give Figma properties and code props the same names.
7. 07Document, review, publish and log the change.

Button anatomy

┌──────────────────────────────────┐
│  [icon]    Label text    [icon]  │  ← container: radius.md, padding
└──────────────────────────────────┘
    ① leading   ② label   ③ trailing

Naming the parts gives designers, engineers and the documentation one vocabulary. “The leading icon is too close to the label” is a clear bug report; “the thing on the left looks off” is not.

Variants and properties

Note that most states are not props. Hover, pressed and focus come from the browser through CSS; only disabled and loading are set by the developer.

Don’t skip a state

• Default.
• Hover, for mouse users.
• Pressed (active).
• Focus-visible, for keyboard users, for example a 2px outline with a 2px offset.
• Disabled.
• Loading: a spinner replaces or joins the label, the width stays the same so the layout doesn’t jump, and repeat clicks are blocked.

Other kinds of component bring their own states:

A documentation template

Give every component page the same sections, so people know where to look:

1. 01Overview: one line on what it does.
2. 02When to use, and when not to. For example: use a danger button for a destructive action; use a link, not a button, for navigation.
3. 03Anatomy.
4. 04Variants and sizes, and when to pick each.
5. 05States.
6. 06Behaviour: keyboard interaction, responsive behaviour, text overflow.
7. 07Do and don’t, with images.
8. 08Accessibility: role, ARIA attributes, contrast, focus order.
9. 09Content: for a button label, start with a verb, use sentence case and keep it to a few words.
10. 10Code: the props table and a link to Storybook.
11. 11Related components.

Rules for the component API

• One name in both places. If the Figma property is variant=secondary, the code prop is variant="secondary".
• Small and composable beats one giant component. A card with thirty props is hard to learn; Card, CardHeader and CardBody that fit together are easy.
• Sensible defaults. With no props at all, the component should still look and behave correctly.
• An escape hatch, documented. Allow a custom class or slot for the rare case the system doesn’t cover, and explain why it should stay rare.

<!-- Defaults cover the common case -->
<Button>Save</Button>

<!-- Props match the Figma properties -->
<Button variant="danger" size="sm" loading>Delete project</Button>

Storybook, the library on the code side

Developers usually show each component in isolation in Storybook, with every variant as its own story. For a designer it is the place to check the built component against the Figma one, side by side, state by state. Tools such as Chromatic add visual regression tests, so an unintended change to a component is caught before release.

Next in the series

A finished component still has to stay finished as teams ask for changes. Part 5 covers governance: team models, how contributions get in, versioning and changelogs, and how to measure whether the system is actually used.