Skip to content

chore(atomic-a11y): add a11y scripts, overrides, and report templates#7125

Draft
y-lakhdar wants to merge 7 commits intofeat/a11y-openacrfrom
feat/a11y-scripts
Draft

chore(atomic-a11y): add a11y scripts, overrides, and report templates#7125
y-lakhdar wants to merge 7 commits intofeat/a11y-openacrfrom
feat/a11y-scripts

Conversation

@y-lakhdar
Copy link
Contributor

@y-lakhdar y-lakhdar commented Feb 16, 2026

Context

CLI scripts that automate a11y workflows on top of the reporter and OpenACR converter from previous PRs. These are developer-facing tools in scripts/ (outside src/).

What this PR does

Three scripts:

  1. ai-wcag-audit.ts — LLM-based WCAG auditing. Launches Playwright for each Storybook component, captures screenshots + a11y trees, evaluates with OpenAI for criteria axe-core can't check.

  2. generate-a11y-issues.ts — Creates GitHub issues from a11y report violations, grouped by WCAG criterion.

  3. manual-audit-delta.ts — Diffs manual audit baselines to track regressions/improvements.

Also: a11y-overrides.json (conformance overrides), vpat-from-openacr.handlebars (VPAT template), reports/deltas/ (delta examples).

Try it

git checkout feat/a11y-scripts && pnpm install
cd packages/atomic-a11y
npm run build

# AI audit (requires OPENAI_API_KEY + running Storybook)
npx tsx scripts/ai-wcag-audit.ts --dry-run
npx tsx scripts/ai-wcag-audit.ts --component atomic-product-link

# GitHub issues (dry run)
npx tsx scripts/generate-a11y-issues.ts

# Manual audit delta
npx tsx scripts/manual-audit-delta.ts status

PR Chain (5 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
5 #7125 feat/a11y-scripts CLI scripts ← this PR
6 #7126 feat/a11y-reporter-wiring Wire reporter into atomic vitest config
7 #7117 feat/a11y-ci-integration Weekly a11y scan workflow

KIT-5471

- Add scripts/ai-wcag-audit.ts for LLM-powered WCAG compliance auditing
- Add scripts/generate-a11y-issues.ts for generating GitHub issues from reports
- Add scripts/manual-audit-delta.ts for computing manual audit deltas
- Add scripts/vpat-from-openacr.handlebars template for VPAT generation
- Add a11y-overrides.json for per-criterion conformance overrides
- Add reports/deltas/ directory with example delta file
Copy link

@chatgpt-codex-connector chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 413369fd80

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment on lines +243 to +245
const pattern =
/\/src\/components\/(?:commerce|search|insight|ipx|recommendations)\/([^/]+)\//;
const match = importPath.match(pattern);

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Extract leaf component folder from story import paths

The current regex captures only the first directory after the surface segment, so nested stories like .../src/components/search/facets/atomic-facet/... resolve to facets instead of the actual component tag. Because selectStories later deduplicates by this extracted name, many components are collapsed into one audit target and --component <tag> filtering misses valid components, which materially undercounts audited coverage and failures.

Useful? React with 👍 / 👎.

status: 'complete',
tier: 2,
keyboardNav: results.keyboardNav ?? 'not-applicable',
screenReader: results.screenReader ?? 'pass',

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Do not default untested screen-reader checks to pass

When a delta adds a new component and omits results.screenReader (which happens for AI-only deltas that only include WCAG 2.2 criteria), merge writes manual.screenReader as pass. This records compliance without any test evidence and can hide real accessibility regressions in downstream baseline/OpenACR reporting for newly introduced components.

Useful? React with 👍 / 👎.

DELTA_PATTERN and VALID_STATUSES were deferred from the foundation PR
since their first consumers are the scripts in this branch.
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