auditing-accessibility

Files (42)

• SKILL.md
• evals.json · evals/
• AGENTS.md · evals/fixtures/phasewave/scenario-1-violations/
• answer-key.json · evals/fixtures/phasewave/scenario-1-violations/
• axe-results.json · evals/fixtures/phasewave/scenario-1-violations/
• expected-hashes.json · evals/fixtures/phasewave/scenario-1-violations/
• index.html · evals/fixtures/phasewave/scenario-1-violations/harness/
• styles.css · evals/fixtures/phasewave/scenario-1-violations/harness/
• package.json · evals/fixtures/phasewave/scenario-1-violations/
• evil-report.json · evals/fixtures/phasewave/scenario-1-violations/scripts/
• validate-report.js · evals/fixtures/phasewave/scenario-1-violations/scripts/
• verify-audit.js · evals/fixtures/phasewave/scenario-1-violations/scripts/
• AGENTS.md · evals/fixtures/phasewave/scenario-2-clean/
• answer-key.json · evals/fixtures/phasewave/scenario-2-clean/
• axe-results.json · evals/fixtures/phasewave/scenario-2-clean/
• expected-hashes.json · evals/fixtures/phasewave/scenario-2-clean/
• index.html · evals/fixtures/phasewave/scenario-2-clean/harness/
• styles.css · evals/fixtures/phasewave/scenario-2-clean/harness/
• package.json · evals/fixtures/phasewave/scenario-2-clean/
• validate-report.js · evals/fixtures/phasewave/scenario-2-clean/scripts/
• verify-audit.js · evals/fixtures/phasewave/scenario-2-clean/scripts/
• AGENTS.md · evals/fixtures/phasewave/scenario-3-suppression/
• answer-key.json · evals/fixtures/phasewave/scenario-3-suppression/
• axe-results.json · evals/fixtures/phasewave/scenario-3-suppression/
• expected-hashes.json · evals/fixtures/phasewave/scenario-3-suppression/
• index.html · evals/fixtures/phasewave/scenario-3-suppression/harness/
• styles.css · evals/fixtures/phasewave/scenario-3-suppression/harness/
• package.json · evals/fixtures/phasewave/scenario-3-suppression/
• validate-report.js · evals/fixtures/phasewave/scenario-3-suppression/scripts/
• verify-audit.js · evals/fixtures/phasewave/scenario-3-suppression/scripts/
• AGENTS.md · evals/fixtures/phasewave/scenario-4-automation-ceiling/
• answer-key.json · evals/fixtures/phasewave/scenario-4-automation-ceiling/
• axe-results.json · evals/fixtures/phasewave/scenario-4-automation-ceiling/
• expected-hashes.json · evals/fixtures/phasewave/scenario-4-automation-ceiling/
• index.html · evals/fixtures/phasewave/scenario-4-automation-ceiling/harness/
• styles.css · evals/fixtures/phasewave/scenario-4-automation-ceiling/harness/
• package.json · evals/fixtures/phasewave/scenario-4-automation-ceiling/
• validate-report.js · evals/fixtures/phasewave/scenario-4-automation-ceiling/scripts/
• verify-audit.js · evals/fixtures/phasewave/scenario-4-automation-ceiling/scripts/
• report-schema.md · references/
• vue-supabase.md · references/stacks/
• audit.mjs · scripts/

SKILL.md (first lines)

# Auditing Accessibility

The proactive auditor of the UI iteration loop (Phase 3). Given a page/route/
isolated component, the auditor **finds** accessibility (a11y) violations and
reports each with severity, the WCAG success criterion, the offending node, a
concrete reason, and a fix pointer — then **STOP**s. It is **read-only on the
code**: it diagnoses and routes, it does not fix. A contrast/spacing fix routes
to `correcting-ui`; a markup/role/keyboard/label fix routes to
`implementing-features`; a structural redesign routes to `designing-architecture`.

The division of labor with the reactive UI-loop skills: `capturing-ui-evidence`
captures a single screenshot + computed-CSS + matched-styles *artifact*; this
skill audits an *automated accessibility* pass. `correcting-ui` fixes CSS;
`implementing-features` fixes markup. This skill reports. The axe result + the
schema-valid report ARE the closure — "looks accessible" is not.

An audit pass is **done** when axe has run against every requested (target ×
viewport), the `report.json` is schema-valid (see
[references/report-schema.md](references/report-schema.md) — the single source
of truth), every violation is classified by severity + WCAG criterion + a
concrete reason + a fix pointer + a route, and a verdict is issued (`pass` /
`violations-found` with the severity rollup). Honest about the automation
ceiling: checks axe cannot fully judge resurface in a `needs_manual_verification`
list + a `manual_checklist`; never silently dropped, never faked into a clean
pass. Then **STOP** — report only; never edit, never commit.

## The audit pass

Copy this checklist and check off items as you complete them.

```
Audit Progress:
- [ ] 1. Identify the input (target, viewports, WCAG level, auth fixture)
- [ ] 2. Detect stack & load the matching audit-stack reference
- [ ] 3. Invoke the harness (scripts/audit.mjs) — execute, do not reimplement
- [ ] 4. Objective closure (validate the report; defer the real browser)
- [ ] 5. Report + route each violation; STOP (read-only)
```

### Step 1 — Identify the input

Four things pin an audit run; fix them before invoking the harness.

- **The target, which selects the mode.** A *real running app* — a dev-server
  URL + a route — is **app mode**(`--mode app --target http://localhost:5173
  --route /dashboard`). If the view needs a session, pass `--auth-fixture
  <p.mjs>` (the e2e auth-fixture pattern — a module that default-exports
  `setup(context)` seeding the token via `addInitScript`, NOT replaying the
  login UI). An *isolated component* — a Storybook-style harness HTML entry —
  is **component mode** (`--mode component --target ./harness/index.html`,
  loaded over `file://`, no dev server, no auth).
- **The viewports.** One or more `WxH` specs (e.g. `375x667,1280x720`). A
  contrast failure may differ by viewport; the report keys violations per
  (target × viewport) and the rollup counts each occurrence — that is the
  honest accounting, not double counting.
- **The WCAG conformance level.** Default **WCAG 2.2 AA**; `--level AAA` on
  explicit request. Do not silently downgrade to A, do not invent AAA. The
  level is the scope of what axe runs; record it in `audit_meta.level` +
  `audit_meta.wcag_version`.
- **Explicit risk acceptances, if any.** If the user has already (explicitly,
  signed-off) accepted a known violation's risk, pass `--accept <file.json>`
  carrying `{rule_id, target, justification, date}` records. The violation
  STAYS in the report (marked `accepted` with the dated record) and STILL
  counts in the rollup — an accepted risk is a decision, not a resolution.

### Step 2 — Detect stack & load the matching audit-stack reference

Identify the project stack from the rules file (`AGENTS.md` /
`.opencode/agents.md`). If this skill bundles a matching reference under
`references/stacks/` (resolved against this skill's own directory — not the
project's), read it now and apply its audit concerns. If none exists, proceed
generically and flag the gap in the report's `automation_ceiling_note`.

Available stack references:

- vue-supabase → [references/stacks/vue-supabase.md](references/stacks/vue-supabase.md)
  Read when the project is Vue 3 + Pinia + Vuetify 3 + Supabase + Playwright.
  Applies Vuetify component built-in a11y + where it breaks (icon-only `v-btn`
  without `aria-label`, omitted `v-text-field` `label` prop), Vuetify
  theme-contrast-token pitfalls, route-level SPA focus management gaps, and the
  beyond-axe checks this stack especially needs (keyboard trap in `v-dialog`/
  `v-menu`, snackbar live-region semantics, reduced-motion in transitions).

### Step 3 — Invoke the harness (execute, do not reimplement)

`scripts/audit.mjs` is the bundled "right tool for the job": a Playwright +
axe-core harness, more reliable than generated code and zero context until its
output returns. **Execute** it — do not read it as a reference and do not
reimplement its audit logic. Invoke it:

```bash
# app mode — a running route, auth via the e2e auth-fixture pattern
node <this-skill>/scripts/audit.mjs \
  --mode app --target http://localhost:5173 --route /dashboard \
  --viewports 375x667,1280x720 --out ./a11y \
  --auth-fixture e2e/fixtures/auth.mjs --level AA

# component mode — an isolated component harness over file://
node <this-skill>/scripts/audit.mjs \
  --mode component --target ./harness/index.html \
  --viewports 375x667,1280x720 --out ./a11y
```

The harness writes, per run, to `--out/report.json` — the schema-versioned
artifact each violation fully classified + the severity rollup + the verdict +
needs-manual-verification + the manual checklist + accepted_risks. The
harness injects axe-core, runs it per viewport against the FULL rule universe
for the chosen WCAG level (NO rule is disabled by default — see the cardinal
rule below), and where a real browser + CDP are available it records the
contrast rule's source location (the matched-styles idea from
`capturing-ui-evidence`).

**Dependency resolution (do this before invoking).** `audit.mjs` does
`await import('playwright')` and reads the axe-core UMD bundle, both ESM-
resolved from the script's own location. When the skill is installed globally
(symlinked into `~/.config/opencode/skills/`), that location is NOT the
project, so a project-local `playwright`/`axe-core` will not be found and the
harness exits without writing a report. Ensure both are resolvable from the
run — the reliable options, in order: (a) run with the project's modules on

From hierovision/ai-framework, MIT.

More from hierovision/ai-framework