Skip to content

feat(atomic-a11y): add AI WCAG audit orchestrator and prompts#7189

Draft
y-lakhdar wants to merge 2 commits intofeat/a11y-browser-llmfrom
feat/a11y-audit-orchestrator
Draft

feat(atomic-a11y): add AI WCAG audit orchestrator and prompts#7189
y-lakhdar wants to merge 2 commits intofeat/a11y-browser-llmfrom
feat/a11y-audit-orchestrator

Conversation

@y-lakhdar
Copy link
Contributor

@y-lakhdar y-lakhdar commented Mar 3, 2026

Context

Split from #7125 for reviewability. This is PR 5c — the main orchestrator that ties together the browser capture and LLM modules from 5b.

What this PR does

AI WCAG audit orchestrator (ai-wcag-audit.ts — 991 lines):

  • CLI argument parsing (component filter, concurrency, dry-run, resume)
  • Storybook story discovery and component matching
  • 4-call LLM evaluation pipeline splitting WCAG criteria across batched calls
  • Concurrency pool for parallel component evaluation
  • Progress tracking with resume capability (restart from where it stopped)
  • Delta file output for integration with the manual audit workflow (5a)
  • Structured JSON report generation

LLM prompts (prompts.ts — 730 lines):

  • Prompt construction for 4 evaluation calls
  • WCAG criteria grouped by domain (perceivable, operable, understandable, robust)
  • Screenshot and a11y tree context injection
  • Structured output format specification for reliable JSON parsing

Entry point:

  • scripts/ai-wcag-audit.mjs — ESM wrapper

Try it

git checkout feat/a11y-audit-orchestrator && pnpm install
cd packages/atomic-a11y && pnpm build

# Dry run (requires running Storybook)
node scripts/ai-wcag-audit.mjs --dry-run

# Audit a single component (requires OPENAI_API_KEY + Storybook)
node scripts/ai-wcag-audit.mjs --component atomic-product-link

# Resume a previous run
node scripts/ai-wcag-audit.mjs --resume

PR Chain (5c of 7)

# PR Branch Description
1 #7111 feat/a11y-package-scaffold Package scaffolding
2 #7122 feat/a11y-shared-foundation Shared types, constants, utilities
3 #7123 feat/a11y-reporter VitestA11yReporter
4 #7124 feat/a11y-openacr OpenACR report generator
5a #7187 feat/a11y-delta-workflow Shared foundation + delta workflow + issue generator
5b #7188 feat/a11y-browser-llm Browser capture + LLM client modules
5c #7189 feat/a11y-audit-orchestrator AI WCAG audit orchestrator + prompts ← this PR
6 #7126 feat/a11y-reporter-wiring Wire reporter into atomic vitest config
7 #7117 feat/a11y-ci-integration Weekly a11y scan workflow

Replaces #7125 (split into 5a/5b/5c)

KIT-5471

@y-lakhdar y-lakhdar added the a11y Accessibility issues label Mar 3, 2026
@y-lakhdar y-lakhdar changed the base branch from feat/a11y-delta-workflow to feat/a11y-browser-llm March 3, 2026 16:08
@y-lakhdar y-lakhdar temporarily deployed to Prerelease (CDN) March 3, 2026 16:14 — with GitHub Actions Inactive
@y-lakhdar y-lakhdar force-pushed the feat/a11y-browser-llm branch from bb0f142 to f8c310c Compare March 3, 2026 16:34
@y-lakhdar y-lakhdar force-pushed the feat/a11y-audit-orchestrator branch from c42f06f to 81433b4 Compare March 3, 2026 16:34
@y-lakhdar y-lakhdar temporarily deployed to Prerelease (CDN) March 3, 2026 16:39 — with GitHub Actions Inactive
@y-lakhdar y-lakhdar temporarily deployed to Prerelease (CDN) March 3, 2026 16:39 — with GitHub Actions Inactive
Add the main AI audit orchestrator that discovers Storybook stories,
captures browser state via Playwright, evaluates WCAG criteria through
a 4-call LLM pipeline, and outputs structured JSON results with
progress tracking and resume capability.
@y-lakhdar y-lakhdar force-pushed the feat/a11y-audit-orchestrator branch from 81433b4 to ffa28bb Compare March 3, 2026 17:06
@y-lakhdar y-lakhdar force-pushed the feat/a11y-browser-llm branch from f8c310c to 2a222a4 Compare March 3, 2026 17:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

a11y Accessibility issues

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant