Skip to content

Commit 7c33985

Browse files
LadyBluenotesautofix-ci[bot]harry-whorlowlachlancollins
authored
a11y plugin (#326)
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com> Co-authored-by: Harry Whorlow <whorlowharry@gmail.com> Co-authored-by: Harry Whorlow <79278353+harry-whorlow@users.noreply.github.com> Co-authored-by: Lachlan Collins <1667261+lachlancollins@users.noreply.github.com>
1 parent 1fc0afa commit 7c33985

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

68 files changed

+8802
-2645
lines changed

‎.changeset/huge-crabs-prove.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
---
2+
'@tanstack/solid-devtools': patch
3+
'@tanstack/devtools-a11y': patch
4+
'@tanstack/devtools-ui': patch
5+
'@tanstack/devtools': patch
6+
---
7+
8+
Adds tanstack Devtool plugin. PR also includes some minor patches

‎docs/config.json‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -156,6 +156,34 @@
156156
]
157157
}
158158
]
159+
},
160+
{
161+
"label": "Plugins",
162+
"children": [],
163+
"frameworks": [
164+
{
165+
"label": "react",
166+
"children": [
167+
{
168+
"label": "a11y",
169+
"to": "framework/react/examples/a11y-devtools"
170+
}
171+
]
172+
},
173+
{
174+
"label": "preact",
175+
"children": []
176+
},
177+
{
178+
"label": "solid",
179+
"children": [
180+
{
181+
"label": "A11y",
182+
"to": "framework/solif/examples/a11y-devtools"
183+
}
184+
]
185+
}
186+
]
159187
}
160188
]
161189
}

‎docs/plugins/a11y.md‎

Lines changed: 175 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
---
2+
title: Accessibility Plugin
3+
id: a11y-plugin
4+
---
5+
6+
The TanStack Devtools Accessibility (A11y) Plugin provides real-time accessibility auditing for your web applications, powered by [axe-core](https://github.com/dequelabs/axe-core). It helps you identify and fix accessibility issues during development.
7+
8+
## Features
9+
10+
- **Full Page Scanning** - Audit your entire page for accessibility violations
11+
- **Component-Level Scanning** - Scope audits to specific components using React hooks
12+
- **Visual Overlays** - Highlight problematic elements with severity-based colors
13+
- **Click-to-Navigate** - Click on an issue to automatically scroll to and highlight the element
14+
- **Dark Mode Support** - Automatically adapts to the devtools theme
15+
- **Devtools-Aware** - Automatically excludes devtools panels from scanning
16+
- **Configurable Rule Sets** - Support for WCAG 2.0/2.1/2.2 (A/AA/AAA), Section 508, and best practices
17+
- **Export Reports** - Download results as JSON or CSV
18+
- **Persistent Settings** - Configuration saved to localStorage
19+
20+
## Installation
21+
22+
```bash
23+
npm install @tanstack/devtools-a11y
24+
# or
25+
pnpm add @tanstack/devtools-a11y
26+
# or
27+
yarn add @tanstack/devtools-a11y
28+
```
29+
30+
## Quick Start (React)
31+
32+
```tsx
33+
import { createRoot } from 'react-dom/client'
34+
import { TanStackDevtools } from '@tanstack/react-devtools'
35+
import { a11yDevtoolsPlugin } from '@tanstack/devtools-a11y/react'
36+
37+
createRoot(document.getElementById('root')!).render(
38+
<>
39+
<App />
40+
<TanStackDevtools plugins={[a11yDevtoolsPlugin()]} />
41+
</>,
42+
)
43+
```
44+
45+
## Quick Start (Solid)
46+
47+
```tsx
48+
import { render } from 'solid-js/web'
49+
import { TanStackDevtools } from '@tanstack/solid-devtools'
50+
import { a11yDevtoolsPlugin } from '@tanstack/devtools-a11y/solid'
51+
52+
render(
53+
() => (
54+
<>
55+
<App />
56+
<TanStackDevtools plugins={[a11yDevtoolsPlugin()]} />
57+
</>
58+
),
59+
document.getElementById('root')!,
60+
)
61+
```
62+
63+
## Quick Start (Vue)
64+
65+
```ts
66+
import { createA11yDevtoolsVuePlugin } from '@tanstack/devtools-a11y/vue'
67+
68+
const plugins = [createA11yDevtoolsVuePlugin()]
69+
```
70+
71+
## Click-to-Navigate
72+
73+
When you click on an issue in the panel, the plugin will:
74+
75+
1. **Scroll** the problematic element into view (centered in the viewport)
76+
2. **Highlight** the element with a pulsing overlay matching its severity color
77+
3. **Show a tooltip** with the rule ID and impact level
78+
79+
This makes it easy to locate and inspect issues directly on the page.
80+
81+
## Panel Configuration
82+
83+
Initial configuration can be provided via the vanilla plugin API:
84+
85+
```ts
86+
import { createA11yPlugin } from '@tanstack/devtools-a11y'
87+
88+
const plugin = createA11yPlugin({
89+
threshold: 'serious',
90+
ruleSet: 'wcag21aa',
91+
showOverlays: true,
92+
persistSettings: true,
93+
disabledRules: [],
94+
})
95+
```
96+
97+
Common `options` fields:
98+
99+
- `threshold`: minimum impact level to show
100+
- `ruleSet`: rule preset (`'wcag2a' | 'wcag2aa' | 'wcag21aa' | 'wcag22aa' | 'section508' | 'best-practice' | 'all'`)
101+
- `showOverlays`: highlight issues in the page
102+
- `persistSettings`: store config in localStorage
103+
- `disabledRules`: rule IDs to ignore
104+
105+
If you don't need to provide initial configuration, you can use the framework plugin helpers
106+
directly (the settings UI persists changes to localStorage by default).
107+
108+
## Severity Levels
109+
110+
Issues are categorized by impact level with corresponding overlay colors:
111+
112+
| Impact | Color | Description |
113+
|--------|-------|-------------|
114+
| Critical | Red | Must be fixed - prevents users from accessing content |
115+
| Serious | Orange | Should be fixed - significantly impacts user experience |
116+
| Moderate | Yellow | Consider fixing - affects some users |
117+
| Minor | Blue | Optional improvement - minor impact |
118+
119+
## Framework Support
120+
121+
The panel UI is implemented in Solid and wrapped for React, Solid, Preact, and Vue
122+
using `@tanstack/devtools-utils`.
123+
124+
## Export Formats
125+
126+
### JSON Export
127+
128+
```ts
129+
import { exportToJSON } from '@tanstack/devtools-a11y'
130+
131+
const jsonString = exportToJSON(auditResult)
132+
```
133+
134+
### CSV Export
135+
136+
```ts
137+
import { exportToCSV } from '@tanstack/devtools-a11y'
138+
139+
const csvString = exportToCSV(auditResult)
140+
```
141+
142+
## Supported Standards
143+
144+
The plugin supports the following accessibility standards:
145+
146+
- **WCAG 2.0** Level A, AA, AAA
147+
- **WCAG 2.1** Level A, AA, AAA
148+
- **WCAG 2.2** Level AA
149+
- **Section 508**
150+
- **Best Practices** (non-standard recommendations)
151+
152+
## Troubleshooting
153+
154+
### Issues not appearing
155+
156+
1. Check that the element is visible in the viewport
157+
2. Ensure the element is not excluded by `excludeSelectors`
158+
3. Verify the selected standard includes the relevant rule
159+
160+
### Overlays not showing
161+
162+
1. Confirm overlays are enabled in the panel settings
163+
2. Check for CSS conflicts with `z-index` or `pointer-events`
164+
3. Ensure the container element exists in the DOM
165+
166+
## Example
167+
168+
See the full working example at:
169+
`examples/react/a11y-devtools/`
170+
171+
Run it with:
172+
```bash
173+
cd examples/react/a11y-devtools
174+
pnpm dev
175+
```

‎examples/react/a11y-devtools/index.html‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
<!doctype html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="utf-8" />
5+
<link rel="icon" type="image/svg+xml" href="/emblem-light.svg" />
6+
<meta name="viewport" content="width=device-width, initial-scale=1" />
7+
<meta name="theme-color" content="#000000" />
8+
9+
<title>A11y Devtools - TanStack Devtools</title>
10+
</head>
11+
<body>
12+
<noscript>You need to enable JavaScript to run this app.</noscript>
13+
<div id="root"></div>
14+
<script type="module" src="/src/index.tsx"></script>
15+
</body>
16+
</html>

‎examples/react/a11y-devtools/package.json‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
{
2+
"name": "@tanstack/react-devtools-a11y-example",
3+
"private": true,
4+
"type": "module",
5+
"scripts": {
6+
"dev": "vite --port=3002",
7+
"build": "vite build",
8+
"preview": "vite preview",
9+
"test:types": "tsc"
10+
},
11+
"dependencies": {
12+
"@tanstack/devtools-a11y": "workspace:*",
13+
"@tanstack/react-devtools": "^0.9.13",
14+
"react": "^19.2.0",
15+
"react-dom": "^19.2.0"
16+
},
17+
"devDependencies": {
18+
"@types/react": "^19.2.0",
19+
"@types/react-dom": "^19.2.0",
20+
"@vitejs/plugin-react": "^5.0.4",
21+
"vite": "^7.1.7"
22+
},
23+
"browserslist": {
24+
"production": [
25+
">0.2%",
26+
"not dead",
27+
"not op_mini all"
28+
],
29+
"development": [
30+
"last 1 chrome version",
31+
"last 1 firefox version",
32+
"last 1 safari version"
33+
]
34+
}
35+
}

0 commit comments

Comments
 (0)