What is the accessibility-per-component skill?
The accessibility-per-component skill is a SKILL.md in murphytrueman/design-system-ops. It has your AI coding agent audit one design system component against WCAG 2.2 AA across five dimensions, then report PASS, FAIL or WARN per criterion with a code example for each fix.
The accessibility-per-component skill audits one design system component's accessibility against WCAG 2.2 AA. It belongs to the design-system-ops skill pack and produces a PASS, FAIL or WARN per criterion with specific remediation guidance.
Component-level audits matter because a component with a correct accessibility implementation propagates that correctness to every product that uses it, and a component with an accessibility bug propagates the bug at the same scale.
The five dimensions
- Keyboard navigation: tab order, Enter and Space activation, arrow keys for composite widgets and Escape for layers.
- Screen reader experience: role, state and name announcement, group labeling, live regions and instructions.
- Color and contrast: 4.5:1 for text, 3:1 for large text, UI component boundaries and focus indicators.
- Focus management: where focus goes on open, the focus trap, return on close and focus not obscured.
- ARIA implementation: role appropriateness, required attributes, prohibited patterns and landmark regions.
Evidence and severity
PASS requires evidence from the running component or a computed ratio. Code-only inference is WARN, and the overall status is the worst criterion result. Without any runtime evidence, only contrast can be PASS or FAIL.
Severity runs from Critical to Low. A control with no accessible name, or a modal that does not trap or return focus, is Critical, and Critical findings block release under the default gates.
Components that get extra checks
Combobox, DatePicker, data table, modal and tabs components get an extended protocol on top of the standard audit. Its findings are interleaved into the main report by dimension, not presented as a separate section.
Who the accessibility-per-component skill is for
Best for
- Auditing a single design system component, such as a combobox, date picker, data table, modal or tabs.
- Teams whose legal baseline is WCAG 2.1 AA, such as EN 301 549, which the skill can audit against instead of 2.2 AA.
- Components assessed from a live implementation, a Storybook or a design file, with the assessment method recorded in the report.
Not for
- A WCAG 2.1 and 2.2 review organized by the four POUR principles, which the wcag-accessibility-audit skill covers.
- A four phase audit of code against WCAG 2.0, 2.1 and 2.2 that writes a prioritised report, which the web-accessibility-audit skill covers.
- Scoring a design system on coverage, tokens, docs, accessibility and adoption, then ranking fixes in a roadmap, which the design-system-audit skill covers.
- Auditing a rendered page with Lighthouse and fixing source code against WCAG 2.2 patterns, which the web accessibility skill covers.
How to install Accessibility Per Component Skill: WCAG 2.2 AA Audit
git clone https://github.com/murphytrueman/design-system-ops.git ~/.claude/skills/design-system-opsClone the pack
Run the command above. For a project-level install, clone into
your-project/.claude/skills/design-system-opsinstead.Confirm it loaded
Run
claude plugin listand look fordesign-system-ops@skills-dirwith status loaded. A project-level install only loads once you trust the project folder, then run/reload-plugins.Run an audit
Name a component and ask for an a11y audit, a WCAG check or whether it is accessible. The skill asks which component to audit if none is named.
Read the report
The report opens with a headline sentence on the overall state, lists results per dimension and ends with a Scope block.
Check that it loaded
After the audit, check that the report opens with a headline sentence and ends with a Scope block, and that every PASS row cites evidence such as a story id, an axe rule or a computed ratio.
Key features
- Five-dimension auditKeyboard navigation, screen reader experience, color and contrast, focus management and ARIA implementation are each assessed, with PASS, FAIL or WARN per criterion.
- Evidence rulePASS needs evidence from the running component or a computed ratio. Code-only inference is WARN, and the overall status is the worst criterion result.
- Runtime evidence searchThe skill looks for a Storybook test-runner or a11y addon, jest-axe or vitest-axe tests, Playwright with
@axe-core/playwright, or a dev server, and runsnpx test-storybook --url <storybook>when the Storybook has the test-runner. - Other component-level criteriaWhere the component type makes them relevant, it checks 2.5.8 Target Size at 24x24 CSS px, 2.5.7 Dragging Movements, 2.5.3 Label in Name, 1.4.13, 1.4.12, 3.3.7, 4.1.3, 3.3.1 and 3.3.2, reflow and resize.
- Forced colors and motionUnder
@media (forced-colors: active)the component's boundaries, focus indicator and state indicators must survive. Animations should respectprefers-reduced-motion. - Complex component protocolCombobox, DatePicker, data table, modal and tabs components get extra checks, such as live-region result counts, grid arrow keys,
aria-modalandinertbackground, andaria-selectedon tabs. - Severity levelsFindings are rated Critical, High, Medium or Low. A target under 24 CSS px or a focus indicator below 3:1 is High, and AAA recommendations are Low.
- Remediation codeEvery FAIL finding gets a before and after code example with the WCAG criterion referenced, and the fix preserves the consumer's existing handlers.
- Screen reader testing guideWhen screen reader findings exist, the report adds steps for VoiceOver on macOS and NVDA on Windows, and asks you to complete the component's primary task with keyboard and screen reader alone.
- Config gatesIf
.ds-ops-config.ymlexists, the skill readsseverity.missing_ariaand the keyboard and contrast release gates, which both default to blocking release.
Frequently asked questions
What is the accessibility-per-component skill?
It is a SKILL.md in the murphytrueman/design-system-ops repository for auditing one design system component against WCAG 2.2 AA. Your AI coding agent covers keyboard, screen reader, color and contrast, focus management and ARIA, then reports PASS, FAIL or WARN per criterion with specific remediation guidance.
How do I install the accessibility-per-component skill?
Run git clone on the design-system-ops repository into ~/.claude/skills/design-system-ops. Then run claude plugin list and look for design-system-ops@skills-dir with status loaded. A project-level install goes into your-project/.claude/skills/design-system-ops, loads once you trust the project folder and then needs /reload-plugins. After that, name a component and ask for an a11y audit.
Which dimensions does the skill audit?
It audits five dimensions: keyboard navigation, screen reader experience, color and contrast, focus management and ARIA implementation. Other component-level criteria such as 2.5.8 Target Size, 1.4.13 Content on Hover or Focus and 4.1.3 Status Messages are checked where the component type makes them relevant.
When does a criterion count as PASS?
A PASS needs evidence from the running component or a computed contrast ratio. Code-only inference is WARN, and the overall status is the worst criterion result. If no runtime evidence exists, the report says so in its first line and only contrast, computed from resolved token values, can be PASS or FAIL.
How does the skill rate severity?
Critical covers a component that cannot be operated by keyboard, a control with no accessible name, a modal that does not trap or return focus, and body text below 4.5:1. High covers unannounced states, a focus indicator below 3:1 and targets under 24 CSS px. Medium covers disabled-state contrast and clipping under text spacing. Low covers AAA recommendations.
Which components get the extended protocol?
Combobox or autocomplete, DatePicker or calendar, data table, modal or dialog, and tabs. Each adds checks to the standard five dimensions, such as announcing filtered result counts in a combobox, arrow key navigation of a calendar grid, a visible announced dialog title and arrow keys between tabs. The findings are interleaved into the main report by dimension.
What happens if no component is named?
The skill audits a single component at a time. If no specific component is identified, it asks which component to audit before proceeding. If the component has no implementation yet and only a design exists, the audit covers design intent only and code-level checks are flagged as pending. Page-level or full-product accessibility audits are outside its scope.