feat: add a11y skills agent (#1387)

* feat(accessibility): add Accessibility Change Audit guideline document

- Introduced a new SKILL.md file outlining the Accessibility Change Audit process.
- The document provides an overview, usage scenarios, a checklist for auditing UI changes, and minimal fix patterns to enhance accessibility in UI components.
- Aimed at improving semantic structure, catching accessibility regressions, and increasing test reliability.

* refactor(accessibility): update Accessibility Change Audit guidelines

- Enhanced the description to include accessibility audits and flaky UI tests.
- Clarified prerequisites and instructions for conducting audits.
- Introduced a diff-first approach for evaluating UI changes.
- Expanded the audit checklist and output format for better clarity and usability.

* feat(accessibility): introduce new a11y-audit skills and update existing guidelines

- Added new SKILL.md files for `claude-a11y-audit` and `codex-a11y-audit`, providing detailed descriptions for accessibility audits.
- Updated the existing `accessibility-change-audit` SKILL.md to rename it to `a11y-audit` for consistency and clarity.
- Adjusted .gitignore to exclude specific settings files.

* feat(a11y): add codex-a11y-audit skill documentation

- Introduced a new SKILL.md file for `codex-a11y-audit`, detailing its use for reviewing UI diffs, accessibility audits, and identifying a11y regressions.
- The document includes a link to the canonical skill for consistency in accessibility auditing practices.

* feat(a11y): update a11y-audit skill documentation and introduce new file

- Updated the SKILL.md files for `claude-a11y-audit` and `codex-a11y-audit` to link to the new `a11y-audit` documentation.
- Introduced a comprehensive SKILL.md file for `a11y-audit`, detailing its purpose, prerequisites, instructions, and a checklist for conducting accessibility audits.
- Enhanced the document to provide clear guidelines for identifying accessibility regressions and proposing minimal fixes.

Author: tyler-dane

.claude/skills/a11y-audit/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: claude-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.
+---
+
+This skill is shared. Read the canonical skill at:
+../../../skills/a11y-audit/SKILL.md

.codex/skills/a11y-audit/SKILL.md

@@ -0,0 +1,7 @@
+---
+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.
+---
+
+This skill is shared. Read the canonical skill at:
+../../../skills/a11y-audit/SKILL.md

.gitignore

@@ -19,7 +19,7 @@ packages/**/yarn.lock
 # DIRS #
 ########
 # root
-.claude/
+.claude/settings.local.json
 .cursor/
 .idea/
 .mcp.json

skills/a11y-audit/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: 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.
+---
+
+# 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 <button> or add role="button", tabIndex=0, and Enter/Space handling.
+
+3. Form label
+
+- Add <label htmlFor> 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 <button type="button"> 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.