Framework · Design systems · 4 min read
Component state matrix
A grid of every state a component must ship (interaction states the browser sets, component states the product sets, data states the content brings) against what each needs: a design, the right attribute, a measured contrast and an edge-case test.
Set by the browser, from what the person does.
Hover, focus, pressedSet by the product, through a prop.
Disabled, loading, selected, errorSet by the content the component receives.
Empty, long, missing, failedA real frame for every state, in every mode.
Next to the variantsThe attribute, where focus goes, what is announced.
Loading keeps focusMeasured contrast per state, plus a test with real content.
4.5:1 text, 3:1 ringEvery state (rows I, C, D) × every need (columns 1, 2, 3) = no empty cell at release
Use it when
- A component is about to be released and you need to know it's complete.
- Bugs keep coming back about focus, loading or long text, not about the default look.
- Two products built the same component and handle disabled or empty differently.
How to use it
- List the rows: every state, by who sets it. Interaction states come from the person (hover, focus, pressed). Component states come from a prop (disabled, loading, selected, error). Data states come from the content (empty, long, missing, failed). Output: the rows of the matrix.
- Add the columns: what each state needs. Use four: the design (a real frame), the behaviour (attribute, focus, what is announced), the measured contrast in each mode, and the test (a story or a frame with real content). Output: an empty grid.
- Fill in behaviour from the pattern, not from memory. Disabled uses the HTML
disabledattribute and leaves the Tab order. Loading usesaria-disabled="true", keeps focus on the element and ignores presses. A finished action is announced with arole="status"message. Output: the behaviour column, with sources. - Measure every state that carries text or a boundary. Text needs 4.5:1 and a focus ring 3:1. WCAG doesn't require contrast for an inactive component, so readable disabled text is your choice; write it down either way. Output: one ratio per state and mode.
- Test the data rows with real content. Long names, translated labels, missing values, a failed load, 200% zoom and a 320 px wide screen. Decide per part: wrap, truncate with the full text available, or limit at entry. Output: one frame or story per edge case.
- Ship the matrix with the component. Put the frames on the component's Figma page and the cases in Storybook. A state that only lives in someone's head isn't designed. Output: no empty cell at release.
Worked example
Harbour's Button before release, light mode. The numbers are the ones measured in the lesson.
| State | Set by | Behaviour | Contrast | Tested with |
|---|---|---|---|---|
| Rest, primary | Component | Default | 6.35:1 | "Book crossing" |
| Hover | Browser | Darker fill | 8.86:1 | Pointer only |
| Focus | Browser | Ring outside the button | Ring 8.35:1 on the page | Keyboard, Tab |
| Disabled | Product, disabled |
Leaves the Tab order; reason shown next to it | 4.92:1 (a choice) | "Choose a sailing first" |
| Loading | Product, aria-disabled |
Keeps focus, ignores presses, then a status message | Same as rest | Double press |
| Long label | Content | Wraps; room for twice the English length | Same as rest | A label translated from 12 characters |
| Compact | Prop size |
32 px high, above the 24 px minimum target | Same as rest | Staff console |
The empty cells the team found: no design for loading in dark mode, and no test for a translated label. Both were fixed before the release.
Watch out for
- Only the resting state designed. Hover, focus and disabled get left to the developer, and every product gets them differently.
disabledfor loading. Focus jumps away in the middle of the action, and keyboard users lose their place.- Contrast checked once. The resting state passes, the hover or the disabled state doesn't, and nobody measured it.
- "Lorem ipsum" and English only. Short labels grow most in translation, and placeholder text never has the long port name that breaks the card.
Template
Copy one grid per component. Leave no cell empty at release: write "n/a" with a reason instead.
Component: ... Modes: light / dark
State | Set by | Design frame | Behaviour (attribute, focus, announced) | Contrast light / dark | Test (story / frame)
Rest | component | ... | ... | ... / ... | ...
Hover | browser | ... | ... | ... / ... | ...
Focus | browser | ... | ring, visible on every background | ring ... / ... | keyboard
Pressed | browser | ... | ... | ... / ... | ...
Disabled | prop | ... | disabled, reason shown | ... / ... | ...
Loading | prop | ... | aria-disabled, focus kept, status msg | ... / ... | double press
Error | prop | ... | ... | ... / ... | ...
Empty | content | ... | part hidden, never "undefined" | n/a | ...
Long content | content | ... | wraps / truncates + full text / limit | ... / ... | real long text
Translated | content | ... | room for growth | ... / ... | ...
200% / 320px | content | ... | reflows, no sideways scroll | ... / ... | ...
- Inclusive ComponentsHeydon PickeringBook · 2019 (Amazon)
- Button patternWAI-ARIA APG (external site)
- Understanding 4.1.3 Status MessagesW3C (external site)
- Text size in translationW3C (external site)
- ButtonGOV.UK Design System (external site)
"See on Amazon" links are affiliate links. As an Amazon Associate I earn from qualifying purchases, at no extra cost to you.