Component spec Template

# Accessibility specification: [name of the component]

> Template version 1.0, 2026-10-07, from https://auricartisan.com/templates/component-spec/
> Licence: CC0 1.0 (https://creativecommons.org/publicdomain/zero/1.0/). Copy it, change it and use it for anything; no credit needed.
> Write this before the component is built, and keep it with the component in your design system.
> Replace everything in [square brackets], delete the parts that do not apply, then delete this note.

| Spec | |
|---|---|
| Component | [Name, as the design system calls it] |
| Spec version | [1.0] |
| Status | [Draft / In review / Agreed] |
| Owner | [Name, team] |
| Last reviewed | [YYYY-MM-DD] |
| Design | [Link to the design file] |
| Code | [Link to the code, or "Not built yet"] |
| Standard | [WCAG 2.2, Level AA] |

Licence: CC0 1.0 Universal, a public domain dedication. Copy, change and use these files for anything, including paid work, without asking or giving credit. The files are plain ASCII text in English, so they open the same everywhere.

1. Purpose. What the component is for, when to use it, and when to use something else.
2. Anatomy. Every part by name, so the design, the code and the spec use the same words.
3. Variants and states. Each size, style and state, how it looks, and how assistive technology is told about it.
4. Semantics. A native HTML element first, otherwise an ARIA role; then the accessible name, the states and the properties.
5. Keyboard. A table of each key, where focus is when it is pressed, and what it does.
6. Focus management. Where focus goes when something opens, closes, is deleted or shows an error.
7. Screen reader announcements. What is announced and when, with a live region only for a change away from focus.
8. Pointer and touch. Targets of at least 24 by 24 CSS pixels (2.5.8, Level AA) or one of its exceptions, an alternative to dragging, and content shown on hover.
9. Color and contrast. 4.5:1 for text, 3:1 for the parts of a control and its states, and never color alone.
10. Motion. What moves, and what replaces the movement when the reduced motion setting is on.
11. Content and language. Labels, error messages, text in other languages, and right-to-left layouts.
12. Test cases. Checklists for the keyboard, screen readers, zoom and reflow, pointer and touch, and automated checks.
13. Related patterns and references. The pattern it follows, the WCAG criteria that apply, and links to the design, the code and the tests.

Enter and Space come from the APG pattern; Tab and Shift+Tab are the browser's own, listed so that nothing overrides them. The button has aria-expanded: true when the content is shown, false when it is hidden. aria-controls, pointing at the content's id, is optional.

1. Start from a pattern. Find the closest pattern, on this site or in the APG, and take its semantics, keys and focus rules rather than inventing new ones. Browse the accessibility patterns
2. Fill it in together. Design, engineering and content each answer the sections they know best, and agree the rest before any code is written.
3. Decide focus and announcements on paper. Where focus goes after a close or a delete, and what a screen reader says when something changes, are easy to leave to chance. Write them down.
4. Turn the tests into acceptance criteria. Each test case in section 12 becomes a check the story must pass before it is done. Use the acceptance criteria template
5. Keep it with the component. Store it beside the component's code or its design system page, give it a version, and update it whenever the component changes.

• Acceptance criteriaGiven/When/Then criteria for common components, each tagged with its WCAG criterion, and a definition of done.
• Contrast matrixEvery pair of your palette's colors with its contrast ratio and what it passes, for text and for interface parts.
• Accessibility patternsWorking components with keyboard and screen reader notes, and code to copy
• WCAG 2.2Every success criterion, with live demos and tests