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 component | APG pattern | Keyboard | Roles, states, properties |
|---|---|---|---|
| Button | Button | Enter and Space activate | A real <button>; aria-disabled="true" while loading; aria-pressed only for toggles |
| Text field | None: native HTML is the pattern | Tab in, type, Tab out | <label for>; hint and error linked with aria-describedby; aria-invalid="true" on error; autocomplete |
| Ticket card | None: a card is a group, not a widget | Tab moves through its actions only | The route is a heading; no role on the card; one control per action |
| Port picker | Combobox | ↓ opens the list and moves into it, Esc closes it | role="combobox", aria-expanded, aria-controls, aria-activedescendant |
| Cancel booking dialog | Dialog (Modal) | Tab stays inside; Esc closes; focus goes back to the button that opened it | role="dialog", aria-modal="true", aria-labelledby the dialog title |
| Ticket details | Disclosure | Enter and Space show and hide | A button with aria-expanded true or false |
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-activedescendantpoints 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-expandedset 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.
<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).autocompletewith 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
divwith 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)
- Open a form in a product you use. Put the mouse away.
- Tab to a field with an error. Is the error next to it, in words? Does it say how to fix it?
- 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
- W3C: ARIA Authoring Practices Guide, patterns · Read Me First · Using ARIA · Labeling controls
- APG patterns used here: Button · Dialog (Modal) · Combobox · Disclosure
- GOV.UK Design System, Text input · Heydon Pickering, Inclusive Components: Cards
Books, courses and videos to go deeper
- Inclusive ComponentsHeydon PickeringBook · Smashing Magazine, 2019 (Amazon)
- Digital Accessibility FoundationsW3C WAICourse · free, online course (external site)
Book links go to Amazon. As an Amazon Associate I earn from qualifying purchases, at no extra cost to you.
Related
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