create-a11y-app

Accessibility-first Next.js project generator with WCAG, Section 508, and EN 301 549 guardrails baked in.

create-a11y-app scaffolds a production-ready Next.js application that ships wired for accessibility from the first commit. Generated apps come with typed accessible primitives, strict ESLint rules, custom WCAG-aware lint rules, a Playwright + axe test suite that sweeps every route, a per-criterion compliance report, and a VPAT-style draft you can attach to a procurement review.

Quick start

# pnpm
pnpm create a11y-app my-app

# npm
npm create a11y-app@latest my-app

# yarn
yarn create a11y-app my-app

# bun
bunx create-a11y-app my-app

Then:

cd my-app
pnpm dev               # http://localhost:3000
pnpm check             # typecheck + a11y lint + axe sweep + reports

CLI options

| Flag | Description | Default | | ------------------------ | -------------------------------------------------- | ------------- | | --profile <id> | Compliance profile to scaffold against. | wcag-2.1-aa | | --package-manager <pm> | One of pnpm, npm, yarn, bun. | pnpm | | --skip-install | Skip the post-scaffold dependency install. | off | | --force | Overwrite the target directory if it is non-empty. | off |

Compliance profiles

| Profile | Standard | What it covers | | ------------- | -------------- | ------------------------------------------------------- | | wcag-2.1-aa | WCAG 2.1 AA | Common commercial and public-sector baseline (default). | | wcag-2.2-aa | WCAG 2.2 AA | WCAG 2.1 plus the new 2.2 success criteria. | | section-508 | US Section 508 | WCAG 2.0 A/AA mapped, with documentation review hooks. | | en-301-549 | EU EN 301 549 | WCAG-mapped European ICT accessibility profile. |

What you get in a generated app

• Accessible component primitives — Button, IconButton, TextField, ErrorSummary, SkipLink, LiveRegion, VisuallyHidden, and a Radix UI–backed Dialog (focus trap, return focus, escape, scroll lock).
• Strict ESLint accessibility rules — eslint-plugin-jsx-a11y configured with the project's full ruleset, plus four local rules under the a11y-app/ namespace:
  • a11y-app/require-skip-link — root layout must render <SkipLink/>.
  • a11y-app/require-error-summary-on-form-pages — files with <form> must also render <ErrorSummary/>.
  • a11y-app/live-region-needs-aria-live — elements with role=alert|status|log must declare aria-live.
  • a11y-app/text-field-needs-label-prop — <TextField/> requires a non-empty label prop.
• Per-route axe sweep — Playwright walks every route under src/app/ (skipping route groups, dynamic segments, parallel slots) and runs axe-core on each, persisting structured results to .a11y/axe-<id>.json.
• Compliance reporter — maps axe findings back to WCAG success criteria, prints a per-criterion terminal summary, and writes a11y-report.md with status (pass / fail / incomplete / no-evidence), evidence counts, and links to the W3C understanding documents.
• VPAT draft — a11y-vpat.md rendered in procurement-style language, grouped by WCAG principle within each level, with Supports / Partially Supports / Does Not Support / Not Evaluated conformance levels.
• CI workflow — GitHub Actions job that runs the full pipeline on push and pull request, uploading both reports plus the raw axe payloads as workflow artifacts.

Scripts in the generated app

| Script | What it does | | ----------------- | ------------------------------------------------------------ | | dev | Run the Next.js dev server. | | build | Production build. | | typecheck | tsc --noEmit. | | a11y:lint | ESLint with --max-warnings=0 (jsx-a11y + custom rules). | | a11y:lint:rules | node --test suite for the custom lint rules. | | a11y:test | Playwright keyboard test plus per-route axe sweep. | | a11y:report | Read axe results, write a11y-report.md and a11y-vpat.md. | | check | Run typecheck → a11y lint → a11y tests → report, end to end. |

Outputs

| File / directory | Purpose | | --------------------- | ------------------------------------------------------------------------- | | a11y.profile.json | Active profile metadata plus the full WCAG criteria list it requires. | | .a11y/axe-<id>.json | Raw axe results per route (violations, passes, incomplete, inapplicable). | | a11y-report.md | Human-readable per-criterion report with W3C SC links. | | a11y-vpat.md | DRAFT VPAT-style document for procurement review. |

Project structure

my-app/
├── src/
│   ├── a11y/
│   │   ├── components/        # accessible primitives
│   │   └── lib/               # reporter, wcag-mapper
│   └── app/                   # Next.js App Router
├── tests/
│   ├── accessibility/         # Playwright + axe specs (+ route discovery)
│   └── lint/                  # node:test suites for custom rules
├── lint/                      # local ESLint plugin (rules/ + index.mjs)
├── .github/workflows/         # accessibility CI
└── a11y.profile.json

A note on conformance

These guardrails reduce common accessibility failures and make findings testable, but they do not certify legal compliance. Real WCAG / Section 508 / EN 301 549 conformance still requires human review of content quality, screen-reader task flows, captions and transcripts, and document accessibility. a11y-vpat.md is a pre-fill from automated evidence, not a signed VPAT.

License

MIT © Kiran Kumar Pradhan