/accessibility-per-component

name: accessibility-per-component
description: "Audit one design system component's accessibility against WCAG 2.2 AA: keyboard, screen reader, contrast, focus, ARIA, target size. Trigger: a11y audit, is this accessible, WCAG check, screen reader support, keyboard navigation check. Not for page- or product-wide audits."
allowed-tools: Read, Write, Grep, Glob, Bash(cat:*), Bash(find:*), Bash(head:*), Bash(ls:*), Bash(npx axe:*), Bash(npx test-storybook:*), Bash(npx playwright:*)
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.

Before you begin: verify references

Confirm that every path in this skill's frontmatter `references:` exists relative to this SKILL.md. If any is missing, stop: the install is incomplete, usually because a flattening installer (for example `npx skills install`) dropped the repo-root `knowledge-notes/` directory. Tell the user to reinstall by a method in `1-INSTALL.md` and run `verify-install.sh` from the install root. Proceed without the references only if the user explicitly says to, and then say in the output that it was produced without the pack's reference material.

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.2 AA as the baseline. Some legal baselines (e.g. EN 301 549) still reference WCAG 2.1 AA; use that if it's the team's obligation. Where a criterion is more stringent at AAA and the difference matters practically (particularly around colour contrast and keyboard accessibility), this is noted. 4.1.1 Parsing is obsolete in WCAG 2.2 — don't cite it. The output is not a compliance report — it is a practical guide to what needs to change and why.

**Evidence rule.** PASS requires evidence from the running component or a computed ratio. Code-only inference is ⚠️ WARN (unverified). Overall status = the worst criterion result.

Configuration

If `.ds-ops-config.yml` exists, follow the configuration-and-recurring knowledge note (`../../knowledge-notes/configuration-and-recurring.md`) for loading, integration fallbacks and recurring runs. This skill reads:

• `severity.missing_aria` — severity for missing or incorrect ARIA findings (default: critical)
• `gates.accessibility.keyboard_blocks_release` and `gates.accessibility.contrast_blocks_release` — whether keyboard and contrast FAILs block release (both default: true). If a gate is set to false, still report the FAIL, and note that it does not block release under the team's config.

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)

**Find the runtime evidence before auditing.** PASS needs the running component, so look for what can run it: a Storybook with the test-runner or the a11y addon (`npx test-storybook --url <storybook>` runs axe per story), `jest-axe` or `vitest-axe` tests in the repo, a Playwright setup with `@axe-core/playwright`, or a dev server. If any exists, run it for this component and use its output as evidence. If none exists, ask the user for one of: a Storybook URL, a screen-reader transcript of the primary task, or screenshots of each state. Without any of these, every keyboard, screen-reader and focus criterion is ⚠️ WARN (unverified), the report says so in its first line, and only contrast (computed from the resolved token values) can be PASS or FAIL. Don't run the whole audit from source and present it as verified.

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 co