a11y-loop 0.1.0

package/skill/a11y-loop/references/ai-failure-modes.md

@@ -0,0 +1,272 @@
+# Accessibility failure modes of generated UI code
+
+These are not edge cases. They are what the training data contains, so they are
+what gets generated unless you actively resist them.
+
+- 84% of LLM-generated websites in a controlled study had accessibility issues
+  ([W4A'24](https://doi.org/10.1145/3677846.3677854)).
+- Accessibility-oriented *prompts alone* produced a slightly **worse** violation
+  rate than agnostic prompts — 17.32% vs 15.93%
+  ([W4A'25](https://doi.org/10.1145/3744257.3744266)). Instructions without
+  verification do not work.
+- "Bad patterns are not edge cases in the training set. They *are* the training
+  set." — Simon Miner (IAAP), *AI-Generated Code is Inaccessible by Default*.
+- **Broken ARIA references**, hallucinated image descriptions, and misleading
+  compliance claims are documented as *emergent, LLM-specific* failure modes
+  (arXiv:2605.13873, a 2026 review of 33 studies).
+
+---
+
+## 1. The clickable div — SC 2.1.1 (A), 4.1.2 (A)
+
+```html
+<!-- WRONG --> <div class="btn" onclick="submit()">Save</div>
+<!-- RIGHT --> <button type="button" class="btn" onclick="submit()">Save</button>
+```
+
+A `div` is not focusable, is not announced as a control, ignores Enter and Space,
+and has no disabled state. `role="button"` plus `tabindex="0"` plus two key
+handlers reproduces perhaps half of what `<button>` already does. Set `type`
+explicitly — a `<button>` in a form defaults to `submit`.
+
+## 2. Icon-only control with no accessible name — SC 4.1.2 (A), 2.4.4 (A)
+
+Empty buttons appear on 30.6% of home pages and empty links on 46.3%,
+overwhelmingly because of this.
+
+```html
+<!-- WRONG -->
+<button><svg><path d="..."/></svg></button>
+<a href="/cart"><i class="icon-cart"></i></a>
+<!-- RIGHT -->
+<button aria-label="Close dialog"><svg aria-hidden="true"><path d="..."/></svg></button>
+<a href="/cart"><span class="sr-only">Cart</span><i class="icon-cart" aria-hidden="true"></i></a>
+```
+
+Otherwise it announces as "button" with no name — unusable by voice control,
+meaningless to a screen reader. Hide the decorative glyph so it cannot leak junk
+into the name.
+
+## 3. Placeholder as label — SC 1.3.1 (A), 3.3.2 (A), 4.1.2 (A)
+
+Missing form labels appear on 51.0% of home pages.
+
+```html
+<!-- WRONG -->
+<input type="email" placeholder="Email address">
+<!-- RIGHT -->
+<label for="email">Email address</label>
+<input type="email" id="email" name="email" autocomplete="email">
+```
+
+A placeholder vanishes as soon as typing starts, is usually low contrast, is not
+reliably announced, and leaves the field nameless once filled. `autocomplete`
+also earns SC 1.3.5. If the design forbids a visible label use `aria-label` — but
+a visible label is the better interface for everyone.
+
+## 4. Skipped heading levels — SC 1.3.1 (A), 2.4.6 (AA)
+
+```html
+<!-- WRONG --> <h1>Pricing</h1> <h4 class="text-sm font-semibold">Starter</h4>
+<!-- RIGHT --> <h1>Pricing</h1> <h2 class="text-sm font-semibold">Starter</h2>
+```
+
+Generated markup picks the level by visual size, breaking the outline screen
+reader users navigate by. Pick the level from the outline; set size in CSS.
+
+## 5. `outline: none` with no replacement — SC 2.4.7 (AA), 1.4.11 (AA)
+
+```css
+/* WRONG */ button:focus, a:focus, input:focus { outline: none; }
+/* RIGHT */ :focus-visible { outline: 2px solid currentColor; outline-offset: 2px; }
+```
+
+Removing the outline makes the interface unusable by keyboard while looking fine
+in a screenshot. `:focus-visible` shows the ring for keyboard use only. Confirm
+the ring reaches 3:1 against its surroundings — including dark mode and forced
+colors, where hard-coded ring colors disappear (use `currentColor` or
+`Highlight`).
+
+## 6. Broken ARIA references — SC 1.3.1 (A), 4.1.2 (A)
+
+An id is referenced that was never rendered, was renamed, or is duplicated across
+component instances.
+
+```html
+<!-- WRONG -->
+<input aria-labelledby="email-label" aria-describedby="email-hint">
+<span id="emailLabel">Email</span>
+<!-- RIGHT -->
+<span id="email-label">Email</span>
+<input id="email" aria-labelledby="email-label" aria-describedby="email-hint">
+<p id="email-hint">We only use this to send your receipt.</p>
+```
+
+A dangling reference is silently ignored, so the control ends up with **no**
+name — worse than writing nothing, because it looks handled. In a component
+rendered more than once per page, ids must be per-instance (`useId()`, a counter,
+a prop), never hard-coded. Grep your diff: every `aria-labelledby`,
+`aria-describedby`, `aria-controls`, `aria-owns`, and `for=` must resolve to one
+element in the rendered page.
+
+## 7. `aria-hidden` on something focusable — SC 1.3.1 (A), 4.1.2 (A)
+
+Rule 4 of the four rules of ARIA use forbids this outright.
+
+```html
+<!-- WRONG -->
+<button aria-hidden="true">Skip</button>
+<div class="offscreen-menu" aria-hidden="true"><a href="/help">Help</a></div>
+<!-- RIGHT -->
+<button hidden>Skip</button>
+<div class="offscreen-menu" inert hidden><a href="/help">Help</a></div>
+```
+
+`aria-hidden` removes an element from the accessibility tree but leaves it in the
+tab order, so focus lands on something that announces nothing at all. Use
+`hidden`, `display: none`, or `inert` — something that removes it from both.
+
+## 8. A role whose behavior was never implemented — SC 2.1.1 (A), 4.1.2 (A)
+
+"A role is a promise" (APG *Read Me First*).
+
+```html
+<!-- WRONG -->
+<div role="tab" aria-selected="true">Overview</div>
+<div role="tab">Billing</div>
+<!-- RIGHT: implement the whole contract, or don't claim the role -->
+<div role="tablist">
+  <button role="tab" id="t1" aria-selected="true" aria-controls="p1" tabindex="0">Overview</button>
+  <button role="tab" id="t2" aria-selected="false" aria-controls="p2" tabindex="-1">Billing</button>
+</div>
+<!-- plus arrow-key roving focus, Home/End, and aria-selected kept in sync -->
+```
+
+`role="tab"` promises the arrow-key contract, roving tabindex, a `tablist`
+parent, and linked panels. ARIA creates no behavior — the role only changes what
+is announced, so an unimplemented contract produces a control that says it works
+one way and works another. Contracts in [apg-patterns.md](apg-patterns.md); if
+you cannot implement one, use links, buttons, or a disclosure.
+
+## 9. Missing document language — SC 3.1.1 (A)
+
+Still missing on 13.5% of home pages, and free to fix.
+
+```html
+<!-- WRONG --> <html>
+<!-- RIGHT --> <html lang="en">
+```
+
+Without it, screen readers use the user's default voice, so English content may
+be read with, say, German phoneme rules. Mark inline language changes with `lang`
+too (SC 3.1.2).
+
+## 10. Animation that ignores reduced motion — SC 2.2.2 (A)
+
+```css
+/* WRONG */ .card { animation: slide-in 600ms ease-out; }
+/* RIGHT */
+.card { animation: slide-in 600ms ease-out; }
+@media (prefers-reduced-motion: reduce) {
+  .card { animation: none; }
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+```
+
+Generated code adds motion enthusiastically and the media query almost never.
+Reduce it genuinely — a global reset that a later rule overrides is worse than
+none — and verify under the reduced-motion pass of the audit. This also matters
+beyond WCAG: unwanted motion triggers vestibular symptoms.
+
+## 11. Focus lost on SPA route change — SC 2.4.3 (A), 4.1.3 (AA)
+
+```jsx
+// WRONG
+function Route({ children }) { return <main>{children}</main>; }
+// RIGHT
+function Route({ title, children }) {
+  const h = useRef(null);
+  useEffect(() => { h.current?.focus(); }, [title]);
+  return <main><h1 ref={h} tabIndex={-1}>{title}</h1>{children}</main>;
+}
+```
+
+Client-side navigation replaces the DOM without a page load, so focus falls back
+to `<body>` — the keyboard user is dumped at the top of the document with no
+announcement that anything changed. Move focus to the new heading (or a
+`tabindex="-1"` container) and update `document.title`.
+
+## 12. Dynamic content that is never announced — SC 4.1.3 (AA)
+
+```jsx
+// WRONG
+{error && <p className="text-red-600">{error}</p>}
+{results.length > 0 && <p>{results.length} results</p>}
+// RIGHT
+<p role="alert">{error}</p>
+<p role="status">{results.length ? `${results.length} results` : ''}</p>
+```
+
+Text that appears without focus moving is invisible to a screen reader unless it
+lands in a live region — and the region must exist in the DOM **before** the text
+arrives, because mounting an already-populated `aria-live` element usually
+announces nothing. Render the container always and change only its text.
+`role="alert"` (assertive) for errors, `role="status"` (polite) for counts,
+saves, and loading. Do not wrap the whole page in `aria-live`.
+
+## 13. Positive `tabindex` — SC 2.4.3 (A)
+
+```html
+<!-- WRONG --> <input tabindex="1"> <input tabindex="2"> <button tabindex="3">Go</button>
+<!-- RIGHT --> <input> <input> <button>Go</button>
+```
+
+Any positive `tabindex` jumps ahead of every natural element on the page and
+decays the moment someone inserts a field. It is always a defect. Only `0` (make
+focusable in natural order) and `-1` (programmatic target only) are legitimate.
+
+## 14. Invented alt text — SC 1.1.1 (A)
+
+```html
+<!-- WRONG -->
+<img src="/hero-2.jpg" alt="A team collaborating in a modern office">
+<img src="/decorative-swirl.svg" alt="decorative image">
+<!-- RIGHT -->
+<img src="/hero-2.jpg" alt="DRAFT: two people reviewing a document at a desk">
+<img src="/decorative-swirl.svg" alt="">
+```
+
+You cannot see the image. A plausible description of an image you have not seen
+is a factual claim you have no basis for, and a wrong `alt` is worse than a
+missing one because nothing will ever flag it. Meanwhile `alt="decorative image"`
+passes every automated check and is strictly worse than `alt=""`. Write the best
+draft you can from filename, surrounding copy, and purpose; label it **DRAFT**;
+ask the user to confirm or replace it. Same rule for `aria-label` text on icons
+whose meaning you inferred rather than read.
+
+---
+
+## Self-review before saving a UI file
+
+1. Any `div`/`span` with a click handler? → native element.
+2. Every button and link has a non-empty accessible name?
+3. Every input has `<label for>` or `aria-label`, plus `autocomplete` where it applies?
+4. Heading levels descend without skipping, exactly one `<h1>`?
+5. Any `outline: none` without a `:focus-visible` replacement?
+6. Every `aria-*` id reference resolves; ids unique per instance?
+7. No `aria-hidden` on anything focusable?
+8. Every ARIA role's keyboard contract actually implemented?
+9. `<html lang>` present?
+10. Every animation has a `prefers-reduced-motion` branch?
+11. Route changes move focus; async updates land in a pre-existing live region?
+12. No positive `tabindex`?
+13. All alt text and inferred labels marked DRAFT for human confirmation?
+
+Then run the audit. This list is the setup, not the verification.
+
+## Related
+
+[wcag22-quick-ref.md](wcag22-quick-ref.md) · [apg-patterns.md](apg-patterns.md) · [manual-testing.md](manual-testing.md)

package/skill/a11y-loop/references/apg-patterns.md

@@ -0,0 +1,264 @@
+# ARIA patterns and their keyboard contracts
+
+Source of truth: the
+[ARIA Authoring Practices Guide](https://www.w3.org/WAI/ARIA/apg/) (APG), plus
+[WAI-ARIA 1.2](https://www.w3.org/TR/wai-aria-1.2/) for normative role
+definitions and [ARIA in HTML](https://www.w3.org/TR/html-aria/) for which roles
+are permitted on which elements. ARIA 1.2 is the stable baseline; treat 1.3
+features (`aria-notify`, `sectionheader`, `aria-braillelabel`, `suggestion`,
+`comment`, `mark`) as emerging and never depend on them.
+
+**First check whether you need ARIA at all.** A `<button>`,
+`<details>`/`<summary>`, an `<input type="radio">` group in a `<fieldset>`, a
+`<select>`, or a `<dialog>` gives you the whole contract for free and cannot drift
+out of sync. Reach for a pattern below only when the native element cannot do the
+job.
+
+**A role is a promise.** Declaring a role commits you to every keyboard
+interaction, state, and focus behavior in its contract, and ARIA adds no behavior
+by itself. Pages using ARIA average *more* failures than pages without it (WebAIM
+Million 2026: 59.1 vs 42.0 errors per page) precisely because the promise usually
+goes unkept. If you cannot implement the full contract, ship the native element
+or the plain version.
+
+## The 30 APG patterns
+
+Accordion (Sections With Show/Hide Functionality) · Alert · Alert and Message
+Dialogs · Breadcrumb · Button · Carousel (Slide Show or Image Rotator) ·
+Checkbox · Combobox · Dialog (Modal) · Disclosure (Show/Hide) · Feed · Grid
+(Interactive Tabular Data and Layout Containers) · Landmarks · Link · Listbox ·
+Menu and Menubar · Menu Button · Meter · Radio Group · Slider · Slider
+(Multi-Thumb) · Spinbutton · Switch · Table · Tabs · Toolbar · Tooltip · Tree
+View · Treegrid · Window Splitter
+
+Index: [w3.org/WAI/ARIA/apg/patterns](https://www.w3.org/WAI/ARIA/apg/patterns/)
+
+**If the component you are building is not detailed below, open its APG page and
+read the keyboard interaction table before writing any code.** The ten patterns
+below cover most application UI; the other twenty (carousel, grid, treegrid,
+slider, spinbutton, toolbar, tree view, window splitter, feed…) have longer
+contracts that are easy to get wrong from memory.
+
+---
+
+## Dialog (Modal)
+
+[APG](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/) · Prefer the
+native `<dialog>` with `showModal()`, which gives you the top layer, backdrop,
+inertness of the rest of the page, and Escape handling.
+
+Roles and states: `role="dialog"` with `aria-modal="true"`; an accessible name
+via `aria-labelledby` (pointing at the dialog's heading) or `aria-label`;
+optionally `aria-describedby` for the body text.
+
+| Key | Behavior |
+|---|---|
+| — (on open) | Focus moves into the dialog: the first focusable element, or the dialog container if there is nothing focusable |
+| `Tab` | Cycles forward through focusable elements **inside the dialog only**, wrapping at the end |
+| `Shift+Tab` | Cycles backward, wrapping at the start |
+| `Escape` | Closes the dialog |
+| — (on close) | Focus returns to the element that opened it |
+
+Content outside the dialog must be inert (native `<dialog>`, the `inert`
+attribute, or `aria-hidden` plus removal from the tab order — never `aria-hidden`
+on a still-focusable element). For an alert dialog use `role="alertdialog"` with
+initial focus on the least destructive button. Focus not returning to the trigger
+on close is the most common defect in generated dialogs, and trivially
+detectable.
+
+## Tabs
+
+[APG](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/)
+
+Roles and states: `role="tablist"` containing elements with `role="tab"`, each
+with `aria-selected="true|false"` and `aria-controls` pointing at its
+`role="tabpanel"`; each panel has `aria-labelledby` pointing back at its tab.
+Add `aria-orientation="vertical"` for a vertical tablist.
+
+Only one tab is in the tab order: `tabindex="0"` on the selected tab,
+`tabindex="-1"` on the rest (roving tabindex).
+
+| Key | Behavior |
+|---|---|
+| `Tab` | Moves focus into the tablist (to the selected tab), then out to the active panel |
+| `Right` / `Left` | Previous/next tab in a horizontal tablist, wrapping optional |
+| `Down` / `Up` | Previous/next tab in a vertical tablist |
+| `Home` / `End` | First / last tab |
+| `Enter` / `Space` | Activates the focused tab — only in manual-activation mode |
+| `Delete` | Optional, for closable tabs; move focus to a neighbouring tab |
+
+Automatic activation (selection follows focus) is the APG default and is right
+when switching panels is cheap. Use manual activation when panels load data.
+
+## Accordion
+
+[APG](https://www.w3.org/WAI/ARIA/apg/patterns/accordion/)
+
+Each header is a real `<button>` wrapped in the heading level appropriate to the
+document outline, with `aria-expanded` and `aria-controls` pointing at its panel.
+The panel may carry `role="region"` with `aria-labelledby` referencing the
+button — helpful with few panels, noisy with many.
+
+| Key | Behavior |
+|---|---|
+| `Enter` / `Space` | Toggles the focused panel |
+| `Tab` | Moves through headers and the content of expanded panels in DOM order |
+| `Down` / `Up` | Optional: next/previous accordion header |
+| `Home` / `End` | Optional: first/last accordion header |
+
+Do not put `aria-expanded` on the heading; it belongs on the button. Do not
+disable the button of an expanded panel unless the pattern genuinely forbids
+collapsing all panels.
+
+## Menu Button
+
+[APG](https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/) · Only for
+*actions*. A list of links is navigation, not a menu — use a disclosure with a
+`<ul>`. `role="menu"` misapplied to navigation is a common and confusing defect.
+
+Roles and states: the trigger is a `<button>` with `aria-haspopup="true"`,
+`aria-expanded`, and `aria-controls` referencing the menu; the menu is
+`role="menu"` containing `role="menuitem"` (or `menuitemcheckbox`/`menuitemradio`).
+
+| Key | Behavior |
+|---|---|
+| `Enter` / `Space` / `Down` (on button) | Opens the menu, focus on the first item |
+| `Up` (on button) | Opens the menu, focus on the last item |
+| `Down` / `Up` (in menu) | Next / previous item, wrapping |
+| `Home` / `End` | First / last item |
+| printable character | Moves to the next item whose label starts with that character |
+| `Enter` / `Space` | Activates the item, closes the menu, focus returns to the button |
+| `Escape` | Closes the menu, focus returns to the button |
+| `Tab` | Closes the menu and moves focus onward in the page |
+
+Menu items use roving tabindex or `aria-activedescendant`; they are never in the
+page tab order themselves.
+
+## Combobox
+
+[APG](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/) · The most intricate
+common pattern. If a plain `<select>` or an `<input list>` will do, use it.
+
+Roles and states: `role="combobox"` on the text input with `aria-expanded`,
+`aria-controls` referencing the popup, `aria-autocomplete="none|list|both"`, and
+`aria-activedescendant` set to the id of the visually focused option while DOM
+focus stays in the input. The popup is usually `role="listbox"` with
+`role="option"` children carrying `aria-selected`. Label the input with `<label
+for>`.
+
+| Key | Behavior |
+|---|---|
+| `Down` | Opens the popup if closed and moves to the first/next option |
+| `Up` | Opens the popup and moves to the last/previous option |
+| `Alt+Down` | Opens the popup without moving the active option |
+| `Enter` | Accepts the active option, closes the popup, keeps focus in the input |
+| `Escape` | Closes the popup; a second press may clear the input |
+| `Home` / `End` | Move the text cursor within the input, not through options |
+| printable characters | Edit the input value and filter the list |
+| `Tab` | Accepts the active option (if any) and moves focus out |
+
+DOM focus must stay in the input throughout — move the *visual* active option
+with `aria-activedescendant`. Announce result counts in a live region so screen
+reader users know filtering happened.
+
+## Disclosure (Show/Hide)
+
+[APG](https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/) · The simplest and
+most under-used pattern. Native `<details>`/`<summary>` covers most cases.
+
+A `<button>` with `aria-expanded="true|false"` and `aria-controls` referencing
+the content, which follows the button in the DOM.
+
+| Key | Behavior |
+|---|---|
+| `Enter` / `Space` | Toggles the content |
+
+That is the entire contract. No arrow keys, no roving tabindex, no focus
+management. Reach for this before menu, before tabs, before dialog.
+
+## Radio Group
+
+[APG](https://www.w3.org/WAI/ARIA/apg/patterns/radio/) · Strongly prefer native
+`<input type="radio">` inputs sharing a `name`, inside a `<fieldset>` with a
+`<legend>` — the browser then supplies the whole contract, grouping and
+required-field semantics included. For the ARIA version: `role="radiogroup"` with
+an accessible name, containing `role="radio"` elements with `aria-checked`, and
+roving tabindex so only the checked radio is tabbable (the first, if none is).
+
+| Key | Behavior |
+|---|---|
+| `Tab` | Moves into the group (to the checked radio) and, next press, out of the group entirely |
+| `Right` / `Down` | Moves focus to the next radio **and checks it**, wrapping |
+| `Left` / `Up` | Moves focus to the previous radio and checks it, wrapping |
+| `Space` | Checks the focused radio if it is not already checked |
+
+Selection follows focus here, unlike a listbox. Never make each radio
+separately tabbable.
+
+## Switch
+
+[APG](https://www.w3.org/WAI/ARIA/apg/patterns/switch/)
+
+Either `<button role="switch" aria-checked="true|false">` or `<input
+type="checkbox" role="switch">`. A switch is on/off with immediate effect; a
+checkbox is a selection a form submits. Do not use `aria-pressed` — that is a
+toggle button.
+
+| Key | Behavior |
+|---|---|
+| `Space` | Toggles the switch |
+| `Enter` | Toggles it too, in the `<button>` form |
+
+The label must name the thing being controlled ("Email notifications"), not the
+state ("Notifications on") — the state lives in `aria-checked`, and putting it in
+the label makes the announcement contradict itself. `aria-checked` must be
+updated in the same handler that changes the visuals. `role="switch"` has no
+mixed state.
+
+## Tooltip
+
+[APG](https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/) · The APG warns this
+pattern is under discussion and support is uneven; a visible text label or a
+disclosure is usually better. The tooltip element has `role="tooltip"` and an
+`id` referenced by the trigger's `aria-describedby`, and the trigger must itself
+be focusable.
+
+| Trigger | Behavior |
+|---|---|
+| hover | Shows the tooltip |
+| focus | Shows the tooltip — required, not optional |
+| `Escape` | Hides it while the trigger keeps focus |
+
+SC 1.4.13 requires the tooltip to be dismissible without moving the pointer,
+hoverable (the pointer can move onto the tooltip without it vanishing), and
+persistent until dismissed or invalid. Never put interactive content — links,
+buttons, form fields — inside a tooltip; it is unreachable. For an icon-only
+button give the *name* with `aria-label` and use the tooltip as the visible
+description; a tooltip alone is not an accessible name.
+
+## Listbox
+
+[APG](https://www.w3.org/WAI/ARIA/apg/patterns/listbox/) · Prefer `<select>`
+unless you need custom option rendering or drag-reordering.
+
+Roles and states: `role="listbox"` with an accessible name, containing
+`role="option"` children with `aria-selected`; `aria-multiselectable="true"` for
+multi-select; roving tabindex or `aria-activedescendant` for focus; `role="group"`
+plus an `aria-label` to group options.
+
+| Key | Behavior |
+|---|---|
+| `Down` / `Up` | Move the focused option |
+| `Home` / `End` | First / last option |
+| printable character | Type-ahead to the next matching option |
+| `Space` | Toggles selection in a multi-select listbox |
+| `Shift+Down` / `Shift+Up` | Extends the selection in a multi-select listbox |
+| `Ctrl+A` | Optional: select or deselect all |
+
+Single-select listboxes normally let selection follow focus. Multi-select must
+not: focus and selection are independent, and `Space` commits.
+
+## Related
+
+[wcag22-quick-ref.md](wcag22-quick-ref.md) (the criteria behind these contracts) ·
+[ai-failure-modes.md](ai-failure-modes.md) · [manual-testing.md](manual-testing.md)