agentleFS
MKS-01MKS-01/appscreenmap/.claude/skills/add-a11y-rule/SKILL.md

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.

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
  1. Distinctive:

    Never duplicate a viewer rule in Python.

    line 17
  2. Distinctive:

    Check the criterion's Understanding page (https://www.w3.org/WAI/WCAG22/Understanding/) for exceptions.

    line 34
  3. Very specific:

    Add a Rule(...) to RULES; the key is the rule id.

    line 39
  4. Very specific:

    Put the detection in the matching function: _screen_checks (per screen, from parse_hierarchy nodes), _cross_screen_checks (map.json …

    line 40
  5. Distinctive:

    Only flag nodes from the app's own package, that are on screen, and that aren't backdrops (≥ 90% of the screen).

    line 46
  6. Very specific:

    Use DPI = 160 so 1 px = 1 dp.

    line 55
  7. Very specific:

    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).

    line 67
  8. Very specific:

    Check every new hit by looking at the screenshot and bounds.

    line 68

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Add an accessibility rule

1. Pick the layer

The check needs…Put it inOwner
Several screens, flows (reach_path, autofill), crawl events, manifest/device factspackages/a11y/src/appscreenmap/a11y/checks.pycrawler (this session)
One screen's hierarchy onlya11y/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 UIapps/viewer/src/a11y.tsweb 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 rulecrawler

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 app

Check 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(...) to RULES; the key is the rule id.
  • Put the detection in the matching function: _screen_checks (per screen, from parse_hierarchy nodes), _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>. Keep label stable 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.View without 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:

  1. a clear failure → flagged with the right sc, level, and kind
  2. each WCAG exception → not flagged
  3. each false-positive guard → not flagged
  4. key stability: running twice gives identical keys
uv run pytest -q packages/a11y/tests/test_a11y.py && uv run ruff check && uv run ruff format

5. 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 in reference/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 from RULES automatically. If the check only means something under a condition (like 1.4.4 needing a 200% font crawl), add it to a11y_report._not_run_reason so the report says Not tested instead of a false No issues detected. If a viewer rule changes its criterion, update VIEWER_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-inconsistent only compares bars that share most items with the common bar.
  • Compose clickables usually have no role (android.view.View). no-role is info because many are cards where the merged text is announced fine; confirm with TalkBack before calling it a failure.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.