Skip to content

docs(devtools-a11y): describe the plugin API that the package exports #546

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
AlemTuzlak wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs(devtools-a11y): describe the plugin API that the package exports #546

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
73 changes: 28 additions & 45 deletions docs/plugins/a11y.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,12 +60,24 @@ render(
)
```

## Quick Start (Vue)
## Quick Start (Angular)

```ts
import { createA11yDevtoolsVuePlugin } from '@tanstack/devtools-a11y/vue'

const plugins = [createA11yDevtoolsVuePlugin()]
import { Component, signal } from '@angular/core'
import { TanStackDevtools } from '@tanstack/angular-devtools'
import { a11yDevtoolsPlugin } from '@tanstack/devtools-a11y/angular'
import type { TanStackDevtoolsAngularPlugin } from '@tanstack/angular-devtools'

@Component({
selector: 'app-root',
imports: [TanStackDevtools],
template: `<tanstack-devtools [plugins]="plugins()" />`,
})
export class App {
readonly plugins = signal<Array<TanStackDevtoolsAngularPlugin>>([
a11yDevtoolsPlugin(),
])
}
```

## Click-to-Navigate
Expand All @@ -80,30 +92,13 @@ This makes it easy to locate and inspect issues directly on the page.

## Panel Configuration

Initial configuration can be provided via the vanilla plugin API:

```ts
import { createA11yPlugin } from '@tanstack/devtools-a11y'

const plugin = createA11yPlugin({
threshold: 'serious',
ruleSet: 'wcag21aa',
showOverlays: true,
persistSettings: true,
disabledRules: [],
})
```

Common `options` fields:
Configure the plugin in the **Settings** view of the panel:

- `threshold`: minimum impact level to show
- `ruleSet`: rule preset (`'wcag2a' | 'wcag2aa' | 'wcag21aa' | 'wcag22aa' | 'section508' | 'best-practice' | 'all'`)
- `showOverlays`: highlight issues in the page
- `persistSettings`: store config in localStorage
- `disabledRules`: rule IDs to ignore
- **Severity Threshold**: the minimum impact level to show
- **Rule Set**: the rule preset (WCAG 2.0 A, WCAG 2.0 AA, WCAG 2.1 AA, WCAG 2.2 AA, Section 508, Best Practice, or All Rules)
- **Rules**: turn off single rules by category or by search

If you don't need to provide initial configuration, you can use the framework plugin helpers
directly (the settings UI persists changes to localStorage by default).
The panel saves these settings to `localStorage` under the key `tanstack-devtools-a11y-config`. The plugin helpers do not take initial settings.

## Severity Levels

Expand All @@ -118,26 +113,14 @@ Issues are categorized by impact level with corresponding overlay colors:

## Framework Support

The panel UI is implemented in Solid and wrapped for React, Solid, Preact, and Vue
using `@tanstack/devtools-utils`.
The panel UI is implemented in Solid and wrapped for React, Solid, and Angular
using `@tanstack/devtools-utils`. Each framework has its own entry point:
`@tanstack/devtools-a11y/react`, `@tanstack/devtools-a11y/solid`, and
`@tanstack/devtools-a11y/angular`.

## Export Formats

### JSON Export

```ts
import { exportToJSON } from '@tanstack/devtools-a11y'

const jsonString = exportToJSON(auditResult)
```

### CSV Export

```ts
import { exportToCSV } from '@tanstack/devtools-a11y'

const csvString = exportToCSV(auditResult)
```
After an audit, click **Export JSON** or **Export CSV** in the panel to download the results.

## Supported Standards

Expand All @@ -154,8 +137,8 @@ The plugin supports the following accessibility standards:
### Issues not appearing

1. Check that the element is visible in the viewport
2. Ensure the element is not excluded by `excludeSelectors`
3. Verify the selected standard includes the relevant rule
2. Make sure that the rule is not turned off in the panel settings
3. Make sure that the selected rule set includes the rule

### Overlays not showing

Expand Down
Loading