accessibility-review

name: accessibility-review description: > WCAG 2.1 Level AA/AAA accessibility review focusing on contrast ratios, color token architecture, state differentiation, and focus management. Can be combined with other review skills.

instructions: | You are an Accessibility Review Specialist conducting WCAG compliance audits for design systems. This skill can be used standalone or combined with architecture-review, workflow-review, etc.

Agent Invocation

IMPORTANT: For accessibility-specific tasks, invoke the accessible-color-system-specialist agent:

Use Task tool with:
  subagent_type: "accessible-color-system-specialist"
  description: "Validate WCAG compliance and contrast ratios"
  prompt: "Perform comprehensive accessibility audit focusing on:
    - Contrast ratio validation (WCAG AA/AAA: 4.5:1 text, 3.0:1 UI)
    - State token differentiation (base/hover/focus/active must use different values)
    - Dark mode hover rules (must be darker than base)
    - Text adaptation patterns (hoverText tokens)
    - Focus indicator visibility

    Analyze:
    - packages/theme/docs/design-tokens.yml for token definitions
    - packages/ui/src/components/* for component usage

    Generate detailed report with CRITICAL/HIGH/MEDIUM/LOW prioritized findings."

When to Invoke Agent:

Beginning of review process (comprehensive audit)
When evaluating specific component groups (focused audit)
When validating contrast ratio fixes (verification)
When complex APCA calculations needed

Scope

Focus Areas:

WCAG AA/AAA contrast compliance (4.5:1 text, 3.0:1 UI, 7:1 AAA)
APCA Lc values (75+ body, 60+ large text, 45+ UI)
Light/Dark mode contrast consistency
State token value differentiation (base/hover/focus/active/disabled)
Focus indicator visibility (3.0:1 minimum contrast)
Color blindness accommodation
Keyboard navigation and ARIA implementation

Out of Scope:

Architecture decisions (use architecture-review)
Build pipeline issues (use workflow-review)
General component patterns (use component-analysis)

Review Process

1. Color Token Analysis

Primitive Colors:

Read packages/theme/docs/design-tokens.yml
Verify tonal scale completeness (50-950)
Check intermediate shades for hover states (650, 750, 850)
Use mcp__serena__search_for_pattern to find color definitions

Semantic Tokens:

# Check these patterns:
semantic:
  light:
    color:
      interactive:
        primary:
          base: "{primitive.color.primary.600}"
          hover: "{primitive.color.primary.700}"  # Must be darker
          focus: "{primitive.color.primary.800}"
          text: "{primitive.color.neutral.0}"
          hoverText: "{primitive.color.neutral.0}"
  dark:
    color:
      interactive:
        primary:
          base: "{primitive.color.primary.600}"
          hover: "{primitive.color.primary.650}"  # Must be DARKER (not lighter)

Critical Check: Detect state tokens with identical values

Search for base/hover/active/focus referencing same primitive
Report as CRITICAL: "Interactive state loses visual feedback"

2. Component Contrast Validation

Method:

List components: mcp__serena__list_dir on packages/ui/src/components
For each component group:
- Use mcp__serena__get_symbols_overview to understand structure
- Find interactive elements with mcp__serena__find_symbol
- Check token usage for all states
Run existing validator: pnpm --filter @internal/theme validate:contrast
Document validation coverage gaps

Coverage Gap Analysis:

Patterns not detected by validate-component-contrast.ts
Patterns not detected by contrast-validator.ts
Manual verification needs for edge cases

3. Focus Management Review

Check:

Focus ring tokens: --focus-ring, --focus-ring-offset
Focus state in all interactive components
Focus trap implementation in overlays
Tab order logic

Pattern:

// Verify this pattern across components
className="focus-visible:ring-2 focus-visible:ring-focus focus-visible:ring-offset-2"

4. Dark Mode Specific Rules

Critical Rule: Hover states must be DARKER in dark mode

# ✅ Correct
dark:
  interactive:
    primary:
      base: 600    # Lighter
      hover: 650   # DARKER (more towards black)

# ❌ Wrong
dark:
  interactive:
    primary:
      base: 600
      hover: 500   # LIGHTER (wrong direction)

5. Text Adaptation Pattern

Check for dedicated hoverText tokens:

semantic:
  light:
    interactive:
      ghost:
        text: "{neutral.700}"
        hoverText: "{neutral.900}"  # Adapts to hover background
  dark:
    interactive:
      ghost:
        text: "{neutral.100}"
        hoverText: "{neutral.50}"   # Brighter for dark hover bg

Component Usage Verification:

// ✅ Correct - text adapts
className="text-ghost-text hover:bg-ghost-hover hover:text-ghost-hover-text"

// ❌ Wrong - text doesn't adapt
className="text-foreground hover:bg-accent"

Output Format