Marcus Andrey Study
Ler em português Library

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.

IInteraction

Set by the browser, from what the person does.

Hover, focus, pressed
CComponent

Set by the product, through a prop.

Disabled, loading, selected, error
DData

Set by the content the component receives.

Empty, long, missing, failed
1Design

A real frame for every state, in every mode.

Next to the variants
2Behaviour

The attribute, where focus goes, what is announced.

Loading keeps focus
3Number

Measured contrast per state, plus a test with real content.

4.5:1 text, 3:1 ring

Every state (rows I, C, D) × every need (columns 1, 2, 3) = no empty cell at release

The three kinds of state a component has, and the three things each state needs before the component ships.

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

  1. 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.
  2. 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.
  3. Fill in behaviour from the pattern, not from memory. Disabled uses the HTML disabled attribute and leaves the Tab order. Loading uses aria-disabled="true", keeps focus on the element and ignores presses. A finished action is announced with a role="status" message. Output: the behaviour column, with sources.
  4. 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.
  5. 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.
  6. 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.
  • disabled for 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             | ... / ...             | ...
Source
Button pattern and aria-disabled: W3C WAI-ARIA Authoring Practices Guide. Contrast, status messages, reflow and target size: W3C, Understanding WCAG 2.2 (1.4.3, 1.4.11, 4.1.3, 1.4.10, 2.5.8). Text growth in translation: W3C Internationalization
Where to find it
Design Systems in Practice: States and edge cases › Two kinds of state

"See on Amazon" links are affiliate links. As an Amazon Associate I earn from qualifying purchases, at no extra cost to you.

Saved only on this device.

↑ ↓ to move · Enter to open · Esc to close