Marcus Andrey Study
Ler em português Library

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

primary · Rest: hover it, Tab to it

Hover darkens; focus adds a 3 px ring

Disabled

Not focusable; WCAG asks no contrast of it

Loading

Still focusable, presses ignored

secondary · Rest: hover it, Tab to it

Hover darkens; focus adds a 3 px ring

Disabled

Not focusable; WCAG asks no contrast of it

Loading

Still focusable, presses ignored

danger · Rest: hover it, Tab to it

Hover darkens; focus adds a 3 px ring

Disabled

Not focusable; WCAG asks no contrast of it

Loading

Still focusable, presses ignored

Three variants of Harbour's Button in the states every variant must have. The first column is live: point at it, or press Tab until it's focused. Disabled uses the real 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 token button.primary.padding-inline from Token tiers, pointing at space.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: reduce the 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 disabled attribute. 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 unlike disabled, 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

Long namesWraps; never cut with an ellipsis

Kestrel Bay Ferry Terminal, North Pier → Mara Island Old Harbour

On time

09:40 · 50 min · Fri 4 Dec

Passengers
2 adults
TranslatedPortuguese labels run longer; the layout makes room

Kestrel Bay → Ilha de Mara

No horário

09:40 · 50 min · sexta-feira, 4 de dezembro

Passageiros
2 adultos
Missing dataNo vehicle and no status yet: the parts disappear, never "undefined"

Kestrel Bay → Mara Island

09:40 · 50 min · Fri 4 Dec

CancelledStatus in words, not only colour; a way forward

Kestrel Bay → Mara Island

Cancelled

09:40 · 50 min · Fri 4 Dec

Passengers
2 adults
LoadingA skeleton the same size as the card, so nothing jumps
Failed to loadSays what happened and what to do

We couldn't load this ticket

Check your connection. Your booking is safe.

One component, six situations it will meet in production. The happy card is the easy one; these are the ones that need a decision written in the docs. Each card here is the same Ticket card markup with different content.

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 disabled for 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)

  1. Pick one component in a product you know, like a list item or a card.
  2. Write its states as a grid: interaction states across, variants down. Which cells exist today?
  3. 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

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.

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

Saved only on this device.

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