# `infra/a11y-reports/` — pa11y-ci Nightly Report Storage (V1-P2-3501)

Nightly `pa11y-ci` runs (configured in
`.github/workflows/a11y-pa11y-nightly.yml`) write their JSON output here as
`pa11y-ci-<UTC-date>.json`. Each run also uploads the same file as a workflow
artifact named `pa11y-ci-nightly-<UTC-date>` retained for 90 days.

## Layout

```
infra/a11y-reports/
├── README.md                       # this file
├── .gitignore                      # ignores generated reports
├── pa11y-ci-2026-05-05.json        # generated daily (not tracked in git)
├── pa11y-ci-2026-05-06.json
└── …
```

The reports themselves are excluded from version control via the `.gitignore`
file; the directory exists so the workflow has a stable path to write into and
so contributors browsing the repo can find the index of where reports live. The
canonical historical record is the GitHub Actions artifact stream.

## Configuration

- **pa11y-ci config**: `tools/a11y/.pa11yci.json` — defaults (`WCAG2AA`, 60s
  timeout, 1.5s wait, 1280x800 viewport, headless Chrome with `--no-sandbox`)
  plus the per-app URL list.
- **Catalog dependency**: `pa11y-ci: ^4.0.1` in `pnpm-workspace.yaml`.
- **Workflow**: `.github/workflows/a11y-pa11y-nightly.yml` — cron-scheduled
  (08:00 UTC daily) plus manual `workflow_dispatch`. Builds + starts the apps on
  the configured ports, runs
  `pa11y-ci --json --config tools/a11y/.pa11yci.json`, writes the JSON to this
  directory, uploads it as an artifact, and posts a summary to the workflow's
  GitHub step summary.

## Reading a report

Each entry has `documentTitle`, `pageUrl`, and per-issue `code`, `type`,
`message`, `selector`, and `context`. To filter for serious issues only:

```bash
jq '
  to_entries
  | map({
      url: .key,
      errors: [.value.issues[] | select(.type == "error")]
    })
  | map(select(.errors | length > 0))
' infra/a11y-reports/pa11y-ci-<date>.json
```

To compare two nights:

```bash
diff \
  <(jq -S 'to_entries | map({url:.key, count:(.value.issues|length)})' infra/a11y-reports/pa11y-ci-<date1>.json) \
  <(jq -S 'to_entries | map({url:.key, count:(.value.issues|length)})' infra/a11y-reports/pa11y-ci-<date2>.json)
```

## Why nightly, not per-PR?

The per-PR a11y signal is the V1-P2-3500 axe auto-fixture (every Playwright spec
runs `expectNoSeriousA11yViolations(page)` via `axeAfterEach`). pa11y-ci runs
against fully-built apps with realistic loading states and complements the
unit-level axe checks with a slower, broader sweep that catches issues visible
only after the page settles in production-like state. Running it nightly keeps
the PR feedback loop fast while still capturing regressions within ~24h.

Per-surface pass/fail verdicts are tracked under V1-P2-3510..3519 (per-app WCAG
2.1 AA verification); V1-P2-3501 owns the tooling and report pipeline, not the
green-build assertion.
