plugins/ui-design/commands/accessibility-audit.md
Comprehensive audit of UI code for WCAG 2.1/2.2 compliance. Identifies accessibility issues and provides actionable remediation guidance.
Check if .ui-design/ directory exists:
.ui-design/ directory.ui-design/audits/ subdirectory for audit resultsLoad project context:
conductor/tech-stack.md for framework info.ui-design/design-system.json for color tokens--level flag (AA or AAA)Q1: Audit Target
What would you like to audit?
1. A specific component (provide name or path)
2. A page/route (provide path)
3. All components in a directory
4. The entire application
5. Recent changes only (last commit)
Enter number or provide a file path:
Q2: Compliance Level
What WCAG compliance level should I audit against?
1. Level A - Minimum accessibility (must-fix issues)
2. Level AA - Standard compliance (recommended, most common target)
3. Level AAA - Enhanced accessibility (highest standard)
Note: Each level includes all requirements from previous levels.
Enter number:
Q3: Focus Areas (optional)
Any specific areas to focus on? (Press enter to audit all)
1. Color contrast and visual presentation
2. Keyboard navigation and focus management
3. Screen reader compatibility
4. Forms and input validation
5. Dynamic content and ARIA
6. All areas
Enter numbers (comma-separated) or press enter:
Create .ui-design/audits/audit_state.json:
{
"audit_id": "{target}_{YYYYMMDD_HHMMSS}",
"target": "{file_path_or_scope}",
"wcag_level": "AA",
"focus_areas": ["all"],
"status": "in_progress",
"started_at": "ISO_TIMESTAMP",
"files_audited": 0,
"issues_found": {
"critical": 0,
"serious": 0,
"moderate": 0,
"minor": 0
},
"criteria_checked": 0,
"criteria_passed": 0
}
Identify all files to audit:
.tsx, .vue, .svelte, etc.)For each file, check against WCAG criteria:
1.1 Text Alternatives:
alt attributesalt="" or role="presentation"1.2 Time-based Media:
1.3 Adaptable:
1.4 Distinguishable:
2.1 Keyboard Accessible:
2.2 Enough Time:
2.3 Seizures:
2.4 Navigable:
2.5 Input Modalities:
3.1 Readable:
lang attribute)3.2 Predictable:
3.3 Input Assistance:
4.1 Compatible:
Identify common accessibility anti-patterns:
// Anti-patterns to detect
const antiPatterns = [
// Missing alt text
/]*alt=)[^>]*>/,
// onClick without keyboard handler
/onClick={[^}]+}(?!.*onKeyDown)/,
// Div/span with click handlers (likely needs role)
/<(?:div|span)[^>]*onClick/,
// Non-semantic buttons
/<(?:div|span)[^>]*role="button"/,
// Missing form labels
/<input(?![^>]*(?:aria-label|aria-labelledby|id))[^>]*>/,
// Positive tabindex (disrupts natural order)
/tabIndex={[1-9]/,
// Empty links
/<a[^>]*>[\s]*<\/a>/,
// Missing lang attribute
/<html(?![^>]*lang=)/,
// Autofocus (usually bad for a11y)
/autoFocus/,
];
If design tokens or CSS available:
Check ARIA usage:
role="button" on <button>)Generate audit report in .ui-design/audits/{audit_id}.md:
# Accessibility Audit Report
**Audit ID:** {audit_id}
**Date:** {YYYY-MM-DD HH:MM}
**Target:** {target}
**WCAG Level:** {level}
**Standard:** WCAG 2.1
## Executive Summary
**Compliance Status:** {Passing | Needs Improvement | Failing}
| Severity | Count | % of Issues |
| -------- | ----- | ----------- |
| Critical | {n} | {%} |
| Serious | {n} | {%} |
| Moderate | {n} | {%} |
| Minor | {n} | {%} |
**Criteria Checked:** {n}
**Criteria Passed:** {n} ({%})
**Files Audited:** {n}
## Critical Issues (Must Fix)
These issues prevent users with disabilities from using the interface.
### Issue 1: {Title}
**WCAG Criterion:** {number} - {name} (Level {A|AA|AAA})
**Severity:** Critical
**Location:** `{file}:{line}`
**Element:** `{element_snippet}`
**Problem:**
{Description of the issue}
**Impact:**
{Who is affected and how}
**Remediation:**
{Step-by-step fix instructions}
**Code Fix:**
```{language}
// Before
{current_code}
// After
{fixed_code}
```
Testing:
These issues create significant barriers for some users.
These issues may cause difficulty for some users.
These are best practice improvements.
The following WCAG criteria passed:
| Criterion | Name | Level |
|---|---|---|
| 1.1.1 | Non-text Content | A |
| 1.3.1 | Info and Relationships | A |
| ... | ... | ... |
Add these tests to catch regressions:
// Example jest-axe test
import { axe, toHaveNoViolations } from "jest-axe";
expect.extend(toHaveNoViolations);
test("component has no accessibility violations", async () => {
const { container } = render(<Component />);
const results = await axe(container);
expect(results).toHaveNoViolations();
});
Generated by UI Design Accessibility Audit WCAG Reference: https://www.w3.org/WAI/WCAG21/quickref/
## Completion
Update `audit_state.json`:
```json
{
"status": "complete",
"completed_at": "ISO_TIMESTAMP",
"compliance_status": "needs_improvement",
"issues_found": {
"critical": 2,
"serious": 5,
"moderate": 8,
"minor": 3
}
}
Display summary:
Accessibility Audit Complete!
Target: {target}
WCAG Level: {level}
Compliance Status: {status}
Issues Found:
- {n} Critical (must fix)
- {n} Serious
- {n} Moderate
- {n} Minor
Full report: .ui-design/audits/{audit_id}.md
What would you like to do next?
1. View details for critical issues
2. Start fixing issues (guided)
3. Generate automated tests
4. Export report for stakeholders
5. Audit another component
Enter number:
If user selects "Start fixing issues":
Let's fix accessibility issues starting with critical ones.
Issue 1 of {n}: {Issue Title}
WCAG {criterion}: {criterion_name}
Location: {file}:{line}
{Show current code}
The fix is:
{Explain the fix}
Should I:
1. Apply this fix automatically
2. Show me the fixed code first
3. Skip this issue
4. Stop fixing
Enter number:
Apply fixes one at a time, re-validating after each fix.