diff --git a/README.md b/README.md index d557efe..a3bf987 100644 --- a/README.md +++ b/README.md @@ -8,10 +8,11 @@ Accessibility Devkit helps a team turn accessibility concerns into work people c The review plugin looks for barriers in an interface and explains each finding in practical terms: what someone is trying to do, what gets in the way, who it affects, the smallest useful repair, and how the team should verify the result. Advocates can use that evidence to describe the impact on people. Engineering managers can use it to set priorities, assign work, and define what “done” means. Engineers can use the TypeScript packages to fix common problems in code. -The project has two parts: +The project has three parts: - **A review plugin for Codex and Claude Code.** It inspects an interface, helps plan or make focused repairs, and keeps automated findings separate from checks that still need a keyboard, screen reader, zoom test, or human judgment. -- **Eight source-only TypeScript packages.** They cover auditing, focus and keyboard behavior, color and text, motor access, cognitive access, language, media, and motion. +- **Ten npm packages.** They include a portable core and CLI, plus auditing, focus and keyboard behavior, color and text, motor access, cognitive access, language, media, and motion. +- **A Python core and CLI.** It shares the command-line report contract with the Node CLI. No overlay. No claim that a scan proves conformance. The work stays in the design, content, and source code where a team can test and maintain it. @@ -35,12 +36,12 @@ This gives advocates and engineering teams a shared record. It also makes uncert ## Choose the part you need -| Your situation | Start here | -| --- | --- | -| You need to understand the barriers in an interface | Install the review plugin and begin with the prompt above | -| You have findings but need help turning them into engineering work | Ask the plugin to group findings by affected task, owner, risk, and verification step | -| You already know the code-level problem | Use the package map below to find a focused utility | -| You need a compliance decision or evidence of real-world access | Use the review to prepare testing, then verify with assistive technology and people who use the relevant access methods | +| Your situation | Start here | +| ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- | +| You need to understand the barriers in an interface | Install the review plugin and begin with the prompt above | +| You have findings but need help turning them into engineering work | Ask the plugin to group findings by affected task, owner, risk, and verification step | +| You already know the code-level problem | Use the package map below to find a focused utility | +| You need a compliance decision or evidence of real-world access | Use the review to prepare testing, then verify with assistive technology and people who use the relevant access methods | ## What the review can establish @@ -48,9 +49,47 @@ The plugin can inspect source, identify likely barriers, explain their impact, m Some conclusions still require people and tools outside the repository. Keyboard use, screen-reader output, zoom and reflow, visual states, captions, error recovery, and complete task flows all need suitable testing. A review should label each check as completed, planned, or unverified. It should never turn an automated scan into a compliance claim. +## Install the published release + +Version 1.1.2 is available for all ten npm packages and the Python package. The examples below select that published release. Changes on the default branch, including dependency updates, are available from source until a later release is published. + +Use Node 22+ or Python 3.11+ to run a check: + +```bash +npx @accessibility-devkit/cli@1.1.2 contrast '#595959' '#ffffff' +pipx run --spec accessibility-devkit==1.1.2 accessibility-devkit contrast '#595959' '#ffffff' +``` + +Import a portable utility: + +```bash +npm install @accessibility-devkit/core@1.1.2 +python -m pip install accessibility-devkit==1.1.2 +``` + +```js +import { getContrastRatio } from '@accessibility-devkit/core'; + +getContrastRatio('#595959', '#ffffff'); +``` + +CommonJS is also supported: + +```js +const { getContrastRatio } = require('@accessibility-devkit/core'); +``` + +```python +from accessibility_devkit import get_contrast_ratio + +get_contrast_ratio("#595959", "#ffffff") +``` + +A passing automated check still needs the manual verification described above. + ## Five-minute quick start -The plugin is the quickest way to bring the review workflow into a project. The TypeScript packages are optional and currently available from this source workspace only. +The plugin is the quickest way to bring the review workflow into a project. The npm and Python packages are optional; install the published release above or build the current source below. ### Codex desktop app @@ -108,29 +147,29 @@ Run these marketplace commands in Claude Code, then use the same first prompt: The general `accessibility` skill starts with the task, evidence, repair, and verification. It can route a review to a specialist when the product has a clear shape. -| Product | Specialist | What it checks first | -| --- | --- | --- | -| Games and real-time interactive experiences | `accessibility-gaming` | Flash safety, input remapping, captions for audio cues, assist modes, and difficulty settings | -| Enterprise software, SaaS, and internal tools | `accessibility-business` | Forms, timeouts, authentication, error recovery, and conformance evidence | -| Visual design and design systems | `accessibility-design` | Color and contrast, typography, motion budgets, and accessible component specifications | -| Mobile and touch-first web apps | `accessibility-mobile` | Target size, alternatives to gestures, orientation and reflow, zoom, and mobile screen readers | +| Product | Specialist | What it checks first | +| --------------------------------------------- | ------------------------ | ---------------------------------------------------------------------------------------------- | +| Games and real-time interactive experiences | `accessibility-gaming` | Flash safety, input remapping, captions for audio cues, assist modes, and difficulty settings | +| Enterprise software, SaaS, and internal tools | `accessibility-business` | Forms, timeouts, authentication, error recovery, and conformance evidence | +| Visual design and design systems | `accessibility-design` | Color and contrast, typography, motion budgets, and accessible component specifications | +| Mobile and touch-first web apps | `accessibility-mobile` | Target size, alternatives to gestures, orientation and reflow, zoom, and mobile screen readers | Ask for a specialist by name or let the general skill route the review. Design work can also use the separate [`intentional-ux`](https://github.com/actually-useful-ai/intentional-ux) skill to examine goals, decisions, and interaction cost. ## TypeScript package map -The packages are source-only and not yet published to npm. Each package handles a specific class of code-level barrier. +The published packages include a [portable core](./packages/core) and [CLI](./packages/cli), plus the eight browser-focused packages below. The [Python package](./python) provides the same portable checks and command-line report contract. -| Barrier | Package | Examples | -| --- | --- | --- | -| Automated checks and pipeline reporting | [`audit`](./packages/audit) | axe-core audits, report formatting, ESLint configuration | -| Focus, keyboard behavior, dialogs, menus, and status messages | [`components`](./packages/components) | focus traps, roving tabindex, skip links, live regions | -| Contrast, color perception, text spacing, and system preferences | [`accommodations`](./packages/accommodations) | contrast checks, color adjustment, reduced-motion detection | -| Small targets, drag-only controls, and repeated accidental input | [`motor`](./packages/motor) | target-size checks, pointer cancellation, keyboard dragging, tremor tolerance | -| Time pressure, repeated entry, blocked paste, and irreversible actions | [`cognitive`](./packages/cognitive) | timeout warnings, field memory, authentication checks, undo | -| Hard-to-read text and unexplained abbreviations | [`language`](./packages/language) | readability scores, long-sentence flags, abbreviation annotation | -| Missing captions, transcripts, and controls for sound | [`media`](./packages/media) | media audits, autoplay detection, pause controls, transcript links | -| Flashing and motion that can cause seizures or vestibular symptoms | [`motion`](./packages/motion) | reduced-motion handling, safe scrolling, flash-rate checks | +| Barrier | Package | Examples | +| ---------------------------------------------------------------------- | --------------------------------------------- | ----------------------------------------------------------------------------- | +| Automated checks and pipeline reporting | [`audit`](./packages/audit) | axe-core audits, report formatting, ESLint configuration | +| Focus, keyboard behavior, dialogs, menus, and status messages | [`components`](./packages/components) | focus traps, roving tabindex, skip links, live regions | +| Contrast, color perception, text spacing, and system preferences | [`accommodations`](./packages/accommodations) | contrast checks, color adjustment, reduced-motion detection | +| Small targets, drag-only controls, and repeated accidental input | [`motor`](./packages/motor) | target-size checks, pointer cancellation, keyboard dragging, tremor tolerance | +| Time pressure, repeated entry, blocked paste, and irreversible actions | [`cognitive`](./packages/cognitive) | timeout warnings, field memory, authentication checks, undo | +| Hard-to-read text and unexplained abbreviations | [`language`](./packages/language) | readability scores, long-sentence flags, abbreviation annotation | +| Missing captions, transcripts, and controls for sound | [`media`](./packages/media) | media audits, autoplay detection, pause controls, transcript links | +| Flashing and motion that can cause seizures or vestibular symptoms | [`motion`](./packages/motion) | reduced-motion handling, safe scrolling, flash-rate checks | Each package README documents its functions and shows code examples. The packages help implement repairs; they do not replace the review or the manual verification that follows it. @@ -146,19 +185,40 @@ pnpm build pnpm test ``` -The build produces CommonJS, ECMAScript module, and TypeScript declaration files. Import examples in the package documentation assume that you are working from this cloned workspace. +The build produces CommonJS, ECMAScript module, and TypeScript declaration files. Use source builds for changes that have not yet been released; package imports also work with the published packages. + +## Report contract + +The shared [report schema](./spec/report.schema.json) uses JSON Schema 2020-12. Reports keep automated findings separate from manual checks; [golden fixtures](./spec/fixtures) verify Node and Python parity. + +## v1.0 to v1.1 migration + +v1.1 makes a clean pre-registry API break so names describe what the code can prove. + +| v1.0 | v1.1 | +| ---------------------------- | ----------------------------------------------------------------------------- | +| `meetsWCAG` | `meetsContrastThreshold` | +| `findAccessibleColor` | `findNearestPassingColor` | +| `simulateColorBlindness` | `simulateColorVisionDeficiency` | +| `applyDyslexiaFriendlyFont` | `applyTypographyPreference` with caller-supplied values | +| `applyTextSpacing` | `applyTextSpacingTest`, including paragraph spacing and restore | +| `meetsTextSpacing` | Removed; author spacing values alone do not establish WCAG 1.4.12 conformance | +| accommodation motion helpers | Use `@accessibility-devkit/motion` | +| `isUnsafeFlashRate` | `exceedsFlashFrequencyLimit`; frequency is only one part of flash review | + +Invalid colors now throw instead of becoming black. Dwell and repeat intervals are explicit. English readability results identify their method. `createSessionTimeout` remains an implementation helper; use `assessTimeLimit` for policy boundaries. ## Repository map -| Path | Contents | -| --- | --- | -| [`skills/accessibility`](./skills/accessibility) | General review workflow and verification guidance | -| [`skills/accessibility-*`](./skills) | Four specialist review lenses | -| [`packages`](./packages) | Eight TypeScript packages and their API documentation | +| Path | Contents | +| -------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | +| [`skills/accessibility`](./skills/accessibility) | General review workflow and verification guidance | +| [`skills/accessibility-*`](./skills) | Four specialist review lenses | +| [`packages`](./packages) | Ten npm packages and their API documentation | | [`examples/accessible-component-review.md`](./examples/accessible-component-review.md) | One component followed from evidence through repair and verification | -| [`docs/01-philosophy.md`](./docs/01-philosophy.md) | Project principles | -| [`docs/02-why-not-overlays.md`](./docs/02-why-not-overlays.md) | Why source-level repairs matter | -| [`docs/03-layered-approach.md`](./docs/03-layered-approach.md) | How reviews, code, and testing fit together | +| [`docs/01-philosophy.md`](./docs/01-philosophy.md) | Project principles | +| [`docs/02-why-not-overlays.md`](./docs/02-why-not-overlays.md) | Why source-level repairs matter | +| [`docs/03-layered-approach.md`](./docs/03-layered-approach.md) | How reviews, code, and testing fit together | ## Development @@ -172,10 +232,10 @@ pnpm changeset # describe a change for versioning ## Related projects -| Project | What it does | -| --- | --- | -| [awesome-accessibility](https://github.com/lukeslp/awesome-accessibility) | Curated accessibility resources and tools | -| [accessibility-atlas](https://github.com/lukeslp/accessibility-atlas) | Disability demographics, web accessibility, and assistive-technology datasets | +| Project | What it does | +| ------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | +| [awesome-accessibility](https://github.com/lukeslp/awesome-accessibility) | Curated accessibility resources and tools | +| [accessibility-atlas](https://github.com/lukeslp/accessibility-atlas) | Disability demographics, web accessibility, and assistive-technology datasets | ## Contributing diff --git a/packages/audit/package.json b/packages/audit/package.json index b6febca..948556a 100644 --- a/packages/audit/package.json +++ b/packages/audit/package.json @@ -48,7 +48,7 @@ "provenance": true }, "dependencies": { - "axe-core": "^4.12.1", + "axe-core": "^4.13.0", "eslint-plugin-jsx-a11y": "^6.10.2" }, "devDependencies": { diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 5717e54..cec5152 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -60,8 +60,8 @@ importers: packages/audit: dependencies: axe-core: - specifier: ^4.12.1 - version: 4.12.1 + specifier: ^4.13.0 + version: 4.13.0 eslint-plugin-jsx-a11y: specifier: ^6.10.2 version: 6.10.2(eslint@8.57.1) @@ -1662,10 +1662,10 @@ packages: } engines: { node: '>= 0.4' } - axe-core@4.12.1: + axe-core@4.13.0: resolution: { - integrity: sha512-s7iGf5GaVMxEG0ENN9x+xTr7GFZCb1ZP/1uATUpCEK2X78nDB3RwbtFCo9pGAf9ru+VwoQ464DkaLEeRM08wJA==, + integrity: sha512-UzGt8zg7Ny8djbYMhxl2zuEevVa7r2gJjYY5Lwr1xM7+XU2nd6CkIWFTVcCIbAP63vSz71NaVyyuSk9lHKcy0A==, } engines: { node: '>=4' } @@ -3112,10 +3112,10 @@ packages: integrity: sha512-z81GNO7nnYMEhrGh9LeymoE4+Yr0Wn5McHIZMK5cfQCl+NDX08sCZgUc9/6MHni9IWuFLm1Z3HTCXu2z9fN62Q==, } - nanoid@3.3.16: + nanoid@3.3.18: resolution: { - integrity: sha512-bzlKTyNJ7+LdGIIwy8ijFpIqEQIvafahV7eYykJ8Cvh42EdJeODoJ6gUJXpQJvej1BddH8OqTXZNE/KfbWAu8Q==, + integrity: sha512-DTg4MJbGMWkfi6VZFdNt2/caMbQy4Ou+Op/hJQvGEWcnVfoA1QA+xzRKAzw9jD6+GVOOeYr/mIcuDSdug6F6+w==, } engines: { node: ^10 || ^12 || ^13.7 || ^14 || >=15.0.1 } hasBin: true @@ -5107,7 +5107,7 @@ snapshots: dependencies: possible-typed-array-names: 1.1.0 - axe-core@4.12.1: {} + axe-core@4.13.0: {} axobject-query@4.1.0: {} @@ -5516,7 +5516,7 @@ snapshots: array-includes: 3.1.9 array.prototype.flatmap: 1.3.3 ast-types-flow: 0.0.8 - axe-core: 4.12.1 + axe-core: 4.13.0 axobject-query: 4.1.0 damerau-levenshtein: 1.0.8 emoji-regex: 9.2.2 @@ -6115,7 +6115,7 @@ snapshots: object-assign: 4.1.1 thenify-all: 1.6.0 - nanoid@3.3.16: {} + nanoid@3.3.18: {} natural-compare@1.4.0: {} @@ -6246,7 +6246,7 @@ snapshots: postcss@8.5.19: dependencies: - nanoid: 3.3.16 + nanoid: 3.3.18 picocolors: 1.1.1 source-map-js: 1.2.1 diff --git a/tests/docs/adoption-quick-start.test.mjs b/tests/docs/adoption-quick-start.test.mjs index 7cc11e0..5e63a78 100644 --- a/tests/docs/adoption-quick-start.test.mjs +++ b/tests/docs/adoption-quick-start.test.mjs @@ -23,13 +23,17 @@ async function read(relativePath) { return readFile(path.join(root, relativePath), 'utf8'); } -test('leads with one-minute outcomes and keeps tool-specific shortcuts secondary', async () => { +test('offers outcomes, installable checks, and the review workflow', async () => { const readme = await read('README.md'); - assert.match(readme, /## Start in a minute/i); - assert.match(readme, /### Run a check/i); - assert.match(readme, /### Import a utility/i); - assert.match(readme, /### Add the review workflow/i); + assert.match(readme, /## Start with the outcome/i); + assert.match(readme, /## Install the published release/i); + assert.match(readme, /npx @accessibility-devkit\/cli@1\.1\.2 contrast/i); + assert.match( + readme, + /Changes on the default branch.*available from source until a later release/i, + ); + assert.doesNotMatch(readme, /source-only|not yet published to npm/i); assert.match(readme, /Plugins Directory/i); assert.match(readme, /marketplace.*import|import.*marketplace/i); assert.match(readme, /\.claude-plugin\/marketplace\.json/); @@ -40,7 +44,6 @@ test('leads with one-minute outcomes and keeps tool-specific shortcuts secondary assert.match(readme, /Review this interface for accessibility barriers/i); assert.match(readme, /Expected (result|output)/i); assert.match(readme, /Verif(y|ication)/i); - assert.doesNotMatch(readme.split('## Start in a minute')[0], /Codex|Claude|TypeScript/i); }); test('offers a repository-backed direct skill fallback and separate Claude commands', async () => { @@ -143,7 +146,7 @@ test('documents installable npm and Python routes without hiding source developm const readme = await read('README.md'); assert.match(readme, /npm install @accessibility-devkit\/core/i); - assert.match(readme, /pipx run accessibility-devkit/i); + assert.match(readme, /pipx run --spec accessibility-devkit==1\.1\.2 accessibility-devkit/i); assert.match(readme, /from accessibility_devkit import/i); assert.match(readme, /require\('@accessibility-devkit\/core'\)/i); assert.match(readme, /## v1\.0 to v1\.1 migration/i);