codex-a11y-audit

name	codex-a11y-audit
description	Use when reviewing UI diffs, accessibility audits, or flaky UI tests to catch a11y regressions, semantic issues, keyboard/focus problems, and to recommend minimal fixes plus role-based test selectors.
version	1.0.0
tags	["accessibility","ui","testing"]

Accessibility Change Audit

Brief purpose: review UI changes for accessibility regressions and missing improvements, then propose minimal fixes tied to the diff.

Overview

This skill audits UI diffs for semantics, keyboard access, focus management, ARIA correctness, contrast, and testability. It is diff-first: only evaluate changed lines and their immediate context.

Prerequisites

• A diff, PR, or change list that includes relevant UI files.
• Optional: a screenshot or description of the changed UI state.

Instructions

Step 1: Scope the audit to the diff

Identify changed UI elements, interactions, and styles. Ignore unrelated files.

Step 2: Run the diff-first checklist

Focus on changes that alter semantics, interaction, or visual affordances.

Step 3: Produce findings and minimal fixes

Tie each issue to a specific change and propose the smallest reasonable fix.

Step 4: Improve test reliability

Recommend role- and name-based queries for tests instead of data or class selectors.

Audit Checklist (Diff-First)

Semantics and structure

• Headings follow order and are not skipped.
• Interactive elements are buttons/links, not divs/spans.
• Landmarks are present for new regions (main, nav, header, footer, aside).
• Lists and tables use correct elements (ul/ol/li, th/thead/tbody).

Labels and names

• Inputs have labels or aria-label/aria-labelledby.
• Icon-only controls have accessible names.
• Helper text ties to inputs via aria-describedby.

Keyboard and focus

• All interactive elements are keyboard reachable and operable.
• Focus order follows DOM order (avoid tabIndex > 0).
• Dialogs/menus trap focus and return focus to trigger.

ARIA correctness

• ARIA only when native semantics are insufficient.
• aria-expanded/controls/pressed reflect actual state.
• role is correct and not redundant.

Visual and motion

• Text and focus indicators meet contrast requirements.
• Color is not the only indicator.
• Motion respects reduced-motion preferences.

Media and imagery

• Images have meaningful alt or empty alt for decorative.
• Media controls are accessible and labeled.

Testing reliability

• New elements can be found by role and accessible name.
• Interaction tests use user flows and semantic queries.

Minimal Fix Patterns

1. Icon-only button

• Add visible text or aria-label.

2. Clickable non-button

• Convert to or add role="button", tabIndex=0, and Enter/Space handling.

3. Form label

• Add or aria-labelledby and connect helper text with aria-describedby.

4. Disclosure

• Toggle uses aria-expanded and aria-controls; update on state change.

5. Dialog

• Use role="dialog", aria-modal, label by heading, and return focus on close.

Output Format

Findings (ordered by severity):

• [severity] path:line - problem and impact Fix: minimal change suggestion

Tests:

• Recommend updates that use role/name queries and user-driven events.

UX/Speed Note:

• Call out any change that impacts perceived speed (layout shifts, heavy DOM, over-rendering).

Severity scale: blocker, high, medium, low.

Example Review Output

Findings:

• high packages/web/src/views/Example.tsx:42 - Clickable div lacks keyboard support; keyboard users cannot activate it. Fix: convert to or add role, tabIndex, and Enter/Space handlers.
• medium packages/web/src/views/Example.tsx:60 - Icon-only control has no accessible name. Fix: add aria-label="Add event".

Tests:

• Add a role-based query: getByRole("button", { name: /add event/i }).

UX/Speed Note:

• No layout shift detected; DOM complexity unchanged.