audit-accessibility

Audit: Accessibility

Purpose

Evaluates the accessibility posture of generated or modified frontend code. Checks for WCAG 2.1 AA compliance, semantic HTML, ARIA correctness, keyboard navigation, focus management, and color contrast — calibrated to Imagine Learning's ed-tech requirements where students with disabilities are a core user population.

A high score means the UI is usable by people with diverse abilities; a low score means barriers exist that prevent or degrade access.

Context: This audit runs against newly generated code changes (the git diff + new/modified files) that contain frontend components, pages, or templates. If the changeset contains no frontend code, this audit should return a score of 10 with a note that no frontend code was present.

Applicability: Skip this audit entirely (return score 10, confidence High, zero findings, summary "No frontend code in changeset") if the changeset contains zero .tsx, .jsx, .vue, .svelte, .html, or template files.

Evaluation Criteria

1. Semantic HTML

• What to look for: Use of native HTML elements for their intended purpose instead of generic div/span with ARIA roles bolted on.
• How to assess: Read component files for element choices. Check that interactive elements use native HTML (button, a, select, input, dialog, nav, main, header, footer, section, article) rather than div with onClick or role="button".
  • Good: <button onClick={...}>, <nav>, <main>, <dialog>, <ul> for lists, <table> for tabular data
  • Bad: <div onClick={...}>, <span role="button">, <div class="nav">, custom dropdown built entirely from divs
• Severity: MAJOR for each interactive element that should be a native element (buttons, links, inputs); MINOR for structural elements (nav, main, section)
• Auto-cap: More than 3 clickable div/span elements without proper roles caps the score at 5 maximum.

2. ARIA Usage

• What to look for: Correct and necessary ARIA attributes — not over-applied, not missing where needed.
• How to assess: Check that ARIA attributes are valid, correctly applied, and only used when native semantics are insufficient.
  • Good: aria-label on icon-only buttons, aria-expanded on disclosure widgets, aria-live on dynamic content regions, aria-describedby linking errors to inputs
  • Bad: aria-label duplicating visible text, invalid ARIA roles, aria-hidden="true" on focusable elements, missing aria-expanded on toggles, redundant ARIA on native elements (role="button" on <button>)
• Severity: CRITICAL if aria-hidden="true" is set on a focusable/interactive element (makes it invisible to screen readers but still focusable — a trap); MAJOR for missing ARIA on custom widgets; MINOR for redundant/unnecessary ARIA
• Key rule: No ARIA is better than bad ARIA. Flag over-application as well as under-application.

3. Keyboard Navigation

• What to look for: All interactive elements reachable and operable via keyboard alone.
• How to assess: Trace the component tree for interactive elements and verify they are keyboard accessible.
  • Good: Native elements used (inherently keyboard accessible), tabIndex={0} with onKeyDown handlers for custom widgets, focus order follows visual order, no tabIndex values greater than 0
  • Bad: Click handlers without keyboard equivalents, tabIndex={-1} on elements that should be in the tab order, positive tabIndex values disrupting natural order, mouse-only interactions (hover to reveal, drag without keyboard alternative)
• Severity: CRITICAL for interactive elements with no keyboard access path; MAJOR for incomplete keyboard support (e.g., can focus but can't activate); MINOR for suboptimal tab order
• IL-specific: Ed-tech applications are used by students who may rely on keyboard navigation, switch devices, or alternative input methods. Keyboard accessibility is not optional.

4. Focus Management

• What to look for: Proper focus handling during dynamic UI changes — modals, dialogs, route transitions, and dynamic content insertion.
• How to assess: Read modal/dialog implementations, route change handlers, and dynamic content components for focus management.
  • Good: Focus moves to modal on open and returns to trigger on close, focus trapped within modal while open, focus moves to new content after route change, skip links present for repeated navigation blocks
  • Bad: Focus lost after modal close (drops to body), no focus trap in modals (user can tab behind the modal), no focus management on route changes, no skip links
• Severity: MAJOR for each modal/dialog without focus trap or focus restoration; MINOR for missing focus management on non-modal dynamic content
• IL-specific: Use the native <dialog> element where possible — it provides focus trapping and restoration for free.

5. Images & Media

• What to look for: Alt text on images, captions on media, decorative images properly hidden.
• How to assess: Grep for <img, <Image, <svg, <video, <audio elements and verify accessibility attributes.
  • Good: Informative images have descriptive alt text, decorative images have alt="", SVG icons have aria-hidden="true" or aria-label, videos have captions/transcripts
  • Bad: Missing alt attributes, decorative images with meaningless alt text ("image", "icon"), SVG icons without any label, auto-playing media without controls
• Severity: MAJOR for missing alt on informative images; MINOR for missing alt on decorative images (should be alt=""); CRITICAL for auto-playing audio/video without controls
• IL-specific: Educational content images often carry meaning that cannot be inferred from context — generic alt text like "illustration" is insufficient.

6. Forms & Error Handling

• What to look for: Form inputs with labels, error messages associated with fields, validation feedback accessible to screen readers.
• How to assess: Read form components for label associations, error handling patterns, and live region announcements.
  • Good: Every input has a visible <label> with matching htmlFor/id, errors linked via aria-describedby, aria-invalid set on errored fields, error summary announced via aria-live="polite" region
  • Bad: Placeholder-only labels (disappear on focus), errors not associated with fields, validation relying only on color (red border), no programmatic indication of required fields
• Severity: MAJOR for inputs without labels or errors not associated with fields; MINOR for missing aria-required or incomplete error announcements
• IL-specific: Student-facing forms must be especially clear — students may not understand implicit UI conventions. Explicit labels and clear error messages are mandatory.

7. Color & Contrast

• What to look for: Color contrast ratios in inline styles, CSS-in-JS, or theme tokens; information conveyed by color alone.
• How to assess: Check inline styles and theme/design token usage for color values. Verify that color is not the sole indicator of state (error, success, active).
  • Good: Design system tokens with pre-validated contrast ratios, state indicated by icon + color + text, focus indicators visible against background
  • Bad: Light gray text on white background, error indicated only by red color, focus outline removed (outline: none) without replacement, custom colors that bypass the design system
• Severity: MAJOR if focus indicator is removed without replacement (users can't see where they are); MAJOR if information is conveyed by color alone; MINOR for potential contrast issues in custom colors
• Note: Static analysis of contrast is limited without rendering. Flag suspicious patterns but set confidence to Medium for color-specific findings unless you can compute the actual ratio from token values.

Scoring Rubric

Domain-specific scoring applies: more than 3 clickable div/span elements caps the score at 5 maximum.

• 9-10: No CRITICAL or MAJOR findings, at most 2 MINOR — fully semantic, keyboard accessible, properly labeled
• 7-8: No CRITICAL, at most 2 MAJOR — good foundation with minor gaps (missing a label, one unlabeled icon button)
• 5-6: No CRITICAL, at most 5 MAJOR — structural issues like missing focus management or several unlabeled inputs
• 3-4: 1 CRITICAL or more than 5 MAJOR — keyboard traps, interactive elements unreachable, widespread labeling gaps
• 1-2: Multiple CRITICAL findings — fundamental barriers to access

Calibration

Your default assumption should be that the generated code has accessibility gaps. Most AI-generated frontend code defaults to divs with click handlers and skips focus management.

• A score of 8+ should be rare for generated code. Most first-pass generated components have at least 2-3 MAJOR a11y gaps — missing keyboard handlers, no focus trap in modals, or unlabeled icon buttons.
• If you find zero CRITICAL or MAJOR findings, explicitly document what you checked. Set confidence to Medium unless you verified every interactive element for keyboard access, checked all images for alt text, and traced focus management through modals and route changes.
• Score anchors:
  • 8/10 example: Semantic HTML throughout, all inputs labeled, keyboard accessible, one MINOR issue (missing aria-describedby on an error message)
  • 5/10 example: Mostly semantic but 3 clickable divs, a modal without focus trap, 2 inputs with placeholder-only labels
  • 2/10 example: Multiple keyboard-inaccessible elements, no alt text on educational images, aria-hidden on a focusable modal
• You are more valuable when you find real barriers than when you confirm compliance.

Sampling Strategy

1. Use Glob to locate all .tsx, .jsx, .vue, .svelte, .html files in the changeset
2. If no frontend files are found, return the "no frontend code" result immediately
3. Read all frontend files in the changeset
4. Grep for div.*onClick, span.*onClick, div.*role= to find non-semantic interactive patterns
5. Grep for <img, <Image, <svg and check for alt or aria-label attributes
6. Grep for <input, <select, <textarea and verify <label> associations
7. Search for modal/dialog implementations and check for focus trap and restoration
8. Grep for outline: none, outline: 0 to find removed focus indicators
9. Grep for aria-hidden and verify it's not on focusable elements
10. Grep for tabIndex usage and flag positive values
11. Set confidence:
    • High: Analyzed all frontend files, verified interactive elements, checked focus management, reviewed ARIA usage
    • Medium: Analyzed most frontend files but component tree is deep or some patterns are in shared libraries outside the changeset
    • Low: Analyzed fewer than 5 frontend files or the changeset is very small

Output Schema

Return results as structured JSON:

{
  "category": "accessibility",
  "score": 5,
  "confidence": "High",
  "findings": [
    {
      "severity": "MAJOR",
      "criterion": "semantic-html",
      "description": "3 clickable div elements used instead of button — score capped at 5",
      "location": "src/components/ActionBar.tsx:24,31,47",
      "recommendation": "Replace <div onClick={...}> with <button onClick={...}> — native buttons provide keyboard access, focus management, and screen reader semantics for free"
    },
    {
      "severity": "MAJOR",
      "criterion": "focus-management",
      "description": "ConfirmDialog component has no focus trap — users can tab behind the dialog to page content",
      "location": "src/components/ConfirmDialog.tsx:18",
      "recommendation": "Use the native <dialog> element or add a focus trap (e.g., focus-trap-react) and return focus to the trigger on close"
    }
  ],
  "top_recommendations": [
    "Replace clickable divs with native button elements across ActionBar component",
    "Add focus trap and focus restoration to ConfirmDialog",
    "Add aria-describedby linking error messages to their form inputs in StudentForm"
  ],
  "summary": "Moderate accessibility gaps -- non-semantic interactive elements and missing focus management in modal dialogs"
}