a11y-toph — accessibility as the subject, proven by running it
NO ACCESSIBILITY CLAIM WITHOUT A RUN CHECK
An accessibility finding is a reproduction, not an opinion about source code.
An accessibility fix is the same reproduction, re-run, now passing. Reading
the JSX and concluding "this is now keyboard-accessible" is the failure this
skill exists to delete — it is exactly what a capable agent does when nobody
stops it, and it is wrong often enough to be worthless.
Everything here binds PRACTICE.md §4 (the reproduction is the failing test —
record it before you touch a line) and §5 (the evidence gate, unchanged).
1. Scope — and the line against design-arwen
Both skills care about the same floor. They are invoked at different moments and
they own different halves, and neither restates the other's mechanics.
|
design-arwen |
a11y-toph |
| Owns a11y as |
a gate inside a design task — a constraint on what it is currently building |
a subject in its own right — invoked against code nobody is redesigning |
| Trigger |
build / redesign / improve / critique an interface |
audit, compliance question, filed a11y bug, screen-reader report, CI wiring |
| Surface |
the design it just produced, on the design's terms (states, both themes, the signature) |
the whole existing surface, whoever wrote it and however long ago |
| Output |
a shipped design that passed its gate |
ranked findings with reproductions, the minimum fixes, re-run evidence |
| Changes |
layout, palette, type, component structure — freely |
only what accessibility requires — never a redesign |
Route to arwen, not here: the work is "build/redesign/improve this UI". Its
ship gate covers a11y for what it writes. Do not run this skill in front of it.
Route here, not arwen: the ask names accessibility, a standard, an assistive
technology, or a user who can't operate something. Also when arwen's gate finds
damage wider than the change it made — hand over the failing pairs and stop.
Hand back to arwen the moment a fix needs a design decision: the palette
fails contrast at the token level, a state is distinguished by colour alone with
no room for a second signal, the fix costs a layout. Report the failing pairs
and the constraint; do not repaint a product's brand inside an audit.
Adjacent: audit-sherlock carries a11y as one lane of a whole-codebase sweep —
it routes here for depth. web-perf owns measured vitals.
2. The evidence gate
Automated tools are the floor, not the claim. axe/pa11y/Lighthouse catch the
machine-checkable minority — roughly a third of real defects, and none of the
classes in §3 marked manual. "axe: 0 violations" is one line of a report, never
a verdict.
Every finding: file:line + the reproduction (the exact keystroke sequence,
the measured number, or the tool output). Every fix: the same reproduction,
re-run. Every report ends with what you did not check.
| Claim |
Requires |
Not sufficient |
| Keyboard accessible |
A recorded Tab transcript: every stop, in order, focus visible, nothing trapped, Escape works |
The elements are <button>s now |
| Contrast passes |
Computed colours pulled off the rendered element, ratio printed, per state |
Token names, a palette, "roughly 3.3:1", eyeballing |
| Screen reader announces it |
The accessibility tree node (role + name + value) or an SR transcript |
aria-label is present in the source |
| Live region announces |
Watched it fire once, with the container in the DOM before the message |
aria-live="polite" is on the div |
| Reduced motion honoured |
Emulated prefers-reduced-motion: reduce, reloaded, content still visible |
A @media block exists |
| Touch targets pass |
Measured getBoundingClientRect() on every interactive element |
The component library "handles it" |
| Fix complete |
The whole §3 sweep re-run, not just the class you touched |
The reported symptom looks addressed |
Fixes break neighbours — re-sweep, always. In this skill's own baseline run,
an agent fixing a keyboard bug shrank a help trigger to 18×18px and introduced a
touch-target and a dismissible-content failure while reporting the bug resolved.
Rationalizations, from the baseline runs
| It said |
Reality |
| "Both files look correct." |
Correct-looking source has never operated a keyboard. Drive it. |
| "Every control is now reachable via Tab and activates with Enter/Space" — with no browser open |
That is a prediction. Tab through it and paste the transcript. |
| "Quick and cheap given the deadline, I'll skip anything not keyboard-specific" |
The scope is the sweep in §3. Deadlines shorten the fix list, never the check list. |
| "It's a disabled control, so contrast isn't strictly required by WCAG" |
Exempt from the standard, not from the product. Unreadable disabled text is why users retry a dead button. Measure it and report it. |
| "~3.3:1, borderline, likely fails" |
Estimating a ratio you could have computed. Print the number. |
"Irrelevant once a real <label> is added" |
You fixed one class by assuming another. Verify both. |
| "There's no dev server, so I can't check" |
Then the deliverable is findings marked unverified, not a completion claim. Or start the server. |
| "The library is accessible" |
Libraries ship a11y bugs, and integration is where they surface. Measure the rendered DOM. |
Red flags — stop and go run something: writing "now accessible", "resolved",
"WCAG AA compliant" · a verdict with no numbers in it · a fix report shorter than
its reproduction · "should announce" / "should be focusable" · reporting on
classes you only read for · skipping the re-sweep because the change was small.
3. The sweep
Run every row. Order matters: static first (cheap, narrows the surface), then
the browser passes, then assistive technology. Depth, exact commands, snippets
and keystrokes: references/checks.md. Correct
implementations for the widgets that fail: references/patterns.md.
| # |
Class |
What actually goes wrong in generated UI |
Check |
| 1 |
Reachability |
onClick on a div/span; a control behind hover; a custom widget with no tab stop |
Static grep, then Tab from the top and count stops against the interactive elements |
| 2 |
Traps & order |
Modal without inert, focus that escapes behind the overlay, tabindex > 0, DOM order ≠ visual order |
Tab and Shift+Tab the whole page; dump the focus order; Escape from every overlay (manual) |
| 3 |
Visible focus |
outline: none with no replacement; a ring that vanishes on a coloured surface; hover styled, focus not |
Grep outline; then focus each element and diff computed styles; measure ring contrast ≥3:1 |
| 4 |
Name / role / value |
A <div role="button"> with no name; aria-expanded that never updates; a cycling button pretending to be a select |
Accessibility-tree dump: every interactive node has role + non-empty name, and value tracks state |
| 5 |
Live regions |
Container injected with the message (announces never); a region wrapping a whole list (announces constantly); alert used for routine status |
Region present at load, aria-live correct, watched firing once (manual) |
| 6 |
Contrast in unscreenshotted states |
placeholder, disabled, hover, visited, error text, text on the accent button, the ring against both surfaces |
Force each state, pull computed colours, compute ratios with alpha resolved. Numbers or it didn't happen |
| 7 |
Motion |
No reduced-motion path; content gated behind a reveal transition ships blank; JS/spring animation ignoring the media query; infinite spinners |
Emulate reduce, reload, screenshot; grep for matchMedia/useReducedMotion in JS animation |
| 8 |
Forms |
Placeholder as label; error not tied by aria-describedby; aria-invalid missing; colour-only error; focus never moved to the failure; no autocomplete |
Submit an invalid form for real: name, description, invalidity, announcement, focus |
| 9 |
Headings & landmarks |
A styled div acting as a heading; levels skipped; no <main>; several <h1> |
Dump the heading outline and landmark list; compare against what looks like a heading |
| 10 |
Images & icons |
alt restating the filename; decorative image with alt text; icon-only button with no name; SVG with neither title nor aria-hidden |
Alt audit: flag alt matching the src basename, empty names on interactive elements |
| 11 |
Target size |
18–32px icon buttons, table row actions, close buttons, adjacent chips with no spacing |
Measure every interactive rect: <44×44 CSS px (or 24 with spacing, WCAG 2.2 AA) is a finding |
| 12 |
Mouse-only |
Hover-only tooltips and menus, drag-only reordering, title as the only carrier, custom scroll, gestures with no button |
Unplug the mouse. Complete every task by keyboard (manual) |
| 13 |
Zoom & reflow |
Fixed heights that clip, overflow: hidden on text, two-dimensional scrolling at 400% |
320 CSS px wide (400% zoom) and 200% text-only: no loss, no horizontal scroll |
Then one assistive-technology pass on the primary flow — NVDA + Firefox
(Windows) or VoiceOver + Safari (macOS/iOS). The tree dump proves the semantics;
only the AT proves it is usable.
4. Fixing
- Reproduce first, and write it down. The recorded reproduction is this
task's failing test (
PRACTICE.md §4). No reproduction, no fix.
- Native element before role before ARIA.
<button> beats
<div role="button" tabindex="0" onKeyDown>. ARIA adds semantics, never
behaviour: it will not make a div focusable, clickable by Space, or
disableable. Bad ARIA is worse than none.
- One class at a time, then re-run its reproduction. A batch of eight
simultaneous fixes has no evidence attached to any of them.
- Fix the source, not the symptom. Ten components with no focus ring is one
token or one base style, not ten patches.
- Never fix by removing.
aria-hidden on a focusable element, tabindex="-1"
to silence a warning, and deleting the failing control all clear the scanner
and break the user.
- Re-sweep §3 after the fix, not just the class you touched.
- Leave a regression guard where the project has tests —
jest-axe /
@axe-core/playwright on the component, plus an explicit keyboard test for
the behaviour that broke. Verify red-green: revert the fix, watch it fail.
5. Report
Ranked by user impact, not by rule number. Severity: blocker (a task cannot
be completed by some user) · serious (completable but degraded) · minor
(friction). A scanner's own severity is an input, not the answer.
Scope: /reports, /reports/:id · Chrome 141 + axe 4.10 · NVDA 2024.4 not run
Automated: axe 7 violations (3 serious) · pa11y clean · Lighthouse a11y 84
BLOCKER Filters.jsx:32 — panel toggle is a div, no tab stop.
Repro: Tab from the search field; focus jumps to Apply, panel unreachable.
BLOCKER Filters.jsx:61 — validation error never announced; no aria-describedby.
Repro: submit "ab" with NVDA; silence, focus stays on the button.
SERIOUS filters.css:9 — .btn:focus{outline:none}, no replacement. All buttons.
Repro: focused Apply, computed outline "none", box-shadow "none".
SERIOUS filters.css:11 — disabled label #e8f0f8 on #a8c8e8 = 1.4:1 (measured).
MINOR Filters.jsx:37 — alt="chevron-down.svg" restates the filename.
Not checked: iOS VoiceOver, Windows High Contrast, the /admin routes (no seed data).
The "not checked" line is mandatory. An audit that hides its gaps is how a
green report and a broken product coexist.
Related
PRACTICE.md §4-5 — the reproduction-as-test law and the evidence gate
- references/checks.md — commands, snippets, keystrokes
- references/patterns.md — the widget contracts
skillator:design-arwen — a11y as a gate inside a design task (§1)
skillator:audit-sherlock — whole-codebase audit; routes here for a11y depth
skillator:clone-odo — scripts/odo.sh contrast <tokens.json> gives the WCAG ratio for every text/background pair in a token file, stdlib Python; use it when the colours are tokens and nothing has rendered yet
1---2name: a11y-toph3description: >-4 Use for accessibility: an a11y or WCAG audit of existing5 code, a VPAT or compliance question, or a reported bug — "can't tab to it",6 "focus ring invisible", "screen reader reads nothing", "the toast never7 announces", "fails contrast", "no reduced-motion", "tap target too small",8 "the error is only red". Also for wiring axe, pa11y or Lighthouse into tests9 or CI. NOT for designing or building an interface — a11y inside a design10 task is design-arwen's ship gate.11metadata:12 source: https://skillmd.com/skills/bodish-coder/a11y-toph13---1415# a11y-toph — accessibility as the subject, proven by running it1617```18NO ACCESSIBILITY CLAIM WITHOUT A RUN CHECK19```2021An accessibility finding is a **reproduction**, not an opinion about source code.22An accessibility fix is **the same reproduction, re-run, now passing**. Reading23the JSX and concluding "this is now keyboard-accessible" is the failure this24skill exists to delete — it is exactly what a capable agent does when nobody25stops it, and it is wrong often enough to be worthless.2627Everything here binds `PRACTICE.md` §4 (the reproduction *is* the failing test —28record it before you touch a line) and §5 (the evidence gate, unchanged).2930---3132## 1. Scope — and the line against `design-arwen`3334Both skills care about the same floor. They are invoked at different moments and35they own different halves, and neither restates the other's mechanics.3637| | `design-arwen` | `a11y-toph` |38|---|---|---|39| **Owns a11y as** | a **gate inside a design task** — a constraint on what it is currently building | a **subject in its own right** — invoked against code nobody is redesigning |40| **Trigger** | build / redesign / improve / critique an interface | audit, compliance question, filed a11y bug, screen-reader report, CI wiring |41| **Surface** | the design it just produced, on the design's terms (states, both themes, the signature) | the whole existing surface, whoever wrote it and however long ago |42| **Output** | a shipped design that passed its gate | ranked findings with reproductions, the minimum fixes, re-run evidence |43| **Changes** | layout, palette, type, component structure — freely | only what accessibility requires — never a redesign |4445**Route to arwen, not here:** the work is "build/redesign/improve this UI". Its46ship gate covers a11y for what it writes. Do not run this skill in front of it.4748**Route here, not arwen:** the ask names accessibility, a standard, an assistive49technology, or a user who can't operate something. Also when arwen's gate finds50damage wider than the change it made — hand over the failing pairs and stop.5152**Hand back to arwen** the moment a fix needs a design decision: the palette53fails contrast at the token level, a state is distinguished by colour alone with54no room for a second signal, the fix costs a layout. Report the failing pairs55and the constraint; do not repaint a product's brand inside an audit.5657Adjacent: `audit-sherlock` carries a11y as one lane of a whole-codebase sweep —58it routes here for depth. `web-perf` owns measured vitals.5960---6162## 2. The evidence gate6364Automated tools are the **floor, not the claim**. axe/pa11y/Lighthouse catch the65machine-checkable minority — roughly a third of real defects, and none of the66classes in §3 marked *manual*. "axe: 0 violations" is one line of a report, never67a verdict.6869Every finding: **`file:line` + the reproduction** (the exact keystroke sequence,70the measured number, or the tool output). Every fix: **the same reproduction,71re-run**. Every report ends with what you did **not** check.7273| Claim | Requires | Not sufficient |74|---|---|---|75| Keyboard accessible | A recorded Tab transcript: every stop, in order, focus visible, nothing trapped, Escape works | The elements are `<button>`s now |76| Contrast passes | Computed colours pulled off the rendered element, ratio printed, per state | Token names, a palette, "roughly 3.3:1", eyeballing |77| Screen reader announces it | The accessibility tree node (role + name + value) or an SR transcript | `aria-label` is present in the source |78| Live region announces | Watched it fire once, with the container in the DOM *before* the message | `aria-live="polite"` is on the div |79| Reduced motion honoured | Emulated `prefers-reduced-motion: reduce`, reloaded, content still visible | A `@media` block exists |80| Touch targets pass | Measured `getBoundingClientRect()` on every interactive element | The component library "handles it" |81| Fix complete | The whole §3 sweep re-run, not just the class you touched | The reported symptom looks addressed |8283**Fixes break neighbours — re-sweep, always.** In this skill's own baseline run,84an agent fixing a keyboard bug shrank a help trigger to 18×18px and introduced a85touch-target and a dismissible-content failure while reporting the bug resolved.8687### Rationalizations, from the baseline runs8889| It said | Reality |90|---|---|91| "Both files look correct." | Correct-looking source has never operated a keyboard. Drive it. |92| "Every control is now reachable via Tab and activates with Enter/Space" — with no browser open | That is a prediction. Tab through it and paste the transcript. |93| "Quick and cheap given the deadline, I'll skip anything not keyboard-specific" | The scope is the sweep in §3. Deadlines shorten the *fix list*, never the *check list*. |94| "It's a disabled control, so contrast isn't strictly required by WCAG" | Exempt from the standard, not from the product. Unreadable disabled text is why users retry a dead button. Measure it and report it. |95| "~3.3:1, borderline, likely fails" | Estimating a ratio you could have computed. Print the number. |96| "Irrelevant once a real `<label>` is added" | You fixed one class by assuming another. Verify both. |97| "There's no dev server, so I can't check" | Then the deliverable is findings marked **unverified**, not a completion claim. Or start the server. |98| "The library is accessible" | Libraries ship a11y bugs, and integration is where they surface. Measure the rendered DOM. |99100**Red flags — stop and go run something:** writing "now accessible", "resolved",101"WCAG AA compliant" · a verdict with no numbers in it · a fix report shorter than102its reproduction · "should announce" / "should be focusable" · reporting on103classes you only read for · skipping the re-sweep because the change was small.104105---106107## 3. The sweep108109Run every row. Order matters: static first (cheap, narrows the surface), then110the browser passes, then assistive technology. Depth, exact commands, snippets111and keystrokes: **[references/checks.md](references/checks.md)**. Correct112implementations for the widgets that fail: **[references/patterns.md](references/patterns.md)**.113114| # | Class | What actually goes wrong in generated UI | Check |115|---|---|---|---|116| 1 | **Reachability** | `onClick` on a `div`/`span`; a control behind hover; a custom widget with no tab stop | Static grep, then Tab from the top and count stops against the interactive elements |117| 2 | **Traps & order** | Modal without `inert`, focus that escapes behind the overlay, `tabindex` > 0, DOM order ≠ visual order | Tab and Shift+Tab the whole page; dump the focus order; Escape from every overlay *(manual)* |118| 3 | **Visible focus** | `outline: none` with no replacement; a ring that vanishes on a coloured surface; hover styled, focus not | Grep `outline`; then focus each element and diff computed styles; measure ring contrast ≥3:1 |119| 4 | **Name / role / value** | A `<div role="button">` with no name; `aria-expanded` that never updates; a cycling button pretending to be a select | Accessibility-tree dump: every interactive node has role + non-empty name, and value tracks state |120| 5 | **Live regions** | Container injected *with* the message (announces never); a region wrapping a whole list (announces constantly); `alert` used for routine status | Region present at load, `aria-live` correct, watched firing once *(manual)* |121| 6 | **Contrast in unscreenshotted states** | placeholder, disabled, hover, visited, error text, text on the accent button, the ring against both surfaces | Force each state, pull computed colours, compute ratios with alpha resolved. Numbers or it didn't happen |122| 7 | **Motion** | No reduced-motion path; content gated behind a reveal transition ships blank; JS/spring animation ignoring the media query; infinite spinners | Emulate reduce, reload, screenshot; grep for `matchMedia`/`useReducedMotion` in JS animation |123| 8 | **Forms** | Placeholder as label; error not tied by `aria-describedby`; `aria-invalid` missing; colour-only error; focus never moved to the failure; no `autocomplete` | Submit an invalid form for real: name, description, invalidity, announcement, focus |124| 9 | **Headings & landmarks** | A styled `div` acting as a heading; levels skipped; no `<main>`; several `<h1>` | Dump the heading outline and landmark list; compare against what *looks* like a heading |125| 10 | **Images & icons** | `alt` restating the filename; decorative image with alt text; icon-only button with no name; SVG with neither `title` nor `aria-hidden` | Alt audit: flag `alt` matching the `src` basename, empty names on interactive elements |126| 11 | **Target size** | 18–32px icon buttons, table row actions, close buttons, adjacent chips with no spacing | Measure every interactive rect: <44×44 CSS px (or 24 with spacing, WCAG 2.2 AA) is a finding |127| 12 | **Mouse-only** | Hover-only tooltips and menus, drag-only reordering, `title` as the only carrier, custom scroll, gestures with no button | Unplug the mouse. Complete every task by keyboard *(manual)* |128| 13 | **Zoom & reflow** | Fixed heights that clip, `overflow: hidden` on text, two-dimensional scrolling at 400% | 320 CSS px wide (400% zoom) and 200% text-only: no loss, no horizontal scroll |129130Then **one assistive-technology pass** on the primary flow — NVDA + Firefox131(Windows) or VoiceOver + Safari (macOS/iOS). The tree dump proves the semantics;132only the AT proves it is usable.133134---135136## 4. Fixing1371381. **Reproduce first, and write it down.** The recorded reproduction is this139 task's failing test (`PRACTICE.md` §4). No reproduction, no fix.1402. **Native element before role before ARIA.** `<button>` beats141 `<div role="button" tabindex="0" onKeyDown>`. ARIA adds semantics, never142 behaviour: it will not make a div focusable, clickable by Space, or143 disableable. Bad ARIA is worse than none.1443. **One class at a time**, then re-run its reproduction. A batch of eight145 simultaneous fixes has no evidence attached to any of them.1464. **Fix the source, not the symptom.** Ten components with no focus ring is one147 token or one base style, not ten patches.1485. **Never fix by removing.** `aria-hidden` on a focusable element, `tabindex="-1"`149 to silence a warning, and deleting the failing control all clear the scanner150 and break the user.1516. **Re-sweep §3 after the fix**, not just the class you touched.1527. **Leave a regression guard** where the project has tests — `jest-axe` /153 `@axe-core/playwright` on the component, plus an explicit keyboard test for154 the behaviour that broke. Verify red-green: revert the fix, watch it fail.155156---157158## 5. Report159160Ranked by user impact, not by rule number. Severity: **blocker** (a task cannot161be completed by some user) · **serious** (completable but degraded) · **minor**162(friction). A scanner's own severity is an input, not the answer.163164```165Scope: /reports, /reports/:id · Chrome 141 + axe 4.10 · NVDA 2024.4 not run166Automated: axe 7 violations (3 serious) · pa11y clean · Lighthouse a11y 84167168BLOCKER Filters.jsx:32 — panel toggle is a div, no tab stop.169 Repro: Tab from the search field; focus jumps to Apply, panel unreachable.170BLOCKER Filters.jsx:61 — validation error never announced; no aria-describedby.171 Repro: submit "ab" with NVDA; silence, focus stays on the button.172SERIOUS filters.css:9 — .btn:focus{outline:none}, no replacement. All buttons.173 Repro: focused Apply, computed outline "none", box-shadow "none".174SERIOUS filters.css:11 — disabled label #e8f0f8 on #a8c8e8 = 1.4:1 (measured).175MINOR Filters.jsx:37 — alt="chevron-down.svg" restates the filename.176177Not checked: iOS VoiceOver, Windows High Contrast, the /admin routes (no seed data).178```179180**The "not checked" line is mandatory.** An audit that hides its gaps is how a181green report and a broken product coexist.182183## Related184185- `PRACTICE.md` §4-5 — the reproduction-as-test law and the evidence gate186- [references/checks.md](references/checks.md) — commands, snippets, keystrokes187- [references/patterns.md](references/patterns.md) — the widget contracts188- `skillator:design-arwen` — a11y as a gate inside a design task (§1)189- `skillator:audit-sherlock` — whole-codebase audit; routes here for a11y depth190- `skillator:clone-odo` — `scripts/odo.sh contrast <tokens.json>` gives the WCAG ratio for every text/background pair in a token file, stdlib Python; use it when the colours are tokens and nothing has rendered yet