Skip to main content

Accessibility Audit

System Prompt​

⚠️ EXECUTION DIRECTIVE: When the user invokes this command, you MUST:

  1. IMMEDIATELY execute - no questions, no explanations first
  2. ALWAYS show full output from script/tool execution
  3. ALWAYS provide summary after execution completes

DO NOT:

  • Say "I don't need to take action" - you ALWAYS execute when invoked
  • Ask for confirmation unless requires_confirmation: true in frontmatter
  • Skip execution even if it seems redundant - run it anyway

The user invoking the command IS the confirmation.

Usage​

/a11y

You are performing a comprehensive WCAG 2.1 AA/AAA accessibility audit using the AccessibilityAuditorAgent.

Your Task​

Audit React components for accessibility compliance and provide detailed remediation guidance:

  • WCAG 2.1 Level AA (minimum standard - required)
  • WCAG 2.1 Level AAA (enhanced accessibility - optional)
  • Automated validation with detailed violation reports
  • Specific recommendations with code examples

Arguments​

$ARGUMENTS - Component Target (required)​

Specify the component, file, or scope to audit:

  • Single component: Component name (e.g., "Button component")
  • File path: Relative path to component file
  • Scope: "navbar", "form", "modal", "entire page layout"

Advanced Options (optional)​

Specify via natural language:

  • Level: "for WCAG AAA compliance" (default: AA)
  • Focus Area: "for keyboard navigation only" (default: all 6 areas)
  • Scope: "for color contrast issues" (specific audit area)
  • Device: "for screen reader compatibility"

Default Behavior​

If no arguments provided, command prompts user for component to audit.

Audit Areas​

1. Semantic HTML​

  • Proper HTML elements (not div soup)
  • Heading hierarchy (h1 → h2 → h3)
  • Landmark regions (header, nav, main, footer)
  • Lists for list content (ul, ol, dl)
  • Buttons vs links (proper semantic usage)

2. ARIA (Accessible Rich Internet Applications)​

  • Roles (when semantic HTML insufficient)
  • Labels (aria-label, aria-labelledby)
  • States (aria-expanded, aria-selected, aria-disabled)
  • Relationships (aria-describedby, aria-controls)
  • Live regions (aria-live, aria-atomic)

3. Keyboard Navigation​

  • Tab order (logical and complete)
  • Focus indicators (visible and clear)
  • No keyboard traps (can escape modals)
  • Skip links (bypass navigation)
  • Shortcuts (documented and non-conflicting)

4. Color Contrast​

  • WCAG AA: 4.5:1 for normal text, 3:1 for large text
  • WCAG AAA: 7:1 for normal text, 4.5:1 for large text
  • UI components: 3:1 contrast
  • Focus indicators: 3:1 contrast
  • Non-text content: 3:1 contrast

5. Focus Management​

  • Visible focus indicators (always)
  • Focus trap in modals (focus stays within)
  • Focus restoration (return after modal close)
  • Skip links (bypass repetitive content)

6. Screen Readers​

  • Alt text for images (descriptive)
  • aria-live regions (dynamic content)
  • aria-describedby (additional context)
  • Hidden content (aria-hidden, hidden)
  • Form labels (explicit associations)

Process​

  1. Use AccessibilityAuditorAgent to analyze component code
  2. Generate violation report with severity levels
  3. Provide specific remediation steps
  4. Show before/after code examples
  5. Calculate accessibility score (0-100)

Output Format​

  • Accessibility score and WCAG level achieved (AA/AAA)
  • Violations list with severity (critical/major/minor)
  • Remediation recommendations with code examples
  • Passed checks summary
  • Re-audit option after fixes
  • Token usage and cost estimate

Severity Levels​

  • Critical: Blocks users with disabilities (0 points)
  • Major: Significant barriers to access (-10 points each)
  • Minor: Usability issues (-5 points each)
  • Enhancement: AAA improvements (bonus points)

Accessibility Score​

100 points - No violations, all best practices
90-99     - Minor improvements needed (WCAG AA)
80-89     - Some accessibility issues (approaching AA)
70-79     - Multiple issues (below AA)
<70       - Critical accessibility problems

Example Usage​

/a11y Audit the Button component
/a11y Check navbar for WCAG AAA compliance
/a11y Review form accessibility
/a11y Analyze modal dialog for keyboard traps
/a11y Audit entire page layout

Advanced Options​

You can request specific audits:

  • Level: "for WCAG AAA compliance"
  • Focus Area: "for keyboard navigation only"
  • Scope: "for color contrast issues"
  • Device: "for screen reader compatibility"

Common Violations & Fixes​

Missing Alt Text​

// Before (violation)
<img src="logo.png" />

// After (fixed)
<img src="logo.png" alt="Company Logo" />

Poor Contrast​

// Before (violation - 2.5:1)
<p className="text-gray-400 bg-white">Low contrast text</p>

// After (fixed - 7:1)
<p className="text-gray-900 bg-white">High contrast text</p>

Missing Focus Indicator​

// Before (violation)
<button className="outline-none">Click me</button>

// After (fixed)
<button className="focus:ring-2 focus:ring-blue-500">Click me</button>

Keyboard Trap in Modal​

// Before (violation - no focus trap)
<div className="modal">{children}</div>

// After (fixed - with focus trap)
<FocusTrap>
  <div className="modal" role="dialog" aria-modal="true">
    {children}
  </div>
</FocusTrap>

Missing Form Labels​

// Before (violation)
<input type="text" placeholder="Name" />

// After (fixed)
<label htmlFor="name">Name</label>
<input id="name" type="text" placeholder="Name" />

Quality Gates​

All components must achieve:

  1. WCAG 2.1 AA compliance (minimum 90/100 score)
  2. No critical violations (blocking issues)
  3. All interactive elements keyboard accessible
  4. Proper ARIA usage (roles, labels, states)
  5. Sufficient color contrast (4.5:1 minimum)

Tools & Testing​

  • Automated: AccessibilityAuditorAgent (this command)
  • Manual: Screen reader testing (NVDA, JAWS, VoiceOver)
  • Browser: Chrome DevTools Accessibility Panel
  • Extensions: axe DevTools, WAVE
  • Keyboard: Tab through all interactive elements

Action Policy​

<default_behavior> This command analyzes and recommends without making changes. Provides:

  • Comprehensive WCAG 2.1 AA/AAA accessibility audit
  • Specific violations with severity levels (critical/major/minor)
  • Detailed remediation recommendations with code examples
  • Accessibility score (0-100) and compliance level achieved
  • Before/after code comparisons for all violations

User decides which accessibility fixes to implement. </default_behavior>

After audit completion, verify: - All 6 audit areas covered (semantic HTML, ARIA, keyboard, contrast, focus, screen readers) - Violations categorized by severity with specific line numbers - Code examples provided for all major/critical violations - Accessibility score calculated correctly - WCAG compliance level (AA/AAA) clearly stated - Re-audit instructions provided for post-fix verification

Integration​

Agent Invocation​

This command uses the generative-ui-accessibility-auditor agent for comprehensive WCAG compliance analysis:

# Invoke accessibility auditor agent
Task(
    subagent_type="generative-ui-accessibility-auditor",
    description="Audit React component for WCAG 2.1 AA compliance",
    prompt=f"""Analyze {component_path} for accessibility compliance:

    - Check all 6 audit areas (semantic HTML, ARIA, keyboard, contrast, focus, screen readers)
    - Identify violations with severity levels (critical/major/minor)
    - Provide specific remediation recommendations with code examples
    - Calculate accessibility score (0-100)
    - Report WCAG 2.1 compliance level (AA/AAA)

    Component: {component_name}
    Target Level: WCAG 2.1 AA (minimum)
    """
)

Workflow Integration​

Typical workflow:

  1. Pre-Audit - User identifies component to audit
  2. Agent Execution - generative-ui-accessibility-auditor analyzes component
  3. Report Generation - Violations report with severity levels
  4. User Review - Developer reviews findings and prioritizes fixes
  5. Remediation - Developer implements recommended fixes
  6. Re-Audit - Run command again to verify improvements

CI/CD Integration:

# GitHub Actions example
- name: Accessibility Audit
  run: |
    # Run accessibility audit on changed components
    /a11y "Audit Button component for WCAG AA compliance"

    # Fail if critical violations found
    if grep -q "Critical:" audit-report.txt; then
      exit 1
    fi

Input/Output Format​

Input: Component name, file path, or scope description

Output:

  • Accessibility score (0-100)
  • WCAG compliance level (AA/AAA/Failed)
  • Violations list (critical/major/minor)
  • Remediation recommendations with code examples
  • Passed checks summary

Required Tools​

ToolPurposeRequired
ReadRead component source codeYes
TaskInvoke generative-ui-accessibility-auditorYes
GlobFind component filesOptional

Agent Used:

  • generative-ui-accessibility-auditor - WCAG compliance analysis

External Testing Tools (manual verification):

  • axe DevTools extension
  • WAVE accessibility tool
  • Chrome DevTools Accessibility Panel
  • Screen readers (NVDA, JAWS, VoiceOver)

Output Validation​

Before marking complete, verify output contains:

  • All 6 audit areas analyzed (semantic HTML, ARIA, keyboard, contrast, focus, screen readers)
  • Accessibility score (0-100) calculated
  • WCAG compliance level stated (AA/AAA/Failed)
  • Violations categorized by severity
  • Code examples for all major/critical violations
  • Re-audit instructions provided

Error Handling​

Common Issues​

Issue: Component file not found

  • Solution: Verify file path is correct relative to project root
  • Example: Use src/components/Button.tsx not Button.tsx

Issue: Invalid component syntax

  • Solution: Ensure component is valid React/TypeScript code
  • Example: Fix syntax errors before running audit

Issue: Agent timeout

  • Solution: Break large components into smaller chunks for analysis
  • Example: Audit individual sections of complex page layouts

Issue: Unclear audit scope

  • Solution: Be specific about what to audit (component name, file path, or scope)
  • Example: "Audit navbar" vs. "Audit entire page layout"

Troubleshooting​

Audit returns no violations but component has issues:

  • Manually test with screen reader
  • Use browser DevTools Accessibility Panel
  • Run axe DevTools extension
  • Check for dynamic content issues (AJAX, modals)

Audit finds too many violations:

  • Prioritize critical violations first
  • Focus on one audit area at a time
  • Use scope filters: /a11y Check navbar for keyboard navigation only

Score seems incorrect:

  • Verify all 6 audit areas were analyzed
  • Check if dynamic content was evaluated
  • Re-run audit after fixing critical issues

Success Output​

When accessibility audit completes:

✅ COMMAND COMPLETE: /a11y
Component: <component-name>
Score: X/100 (WCAG <AA|AAA>)
Violations: Critical: X, Major: Y, Minor: Z
Remediation: N recommendations provided

Completion Checklist​

Before marking complete:

  • All 6 audit areas analyzed
  • Violations categorized by severity
  • Code examples provided for fixes
  • Accessibility score calculated
  • WCAG compliance level reported

Failure Indicators​

This command has FAILED if:

  • ❌ Component file not found
  • ❌ No audit areas analyzed
  • ❌ No score calculated
  • ❌ Missing remediation guidance

When NOT to Use​

Do NOT use when:

  • No React components exist
  • Need full site audit (use automated scanner)
  • Just checking color contrast (use browser tools)

Anti-Patterns (Avoid)​

Anti-PatternProblemSolution
Skip critical violationsUsers blockedFix critical first
Ignore ARIAIncomplete accessibilityAdd proper ARIA
No re-auditFixes not verifiedRun again after fixes

Principles​

This command embodies:

  • #3 Complete Execution - All 6 audit areas
  • #9 Based on Facts - WCAG-based scoring
  • #6 Clear, Understandable - Severity categorization

Full Standard: CODITECT-STANDARD-AUTOMATION.md

Ask the user what component to audit or provide component code to analyze.