add-a11y-rule
Skill2 starsChanged 20 days agoMITView on GitHub
Add or improve an automated WCAG 2.2 accessibility check in AppScreenMap — choose the right layer (crawler a11y/checks.py vs the web viewer's a11y.ts), write the rule spec, guard against false positives, test it with synthetic hierarchies, and document it. Use when a new criterion should be detected automatically or an existing a11y rule is noisy or wrong.
In this repository22 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- a11y-auditSkill
- adaptiveSkill
- add-exporterSkill
- android-intent-securitySkill
- android-permissions-securitySkill
- crawl-appSkill
- design-systemSkill
- edge-to-edgeSkill
- extend-crawlerSkill
- ios-a11y-rulesSkill
- ios-simulatorSkill
- maintain-crawlerSkill
- play-policy-insightsSkill
- security-auditSkill
- security-rulesSkill
- stack-iosSkill
- stack-rulesSkill
- store-requirementsSkill
- tune-crawlerSkill
- wcag-mobile-rulesSkill
- web-uiSkill
The file
We split this skill into the rules it gives an agent
8 rules. About 0 are common, 3 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 17
Never duplicate a viewer rule in Python.
- Distinctive: line 34
Check the criterion's Understanding page (https://www.w3.org/WAI/WCAG22/Understanding/) for exceptions.
- Very specific: line 39
Add a Rule(...) to RULES; the key is the rule id.
- Very specific: line 40
Put the detection in the matching function: _screen_checks (per screen, from parse_hierarchy nodes), _cross_screen_checks (map.json …
- Distinctive: line 46
Only flag nodes from the app's own package, that are on screen, and that aren't backdrops (≥ 90% of the screen).
- Very specific: line 55
Use DPI = 160 so 1 px = 1 dp.
- Very specific: line 67
Run uv run appscreenmap-engine a11y runs/playground/<run-id> --level AAA on a local run of a sample app (samples/demo.sh makes one).
- Very specific: line 68
Check every new hit by looking at the screenshot and bounds.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Add an accessibility rule
1. Pick the layer
| The check needs… | Put it in | Owner |
Several screens, flows (reach_path, autofill), crawl events, manifest/device facts | packages/a11y/src/appscreenmap/a11y/checks.py | crawler (this session) |
| One screen's hierarchy only | a11y/checks.py if the viewer doesn't already cover it (see the table in wcag-mobile-rules) | crawler |
| Screenshot pixels in the browser (contrast), interactive UI | apps/viewer/src/a11y.ts | web session. Don't edit it. Write the spec below and give it to the user to pass on. |
| Data the crawl doesn't capture yet (e.g. focus traversal, live regions, autofill hints) | First extend the driver/explorer to record it (extend-crawler), add it to map.json (additive), then write the rule | crawler |
Never duplicate a viewer rule in Python. If a viewer rule is wrong (e.g. it calls 48 dp a WCAG failure), write up the correction for the web session instead.
2. Write the spec first
id: kebab-case, unique across a11y/checks.py and a11y.ts
criterion: SC number + name + level (WCAG 2.2). One primary SC.
kind: automated (detects a likely failure) | review (flags something a person must check)
severity: error (likely failure) | warning | info
detects: precise condition, with thresholds in dp (px / (density/160))
exceptions: WCAG's own exceptions for this SC (e.g. 2.5.8 spacing/inline/essential)
false +: known noise sources and the guard for each
fix: View + Compose guidance (1–2 sentences)
native_note: set when WCAG2ICT doesn't apply the SC to a single appCheck the criterion's Understanding page (https://www.w3.org/WAI/WCAG22/Understanding/) for exceptions. Most false-positive complaints come from a missed exception.
3. Implement in a11y/checks.py
- Add a
Rule(...)toRULES; the key is the rule id. - Put the detection in the matching function:
_screen_checks(per screen, fromparse_hierarchynodes),_cross_screen_checks(map.json elements across screens),_flow_checks(reach paths, autofill, events),_app_checks(manifest/device). - Report with
out.add(rule_id, screen_id, label, detail, node=…). This builds the shared issue key<screen>::<rule>::<rid|class>::<label>::<x>,<y>. Keeplabelstable between runs (no counts or timestamps), or triage decisions get lost. - Only flag nodes from the app's own package, that are on screen, and that aren't backdrops (≥ 90% of the screen).
- Convert sizes with
dp = _dp(data). Never hard-code pixels. - Compose specifics: nodes are often
android.view.Viewwithout ids, and names come from merged children. Use_name(n)and_visible_text(n).
4. Test
In packages/a11y/tests/test_a11y.py, build a run with make_run(tmp_path, [(_screen(...), hierarchy(...))]).
Use DPI = 160 so 1 px = 1 dp. Cover:
- a clear failure → flagged with the right
sc,level, andkind - each WCAG exception → not flagged
- each false-positive guard → not flagged
- key stability: running twice gives identical keys
uv run pytest -q packages/a11y/tests/test_a11y.py && uv run ruff check && uv run ruff format5. Check it on a real crawl
Run uv run appscreenmap-engine a11y runs/playground/<run-id> --level AAA on a local run of a sample app (samples/demo.sh makes one).
Check every new hit by looking at the screenshot and bounds. If more than about 1 in 5 hits is
wrong, tighten the rule or downgrade it to review/info before shipping.
6. Document
wcag-mobile-rules: add the rule to the "Who checks what" table and to the criterion's row inreference/criteria.md(Check column).docs/MAP_SCHEMA.md§ a11y.json if the output shape changed (additive only).packages/a11y/src/appscreenmap/a11y/wcag.py: the report's criteria catalogue. Crawler coverage is derived fromRULESautomatically. If the check only means something under a condition (like 1.4.4 needing a 200% font crawl), add it toa11y_report._not_run_reasonso the report says Not tested instead of a false No issues detected. If a viewer rule changes its criterion, updateVIEWER_RULES.- Note any lesson learned (a false-positive pattern) in this skill.
Lessons
- 48 dp is Android's guideline; WCAG AA (2.5.8) is 24 dp with a spacing exception. Keep them apart.
- A device's own bottom control row (player buttons, timer controls) isn't app navigation.
nav-inconsistentonly compares bars that share most items with the common bar. - Compose clickables usually have no role (
android.view.View).no-roleisinfobecause many are cards where the merged text is announced fine; confirm with TalkBack before calling it a failure.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

