{"id":"l-ds-3-3","courseId":"design-systems","lang":"en","kind":"lesson","summary":"Build every interaction state and accessibility behavior into components by default, including visible focus with :focus-visible, disabled and pressed states, and ARIA patterns that follow the WAI-ARIA Authoring Practices.","html":"

Northwind’s 2021 Button looked perfect in every screenshot, because screenshots only show the default state. In production it had no visible keyboard focus, its disabled style failed contrast on the Tidewater brand, and its “loading” state made the button shrink and the layout jump. None of that was in the Figma file. Components fail in their states, so the system has to design, build and test all of them.

\n

The state matrix

\n

Every interactive component gets a state matrix: one row per variant, one column per state. For Button:

\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
StateTriggerBuilt with
HoverPointer over it:hover
Focus visibleKeyboard focus:focus-visible
ActiveBeing pressed:active
DisabledNot availabledisabled or aria-disabled="true"
LoadingAction in progressaria-busy, stable width
PressedToggle is onaria-pressed="true"

Northwind designs every cell in Figma (as component variants) before anyone writes code, and the visual tests in Section 4 render every cell in every theme. When a contribution arrives with only default and hover designed, the review sends it back.

\n

Focus that people can see

\n

Keyboard users need to see where focus is; WCAG 2.2 requires it at level AA (2.4.7, Focus Visible). Mouse users usually don’t want a ring after clicking. :focus-visible resolves this: browsers apply it when focus should be visible, typically after keyboard navigation, and not after most mouse clicks.

\n
CSS
:root {\n  --nw-focus-ring-color: var(--nw-blue-600);\n  --nw-focus-ring-width: 2px;\n  --nw-focus-ring-offset: 2px;\n}\n\n.nw-button:focus-visible {\n  outline: var(--nw-focus-ring-width) solid var(--nw-focus-ring-color);\n  outline-offset: var(--nw-focus-ring-offset);\n}
\n

The ring is built from tokens, so dark mode and Tidewater can adjust it, and every component uses the same ring. It is an outline, not a box-shadow, because forced-colors modes like Windows contrast themes remove box shadows but keep outlines.

\n\n

Disabled, two ways

\n

The disabled attribute removes a button from the tab order and from activation. That’s right for most cases, but it creates a problem: keyboard and screen reader users can’t reach the button to learn why it is disabled.

\n

When you need an explanation, use aria-disabled="true" instead. The button stays focusable and is announced as unavailable; you connect the reason with aria-describedby; and because the browser won’t block the click for you, the component must:

\n
JavaScript
button.addEventListener('click', (event) => {\n  if (button.getAttribute('aria-disabled') === 'true') {\n    event.preventDefault();\n    event.stopImmediatePropagation();\n  }\n});
\n

The system’s Button does this internally, so teams set one prop and get the behavior. That’s the whole point of building accessibility in: forty teams won’t each remember stopImmediatePropagation, but one component can.

\n

Toggles, targets and patterns

\n

A button that switches something on and off is a toggle button. Mark its state with aria-pressed="true" or "false", and style that attribute so the visual and announced states can’t drift apart:

\n
CSS
.nw-button[aria-pressed=\"true\"] {\n  --nw-button-bg: var(--nw-color-action-bg-subtle);\n  --nw-button-border: var(--nw-color-action-bg);\n}
\n

Size matters too: WCAG 2.2 success criterion 2.5.8 asks for pointer targets of at least 24 by 24 CSS pixels at level AA, with some exceptions. Northwind’s smallest control height is 32px, enforced by the sm size tokens.

\n

For anything beyond a button, use native elements first: <button>, <dialog>, <details>, <select>. When you build a custom widget such as tabs, a menu button or a combobox, follow the matching pattern in the WAI-ARIA Authoring Practices Guide: its roles, states and keyboard interactions. Users of assistive technology expect those behaviors, and the guide documents them precisely.

\n\n

In the exercise, you fix a button set that hides keyboard focus and ignores its own disabled state. Next, you write the documentation that tells teams how to use all of this.

\n","toc":[{"id":"sec-1","text":"The state matrix","level":2},{"id":"sec-2","text":"Focus that people can see","level":2},{"id":"sec-3","text":"Disabled, two ways","level":2},{"id":"sec-4","text":"Toggles, targets and patterns","level":2}],"takeaways":["Design and build a full state matrix for every interactive component, including focus, disabled, loading and pressed, not just default and hover.","Style keyboard focus with :focus-visible and an outline from a token; never remove the outline without a visible replacement.","Use native elements first and follow the WAI-ARIA Authoring Practices for custom widgets like tabs, menus and comboboxes.","aria-disabled="true" keeps a control focusable so you can explain why it is unavailable, but you must block its action yourself.","When accessibility lives in the component, 40 teams get it for free; when it lives in the docs, most of them miss it."],"further":[{"title":":focus-visible (MDN)","url":"https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Selectors/:focus-visible"},{"title":"WAI-ARIA Authoring Practices Guide patterns (W3C)","url":"https://www.w3.org/WAI/ARIA/apg/patterns/"},{"title":"Understanding SC 2.5.8 Target Size (Minimum) (W3C)","url":"https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html"},{"title":"aria-pressed (MDN)","url":"https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-pressed"}],"quiz":[{"q":"

A team ships .nw-button:focus { outline: none; } because the ring “looks ugly on click”. What’s the right fix in the system?

","options":[{"text":"Keep outline: none and rely on the hover color for keyboard users.","why":"Keyboard users don’t hover, so they lose any indication of where they are."},{"text":"Move the ring to :focus-visible so it shows for keyboard focus but not for most mouse clicks.","why":"Correct. Browsers apply :focus-visible when focus needs to be visible, which is what both groups actually want."},{"text":"Replace the outline with a box-shadow ring on :focus.","why":"It still shows on click, and box shadows are removed in forced-colors modes, so high-contrast users lose the ring."},{"text":"Add tabindex="-1" to buttons so they can’t get focus.","why":"That removes buttons from the keyboard order entirely, making them unusable without a mouse."}],"answer":1},{"q":"

The Save button is unavailable until a driver is selected. Product wants a tooltip explaining why. Which approach works?

","options":[{"text":"Use the disabled attribute and attach the tooltip to the button.","why":"A disabled button can’t receive focus, so keyboard and screen reader users never reach the tooltip."},{"text":"Hide the button until a driver is selected.","why":"Hiding it removes the hint that saving is possible at all, and the layout jumps when it appears."},{"text":"Set aria-disabled="true", keep it focusable, block the click in code, and connect the explanation with aria-describedby.","why":"Correct. The control stays reachable and announced as unavailable, and the reason is available to everyone."}],"answer":2},{"q":"

Northwind needs a “Show only late shipments” toggle button. Which markup communicates its state correctly?

","options":[{"text":"<button type="button" aria-pressed="true">Show only late shipments</button>","why":"Correct. aria-pressed turns a button into a toggle, and screen readers announce it as pressed or not pressed."},{"text":"<button type="button" class="is-active">Show only late shipments</button>","why":"The class changes the look but tells assistive technology nothing about the state."},{"text":"<div role="button" data-on="true">Show only late shipments</div>","why":"A div needs keyboard handling and focusability added by hand, and data-on isn’t exposed to assistive technology."},{"text":"<button type="button" aria-label="on">Show only late shipments</button>","why":"The label replaces the visible name with “on”, which is worse than saying nothing."}],"answer":0},{"q":"

Why does Northwind draw focus rings with outline rather than box-shadow?

","options":[{"text":"Outlines are faster to render.","why":"Rendering cost isn’t a meaningful difference here."},{"text":"Box shadows can’t use custom properties.","why":"They can; any CSS value can come from a custom property."},{"text":"Outlines always render outside the border box, so offsets are impossible with shadows.","why":"Both can create gaps; outline-offset is just more convenient. The deciding reason is elsewhere."},{"text":"Forced-colors modes such as Windows contrast themes remove box shadows but keep outlines.","why":"Correct. An outline-based ring survives high-contrast settings, so those users still see focus."}],"answer":3}],"exercise":{"kind":"web","mode":"dom","starter":{"html":"
\n \n \n \n

Select a driver before saving.

\n
\n

Saved 0 times

","css":":root {\n --nw-blue-600: #1f5ae0;\n --nw-blue-50: #eaf0fd;\n --nw-gray-200: #d9dee3;\n --nw-gray-500: #7b8794;\n --nw-color-action-bg: var(--nw-blue-600);\n --nw-color-action-bg-subtle: var(--nw-blue-50);\n --nw-color-text-disabled: var(--nw-gray-500);\n --nw-color-border: var(--nw-gray-200);\n --nw-focus-ring-color: var(--nw-blue-600);\n --nw-focus-ring-width: 2px;\n --nw-focus-ring-offset: 2px;\n}\n.nw-button {\n --nw-button-bg: #ffffff;\n --nw-button-text: #1f2933;\n --nw-button-border: var(--nw-color-border);\n background: var(--nw-button-bg);\n color: var(--nw-button-text);\n border: 1px solid var(--nw-button-border);\n padding: 8px 16px;\n border-radius: 6px;\n font: inherit;\n cursor: pointer;\n}\n.nw-button:focus {\n outline: none;\n}\n","js":"let saves = 0;\nconst log = document.querySelector('#log');\nconst save = document.querySelector('#save');\nconst late = document.querySelector('#late');\n\nsave.addEventListener('click', () => {\n saves += 1;\n log.textContent = `Saved ${saves} times`;\n});\n\nlate.addEventListener('click', () => {\n // Toggle the filter here\n});\n"},"solution":{"html":"
\n \n \n \n

Select a driver before saving.

\n
\n

Saved 0 times

","css":":root {\n --nw-blue-600: #1f5ae0;\n --nw-blue-50: #eaf0fd;\n --nw-gray-200: #d9dee3;\n --nw-gray-500: #7b8794;\n --nw-color-action-bg: var(--nw-blue-600);\n --nw-color-action-bg-subtle: var(--nw-blue-50);\n --nw-color-text-disabled: var(--nw-gray-500);\n --nw-color-border: var(--nw-gray-200);\n --nw-focus-ring-color: var(--nw-blue-600);\n --nw-focus-ring-width: 2px;\n --nw-focus-ring-offset: 2px;\n}\n.nw-button {\n --nw-button-bg: #ffffff;\n --nw-button-text: #1f2933;\n --nw-button-border: var(--nw-color-border);\n background: var(--nw-button-bg);\n color: var(--nw-button-text);\n border: 1px solid var(--nw-button-border);\n padding: 8px 16px;\n border-radius: 6px;\n font: inherit;\n cursor: pointer;\n}\n.nw-button:focus-visible {\n outline: var(--nw-focus-ring-width) solid var(--nw-focus-ring-color);\n outline-offset: var(--nw-focus-ring-offset);\n}\n.nw-button[aria-pressed=\"true\"] {\n --nw-button-bg: var(--nw-color-action-bg-subtle);\n --nw-button-border: var(--nw-color-action-bg);\n}\n.nw-button[aria-disabled=\"true\"] {\n --nw-button-text: var(--nw-color-text-disabled);\n cursor: not-allowed;\n}\n","js":"let saves = 0;\nconst log = document.querySelector('#log');\nconst save = document.querySelector('#save');\nconst late = document.querySelector('#late');\n\nsave.addEventListener('click', () => {\n if (save.getAttribute('aria-disabled') === 'true') return;\n saves += 1;\n log.textContent = `Saved ${saves} times`;\n});\n\nlate.addEventListener('click', () => {\n const pressed = late.getAttribute('aria-pressed') === 'true';\n late.setAttribute('aria-pressed', String(!pressed));\n});\n"},"checks":[{"id":"focus-visible-rule","test":"const rules = [...document.styleSheets].flatMap((s) => [...s.cssRules]).filter((r) => r.selectorText); const fv = rules.filter((r) => r.selectorText.includes(':focus-visible')); const plainFocus = rules.filter((r) => /:focus(?![-\\w])/.test(r.selectorText) && /outline/.test(r.style.cssText) && /none|0px/.test(r.style.outlineStyle + r.style.outline + r.style.outlineWidth)); return fv.length > 0 && plainFocus.length === 0;"},{"id":"ring","test":"const b = $('#assign'); b.focus(); const ok = b.matches(':focus-visible') && style(b, 'outline-style') === 'solid' && style(b, 'outline-width') === '2px' && style(b, 'outline-color') === 'rgb(31, 90, 224)' && style(b, 'outline-offset') === '2px'; b.blur(); return ok;"},{"id":"toggle","test":"const b = $('#late'); click(b); await tick(); const on = b.getAttribute('aria-pressed') === 'true' && style(b, 'background-color') === 'rgb(234, 240, 253)'; click(b); await tick(); return on && b.getAttribute('aria-pressed') === 'false' && style(b, 'background-color') === 'rgb(255, 255, 255)';"},{"id":"blocked","test":"click($('#save')); await tick(); return text('#log') === 'Saved 0 times';"},{"id":"disabled-look","test":"return style('#save', 'color') === 'rgb(123, 135, 148)' && style('#save', 'cursor') === 'not-allowed';"}],"title":"Build focus, toggle and disabled states in","prompt":"

This toolbar hides keyboard focus and ignores its own states. Fix it in CSS and JS:

\n
    \n
  1. Remove the :focus { outline: none } rule and add a :focus-visible ring: a solid outline using --nw-focus-ring-width, --nw-focus-ring-color and an outline-offset of --nw-focus-ring-offset.
    2. \n
  2. Make Show only late a real toggle: each click flips aria-pressed between "true" and "false". When pressed, its background is --nw-color-action-bg-subtle and its border --nw-color-action-bg.
    3. \n
  3. Save route has aria-disabled="true": clicking it must not save, its text uses --nw-color-text-disabled, and its cursor is not-allowed.
    4. \n
\n","hints":["Style states by their attributes: .nw-button[aria-pressed="true"] and .nw-button[aria-disabled="true"]. Override the component tokens inside them.","In the toggle’s click handler, read aria-pressed, then set it to the opposite with setAttribute('aria-pressed', String(!pressed)).","At the top of the save handler, return early when save.getAttribute('aria-disabled') === 'true'."],"explanation":"

The ring now appears for keyboard focus via :focus-visible and comes from tokens, so every component and theme can share it. The toggle’s look is driven by aria-pressed, so the visual state and the announced state can never disagree. aria-disabled keeps Save focusable so its aria-describedby explanation is reachable, which is why the click handler has to guard the action itself. In the real system, the Button component does all of this internally, and teams get it by default.

\n","checkLabels":{"focus-visible-rule":"Focus styling uses :focus-visible, and no :focus rule removes the outline","ring":"Keyboard focus shows a 2px solid ring in the focus color with a 2px offset","toggle":"Clicking Show only late toggles aria-pressed and its pressed styling","blocked":"Clicking the aria-disabled Save button doesn’t save","disabled-look":"Save uses the disabled text color and a not-allowed cursor"}},"words":659,"readMinutes":3}