Tpl Situacao Acessibilidade A11Y

SITUATION: Accessibility Audit & Implementation

Skill gerado a partir do pack templates-claude-code. Arquivo de origem: situacao/19-acessibilidade-a11y.md. Use como baseline e adapte ao projeto antes de mudancas grandes.

Conteudo do template

CONTEXT

Use this configuration when auditing an application for accessibility (a11y) compliance, implementing WCAG 2.1 AA requirements, fixing specific accessibility issues found in user testing or automated audits, or building new UI components with accessibility-first. Accessibility is not a checkbox — it's a quality standard that improves usability for all users, including those using keyboards, screen readers, voice control, or operating in challenging visual conditions.

OBJECTIVES

• Achieve WCAG 2.1 AA compliance across all user-facing interfaces
• Ensure keyboard-only users can complete all critical user flows
• Make all content usable with popular screen readers (NVDA, JAWS, VoiceOver)
• Meet minimum color contrast ratios for text and interactive elements
• Implement focus management that makes sense for keyboard users

APPROACH RULES

1. Semantic HTML first, ARIA second. The most reliable way to convey meaning to assistive technology is semantic HTML: <button>, <nav>, <main>, <h1>…<h6>, <label>, <table>. Add ARIA only when HTML semantics are insufficient. Incorrect ARIA is worse than no ARIA.

2. Every interactive element must be keyboard accessible. Tab focus must reach all buttons, links, form fields, and interactive controls. Every focusable element must have a visible focus indicator. No keyboard traps (users can always navigate away).

3. Focus management is mandatory for dynamic UI. When a modal opens, focus moves into it. When it closes, focus returns to the trigger. When a new section loads (SPA navigation), focus moves to the content. Unmanaged focus makes screen readers disorienting.

4. No information conveyed by color alone. Error states need text labels, not just red borders. Status indicators need text or icons, not just colors. Add at least one non-color indicator for every color-coded meaning.

5. All images need descriptive alt text. Decorative images: alt="". Informative images: alt="A bar chart showing sales growth from 2023 to 2024". Never alt="image" or alt="photo". Icon buttons: aria-label="Close dialog".

6. WCAG 2.1 AA minimum color contrast: 4.5:1 for normal text, 3:1 for large text (18pt+ or 14pt+ bold), 3:1 for UI components (borders of form inputs, focus indicators). Test with real tools, not your eyes.

7. Screen reader testing is required — automated tools find only ~30% of issues. Test with: NVDA + Firefox (Windows), VoiceOver + Safari (macOS/iOS), TalkBack (Android). The goal: can a screen reader user complete all critical flows independently?

ROUTING TABLE

WCAG 2.1 AA Checklist

Perceivable

• All images have descriptive alt text (or alt="" for decorative)
• All audio/video has captions and/or transcripts
• Color is not the only way to convey information
• Text contrast ratio: ≥ 4.5:1 (normal), ≥ 3:1 (large text ≥18pt)
• UI component contrast ratio: ≥ 3:1 for borders, focus indicators
• Text can be resized to 200% without loss of content or functionality
• Content is not blocked by horizontal scrolling at 320px viewport width

Operable

• All functionality available via keyboard
• No keyboard traps
• Skip navigation link present and functional
• Visible focus indicator on all focusable elements (not removed with outline: none without replacement)
• No content flashes more than 3 times per second (seizure risk)
• Page titles are descriptive and unique per page
• Link text describes destination (no "click here", "read more")
• Focus order is logical (matches visual reading order)

Understandable

• Language of page set: <html lang="en">
• Language changes marked: <span lang="fr">Bonjour</span>
• Form inputs have labels visible at all times
• Error messages identify: what went wrong + how to fix it
• No unexpected context changes on focus or input

Robust

• Valid HTML (no duplicate IDs, properly nested elements)
• Custom components have correct ARIA roles, states, and properties
• Status messages (role="alert", aria-live) announced to screen readers without receiving focus

Focus Indicator (CSS)

/* ✅ Good: visible focus indicator */
:focus-visible {
  outline: 2px solid #0066CC;
  outline-offset: 2px;
  border-radius: 2px;
}

/* ❌ Bad: removes all focus indicators */
* {
  outline: none;
}

/* Screen reader only utility class */
.sr-only {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  white-space: nowrap;
  border: 0;
}

Modal Focus Management (React)

import { useEffect, useRef } from 'react'

function Modal({ isOpen, onClose, title, children }) {
  const modalRef = useRef<HTMLDivElement>(null)
  const triggerRef = useRef<HTMLElement | null>(null)

  useEffect(() => {
    if (isOpen) {
      triggerRef.current = document.activeElement as HTMLElement
      // Move focus to first interactive element in modal
      const firstFocusable = modalRef.current?.querySelector<HTMLElement>(
        'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
      )
      firstFocusable?.focus()
    } else {
      // Return focus to trigger when modal closes
      triggerRef.current?.focus()
    }
  }, [isOpen])

  if (!isOpen) return null

  return (
    <div
      ref={modalRef}
      role="dialog"
      aria-modal="true"
      aria-labelledby="modal-title"
    >
      <h2 id="modal-title">{title}</h2>
      {children}
      <button aria-label="Close dialog">×</button>
    </div>
  )
}

DO NOT

• DO NOT use outline: none or outline: 0 without providing an alternative visible focus indicator
• DO NOT use placeholder as a label — it disappears when the user types
• DO NOT rely only on automated tools (axe, Lighthouse) — they find ~30% of real issues
• DO NOT add role="button" to a <div> without also adding tabIndex={0} and keyboard handlers
• DO NOT convey error state through color alone — add an error message or icon
• DO NOT use aria-label to override visible text — confuses users who can both see and use a screen reader
• DO NOT auto-focus a form field on page load in a way that skips past important page context
• DO NOT use tabIndex > 0 (e.g., tabIndex={3}) — it creates confusing non-linear tab order

OUTPUT FORMAT

For each accessibility audit, produce:

Accessibility Audit Report:

## Accessibility Audit Report

**Date:** 2024-01-15
**Scope:** Checkout flow (5 pages)
**WCAG Level:** 2.1 AA
**Tools Used:** axe DevTools + manual keyboard testing + VoiceOver

### Summary
| Severity | Count |
|----------|-------|
| Critical | 3 |
| Serious | 7 |
| Moderate | 12 |
| Minor | 5 |

### Critical Issues (Must Fix)
#### 1. Missing form labels on checkout address form
- WCAG Criterion: 1.3.1 Info and Relationships (Level A)
- Element: `<input id="street-address">` (no associated label)
- Impact: Screen reader users hear "edit text" with no context
- Fix: Add `<label for="street-address">Street Address</label>`
- Files: CheckoutAddressForm.tsx:34

### Keyboard Navigation
- [x] Tab through checkout: All fields reachable ✅
- [ ] Modal focus: Focus not trapped in order confirmation modal ❌
- [ ] Skip link: Missing ❌

### Color Contrast Failures
| Element | Foreground | Background | Actual Ratio | Required |
|---------|-----------|-----------|--------------|----------|
| Help text | #999999 | #FFFFFF | 2.85:1 | 4.5:1 |
| Disabled button text | #AAAAAA | #EEEEEE | 1.9:1 | 3:1 |

QUALITY GATES

• Automated tool (axe or Lighthouse) shows zero Critical and zero Serious violations
• Full tab navigation through all critical user flows completed without mouse
• All form fields have visible, persistent labels (not just placeholder)
• Modal/dialog focus management tested: open → focus in, close → focus returns
• Color contrast verified for all text elements (≥ 4.5:1 normal, ≥ 3:1 large)
• All images have appropriate alt text (not "image" or filename)
• <html lang="..."> set correctly on all pages
• Skip link present and navigates to <main> correctly
• Screen reader test (VoiceOver or NVDA) completed on checkout flow
• prefers-reduced-motion respected for all animations