Pre-push a11y audit

Accessibility is a convention in this codebase, not a nice-to-have. To make sure the convention is actually enforced, the pre-push git hook runs an accessibility audit against any UI component files you've changed on this branch — automatically, every time you git push.

You don't have to remember to run it. You don't have to opt in. If you touch packages/ui/src/components/, the audit runs.

Why it exists

The ITU platform serves content in six languages to a global audience that includes people using screen readers, keyboard navigation, and other assistive technology. Accessibility regressions are invisible until they aren't, and by the time a user reports one it has already shipped.

The a11y audit is the enforcement arm of the accessibility-first convention:

• Every time a UI component changes, its accessibility is re-verified.
• The verification happens on your machine, before the code leaves your branch.
• Results are captured as JSON and committed alongside the component so the current state is always traceable.
• If the audit finds a regression, you see it immediately — not days later in CI, not weeks later in production.

Put differently: the audit makes accessibility a property of the component file itself, not a task on someone's checklist.

How it works

The hook runs in three phases.

1
git diff --name-only main...HEAD -- packages/ui/src/components/

1
pnpm --filter @itu/ui exec tsx scripts/extract-variants.ts

1
pnpm --filter @itu/ui run a11y $SLUGS

1
git add packages/ui/generated/a11y/<slug>.json

Artifacts produced

Both directories live under packages/ui/generated/. The a11y/ results are exported from @itu/ui via the ./a11y/* export in its package.json, which means other packages (notably the docs site) can import and render them.

Scope: only what changed

The hook deliberately does not re-audit every component on every push. It diffs against main and audits only the slugs that appear in the diff:

1
CHANGED_COMPONENTS=$(git diff --name-only main...HEAD -- packages/ui/src/components/ 2>/dev/null | \
2
  sed -n 's|packages/ui/src/components/\([^/]*\).*|\1|p' | \
3
  sort -u | \
4
  tr '[:upper:]' '[:lower:]' | \
5
  sed 's/\([a-z]\)\([A-Z]\)/\1-\2/g')

This keeps the feedback loop tight. A typical push touches one or two components, and auditing those two components takes seconds — not the tens of minutes it would take to audit all of them.

The trade-off is that a component you didn't touch can still have stale audit results on disk. That's fine: a full-codebase audit is a separate concern (run pnpm --filter @itu/ui a11y --all locally or in CI if you need it).

What if I see this hang?

The audit spins up Playwright and renders components in a real browser. That's usually fast, but if git push appears to hang after printing Running a11y audit for changed components: ..., here are the most common causes.

If you want to bypass the hook temporarily — for example, to push a work-in-progress branch to get a colleague's eyes on it — you can use git push --no-verify. Use this sparingly. It means the audit doesn't run, which means the convention isn't being enforced on that push.

Running the audit manually

You rarely need to invoke the audit yourself, but when you do:

1
# Audit a specific component
2
pnpm --filter @itu/ui run a11y button

1
# Audit several components at once
2
pnpm --filter @itu/ui run a11y button hero links-grid

1
# Audit every component (slow — full sweep)
2
pnpm --filter @itu/ui run a11y --all

1
# Regenerate the variants manifest before an audit
2
pnpm --filter @itu/ui exec tsx scripts/extract-variants.ts

Related

• The git hooks overview explains how the pre-push hook sits alongside the other hooks (commit-msg, pre-commit) in the enforcement chain.
• Component-level accessibility state is rendered on each component's documentation page under the "Accessibility" section, sourced directly from packages/ui/generated/a11y/<slug>.json.