Design Systems · Step 3 · 8 min read
States and edge cases
A component isn't finished when the happy version looks right. Every Harbour component has interaction states the browser sets and data states the product sets, plus the edge cases real content brings: long names, translations, missing data, errors. A live button with the exact CSS, the contrast numbers, and a list to design against.
The happy version of a component is the one you'll see least. In the mockup, every ticket is on time, every name is short and the network never fails. In production, a German port name wraps to three lines, a sailing is cancelled at 06:00 and somebody's phone loses signal on the pier. A system component has to have an answer for all of that, designed once, so no product team improvises it at midnight.
What you'll be able to do after reading:
- Tell interaction states from data states, and who sets each
- Build hover, focus, disabled and loading into a component, with real CSS
- Measure the contrast of every state, not just the resting one
- List the edge cases a component must survive, and design them before release
1. Two kinds of state
| Who sets it | Examples | Where it's covered | |
|---|---|---|---|
| Interaction states | The browser, from what the person does | Hover, focus, pressed | Interactive states: hover, press, focus |
| Component states | The product, through a prop | Disabled, loading, selected, error | This lesson |
| Data states | The content | Empty, long, missing, failed | This lesson, and Interface states: empty, loading, error, success |
The Motion course explains how hover, press and focus should feel and how fast they should appear. Here the question is different: what does the system have to ship, so that every product gets the states right without designing them again?
2. One button, every state
Hover darkens; focus adds a 3 px ring
Not focusable; WCAG asks no contrast of it
Still focusable, presses ignored
Hover darkens; focus adds a 3 px ring
Not focusable; WCAG asks no contrast of it
Still focusable, presses ignored
Hover darkens; focus adds a 3 px ring
Not focusable; WCAG asks no contrast of it
Still focusable, presses ignored
disabled attribute; loading uses aria-disabled="true", so it stays in the Tab order. With reduced motion on, the spinner stops and becomes a dotted ring. Live CSS, the exact rules in the lesson.These are the rules that run in the figure, exactly. The colours come from Harbour's tokens, set per mode in a separate block; each variant only sets three component tokens.
.ds-b-btn {
display: inline-flex; align-items: center; justify-content: center; gap: var(--hb-space-2);
min-height: 44px; padding-block: var(--hb-space-2); padding-inline: var(--hb-space-5);
border: 2px solid transparent; border-radius: var(--hb-radius-control);
background: var(--hb-button-background); color: var(--hb-button-text);
font: 600 var(--hb-font-size-300)/1.2 var(--text); cursor: pointer;
transition: background-color 100ms linear, border-color 100ms linear;
}
@media (hover: hover) {
.ds-b-btn:hover { background: var(--hb-button-background-hover); }
}
.ds-b-btn:focus-visible { outline: 3px solid var(--hb-color-focus); outline-offset: 2px; }
.ds-b-btn:disabled { background: var(--hb-color-disabled-surface); border-color: transparent; color: var(--hb-color-disabled-text); cursor: not-allowed; }
.ds-b-btn[aria-disabled="true"] { background: var(--hb-button-background); cursor: progress; }
.ds-b-btn__spin { width: 1em; height: 1em; border: 2px solid currentColor; border-right-color: transparent; border-radius: 50%; animation: ds-b-spin 800ms linear infinite; }
@keyframes ds-b-spin { to { transform: rotate(1turn); } }
@media (prefers-reduced-motion: reduce) {
.ds-b-btn { transition: none; }
.ds-b-btn__spin { animation: none; border-style: dotted; border-right-color: currentColor; }
}
/* variants: each one only sets the component tokens */
.ds-b-btn--primary { --hb-button-background: var(--hb-color-action-primary); --hb-button-background-hover: var(--hb-color-action-primary-hover); --hb-button-text: var(--hb-color-on-action); }
Three things in that code are system decisions, not styling:
padding-inline: var(--hb-space-5)is the component tokenbutton.primary.padding-inlinefrom Token tiers, pointing atspace.5, 24 px. Nobody types 24.- Hover sits inside
@media (hover: hover), so phones don't get a hover that sticks after a tap (MDN, hover media feature). - Reduced motion is part of the component. With
prefers-reduced-motion: reducethe spinner stops and becomes a dotted ring (MDN, prefers-reduced-motion). The words "Booking…" still say what's happening, so nothing is lost.
3. Disabled and loading are not the same
Both say "not now", but they behave differently, and the difference matters to keyboard and screen reader users.
- Disabled uses the HTML
disabledattribute. The button leaves the Tab order and can't be pressed. The GOV.UK Design System is blunt about it: "Disabled buttons have poor contrast and can confuse some users, so avoid them if possible" (GOV.UK, Button). Harbour's rule: prefer an active button that explains what's missing when pressed; if you must disable, say why next to it. - Loading uses
aria-disabled="true". The WAI-ARIA button pattern uses this attribute "when the action associated with a button is unavailable" (APG, Button pattern), and unlikedisabled, it doesn't remove the element from the focus order (MDN, aria-disabled). Focus stays on the button, so the person isn't dropped at the top of the page. The component ignores presses while loading, which also stops double bookings. GOV.UK tells the same story from real life: the Notify team found people receiving invitations twice "because the person sending them was double clicking the 'send' button".
When the booking finishes, say so with a status message, a role="status" region the screen reader announces without moving focus (W3C, Understanding 4.1.3 Status Messages).
4. Measure every state
Contrast is checked on the resting button, then forgotten. Every state that carries text or a boundary needs its number. These are Harbour's, measured with the WCAG formula:
| State | Light mode | Dark mode |
|---|---|---|
| Primary, rest | White on blue.600 #1F5FAE: 6.35:1 |
ink.900 on blue.400 #5B95DB: 5.32:1 |
| Primary, hover | White on blue.700 #174A88: 8.86:1 |
ink.900 on #8AB4E8: 7.69:1 |
| Danger, rest | White on coral.600 #C2412D: 5.14:1 |
ink.900 on #E0705E: 5.23:1 |
| Focus ring against the page | #174A88 on sand.50: 8.35:1 |
#8AB4E8 on ink.900: 7.69:1 |
| Disabled label | #56636F on #E3E6E9: 4.92:1 | #9AA7B3 on #2A3642: 5.02:1 |
Text needs 4.5:1 and the focus ring, as a user interface component, needs 3:1 (W3C, Understanding 1.4.3; Understanding 1.4.11). WCAG doesn't require contrast for "an inactive user interface component", so the disabled row is a choice: Harbour keeps it readable anyway, because people still need to read what they can't press.
5. Edge cases: what real content does
Kestrel Bay Ferry Terminal, North Pier → Mara Island Old Harbour
On time09:40 · 50 min · Fri 4 Dec
Kestrel Bay → Ilha de Mara
No horário09:40 · 50 min · sexta-feira, 4 de dezembro
Kestrel Bay → Mara Island
09:40 · 50 min · Fri 4 Dec
Kestrel Bay → Mara Island
Cancelled09:40 · 50 min · Fri 4 Dec
We couldn't load this ticket
Check your connection. Your booking is safe.
Interaction states are the same for every product. Edge cases depend on the content, and they're where components break. The ones every Harbour component is tested with:
- Long content. Real port names, long passenger names, three-line errors. Decide for each part: wrap, truncate with the full text available, or limit at entry. Routes always wrap.
- Translation. Short strings grow the most. W3C quotes IBM's figures: text up to 10 characters in English can be 200 to 300% as long in another language, and text over 70 characters about 130% (W3C Internationalization, Text size in translation). A 12-character button label needs room for about 24.
- Missing data. No vehicle, no status yet, no seat. The part disappears; it never shows "undefined", "null" or an empty label.
- Loading and failure. A skeleton the size of the real card, so nothing jumps; an error that says what happened and what to do. Feedback while waiting covers the timing.
- Zoom and small screens. Text must work at 200% (Understanding 1.4.4) and content must reflow at a width of 320 CSS pixels without scrolling sideways (Understanding 1.4.10).
- Density. The staff console's compact size, 32 px high: still above the 24 by 24 px minimum target of WCAG 2.2 (Understanding 2.5.8).
Put these in the component's Figma page as real frames, next to the variants, and in Storybook as stories (see Storybook and living documentation). An edge case that only lives in someone's head isn't designed.
6. Common mistakes
- Designing only the resting state and leaving hover, focus and disabled to the developer.
- Using
disabledfor loading, so focus jumps away mid-action. - A spinner that keeps spinning under reduced motion, or a spinner with no words.
- Checking contrast on the resting state only.
- Testing with "Lorem ipsum" and English only.
- Showing "undefined" or an empty row when data is missing.
7. Vocabulary
| Term | Meaning |
|---|---|
| Interaction state | A state the browser sets: hover, focus, pressed |
| Component state | A state the product sets through a prop: disabled, loading, selected |
aria-disabled |
Tells assistive technology a control is unavailable, without removing it from the Tab order |
| Status message | A change announced by a screen reader without moving focus, often with role="status" |
| Edge case | Content or conditions at the limits: very long, missing, failed, zoomed |
| Skeleton | A grey placeholder in the shape of the content that's loading |
8. Try it (no tools needed)
- Pick one component in a product you know, like a list item or a card.
- Write its states as a grid: interaction states across, variants down. Which cells exist today?
- Now write five edge cases for it, using the list in section 5. Sketch the worst one.
Reflection questions: Which state does your team design last? If the network failed right now, what would your most-used component show?
9. If you already practise
- Add a "states and edge cases" page to every component in Figma, and a story per state in code.
- Keep a test content set: the longest real names, a translated string, an empty record, a failed request.
- Record the contrast of every state in the component docs, in both modes, so nobody has to measure again.
- Review loading behaviour with a screen reader: does focus stay, and is the result announced?
Checklist
Learn more
- W3C: APG, Button pattern · Understanding 4.1.3 Status Messages · Understanding 1.4.10 Reflow · Text size in translation
- GOV.UK Design System, Button: disabled buttons and double clicks
- MDN: aria-disabled · prefers-reduced-motion
Books, courses and videos to go deeper
Book links go to Amazon. As an Amazon Associate I earn from qualifying purchases, at no extra cost to you.
Related
Variants, properties and slots · Composition over configuration · Interactive states: hover, press, focus · Interface states: empty, loading, error, success · Feedback while waiting · Token tiers · Storybook and living documentation · Accessible components · Component state matrix