Designing components properly
A component is only reusable if it is fully defined. For each one I document:
| Aspect | What's defined |
|---|
| Purpose | What the component is for, and what to use instead in similar situations |
|---|
| Anatomy | The parts - label, icon, helper text, container - and which are optional |
|---|
| Variants | Sizes, emphasis levels (primary, secondary, tertiary, destructive) and layouts |
|---|
| States | Default, hover, focus, active, disabled, loading, error, success, read-only, selected |
|---|
| Behaviour | Keyboard interaction, focus management, responsive behaviour, motion |
|---|
| Accessibility | Contrast values, accessible name, role, screen-reader output, target size |
|---|
| Content rules | Label length, capitalisation, when to use icons, error wording |
|---|
The focus and error states deserve particular care. WebAIM's 2026 analysis of the top million home pages found missing form labels on 51% and empty buttons on 30.6% - problems that a properly specified input and button component prevent everywhere at once.
Tokens turn design decisions into data. Instead of "#E2480A" scattered through the code and design files, you have a name - color.action.primary - that points to a value. Change the value once and every use updates.
Tokens have also become a standard. On 28 October 2025, the W3C Design Tokens Community Group announced the first stable version of the Design Tokens specification - a vendor-neutral format for sharing tokens between design tools and code, with support for theming and modern colour spaces.
I structure tokens in tiers so they stay manageable:
| Tier | Example | Used by |
|---|
| Primitive | orange.600, space.4, font.size.300 | Only by other tokens |
|---|
| Semantic | color.action.primary, color.text.secondary, space.stack.md | Components and layouts |
|---|
| Component | button.primary.background, input.border.error | Specific components where needed |
|---|
Semantic tokens are where accessibility is protected: text tokens only exist for colour pairings that meet WCAG 2.1 contrast - 4.5:1 for normal text, 3:1 for large text - so failing combinations are hard to use by accident.
Themes and multiple brands
With semantic tokens in place, themes become a matter of swapping values rather than rebuilding components:
- Light and dark modes, each with its own tested contrast.
- White-label or multi-brand products, sharing components but not colours.
- Density modes for data-heavy screens, adjusting spacing tokens.
