# @pigmilcom/a11y
About
Simple, lightweight accessibility widget that enhances usability and adds control features to any website instantly. Zero dependencies.
WCAG 2.1 Ready. Drop in one `
```
Pin to a specific version:
```html
```
### Self-hosted (pigmil CDN)
Use your own CDN endpoint for full control over deployment:
```html
```
The widget auto-mounts on `DOMContentLoaded`. React 18 and all CSS are bundled inside — nothing else needed.
### `data-position` values
| Value | Placement |
| --------------- | ------------------ |
| `bottom-right` | Bottom-right corner (default) |
| `bottom-left` | Bottom-left corner |
| `top-right` | Top-right corner |
| `top-left` | Top-left corner |
### `data-theme` values
| Value | Behaviour |
| -------- | ------------------------------------------------------ |
| omitted / `auto` | Matches `` or `color-scheme: dark`; otherwise light |
| `light` | Always use the light theme |
| `dark` | Always use the dark theme |
### `data-lang` values
| Value | Language |
| ----- | -------- |
| `en` | English (default) |
| `es` | Spanish |
| `fr` | French |
| `de` | German |
| `pt` | Portuguese |
| `zh` | Chinese (Simplified) |
| `ar` | Arabic |
| `hi` | Hindi |
Language resolution works like this:
1. If `data-lang` or the React `lang` prop is provided, that language is used and saved to `localStorage['a11y-lang']`.
2. If `data-lang` / `lang` is omitted, the widget reads `localStorage['a11y-lang']`.
3. If `localStorage['a11y-lang']` does not exist yet, the widget defaults to `'en'` and saves it.
This means the widget language can be changed dynamically by updating `localStorage['a11y-lang']`.
```html
```
```js
localStorage.setItem('a11y-lang', 'fr');
window.dispatchEvent(new CustomEvent('pgm-a11y-language-change', {
detail: { lang: 'fr' }
}));
```
If you still pass `data-lang="fr"`, that explicit value wins and also updates `localStorage['a11y-lang']`.
### Programmatic control
The CDN build exposes `window.PigmilA11y` for manual control:
```js
PigmilA11y.mount(); // mount the widget
PigmilA11y.unmount(); // remove the widget and clean up
```
---
## npm Installation
```bash
npm install @pigmilcom/a11y
# yarn
yarn add @pigmilcom/a11y
# pnpm
pnpm add @pigmilcom/a11y
```
---
## Features
- Text size — Normal / Large / X-Large
- High contrast
- Invert colours
- Grayscale
- Reduce motion
- Highlight links
- Text spacing (WCAG 1.4.12)
- Dyslexia-friendly font
- Persists in `localStorage`
- Full keyboard & screen-reader support (`role="dialog"`, `aria-checked`, `aria-expanded`)
- Zero runtime dependencies (React peer dep only)
---
## Dist files
Every build outputs these files to `dist/`:
| File | Format | Description |
| ------------------- | ------ | --------------------------------------------- |
| `index.js` | CJS | npm (unminified, for bundlers) |
| `index.mjs` | ESM | npm (unminified, for bundlers) |
| `index.min.js` | CJS | npm (minified) |
| `index.min.mjs` | ESM | npm (minified) |
| `index.css` | CSS | Stylesheet import (`@pigmilcom/a11y/styles`) |
| `index.min.css` | CSS | Minified stylesheet |
| `a11y.cdn.js` | IIFE | CDN bundle — React bundled, CSS inlined, minified |
---
## Quick start (React)
### 1 — Import the stylesheet (once, globally)
```js
import '@pigmilcom/a11y/styles';
```
This single import contains both the panel UI styles and all the accessibility
class rules applied to ``.
### 2 — Drop in the widget
```jsx
import a11y from '@pigmilcom/a11y';
// Assign to a capitalized variable to use in JSX
const A11y = a11y;
```
The `className` prop is merged onto the trigger button — use Tailwind classes,
custom classes, or anything your bundler supports to position the widget. The
`lang` prop is reactive, and when provided it also syncs `localStorage['a11y-lang']`.
---
## Customising the widget with CSS
The widget exposes stable **`a11y-widget-*`** class names on its key elements
as a public API. Target them from a `
```
| Public class | Element |
| --------------------------- | -------------------- |
| `a11y-widget-btn` | Trigger button |
| `a11y-widget-dialog` | Dialog panel |
| `a11y-widget-toggle-btn` | Each toggle option |
> Place your `