/accessibility-per-component

name: accessibility-per-component
description: "Run an accessibility audit on a specific design system component. Trigger when someone says: accessibility check, a11y audit, WCAG compliance, is this accessible, check accessibility, does this meet WCAG, screen reader support, keyboard navigation check, or anything about auditing the accessibility of a specific component."
references:
  - ../../knowledge-notes/output-discipline.md

Accessibility per component

A skill for running a structured accessibility audit on a design system component, covering five dimensions: keyboard navigation, screen reader experience, colour and contrast, focus management, and ARIA implementation. Produces a PASS/FAIL/WARN per criterion with specific remediation guidance.

Context

Accessibility audits at the component level are more valuable than page-level or system-level assessments because they fix the problem at its source. A component with a correct accessibility implementation propagates that correctness to every product that uses it. A component with an accessibility bug propagates that bug at the same scale.

This skill audits against WCAG 2.1 AA as the baseline. Where a criterion is more stringent at AAA and the difference matters practically (particularly around colour contrast and keyboard accessibility), this is noted. The output is not a compliance report — it is a practical guide to what needs to change and why.

Boundaries

This skill audits a single component at a time. If the request is for a page-level or full-product accessibility audit, escalate to a dedicated accessibility review process — this skill is not designed for that scope. If no specific component is identified, ask which component to audit before proceeding. If the component has no implementation yet (design only, no code), note that the audit covers design intent only and flag code-level checks as pending.

---

Step 1: Gather component information

Ask for or confirm:

• Component name and its design system context
• Access to the component for testing: Storybook, a live implementation, or a design file
• The component's interactive states (default, hover, focus, active, disabled, error, etc.)
• Any existing accessibility documentation for the component
• Whether the component is used in any assistive technology-sensitive contexts (financial, medical, government — these warrant extra rigour)

If the component can only be assessed from a design file rather than a live implementation, note that the keyboard and screen reader dimensions are being assessed against the specification rather than the built behaviour. These findings should be verified against the implementation before being marked as passing.

Step 2: Run the five-dimension audit

Dimension 1: Keyboard navigation

Every interactive component must be fully operable by keyboard alone. Assess:

**Tab order**

• Does the component receive keyboard focus in a logical order relative to surrounding content?
• If the component is a composite widget (e.g. a modal, a menu, a tab panel), is the internal tab order logical?

**Activation**

• Can the component's primary action be triggered with Enter?
• If the component behaves like a button (not a link), can it also be triggered with Space?
• For components with multiple actions (e.g. a dropdown with options), are all actions keyboard accessible?

**Arrow key navigation**

• For composite widgets (menus, tab panels, radio groups, listboxes), is arrow key navigation implemented correctly per the ARIA Authoring Practices Guide (APG) pattern for this widget type?

**Escape key**

• For components that open a layer (modal, popover, tooltip, dropdown), does Escape close it and return focus correctly?

**Skip/bypass mechanisms**

• If the component contains a large block of content (e.g. a data table), is there a mechanism to skip past it?

Result per criterion: PASS / FAIL / WARN (warn = partially implemented or needs verification in a specific context)

Dimension 2: Screen reader experience

Assess the experience for a screen reader user navigating with keyboard focus:

**Role announcement**

• Does the component announce the correct ARIA role? Is the role appropriate for how the component behaves?
• FAIL example: a custom dropdown built from a `<div>` with no role — announces as nothing
• PASS example: `role="combobox"` on an autocomplete input

**State announcement**

• Are interactive states announced correctly? Expanded/collapsed, checked/unchecked, selected, disabled, required, invalid
• FAIL example: a toggle switch with no `aria-checked` — the state is not communicated
• PASS example: `aria-checked="true"` toggling to `aria-checked="false"` with a live region or label change

**Name computation**

• Does the component have an accessible name? Is it descriptive enough to be meaningful out of context?
• For form elements: is the label correctly associated (via `for`/`id`, `aria-labelledby`, or `aria-label`)?
• For icon-only buttons: is there an accessible name via `aria-label` or visually hidden text?
• FAIL example: an icon button with no accessible name — announces only as "button"

**Group labelling**

• If the component is part of a group (radio group, checkbox group, fieldset), is the group correctly labelled?

**Live regions**

• If the component produces dynamic content changes (error messages appearing, status updates), are these communicated via `aria-live` or an appropriate role?

**Instructions and descriptions**

• If the component requires usage instructions to be usable (e.g. a date picker, a password field with requirements), are these instructions programmatically associated via `aria-describedby`?

Result per criterion: PASS / FAIL / WARN

Dimension 3: Colour and contrast

**Text contrast**

• All text within the component must meet a minimum 4.5:1 contrast ratio against its background at WCAG AA (3:1 for large text — 18pt regular or 14pt bold).
• Check all text at all states: default, hover,