# AllyKit A lightweight, zero-dependency accessibility toolkit you drop into any webpage with a single ` ``` **For production** (minified, ~20% smaller): ```html ``` AllyKit self-initializes on `DOMContentLoaded` and attaches to `window.AllyKit`. ### npm / yarn / pnpm ```bash # npm npm install @preepo/allykit # yarn yarn add @preepo/allykit # pnpm pnpm add @preepo/allykit ``` ### CDN Via GitHub (works as soon as the repo is public — no publish needed): ```html ``` Via npm (works after `npm publish`): ```html ``` --- ## Usage ### Plain ` ``` ### ES module (Vite, webpack, Rollup, etc.) ```js import AllyKit from '@preepo/allykit'; // init() must be called manually in module context. // Pass options directly — window.AllyKitConfig is not read. const kit = AllyKit.init({ accentColor: '#7c3aed', position: 'left', features: { adhd: false, hideImages: false } }); // kit is the full API object kit.open(); ``` ### CommonJS (Node-compatible bundlers) ```js const AllyKit = require('@preepo/allykit'); const kit = AllyKit.init({ accentColor: '#ea580c' }); ``` ### React example ```jsx import { useEffect, useRef } from 'react'; import AllyKit from '@preepo/allykit'; export function AccessibilityToolkit() { const kitRef = useRef(null); useEffect(() => { kitRef.current = AllyKit.init({ accentColor: '#4f46e5', position: 'right', features: { adhd: false } }); return () => { kitRef.current?.destroy(); }; }, []); return null; // AllyKit renders its own DOM } ``` ### Vue example ```js import AllyKit from '@preepo/allykit'; import { onMounted, onUnmounted } from 'vue'; export function useAllyKit(options = {}) { let kit = null; onMounted(() => { kit = AllyKit.init(options); }); onUnmounted(() => { kit?.destroy(); }); return { kit }; } ``` > **SSR note** — AllyKit renders real DOM into `document.body` via Shadow DOM. It requires a browser environment. With Next.js, Nuxt, or any SSR framework make sure `init()` is only called client-side (inside `useEffect`, `onMounted`, or a `"use client"` boundary). --- ## Configuration ### All options at a glance ```html ``` You only need to list the values you want to **change** — everything omitted falls back to its default. ### Layout options | Option | Type | Default | Description | |---|---|---|---| | `position` | `"left"` \| `"right"` | `"right"` | Which side of the screen the button and panel appear on | | `buttonOffset` | CSS string | `"24px"` | Distance of the button from the screen edge | | `panelWidth` | CSS string | `"560px"` | Width of the settings panel | ### Accent colour | Option | Type | Default | Description | |---|---|---|---| | `accentColor` | 3- or 6-digit hex string | `"#4f46e5"` | Primary brand colour for the toolkit | AllyKit derives a complete four-token palette from this single value at runtime: | CSS custom property | Role | Derived from | |---|---|---| | `--ak-primary` | Button background, active borders, step indicators, header icon | `accentColor` directly | | `--ak-on-primary` | Text/icons on primary surfaces | White or black — whichever achieves the higher WCAG contrast ratio against `accentColor` | | `--ak-primary-container` | Active feature card background, Reset button chip | 82 % tint toward white | | `--ak-on-primary-container` | Text inside primary-container surfaces | 70 % shade toward black | The focus ring (`--ak-focus`) also tracks `--ak-primary`, so keyboard navigation stays on-brand. **All neutral surfaces** (`--ak-surface`, `--ak-surface-container`, `--ak-on-surface`, etc.) are fixed greys and are not affected by `accentColor`. Quick examples: ```js accentColor: "#4f46e5" // Indigo (default) accentColor: "#16a34a" // Brand green accentColor: "#ea580c" // Warm orange accentColor: "#7c3aed" // Deep violet accentColor: "#3b82f6" // Slate blue accentColor: "#0891b2" // Cyan ``` > If `accentColor` is missing, invalid, or not a hex value, AllyKit silently falls back to `"#4f46e5"`. ### Feature toggles Set any feature key to `false` to hide it from the panel entirely. The feature's body class and CSS filter are never applied when disabled. ```html ``` #### Common recipes **Minimal set** — just the essentials: ```js window.AllyKitConfig = { features: { textSize: true, highContrast: true, dyslexia: true, pauseAnimation: true, screenReader: true, textSpacing: false, lineHeight: false, adhd: false, saturation: false, invert: false, bigCursor: false, hideImages: false, highlightLinks: false } }; ``` **E-commerce** — preserve product imagery and brand palette: ```js window.AllyKitConfig = { features: { invert: false, saturation: false, hideImages: false } }; ``` **Blog / docs** — reading-focused: ```js window.AllyKitConfig = { features: { adhd: false, bigCursor: false, invert: false, saturation: false, hideImages: false } }; ``` **Web app** — avoid obscuring UI chrome: ```js window.AllyKitConfig = { features: { adhd: false, // reading mask covers interactive elements hideImages: false // icons are functional, not decorative } }; ``` ### WCAG Auto-fixer AllyKit includes a built-in WCAG 2.2 auto-fixer that scans your page and automatically fixes common accessibility issues: | Issue | Auto-fix | |---|---| | Missing `alt` attributes on images | Adds `alt=""` for decorative images or descriptive text from context | | Form inputs without labels | Generates labels from nearby text or adds `aria-label` | | Missing `lang` attribute on `` | Adds default language (configurable via `autoFixLang`) | | Links/buttons without accessible names | Adds `aria-label` from visible text or context | | Duplicate IDs | Renames duplicates to ensure uniqueness | | Missing ARIA roles | Adds semantic roles where appropriate | | Redundant role attributes | Removes roles that match native semantics | | Skip-to-content link | Adds a keyboard-accessible skip link if missing | **Configuration:** ```js window.AllyKitConfig = { autoFix: true, // Enable/disable auto-fixer (default: true) autoFixLang: "en" // Default lang attribute (default: "en") }; ``` The auto-fixer runs on page load and monitors for dynamically added content. Fixed elements are marked with `data-allykit-fixed` attribute. A badge displays the number of issues fixed. **Note:** Auto-fixes are client-side only and don't modify your source code. For permanent fixes, address issues at the source. --- ## Feature reference ### Text size Applies a CSS `zoom` multiplier to every direct child of `` except the AllyKit root itself. | Level | Value | |---|---| | 0 (default) | 100 % | | 1 | 110 % | | 2 | 120 % | | 3 | 130 % | | 4 | 140 % | ### High contrast Adds a body class that overrides background, foreground, border, and link colours with `!important` rules. Level 4 (Dark Mode) is a WCAG AA–compliant dark theme. | Level | Name | Background | Foreground | |---|---|---|---| | 1 | Enhanced | `#000` | `#fff` | | 2 | Black / White | `#000` | `#fff` (thicker link underline) | | 3 | Black / Yellow | `#000` | `#ffff68` | | 4 | Dark Mode | `#121212` | `#e0e0e0` | ### Text spacing Adds letter-spacing and word-spacing to all text elements (`p`, `h1–h6`, `li`, `a`, `button`, `td`, etc.). | Level | Letter spacing | Word spacing | |---|---|---| | 1 (Loose) | 0.08 em | 0.16 em | | 2 (Wider) | 0.12 em | 0.24 em | | 3 (Widest) | 0.16 em | 0.32 em | ### Line height | Level | Multiplier | |---|---| | 1 | 1.5 × | | 2 | 1.8 × | | 3 | 2 × | ### Dyslexia friendly Switches the font stack of all text elements to **OpenDyslexic** (loaded from a `.woff` file). Falls back to Arial / system-ui if the font fails to load. ### ADHD mode Injects a full-width focus strip element that follows the mouse pointer vertically, dimming everything above and below the current line of text. The strip is a separate DOM element (`#allykit-adhd-mask`) that sits outside the Shadow DOM so it can overlay the page. ### Saturation Applies a CSS filter to all top-level body children. | Level | Filter | |---|---| | 1 (Low) | `saturate(0.45)` | | 2 (High) | `saturate(1.9)` | | 3 (Grayscale) | `grayscale(1) saturate(0)` | ### Invert colors Applies `invert(1) hue-rotate(180deg)` — the hue rotation cancels the colour shift while keeping the luminance inversion. Composes correctly when used together with Saturation. ### Pause animations Sets `animation-duration: 0.001ms`, `animation-iteration-count: 1`, `transition-duration: 0s`, and `scroll-behavior: auto` on every element including `::before` / `::after` pseudo-elements. Also pauses any `