skip to content

On a design system's component documentation page, what should the accessibility section tell designers and engineers who use the component?

level: middleimportance: should knowfreq 30%

answer

  1. built in versus still yours
  2. keyboard table, key by key
  3. what assistive tech announces
  4. labels the consumer must supply
  5. criteria the component addresses

basics

~20 s

What the component already handles - its role, keyboard interaction and announcements - and what consumers must still do, such as supplying a meaningful label, preserving contrast and target size in their layout, and testing the finished page.

solid answer

~50 s

The section splits **built-in behaviour** from **consumer obligations**. Built in: the component's role and states, a **keyboard interaction table** key by key, what a screen reader announces, focus behaviour, and which WCAG 2.2 criteria it addresses. Consumer obligations: supply a **meaningful accessible name**, do not signal meaning by color alone, keep contrast and **target size** intact when placing it, and test the finished screen. For a radio group used as a ticket-type selector, the table would say that Tab moves focus into the group, landing on the checked option or the first one; arrow keys move focus and select the next or previous option, wrapping at the ends; and Space selects the focused option if it is not already selected. Designers need the obligations as much as engineers, because labels and layout are decided in design.

go deeper

for a junior

Recall that the section separates what the component already handles from what you must still do when using it, such as providing a label.

for a middle

Explain the keyboard table for a standard pattern, what screen readers announce, and which WCAG criteria and thresholds the component is tested against.

for a senior

Show how you would make consumer obligations hard to miss across many pages and platforms, including writing them for designers who decide labels and layout.

for a principal

Weigh how much accessibility the system builds in versus documents as obligation, since every obligation left to consumers is one some team will miss.

## Why the section exists Every component page on a design system's documentation site should have an **accessibility section**. A design system can build a lot of accessibility into a component, but not all of it: whether the finished screen is accessible also depends on how the component is labelled, placed and combined. The section tells readers **exactly where that line falls**, so they neither redo work the component already does nor assume it does work it cannot do. ## Two halves: built in, and still yours | Built into the component | Still the consumer's job | |---|---| | its role, states and properties exposed to assistive technology | a meaningful accessible name for the instance | | keyboard interaction | a sensible place in the screen's focus order | | visible focus indicator | not covering it with sticky content or overlays | | contrast of its own parts in every supported theme | contrast against custom backgrounds the consumer adds | | a target size meeting the system's rules | not shrinking or crowding it in a dense layout | | announcements of its own state changes | not conveying meaning by color alone in surrounding content | ## The keyboard interaction table The most used part of the section is a key-by-key table. It should follow the **WAI-ARIA Authoring Practices** pattern for that kind of widget where one exists, so keyboard users meet familiar behaviour. Take a museum ticketing kiosk whose ticket-type selector is a **radio group** (adult, child, concession). Following the Authoring Practices radio group pattern: | Key | Behaviour | |---|---| | Tab / Shift+Tab | move focus into and out of the group; on entry, focus lands on the checked option, or the first option if none is checked | | Down Arrow / Right Arrow | move focus to the next option and check it; from the last option, wrap to the first | | Up Arrow / Left Arrow | move focus to the previous option and check it; from the first option, wrap to the last | | Space | check the focused option if it is not already checked | The same selector runs on the museum's web booking site and on the kiosk. The kiosk may have an accessible keypad and audio output rather than a full keyboard, which is why documenting the interaction model, rather than one device's keys only, matters. ## What to include beyond the keyboard 1. **Screen reader output**: what is announced on focus - the role, the name, the checked state, often the position in the group - and what is announced on change. 2. **Naming**: the group needs a label, typically its visible heading, and each option is named by its own text. 3. **Criteria addressed**: the WCAG 2.2 success criteria the component was tested against, such as 2.1.1 Keyboard (A), 4.1.2 Name, Role, Value (A), 1.4.3 Contrast (Minimum) at 4.5:1 for text (AA), 1.4.11 Non-text Contrast at 3:1 for the radio indicators (AA), and 2.5.8 Target Size (Minimum) at 24 by 24 pixels with a spacing exception (AA). 4. **Platform notes**: where web and native mobile differ in how the component exposes its name and state. 5. **Known limitations**: anything not yet supported, with any workaround. Touch kiosks commonly use targets well above the AA minimum - often around the 44 by 44 of the AAA criterion 2.5.5 or larger - because visitors may have limited reach or dexterity; that is common practice, not an AA requirement. ## Writing for designers too Many obligations are decided in design, before code exists: the label wording, the order of controls, whether sold-out tickets are shown only by a grey color. So the section is written for **both** disciplines, in plain language, and is not hidden behind an engineering-only tab. ## Common mistakes - A single sentence such as 'this component is accessible', which tells readers nothing they can act on. - Listing only built-in behaviour, so consumers assume there is nothing left for them to do. - A keyboard model invented per component instead of following the established pattern readers already know. - Hiding the section where designers never look.

  • Why should a component page's keyboard table follow the WAI-ARIA Authoring Practices pattern where one exists?
    Keyboard and screen reader users carry expectations from every other interface they use. A radio group that behaves like other radio groups - arrows moving and selecting, Tab leaving the group - is learnable immediately. An invented model forces users to discover it by trial, and the documentation then has to explain an unusual behaviour instead of a familiar one.
  • What should the accessibility section say about a sold-out ticket option shown only in grey?
    That color alone must not carry the meaning: WCAG 2.2 criterion 1.4.1 Use of Color is level A. The section should tell consumers to add a text or icon cue such as a 'sold out' label, and say how the component exposes the unavailable state to assistive technology, for example as disabled.

saying these in an interview costs you the question

  • A statement that the component is accessible is enough for the accessibility section.
  • If the component handles keyboard access, consumers have no accessibility obligations left.
  • In a radio group, Tab should move between each option in turn.
  • The accessibility section is for engineers only, so it can live on the code tab.
  • Target size of 44 by 44 pixels is the WCAG 2.2 AA minimum.