a11y-fixes

Name: a11y-fixes
Author: gaia-react

20stars3forks

How to install a11y-fixes?

gaia-react/gaia/a11y-fixes

$npx -y skills add gaia-react/gaia --skill a11y-fixes

Installs into the current project.

Summary

Resolve axe-core accessibility violations reported by Vitest (test/a11y.ts), Playwright (.playwright/a11y.ts), or the code-audit-frontend agent's a11y bucket. Trigger on any axe rule id appearing in test output, not only the ones named here. Contains fix patterns for the most com

Files · 1

View on GitHub

SKILL.md

1	# Accessibility Fix Patterns
2
3	How to resolve specific axe-core violations in this project.
4
5	Violations come from `test/a11y.ts` (Vitest), `.playwright/a11y.ts` (Playwright), or the `code-audit-frontend` agent's a11y bucket. General a11y guidance lives in `.claude/rules/accessibility.md`.
6
7	## color-contrast
8
9	WCAG AA requires 4.5:1 for normal text, 3:1 for large text. Use the project's semantic Tailwind tokens (see `.claude/rules/tailwind.md`) instead of arbitrary palette colors, they pair light/dark modes correctly.
10
11	```tsx
12	// BAD, fails contrast in dark mode, raw colors
13	<p className="text-gray-400 bg-white">Status</p>
14
15	// GOOD, semantic tokens, contrast-safe in both modes
16	<p className="text-body bg-body">Status</p>
17	```
18
19	## label
20
21	Form inputs need an associated `<label>`. Use GAIA's `Field` wrapper from `~/components/Form/Field` rather than a bare `<label>`, it wires `htmlFor`, error text, and description automatically. See the `form-components.md` audit extension.
22
23	```tsx
24	// BAD, bare input with no label association
25	<input type="text" name="email" />
26
27	// GOOD, Field wraps a project input with the right wiring
28	<Field type="input" name="email" label={t('email')}>
29	<InputText name="email" />
30	</Field>
31	```
32
33	## label-title-only
34
35	`title` attributes are not labels, screen readers and mobile devices ignore them. Use `aria-label` or a real `<label>`.
36
37	```tsx
38	// BAD, title is not an accessible name
39	<input type="text" title="Search" />
40
41	// GOOD, aria-label provides the accessible name
42	<input type="text" aria-label={t('search')} />
43	```
44
45	## image-alt
46
47	Every `<img>` needs `alt`. Content images describe the image; decorative images use `alt=""`. See `.claude/rules/accessibility.md`.
48
49	```tsx
50	// BAD, no alt attribute
51	<img src="/logo.png" />
52
53	// GOOD, content image
54	<img src="/logo.png" alt={t('companyLogo')} />
55
56	// GOOD, decorative image, hidden from AT
57	<img src="/divider.svg" alt="" />
58	```
59
60	## button-name
61
62	Buttons need an accessible name. Visible text is fine; icon-only buttons need `aria-label`.
63
64	```tsx
65	// BAD, icon-only button with no name
66	<button onClick={onClose}>
67	<CloseIcon />
68	</button>
69
70	// GOOD, aria-label supplies the name
71	<button aria-label={t('close')} onClick={onClose}>
72	<CloseIcon />
73	</button>
74
75	// GOOD, visible text, no aria-label needed
76	<button onClick={onSave}>{t('save')}</button>
77	```
78
79	## link-name
80
81	Same pattern as `button-name`, anchors need an accessible name.
82
83	```tsx
84	// BAD, icon-only link
85	<Link to="/settings"><GearIcon /></Link>
86
87	// GOOD, aria-label on the link
88	<Link to="/settings" aria-label={t('settings')}>
89	<GearIcon />
90	</Link>
91	```
92
93	## region / landmark-one-main
94
95	Page content must live inside a landmark, and there must be exactly one `<main>`. GAIA's Layout component owns the `<main>` landmark, page components render inside it and should not add their own.
96
97	```tsx
98	// BAD, page component wraps itself in <main>, duplicating Layout's
99	const Page = () => (
100	<main>
101	<h1>{t('title')}</h1>
102	</main>
103	);
104
105	// GOOD, page renders into Layout's <main>
106	const Page = () => (
107	<>
108	<h1>{t('title')}</h1>
109	</>
110	);
111	```
112
113	## heading-order
114
115	One `<h1>` per page. Levels do not skip, `h2 → h4` is a violation.
116
117	```tsx
118	// BAD, skips h3
119	<h2>{t('section')}</h2>
120	<h4>{t('subsection')}</h4>
121
122	// GOOD, sequential levels
123	<h2>{t('section')}</h2>
124	<h3>{t('subsection')}</h3>
125	```
126
127	## aria-allowed-attr
128
129	ARIA attributes are role-scoped. Look up the role; only attrs in its allowed list are valid. Common case: `aria-checked` only on `role="checkbox"`, `role="radio"`, `role="menuitemcheckbox"`, `role="menuitemradio"`, `role="switch"`, `role="treeitem"`.
130
131	```tsx
132	// BAD, aria-checked is not allowed on a button
133	<button aria-checked={selected}>{t('toggle')}</button>
134
135	// GOOD, aria-pressed for buttons, aria-checked for checkbox role
136	<button aria-pressed={selected}>{t('toggle')}</button>
137	```
138
139	## aria-required-attr
140
141	Some roles require companion attrs. Disclosure widgets (`aria-expanded`) need `aria-controls` pointing at the controlled element's id.
142
143	```tsx
144	// BAD, aria-expanded with no aria-controls
145	<button aria-expanded={open}>{t('menu')}</button>
146
147	// GOOD, aria-controls names the panel
148	<button aria-expanded={open} aria-controls="menu-panel">
149	{t('menu')}
150	</button>
151	<div id="menu-panel" hidden={

People who liked this also viewed

6 picks

Type

a11y-fixes

20stars3forks

View on GitHub

How to install a11y-fixes?

gaia-react/gaia/a11y-fixes

$npx -y skills add gaia-react/gaia --skill a11y-fixes

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Accessibility Fix Patterns
2
3	How to resolve specific axe-core violations in this project.
4
5	Violations come from `test/a11y.ts` (Vitest), `.playwright/a11y.ts` (Playwright), or the `code-audit-frontend` agent's a11y bucket. General a11y guidance lives in `.claude/rules/accessibility.md`.
6
7	## color-contrast
8
9	WCAG AA requires 4.5:1 for normal text, 3:1 for large text. Use the project's semantic Tailwind tokens (see `.claude/rules/tailwind.md`) instead of arbitrary palette colors, they pair light/dark modes correctly.
10
11	```tsx
12	// BAD, fails contrast in dark mode, raw colors
13	<p className="text-gray-400 bg-white">Status</p>
14
15	// GOOD, semantic tokens, contrast-safe in both modes
16	<p className="text-body bg-body">Status</p>
17	```
18
19	## label
20
21	Form inputs need an associated `<label>`. Use GAIA's `Field` wrapper from `~/components/Form/Field` rather than a bare `<label>`, it wires `htmlFor`, error text, and description automatically. See the `form-components.md` audit extension.
22
23	```tsx
24	// BAD, bare input with no label association
25	<input type="text" name="email" />
26
27	// GOOD, Field wraps a project input with the right wiring
28	<Field type="input" name="email" label={t('email')}>
29	<InputText name="email" />
30	</Field>
31	```
32
33	## label-title-only
34
35	`title` attributes are not labels, screen readers and mobile devices ignore them. Use `aria-label` or a real `<label>`.
36
37	```tsx
38	// BAD, title is not an accessible name
39	<input type="text" title="Search" />
40
41	// GOOD, aria-label provides the accessible name
42	<input type="text" aria-label={t('search')} />
43	```
44
45	## image-alt
46
47	Every `<img>` needs `alt`. Content images describe the image; decorative images use `alt=""`. See `.claude/rules/accessibility.md`.
48
49	```tsx
50	// BAD, no alt attribute
51	<img src="/logo.png" />
52
53	// GOOD, content image
54	<img src="/logo.png" alt={t('companyLogo')} />
55
56	// GOOD, decorative image, hidden from AT
57	<img src="/divider.svg" alt="" />
58	```
59
60	## button-name
61
62	Buttons need an accessible name. Visible text is fine; icon-only buttons need `aria-label`.
63
64	```tsx
65	// BAD, icon-only button with no name
66	<button onClick={onClose}>
67	<CloseIcon />
68	</button>
69
70	// GOOD, aria-label supplies the name
71	<button aria-label={t('close')} onClick={onClose}>
72	<CloseIcon />
73	</button>
74
75	// GOOD, visible text, no aria-label needed
76	<button onClick={onSave}>{t('save')}</button>
77	```
78
79	## link-name
80
81	Same pattern as `button-name`, anchors need an accessible name.
82
83	```tsx
84	// BAD, icon-only link
85	<Link to="/settings"><GearIcon /></Link>
86
87	// GOOD, aria-label on the link
88	<Link to="/settings" aria-label={t('settings')}>
89	<GearIcon />
90	</Link>
91	```
92
93	## region / landmark-one-main
94
95	Page content must live inside a landmark, and there must be exactly one `<main>`. GAIA's Layout component owns the `<main>` landmark, page components render inside it and should not add their own.
96
97	```tsx
98	// BAD, page component wraps itself in <main>, duplicating Layout's
99	const Page = () => (
100	<main>
101	<h1>{t('title')}</h1>
102	</main>
103	);
104
105	// GOOD, page renders into Layout's <main>
106	const Page = () => (
107	<>
108	<h1>{t('title')}</h1>
109	</>
110	);
111	```
112
113	## heading-order
114
115	One `<h1>` per page. Levels do not skip, `h2 → h4` is a violation.
116
117	```tsx
118	// BAD, skips h3
119	<h2>{t('section')}</h2>
120	<h4>{t('subsection')}</h4>
121
122	// GOOD, sequential levels
123	<h2>{t('section')}</h2>
124	<h3>{t('subsection')}</h3>
125	```
126
127	## aria-allowed-attr
128
129	ARIA attributes are role-scoped. Look up the role; only attrs in its allowed list are valid. Common case: `aria-checked` only on `role="checkbox"`, `role="radio"`, `role="menuitemcheckbox"`, `role="menuitemradio"`, `role="switch"`, `role="treeitem"`.
130
131	```tsx
132	// BAD, aria-checked is not allowed on a button
133	<button aria-checked={selected}>{t('toggle')}</button>
134
135	// GOOD, aria-pressed for buttons, aria-checked for checkbox role
136	<button aria-pressed={selected}>{t('toggle')}</button>
137	```
138
139	## aria-required-attr
140
141	Some roles require companion attrs. Disclosure widgets (`aria-expanded`) need `aria-controls` pointing at the controlled element's id.
142
143	```tsx
144	// BAD, aria-expanded with no aria-controls
145	<button aria-expanded={open}>{t('menu')}</button>
146
147	// GOOD, aria-controls names the panel
148	<button aria-expanded={open} aria-controls="menu-panel">
149	{t('menu')}
150	</button>
151	<div id="menu-panel" hidden={

People who liked this also viewed

6 picks

Type