WCAG 2.2 accessibility audit

Read wcag-mobile-rules first. It defines terms, thresholds, and how to word findings. Target app: the Playground sample (dev.appscreenmap.playground; it has deliberate A11Y BUG screens) unless the user names another. Default level: AA.

1. Automated pass on a normal crawl

Use the newest good run, or crawl first (crawl-app skill):

uv run appscreenmap-engine a11y runs/<project>/<run-id>                 # level ≤ AA, open + confirmed issues
uv run appscreenmap-engine a11y runs/<project>/<run-id> --level AAA --json > <scratchpad>/a11y.json

Every crawl also writes <run>/a11y.json. The web viewer's Accessibility tab adds the per-screen scanner rules (labels, 48 dp guideline, contrast estimate). Look at both. Their issue keys share one format, so one triage covers both.

If density_exact is false, the run predates density recording; dp values are estimates. Re-crawl for exact numbers.

2. Resize text: crawl at 200%

APP_PASSWORD=playground-demo uv run appscreenmap-engine crawl --package dev.appscreenmap.playground \
  --config samples/playground-app/appscreenmap.toml --clear-data --font-scale 2.0 --name font200
uv run appscreenmap-engine a11y runs/playground/font200-<stamp>
uv run appscreenmap-engine diff runs/playground/<normal-run> runs/playground/font200-<stamp>

The font scale is restored afterwards. Look for text-truncated (1.4.4), screens missing compared to the normal run (content no longer reachable), and overlapping or clipped controls in screenshots (1.4.4 / 1.4.10). Read the screenshots; the diff only says what changed.

3. Device tests (adb). Restore every setting afterwards.

Run device tests only with the app pinned or on screens you navigated to deliberately, and don't leave the app (stay_in_app rule).

4. Manual review of what can't be automated

Walk the screen list (map.json) and screenshots, guided by each screen's patterns:

When the app's source is available (Playground: samples/playground-app/app/), grep it to confirm or rule out findings: contentDescription, semantics, Role., paneTitle, liveRegion, autofillHints, screenOrientation, maxLines.

5. Triage

Each issue's status lives in <run>/notes.json under a11y: { "<issue key>": { "status": "confirmed" | "wontfix" | "false_positive", "note": "…", "updated": "<iso>" } }. The viewer edits the same file. To write it from the CLI, load the existing file, merge your decisions, and validate with appscreenmap.core.notes.validate before saving (format owned by the web session; don't change it). appscreenmap a11y then hides false positives and won't-fixes.

6. Report

Generate the report after triage, so confirmed viewer findings and your decisions are included:

uv run appscreenmap-engine a11y runs/<project>/<run-id> --report            # AA (default)
uv run appscreenmap-engine a11y runs/<project>/<run-id> --report --level AAA

This writes a11y-report.html (self-contained, shareable) and a11y-report.md (+ a11y/crops/). For every WCAG 2.2 criterion it gives a status: Fails (confirmed), Issues found, Needs review, No issues detected (automated, not proof), Check in viewer, or Not tested. Repeated elements (a nav item on every screen) are grouped into one finding. Open the HTML and read it before handing it over. Then add what the generator can't know: your device and manual test results.

When writing up findings yourself (e.g. in a PR or the chat), group by success criterion, A then AA (AAA only if asked). For each finding include:

• SC number and name, level, and status: Fails (confirmed) / Needs review / Advisory (native) / Guideline only
• Screens (ids and titles), evidence (screenshot path plus what's wrong, with dp sizes or ratios)
• Fix for Views and/or Compose (from wcag-mobile-rules/reference/criteria.md), as specific to the code as you can make it

End with:

• coverage: which criteria were tested automatically, on device, or manually, and which were not tested
• a clear statement that automated results are not a conformance claim

If the user wants a shareable report, publish it rather than leaving it in the terminal.