Skip to content

Commit e27eb1e

Browse files
Copilottyler-daneCopilot
authored
chore: create dedicated Claude and Codex skills, remove shared skill (#1409)
* Initial plan * feat: create dedicated Claude and Codex skills, remove shared skill Co-authored-by: tyler-dane <30163055+tyler-dane@users.noreply.github.com> * Update .codex/skills/a11y-audit/SKILL.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * fix(cursorrules): update accessibility.md to reference only codex skill Co-authored-by: tyler-dane <30163055+tyler-dane@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: tyler-dane <30163055+tyler-dane@users.noreply.github.com> Co-authored-by: Tyler Dane <tyler@switchback.tech> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
1 parent b9b5d0d commit e27eb1e

File tree

4 files changed

+267
-142
lines changed

4 files changed

+267
-142
lines changed

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

Lines changed: 129 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,5 +3,132 @@ name: claude-a11y-audit
33
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.
44
---
55

6-
This skill is shared. Read the canonical skill at:
7-
../../../skills/a11y-audit/SKILL.md
6+
# Accessibility Change Audit
7+
8+
Brief purpose: review UI changes for accessibility regressions and missing improvements, then propose minimal fixes tied to the diff.
9+
10+
## Overview
11+
12+
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.
13+
14+
## Prerequisites
15+
16+
- A diff, PR, or change list that includes relevant UI files.
17+
- Optional: a screenshot or description of the changed UI state.
18+
19+
## Instructions
20+
21+
### Step 1: Scope the audit to the diff
22+
23+
Identify changed UI elements, interactions, and styles. Ignore unrelated files.
24+
25+
### Step 2: Run the diff-first checklist
26+
27+
Focus on changes that alter semantics, interaction, or visual affordances.
28+
29+
### Step 3: Produce findings and minimal fixes
30+
31+
Tie each issue to a specific change and propose the smallest reasonable fix.
32+
33+
### Step 4: Improve test reliability
34+
35+
Recommend role- and name-based queries for tests instead of data or class selectors.
36+
37+
## Audit Checklist (Diff-First)
38+
39+
Semantics and structure
40+
41+
- Headings follow order and are not skipped.
42+
- Interactive elements are buttons/links, not divs/spans.
43+
- Landmarks are present for new regions (main, nav, header, footer, aside).
44+
- Lists and tables use correct elements (ul/ol/li, th/thead/tbody).
45+
46+
Labels and names
47+
48+
- Inputs have labels or aria-label/aria-labelledby.
49+
- Icon-only controls have accessible names.
50+
- Helper text ties to inputs via aria-describedby.
51+
52+
Keyboard and focus
53+
54+
- All interactive elements are keyboard reachable and operable.
55+
- Focus order follows DOM order (avoid tabIndex > 0).
56+
- Dialogs/menus trap focus and return focus to trigger.
57+
58+
ARIA correctness
59+
60+
- ARIA only when native semantics are insufficient.
61+
- aria-expanded/controls/pressed reflect actual state.
62+
- role is correct and not redundant.
63+
64+
Visual and motion
65+
66+
- Text and focus indicators meet contrast requirements.
67+
- Color is not the only indicator.
68+
- Motion respects reduced-motion preferences.
69+
70+
Media and imagery
71+
72+
- Images have meaningful alt or empty alt for decorative.
73+
- Media controls are accessible and labeled.
74+
75+
Testing reliability
76+
77+
- New elements can be found by role and accessible name.
78+
- Interaction tests use user flows and semantic queries.
79+
80+
## Minimal Fix Patterns
81+
82+
1. Icon-only button
83+
84+
- Add visible text or aria-label.
85+
86+
2. Clickable non-button
87+
88+
- Convert to <button> or add role="button", tabIndex=0, and Enter/Space handling.
89+
90+
3. Form label
91+
92+
- Add <label htmlFor> or aria-labelledby and connect helper text with aria-describedby.
93+
94+
4. Disclosure
95+
96+
- Toggle uses aria-expanded and aria-controls; update on state change.
97+
98+
5. Dialog
99+
100+
- Use role="dialog", aria-modal, label by heading, and return focus on close.
101+
102+
## Output Format
103+
104+
Findings (ordered by severity):
105+
106+
- [severity] path:line - problem and impact
107+
Fix: minimal change suggestion
108+
109+
Tests:
110+
111+
- Recommend updates that use role/name queries and user-driven events.
112+
113+
UX/Speed Note:
114+
115+
- Call out any change that impacts perceived speed (layout shifts, heavy DOM, over-rendering).
116+
117+
Severity scale: blocker, high, medium, low.
118+
119+
## Example Review Output
120+
121+
Findings:
122+
123+
- high `packages/web/src/views/Example.tsx:42` - Clickable div lacks keyboard support; keyboard users cannot activate it.
124+
Fix: convert to <button type="button"> or add role, tabIndex, and Enter/Space handlers.
125+
- medium `packages/web/src/views/Example.tsx:60` - Icon-only control has no accessible name.
126+
Fix: add aria-label="Add event".
127+
128+
Tests:
129+
130+
- Add a role-based query: getByRole("button", { name: /add event/i }).
131+
132+
UX/Speed Note:
133+
134+
- No layout shift detected; DOM complexity unchanged.

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

Lines changed: 134 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,139 @@
11
---
22
name: codex-a11y-audit
33
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.
4+
version: 1.0.0
5+
tags:
6+
- accessibility
7+
- ui
8+
- testing
49
---
510

6-
This skill is shared. Read the canonical skill at:
7-
../../../skills/a11y-audit/SKILL.md
11+
# Accessibility Change Audit
12+
13+
Brief purpose: review UI changes for accessibility regressions and missing improvements, then propose minimal fixes tied to the diff.
14+
15+
## Overview
16+
17+
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.
18+
19+
## Prerequisites
20+
21+
- A diff, PR, or change list that includes relevant UI files.
22+
- Optional: a screenshot or description of the changed UI state.
23+
24+
## Instructions
25+
26+
### Step 1: Scope the audit to the diff
27+
28+
Identify changed UI elements, interactions, and styles. Ignore unrelated files.
29+
30+
### Step 2: Run the diff-first checklist
31+
32+
Focus on changes that alter semantics, interaction, or visual affordances.
33+
34+
### Step 3: Produce findings and minimal fixes
35+
36+
Tie each issue to a specific change and propose the smallest reasonable fix.
37+
38+
### Step 4: Improve test reliability
39+
40+
Recommend role- and name-based queries for tests instead of data or class selectors.
41+
42+
## Audit Checklist (Diff-First)
43+
44+
Semantics and structure
45+
46+
- Headings follow order and are not skipped.
47+
- Interactive elements are buttons/links, not divs/spans.
48+
- Landmarks are present for new regions (main, nav, header, footer, aside).
49+
- Lists and tables use correct elements (ul/ol/li, th/thead/tbody).
50+
51+
Labels and names
52+
53+
- Inputs have labels or aria-label/aria-labelledby.
54+
- Icon-only controls have accessible names.
55+
- Helper text ties to inputs via aria-describedby.
56+
57+
Keyboard and focus
58+
59+
- All interactive elements are keyboard reachable and operable.
60+
- Focus order follows DOM order (avoid tabIndex > 0).
61+
- Dialogs/menus trap focus and return focus to trigger.
62+
63+
ARIA correctness
64+
65+
- ARIA only when native semantics are insufficient.
66+
- aria-expanded/controls/pressed reflect actual state.
67+
- role is correct and not redundant.
68+
69+
Visual and motion
70+
71+
- Text and focus indicators meet contrast requirements.
72+
- Color is not the only indicator.
73+
- Motion respects reduced-motion preferences.
74+
75+
Media and imagery
76+
77+
- Images have meaningful alt or empty alt for decorative.
78+
- Media controls are accessible and labeled.
79+
80+
Testing reliability
81+
82+
- New elements can be found by role and accessible name.
83+
- Interaction tests use user flows and semantic queries.
84+
85+
## Minimal Fix Patterns
86+
87+
1. Icon-only button
88+
89+
- Add visible text or aria-label.
90+
91+
2. Clickable non-button
92+
93+
- Convert to <button> or add role="button", tabIndex=0, and Enter/Space handling.
94+
95+
3. Form label
96+
97+
- Add <label htmlFor> or aria-labelledby and connect helper text with aria-describedby.
98+
99+
4. Disclosure
100+
101+
- Toggle uses aria-expanded and aria-controls; update on state change.
102+
103+
5. Dialog
104+
105+
- Use role="dialog", aria-modal, label by heading, and return focus on close.
106+
107+
## Output Format
108+
109+
Findings (ordered by severity):
110+
111+
- [severity] path:line - problem and impact
112+
Fix: minimal change suggestion
113+
114+
Tests:
115+
116+
- Recommend updates that use role/name queries and user-driven events.
117+
118+
UX/Speed Note:
119+
120+
- Call out any change that impacts perceived speed (layout shifts, heavy DOM, over-rendering).
121+
122+
Severity scale: blocker, high, medium, low.
123+
124+
## Example Review Output
125+
126+
Findings:
127+
128+
- high `packages/web/src/views/Example.tsx:42` - Clickable div lacks keyboard support; keyboard users cannot activate it.
129+
Fix: convert to <button type="button"> or add role, tabIndex, and Enter/Space handlers.
130+
- medium `packages/web/src/views/Example.tsx:60` - Icon-only control has no accessible name.
131+
Fix: add aria-label="Add event".
132+
133+
Tests:
134+
135+
- Add a role-based query: getByRole("button", { name: /add event/i }).
136+
137+
UX/Speed Note:
138+
139+
- No layout shift detected; DOM complexity unchanged.

‎.cursorrules/accessibility.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
description: Accessibility standards - semantic HTML, keyboard navigation, ARIA labels, refer to skills/a11y-audit/SKILL.md for comprehensive checklist
2+
description: Accessibility standards - semantic HTML, keyboard navigation, ARIA labels, refer to .codex/skills/a11y-audit/SKILL.md for comprehensive checklist
33
globs:
44
- "packages/web/**/*.{ts,tsx}"
55
---
@@ -23,7 +23,7 @@ Follow accessibility best practices to ensure the application is usable by every
2323
## Detailed Guidelines
2424

2525
Refer to the comprehensive accessibility audit checklist in:
26-
**`skills/a11y-audit/SKILL.md`**
26+
**`.codex/skills/a11y-audit/SKILL.md`**
2727

2828
This skill provides:
2929

@@ -131,7 +131,7 @@ This aligns with the testing standards in `testing.md`.
131131
## Audit Checklist Reference
132132

133133
For comprehensive review of UI changes, refer to:
134-
**`skills/a11y-audit/SKILL.md`**
134+
**`.codex/skills/a11y-audit/SKILL.md`**
135135

136136
Key sections:
137137

@@ -157,4 +157,4 @@ Review these for accessibility patterns:
157157
- Support keyboard navigation (Tab, Enter, Space)
158158
- Use ARIA when needed (`aria-expanded`, `aria-label`, `role`)
159159
- Test with semantic queries (`getByRole`, `getByLabelText`)
160-
- Refer to `skills/a11y-audit/SKILL.md` for detailed guidance
160+
- Refer to `.codex/skills/a11y-audit/SKILL.md` for detailed guidance

0 commit comments

Comments
 (0)