docs(help): add accessibility review help topic
Merged
TH
9h ago+96+96+01234567890123456789-4-4-0123456789
Summary
Agents had no single workflow for a whole-app accessibility review. This PR adds agent-device help accessibility. The topic gives a per-screen audit loop, whole-app coverage rules, and checks that audit cannot do (large text, dark mode, screen reader order and labels, gesture-only actions). It states the scope: audit findings are advisory, and no compliance verdict is given.
- Routing:
skills/agent-device/SKILL.md, theagent-setuprule, the root help topic list, andhelp dogfoodPlatform checks point to the topic. - Refs: audit's pinned refs stay valid only until the next snapshot. The topic and
help dogfoodtell the agent to act through the followingsnapshot -irefs, found by role and position (rects fromaudit --jsonandsnapshot -i --json). Element-name matching waits until audit prints names (#4652). - Bench: new
accessibility-reviewhelp-conformance case (auditrun, two or more audits,settings text-size, relaunch after the size change). The task states the starting settings, so a static plan can name the size to restore. - Touched files: 7. No change to audit output or the audit command description.
Validation
- Tested SHA:
6a4ec0ee4f3f58a7afc6eb0b73265ce186f631bc. pnpm check:affected --run: all runnable checks passed (exactCommit=true).vitest run src/commands/schema: 116 passed.pnpm bench:help-conformance --case accessibility-review --runner claude:sonnet --repeat 3: 3/3 trials, 8/8 checks each.- Docs and help text only. No runtime behavior changes, so no device run applies.
Rendered agent-device help accessibility
agent-device <version> — accessibility
Use this when asked for an accessibility review, a11y audit, or a screen-reader or touch-target check of an app.
Scope:
Audit findings are advisory heuristics. Audit checks touch-target size, missing accessible names, and covered controls.
This tool does not measure color contrast or focus order, and does not give a compliance verdict. Do not claim compliance.
Loop for each screen:
1. Open the app: agent-device open <app>. Run mkdir -p ./a11y-output once.
2. Run agent-device audit, then agent-device snapshot -i. Audit captures the screen itself, so it goes first.
3. Record each finding with its kind, role, and size. Audit's pinned refs (@eN~sG) stay valid only until the next snapshot.
To act on a finding, use the ref from that snapshot -i. The ref numbers can differ, so do not match by ref number.
Find the element in the snapshot by role and position. To compare positions, use the rect from agent-device audit --json and from agent-device snapshot -i --json.
4. Capture evidence: agent-device screenshot ./a11y-output/<screen>.png --overlay-refs
Coverage:
Visit every tab, pushed screen, sheet, dialog, and empty, error, and loading state.
Audit covers the visible screen only. On a long list, run agent-device scroll down 0.8, then run audit again.
Checks audit cannot do:
Large text: first run agent-device settings text-size to record the current size. Then run agent-device settings text-size accessibility-extra-extra-extra-large, then agent-device open <app> --relaunch. The app adopts the size only after a relaunch.
Then run audit and screenshot each key screen. Look for clipped, truncated, or overlapping text.
At the end, set the recorded size again. For example, if the recorded size was large, run agent-device settings text-size large.
Dark mode: first note the current mode from a screenshot. Then run agent-device settings appearance dark, then screenshot each key screen. Look for low-contrast text and icons by eye.
At the end, set the noted mode again. For example, if the noted mode was light, run agent-device settings appearance light.
If settings refuses on this device, such as a physical iPhone, list large text and dark mode as not done.
Screen reader order and labels: read agent-device snapshot (without -i) from top to bottom. The order must match the visual order.
A label must be specific and unique: "Save Lemon Herb Rice", not "Save". A control must expose its state (selected, checked, disabled).
Gesture-only actions: every swipe or long-press action needs another way to reach it, such as a visible control or an accessibility action.
On the iOS simulator, agent-device snapshot -i --actions names the custom actions that a merged element hides.
Fix loop (only when the user asks to fix):
Change the app source, then reload (Fast Refresh, or agent-device open <app> --relaunch).
Run audit again on the same screen and confirm the finding is gone. Report the before and after audit output.
Report:
Group findings by screen. For each finding, give the kind, element name, ref, screenshot path, and suggested fix.
List the checks you could not do. Include audit's limitation lines in that list.
Related:
agent-device help <command> command-specific flags
agent-device help manual-qa routine QA loop
agent-device help workflow full automation reference
![Autofix with [code]smith](https://pr-comments-assets.blacksmith.sh/codesmith/autofix-with-codesmith-dark-3x.png)
Open in [code]smith · Need help on this PR? Tag @codesmith-bot with what you need.