# Accessibility Instructions — MRPS Agent Toolkit

## Overview
Auditing web accessibility against **WCAG 2.2 AA**: semantics, contrast, labels,
landmarks, and keyboard operation.

## Category & Tools
- **Tools**: `axe-core` (`kind: library`)
- **Category**: `accessibility`
- **ID prefix**: `a11y` · **Report slug**: `a11y`
- **Produces findings**: yes

## When to Reach for What
Reach for `axe-core` to evaluate the rendered DOM: contrast ratios, accessible names,
ARIA validity, landmark structure, form labels.

## Prerequisites (state these in the plan)
- A **running page** — axe tests the rendered DOM, not source. If no server is running,
  say you will start one and wait for approval.
- Headless Chrome available (the CLI drives it).
- A self-signed localhost cert may block the CLI. Prefer `http://localhost:<port>` over HTTPS.

## What Inspect means here
Run the audit, capture the raw JSON, and map violations to findings. Do not edit templates.

## The ladder, applied here
- **Inspect** — run axe, save JSON, count violations.
- **Critique** — triage by user impact, not only by axe's label.
- **Recommend** — give the exact HTML/ARIA/contrast change.
- **Fix** — only on explicit instruction.

## Commands
```bash
npx @axe-core/cli http://localhost:8080 --save reports/a11y/axe.json
```
If a single URL is not representative, run one pass per key template and note which URL
each finding came from.

## Severity mapping
| axe impact | Sev |
|---|---|
| critical | C |
| serious | H |
| moderate | M |
| minor | L |

Override axe only upward, and say why (e.g. a `moderate` violation on a primary
checkout flow is `H`).

## Required manual checks (axe cannot do these)
List them under `## Not checked` if you did not perform them:
1. Keyboard-only operation of the primary flow.
2. Visible focus order and focus trapping in dialogs.
3. 200% zoom / 400% reflow without loss of content.
4. One screen-reader spot check (VoiceOver or NVDA).
5. `prefers-reduced-motion` behaviour.

axe catches roughly a third of real issues. Never present a clean axe run as "accessible".

## Evidence rules
Cite `rule id` + `html` snippet or selector + the page URL. Example:
`image-alt · <img src="hero.jpg"> · /`.

## Report example
```markdown
# a11y — 2026-11-09T14-32-05Z

Prior: none (first run)
Toolchain: axe-core 4.10.0
Delta: +1 new · 0 still open · 0 resolved · 1 not checked

## What was found (plain English)
- **a11y-01** — A hero image has no text alternative, so screen-reader users get nothing. (High)

## What changed since last run
- First run.

## Technical detail
| ID | Sev | Evidence | File | Rule | Status |
|----|-----|----------|------|------|--------|
| a11y-01 | H | <img src="hero.jpg"> | templates/base.html | image-alt | NEW |

## Commands run
| Command | Exit | Note |
|---------|------|------|
| npx @axe-core/cli http://localhost:8080 | 0 | 1 violation |

## Not checked
- Manual keyboard and screen-reader passes.

Generated by <agent name>. Read-only. No source files were modified.
Findings are advisory; the user decides what to fix.
```