Marcus Andrey Study
Ler em português Library

Design Systems · Step 3 · 8 min read

Accessible components

Accessibility built into a component reaches every screen that uses it; a mistake in one reaches them too. Start from native HTML, follow the WAI-ARIA Authoring Practices patterns where they exist, and write down what the component guarantees and what the product still owns. With Harbour's Button, Text field and Ticket card.

A design system multiplies whatever you put in it, including the bugs. Fix the focus order of Harbour's dialog once and every product gets it in the next release. Ship a text field whose error isn't announced, and two hundred forms have the same problem by Friday. That's why accessibility belongs in the component itself, written down as a contract, and tested before release, not audited screen by screen afterwards.

What you'll be able to do after reading:

  • Start a component from native HTML and add ARIA only where HTML stops
  • Use the WAI-ARIA Authoring Practices patterns for keyboard and roles
  • Build a text field whose label, hint and error reach a screen reader
  • Write a component's accessibility contract: what it guarantees, what the product owns

1. Start with HTML

Accessibility fundamentals covers the basics: perceivable, operable, understandable, robust. For components, two rules from W3C come first.

  • The first rule of ARIA use: "If you can use a native HTML element or attribute with the semantics and behavior you require already built in, instead of re-purposing an element and adding an ARIA role, state or property to make it accessible, then do so" (W3C, Using ARIA).
  • No ARIA is better than bad ARIA. The Authoring Practices Guide opens with it: "Incorrect ARIA misrepresents visual experiences, with potentially devastating effects" for screen reader users (APG, Read Me First).

So Harbour's Button renders a real <button>, which brings focus, Enter and Space for free. Its Text field renders a real <input> with a real <label>. ARIA only comes in for things HTML has no element for, like a combobox's open list.


2. Follow the patterns that exist

The WAI-ARIA Authoring Practices Guide (APG) describes, for each common widget, the keyboard behaviour people expect and the roles, states and properties that go with it. Harbour links every component to its pattern, or says why there isn't one:

Harbour componentAPG patternKeyboardRoles, states, properties
ButtonButtonEnter and Space activateA real <button>; aria-disabled="true" while loading; aria-pressed only for toggles
Text fieldNone: native HTML is the patternTab in, type, Tab out<label for>; hint and error linked with aria-describedby; aria-invalid="true" on error; autocomplete
Ticket cardNone: a card is a group, not a widgetTab moves through its actions onlyThe route is a heading; no role on the card; one control per action
Port pickerCombobox↓ opens the list and moves into it, Esc closes itrole="combobox", aria-expanded, aria-controls, aria-activedescendant
Cancel booking dialogDialog (Modal)Tab stays inside; Esc closes; focus goes back to the button that opened itrole="dialog", aria-modal="true", aria-labelledby the dialog title
Ticket detailsDisclosureEnter and Space show and hideA button with aria-expanded true or false
Harbour's accessibility contract, one row per component. Where the WAI-ARIA Authoring Practices Guide has a pattern, the component follows it and links to it; where it doesn't, the answer is plain HTML. This table belongs on every component's doc page.Patterns: W3C, ARIA Authoring Practices Guide.

What the patterns ask for, in Harbour's components:

  • Button pattern. Space and Enter activate it. "When the action associated with a button is unavailable, the button has aria-disabled set to true", which is how Harbour's loading state works. For toggles, aria-pressed, and a warning worth copying into your docs: "it is critical the label on a toggle does not change when its state changes" (APG, Button).
  • Dialog (Modal) pattern. Focus moves into the dialog when it opens, Tab and Shift+Tab stay inside, Escape closes it. The container has role="dialog", aria-modal="true" and a label from its visible title (APG, Dialog (Modal)). Harbour's "Cancel booking" dialog does all of it, so no product team has to.
  • Combobox pattern. The port picker: Down Arrow opens the list and moves into it, Escape closes it, and DOM focus stays on the input while aria-activedescendant points at the highlighted option (APG, Combobox). This is the hardest pattern in the list; it's exactly the kind of thing a system should build once.
  • Disclosure pattern. "Show details" on a ticket: a button with aria-expanded set to true or false (APG, Disclosure).

3. When there's no pattern: the Text field

There's no APG pattern for a text field, because HTML already has one. The work is in connecting the parts.

As it appears on your passport or ID card Enter the surname of passenger 2
We only use it if your sailing changes
Harbour's Text field, real and focusable, in its error state. The label is a <label for>; the hint and the error are tied to the input with aria-describedby, so a screen reader reads all three when the field gets focus; aria-invalid="true" says the value is wrong. The error is in words with an icon, not only a red border. Tab into both fields.
  • A visible label, linked with for. The GOV.UK Design System asks for labels that are visible, above the input, short and in sentence case, and warns: "Do not use placeholder text in place of a label", because it vanishes when people type and not all screen readers read it (GOV.UK, Text input; W3C, Labeling controls).
  • Hint and error tied in with aria-describedby, so they're read with the label (MDN, aria-describedby).
  • aria-invalid="true" when the value is wrong (MDN, aria-invalid), and the error in words, not only a red border (W3C, Understanding 3.3.1 Error Identification).
  • autocomplete with the right value, so browsers can fill it in. GOV.UK recommends it for the same reason.

The component builds all of this from three props, label, hint and error. The product team never writes an id or an aria-describedby by hand, so they can't get it wrong.


4. When there's no pattern: the Ticket card

A card isn't a widget; it's a group of content. It doesn't need a role. What it needs:

  • A heading for the route, so screen reader users can jump from ticket to ticket. The heading level is a prop, because only the page knows its outline.
  • One control per action, in a sensible order. Tab goes to "Show ticket", then "Get a refund", and nowhere else.
  • Status in words. "Cancelled" is text inside the badge, not just a coral border (W3C, Understanding 1.4.11 for the border's contrast).

Heydon Pickering's chapter on cards shows the case of a card that's clickable as a whole: keep one real link inside and stretch it over the card with a pseudo-element, instead of wrapping everything in a link (Pickering, Inclusive Components: Cards). The Ticket card has two actions, so it doesn't do that: a whole-card link would hide the second button.


5. The accessibility contract

Write down, on each component's doc page, what the component guarantees and what the product still has to do. Harbour's Button:

The component guarantees The product owns
A real <button>; Enter and Space work A label that says what happens: "Book crossing", not "Click here"
A focus ring of 3 px, 3:1 or more in both modes Not hiding it under a sticky header
A target of 44 px (32 px compact), above WCAG's 24 px minimum (Understanding 2.5.8) Enough space between buttons in a row
Loading keeps focus; presses ignored Announcing the result with a status message
Text contrast measured in every state Not overriding colours

Then test the component, not just the screens: keyboard only, a screen reader (VoiceOver on Mac and iOS, NVDA on Windows), 200% zoom and 320 px width. A component that passes is one less thing to check on every page. W3C's free Digital Accessibility Foundations course is a good place for a whole team to start.


6. Common mistakes

  • A div with a click handler instead of a <button>.
  • Adding ARIA roles to elements that already have them, or roles that promise keyboard behaviour nobody built.
  • Placeholder text instead of a label.
  • Errors shown in red only, and not linked to the field.
  • A dialog that doesn't move focus in, or doesn't give it back when it closes.
  • Leaving the accessibility contract unwritten, so product teams don't know what's left for them.

7. Vocabulary

Term Meaning
ARIA Attributes that tell assistive technology what an element is and what state it's in
APG The WAI-ARIA Authoring Practices Guide: W3C's patterns for keyboard and roles
Role What an element is to assistive technology: button, dialog, combobox
Accessible name What a screen reader calls a control, usually from its label
aria-describedby Links extra text, like a hint or an error, to a control
Accessibility contract What a component guarantees, and what the product using it still owns

8. Try it (no tools needed)

  1. Open a form in a product you use. Put the mouse away.
  2. Tab to a field with an error. Is the error next to it, in words? Does it say how to fix it?
  3. Open a dialog. Where is the focus? Press Escape. Where does focus go?

Reflection questions: Which of those problems would disappear if they were fixed in one component? Who on your team would notice if they came back?


9. If you already practise

  • Link each component's doc page to its APG pattern, and copy the keyboard table into the docs.
  • Run automated checks in Storybook on every story, and keep a short manual test script per component for what tools can't catch.
  • Include people who use assistive technology in testing the hardest components: combobox, dialog, date picker.
  • Treat an accessibility bug in a component as a release blocker, because it ships everywhere.

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.

Composition over configuration · From components to patterns · Accessibility fundamentals · States and edge cases · Forms · Interactive states: hover, press, focus · Storybook and living documentation · Component accessibility checklist

Saved only on this device.

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