# Accessibility Plugin

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.

## Features

- **Full Page Scanning** - Audit your entire page for accessibility violations
- **Component-Level Scanning** - Scope audits to specific components using React hooks
- **Visual Overlays** - Highlight problematic elements with severity-based colors
- **Click-to-Navigate** - Click on an issue to automatically scroll to and highlight the element
- **Dark Mode Support** - Automatically adapts to the devtools theme
- **Devtools-Aware** - Automatically excludes devtools panels from scanning
- **Configurable Rule Sets** - Support for WCAG 2.0/2.1/2.2 (A/AA/AAA), Section 508, and best practices
- **Export Reports** - Download results as JSON or CSV
- **Persistent Settings** - Configuration saved to localStorage

## Installation

```bash
npm install @tanstack/devtools-a11y
# or
pnpm add @tanstack/devtools-a11y
# or
yarn add @tanstack/devtools-a11y
```

## Quick Start (React)

```tsx
import { createRoot } from 'react-dom/client'
import { TanStackDevtools } from '@tanstack/react-devtools'
import { a11yDevtoolsPlugin } from '@tanstack/devtools-a11y/react'

createRoot(document.getElementById('root')!).render(
  <>
    <App />
    <TanStackDevtools plugins={[a11yDevtoolsPlugin()]} />
  </>,
)
```

## Quick Start (Solid)

```tsx
import { render } from 'solid-js/web'
import { TanStackDevtools } from '@tanstack/solid-devtools'
import { a11yDevtoolsPlugin } from '@tanstack/devtools-a11y/solid'

render(
  () => (
    <>
      <App />
      <TanStackDevtools plugins={[a11yDevtoolsPlugin()]} />
    </>
  ),
  document.getElementById('root')!,
)
```

## Quick Start (Vue)

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

const plugins = [createA11yDevtoolsVuePlugin()]
```

## Click-to-Navigate

When you click on an issue in the panel, the plugin will:

1. **Scroll** the problematic element into view (centered in the viewport)
2. **Highlight** the element with a pulsing overlay matching its severity color
3. **Show a tooltip** with the rule ID and impact level

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:

- `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

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).

## Severity Levels

Issues are categorized by impact level with corresponding overlay colors:

| Impact | Color | Description |
|--------|-------|-------------|
| Critical | Red | Must be fixed - prevents users from accessing content |
| Serious | Orange | Should be fixed - significantly impacts user experience |
| Moderate | Yellow | Consider fixing - affects some users |
| Minor | Blue | Optional improvement - minor impact |

## Framework Support

The panel UI is implemented in Solid and wrapped for React, Solid, Preact, and Vue
using `@tanstack/devtools-utils`.

## 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)
```

## Supported Standards

The plugin supports the following accessibility standards:

- **WCAG 2.0** Level A, AA, AAA
- **WCAG 2.1** Level A, AA, AAA
- **WCAG 2.2** Level AA
- **Section 508**
- **Best Practices** (non-standard recommendations)

## Troubleshooting

### 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

### Overlays not showing

1. Confirm overlays are enabled in the panel settings
2. Check for CSS conflicts with `z-index` or `pointer-events`
3. Ensure the container element exists in the DOM

## Example

See the full working example at:
`examples/react/a11y-devtools/`

Run it with:
```bash
cd examples/react/a11y-devtools
pnpm dev
```