From design-system-ops
Audits specific design system components for WCAG 2.1 AA accessibility across keyboard navigation, screen readers, color contrast, focus management, and ARIA. Provides PASS/FAIL/WARN with remediation guidance.
npx claudepluginhub murphytrueman/design-system-opsThis skill uses the workspace's default tool permissions.
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.
Checks specific UI elements or code for accessibility issues like WCAG compliance, keyboard access, focus indicators, contrast, ARIA, alt text, and form labels.
Implements WCAG 2.1/2.2 compliance, ARIA patterns, keyboard navigation, focus management, and accessibility testing for web components.
Fetches up-to-date documentation from Context7 for libraries and frameworks like React, Next.js, Prisma. Use for setup questions, API references, and code examples.
Share bugs, ideas, or general feedback.
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.
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.
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.
Ask for or confirm:
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.
Every interactive component must be fully operable by keyboard alone. Assess:
Tab order
Activation
Arrow key navigation
Escape key
Skip/bypass mechanisms
Result per criterion: PASS / FAIL / WARN (warn = partially implemented or needs verification in a specific context)
Assess the experience for a screen reader user navigating with keyboard focus:
Role announcement
<div> with no role — announces as nothingrole="combobox" on an autocomplete inputState announcement
aria-checked — the state is not communicatedaria-checked="true" toggling to aria-checked="false" with a live region or label changeName computation
for/id, aria-labelledby, or aria-label)?aria-label or visually hidden text?Group labelling
Live regions
aria-live or an appropriate role?Instructions and descriptions
aria-describedby?Result per criterion: PASS / FAIL / WARN
Text contrast
Non-text contrast (UI components)
Focus indicator contrast
Colour as the only means of conveying information
Result per criterion: PASS / FAIL / WARN with specific contrast ratio figures where assessable
Focus management is a component-level concern whenever a component opens, closes, moves, or otherwise changes the focus context.
Assess:
Focus on open
Focus trap
Focus on close
Focus visibility
Result per criterion: PASS / FAIL / WARN
For teams new to screen reader testing, provide this practical guide alongside the audit findings. Screen reader testing is the dimension most often skipped because teams do not know how to do it.
Quick-start screen reader testing (macOS — VoiceOver):
Quick-start screen reader testing (Windows — NVDA):
What to listen for per component type:
Include this guide in the audit output when Dimension 2 (Screen reader experience) has any FAIL or WARN findings, so teams can verify the fix.
Assess the correctness of ARIA usage:
Role appropriateness
Required ARIA attributes
aria-expanded for a disclosure, aria-selected for a tab, aria-controls linking a trigger to its content)Prohibited ARIA patterns
Landmark regions
Result per criterion: PASS / FAIL / WARN
Open with a headline sentence that tells the reader the overall state and where to focus.
Audit date: [date] WCAG level: 2.1 AA Assessment method: [live component / design specification / Storybook] Additional context: [e.g. tested with VoiceOver/macOS, NVDA/Windows — if applicable]
✅ PASS / ⚠️ WARN / ❌ FAIL
| Dimension | Criterion | Result | Finding | Remediation |
|---|---|---|---|---|
| Keyboard | Tab order | ✅ PASS / ⚠️ WARN / ❌ FAIL | [specific finding] | [specific fix] |
| ... |
Status key: ✅ PASS / ⚠️ WARN / ❌ FAIL
Pull out any FAIL results that create significant barriers — particularly any that prevent a user from completing a task using only a keyboard or screen reader. These need to be fixed before the component ships or remains in the system.
For each FAIL or WARN finding, include the relevant WCAG criterion (e.g. 1.4.3 Contrast Minimum, 2.1.1 Keyboard). This makes it easier to prioritise against compliance requirements and to communicate findings to stakeholders.
For every FAIL or WARN finding, include a concrete code example showing the fix. Remediation guidance without code is advice; remediation guidance with code is a pull request waiting to happen.
Format for each code example:
Finding: [finding ID and short description]
Before (violation):
[The exact code pattern that causes the failure]
After (fixed):
[The corrected code with the specific change highlighted]
Why this fixes it:
[One sentence explaining what changed and which WCAG criterion it satisfies]
Examples by dimension:
Keyboard navigation — missing Enter/Space activation:
Before:
<div className="button" onClick={handleClick}>Submit</div>
After:
<button type="button" onClick={handleClick}>Submit</button>
Why: Native <button> provides Enter and Space activation, focus management,
and correct role announcement without additional ARIA. (WCAG 2.1.1)
Screen reader — missing accessible name on icon button:
Before:
<button><Icon name="close" /></button>
After:
<button aria-label="Close dialog"><Icon name="close" aria-hidden="true" /></button>
Why: aria-label provides the accessible name. aria-hidden on the icon prevents
the icon name from being announced alongside the label. (WCAG 4.1.2)
Focus management — focus not returned on close:
Before:
const handleClose = () => {
setIsOpen(false);
};
After:
const triggerRef = useRef(null);
const handleClose = () => {
setIsOpen(false);
triggerRef.current?.focus();
};
// On the trigger: ref={triggerRef}
Why: Focus returns to the element that opened the overlay, maintaining
the user's position in the page. (WCAG 2.4.3)
ARIA — missing required attributes on disclosure:
Before:
<button onClick={toggle}>FAQ Item</button>
<div className={isOpen ? 'visible' : 'hidden'}>Answer text</div>
After:
<button
onClick={toggle}
aria-expanded={isOpen}
aria-controls="faq-answer-1"
>FAQ Item</button>
<div id="faq-answer-1" role="region" aria-labelledby="faq-trigger-1">
Answer text
</div>
Why: aria-expanded communicates state. aria-controls links trigger to content.
role="region" with aria-labelledby makes the content a labelled landmark. (WCAG 4.1.2)
Colour contrast — insufficient text contrast:
Before:
.label { color: #999999; background: #FFFFFF; }
/* Contrast ratio: 2.85:1 — fails WCAG AA (4.5:1 required) */
After:
.label { color: #595959; background: #FFFFFF; }
/* Contrast ratio: 7.0:1 — passes WCAG AA and AAA */
Why: Darkening the text colour from #999 to #595959 exceeds the 4.5:1 minimum. (WCAG 1.4.3)
Include the appropriate code example pattern for every FAIL finding. For WARN findings, include the example if the fix is clear; omit it if the finding requires contextual judgment that code alone cannot resolve.
Simple components (buttons, badges, basic inputs) tend to pass most checks. The real value of this skill is exposed on complex, high-CR components where accessibility failures are subtle and compound. When the target component is one of the following types, apply the extended protocol:
Additional checks beyond the standard five dimensions:
Additional checks:
role="grid" with correct row/cell roles?Additional checks:
scope="col" or equivalent ARIA?Additional checks:
aria-modal="true" set on the dialog element?Additional checks:
role="tablist", role="tab", role="tabpanel" correctly?aria-selected state correctly toggled between tabs?For any component matching these types, run both the standard five-dimension audit AND the extended protocol. The extended protocol findings should be interleaved into the main report by dimension, not presented as a separate section.