@tamsensedev/runner 0.13.0 → 0.18.0

package/library/skills/accessibility/SKILL.md

@@ -1,144 +1,144 @@
----
-name: accessibility
-description: Use when building or reviewing web UI people interact with (forms, buttons, links, dialogs, menus, tabs, images, colour, focus, keyboard handling, dynamic messages) or when a task mentions accessibility, a11y, WCAG or screen readers. Checks WCAG 2.2 AA from the code without a browser, plus an optional headless axe scan and keyboard pass.
----
-
-# Accessibility (WCAG 2.2 AA)
-
-Most accessibility bugs are visible in the code: a clickable `div`, an icon button with no name, an input without a label, a removed focus outline, an error shown only in red. This skill finds them in the changed UI, works without a browser, and adds an automated scan and a keyboard pass when a headless browser is available.
-
-The project's own rules come first: its component library (which may already handle focus and ARIA), its lint rules (`eslint-plugin-jsx-a11y`, `eslint-plugin-vuejs-accessibility`, Svelte's compiler warnings, Angular's template checks), its tests and any stated conformance target. Visual design rules are covered by the `web-interface-guidelines` and `design-review` skills; this skill does not repeat them.
-
-## Process
-
-### 1. Scope
-
-List the UI the change touches: components, templates, styles, routes. Include states the change adds (loading, empty, error, disabled, expanded) and anything that appears on top (dialogs, menus, toasts, tooltips).
-
-### 2. Check the code
-
-Go through the list below for every changed component. Examples are plain HTML; the same rules apply to JSX, Vue, Svelte and Angular templates (`htmlFor` in React, `:aria-label` bindings in Vue, and so on). Full criteria and longer patterns: [references/wcag-checks.md](references/wcag-checks.md).
-
-**Names and semantics (1.1.1, 1.3.1, 2.4.4, 4.1.2)**
-
-- Use native elements: `<button>` for actions, `<a href>` for navigation, `<input>`, `<select>`, `<dialog>`. A `div` with a click handler is not focusable and does not respond to Enter or Space.
-- Every interactive element has an accessible name: visible text, `aria-label` or `aria-labelledby`. Icon-only buttons need one; the icon itself gets `aria-hidden="true"`.
-- The visible label is part of the accessible name (2.5.3): a button showing "Save" must not be labelled "Submit form".
-- Images: meaningful ones get alt text that says what matters; decorative ones get `alt=""`.
-- Link text makes sense out of context ("Download invoice", not "click here").
-- Headings follow the page structure without skipping levels for styling; lists are lists; data tables have `<th>` with scope or headers.
-
-Wrong, then right:
-
-```html
-<div class="icon-btn" onclick="remove()"><svg>...</svg></div>
-
-<button type="button" aria-label="Remove item"><svg aria-hidden="true">...</svg></button>
-```
-
-**Keyboard and focus (2.1.1, 2.1.2, 2.4.3, 2.4.7, 2.4.11)**
-
-- Everything a mouse can do, the keyboard can do. Custom widgets (menus, tabs, comboboxes, sliders) follow the WAI-ARIA Authoring Practices key patterns, or better, come from the project's component library.
-- No traps: Tab and Shift+Tab can leave every component; dialogs trap focus only while open and Escape closes them.
-- Focus order follows the visual order. No positive `tabindex`.
-- Focus is managed: opening a dialog moves focus into it, closing returns it to the trigger; deleting an item moves focus somewhere sensible; client-side route changes move focus to the new content or its heading.
-- Focus is visible. `outline: none` without a replacement style is a bug. Use `:focus-visible` with a style that contrasts at least 3:1 with its background.
-- Sticky headers, footers and banners do not cover the focused element (`scroll-margin` or `scroll-padding` helps).
-
-**Colour and contrast (1.4.1, 1.4.3, 1.4.11)**
-
-- Text contrast at least 4.5:1; large text (at least 24 px, or 18.66 px bold) at least 3:1.
-- Control boundaries, focus indicators, icons that carry meaning and chart elements at least 3:1 against what is next to them.
-- Colour is never the only signal: errors also get text or an icon, links in body text are underlined or otherwise distinct, chart series also differ by label or pattern.
-- Check placeholder text, disabled-looking text that is still important, and text over images or gradients. Compute contrast from the design tokens when you can; say when you estimated.
-
-**Forms and errors (1.3.5, 3.3.1, 3.3.2, 3.3.3, 3.3.7, 3.3.8)**
-
-- Every input has a programmatic label (`<label for>` or a wrapping label). A placeholder is not a label.
-- Personal data fields have the right `autocomplete` value (`email`, `name`, `current-password`, `new-password`, `one-time-code`).
-- Errors: text next to the field that says what is wrong and how to fix it, linked with `aria-describedby`, the field marked `aria-invalid="true"`, and focus moved to the first invalid field (or an error summary) on submit.
-- Required fields are marked in text, not only with colour or an asterisk without explanation.
-- Do not block paste in password or code fields, and offer password manager friendly fields (3.3.8). Do not ask again for data the user already entered in the same flow (3.3.7).
-
-```html
-<label for="email">Email</label>
-<input id="email" type="email" autocomplete="email"
-       aria-invalid="true" aria-describedby="email-error">
-<p id="email-error">Enter an email address like name@example.com.</p>
-```
-
-**Dynamic content (4.1.3)**
-
-- Status messages that appear without a focus change (saved, copied, 3 results, upload finished) are announced: put them in a `role="status"` (polite) or `role="alert"` (urgent, errors) region that exists in the page before the message is inserted.
-- Loading states say so in text, not only with a spinner.
-
-**Pointer, motion and timing (2.2.1, 2.3.1, 2.5.7, 2.5.8)**
-
-- Targets are at least 24 by 24 CSS pixels, or spaced so a 24 px circle around each does not overlap another (inline text links are exempt). Touch-first layouts usually want 44 px.
-- Anything done by dragging also works with single clicks or taps (move up and down buttons, a menu, an input).
-- Animations respect `prefers-reduced-motion`; nothing flashes more than three times a second; auto-playing media can be paused.
-- Time limits can be extended, and sessions warn before expiring.
-
-**Page level (2.4.1, 2.4.2, 3.1.1)**
-
-- `<html lang>` is set; each route has a descriptive `<title>` (single-page apps must update it).
-- Landmarks (`header`, `nav`, `main`, `footer`) and a skip link or equivalent let keyboard users bypass repeated navigation.
-
-**ARIA misuse (4.1.2)**
-
-- No ARIA is better than wrong ARIA. Flag `aria-label` on a `div` or `span` with no role, `aria-hidden="true"` on focusable elements or their parents, `role="button"` without keyboard handling, `aria-expanded` or `aria-selected` that never updates, and duplicate `id`s that break label references.
-
-### 3. Run what the project already has
-
-Accessibility lint rules, component or E2E tests with axe, `pa11y` or Lighthouse CI configs, Storybook accessibility checks. Run them on the changed files or pages. Do not install new tools to do this.
-
-### 4. Optional: scan and keyboard pass in a headless browser
-
-When the app can be started (see the `ui-testing` skill):
-
-- **axe:** the headless check in the `ui-testing` skill (its `references/headless-check.md`) runs axe-core on each page when the project already has the `axe-core` package. If the project has `@axe-core/playwright`, use it in its own tests instead. Never download axe or a browser just for this.
-- **Keyboard pass:** use the snippet in [references/wcag-checks.md](references/wcag-checks.md#keyboard-pass-in-a-headless-browser) as the check's `steps` to record the focus order, whether each focused element shows a visible focus style, and whether Escape closes the open dialog and focus returns. The pass is recorded for the task like any browser run: set the check's title to "Keyboard pass" and its purpose to what you checked.
-
-Automated tools find roughly a third of WCAG problems. Zero axe violations is not conformance; a violation in third-party markup you do not control is still worth naming, but separately.
-
-### 5. Fix or report
-
-In a code step, fix with the smallest change that uses the project's components and patterns: a real `<button>` instead of a clickable `div`, a label, a focus style from the design tokens. Do not add ARIA to paper over the wrong element.
-
-In a review or test step, report. Rate each finding:
-
-- **Blocker:** someone cannot complete the flow (keyboard trap, unlabeled or unreachable control in a core flow, focus lost in a dialog, form errors not perceivable).
-- **Serious:** harder but possible (low contrast on body text, missing status announcements, no visible focus on some controls).
-- **Moderate:** friction (heading order, redundant alt text, small targets in secondary places).
-
-A test-step verdict fails on blockers in the changed flow, and on serious findings the change introduced.
-
-## Report
-
-```
-Accessibility: <checked from code | code + axe | code + axe + keyboard>
-Findings:
-- [Blocker] src/components/DeleteButton.vue:12 icon-only button has no accessible name (4.1.2). Fix: aria-label="Delete project", icon aria-hidden.
-- [Serious] ...
-Not checked: <screen reader output, real devices, pages behind login, and why>
-```
-
-Mention WCAG criterion numbers so findings can be looked up, and say which findings were measured (axe, computed contrast) and which come from reading the code.
-
-## Common mistakes
-
-- Adding `role="button"` and `tabindex="0"` to a `div` instead of using `<button>`.
-- `aria-label` that differs from the visible text, or labels like "button" and "icon".
-- Removing focus outlines for looks.
-- Treating a clean axe run as proof of accessibility.
-- Checking only the default state, not errors, loading and open dialogs.
-- Hiding content with `display: none` when it should stay available to screen readers (use a visually-hidden class), or leaving off-screen menus focusable.
-
-## Done when
-
-- Every changed interactive element has a name, a role, keyboard support and visible focus.
-- Forms label inputs and explain errors in text tied to the field.
-- Colour is never the only signal and contrast meets AA where you could compute it.
-- Findings carry file, line, WCAG criterion, severity and a concrete fix; what could not be checked is listed.
-
-Adapted from addyosmani/web-quality-skills `skills/accessibility` (MIT, commit afa8da942115f2961fdbfa80807ea0b232ff6c00, Copyright (c) 2026 Addy Osmani). Changed: rewritten as a review process for unattended runs, framework-neutral notes added, DevTools MCP and Lighthouse steps replaced by optional headless axe and keyboard checks, large-text threshold corrected to 24 px or 18.66 px bold, severity rules for verdicts added.
+---
+name: accessibility
+description: Use when building or reviewing web UI people interact with (forms, buttons, links, dialogs, menus, tabs, images, colour, focus, keyboard handling, dynamic messages) or when a task mentions accessibility, a11y, WCAG or screen readers. Checks WCAG 2.2 AA from the code without a browser, plus an optional headless axe scan and keyboard pass.
+---
+
+# Accessibility (WCAG 2.2 AA)
+
+Most accessibility bugs are visible in the code: a clickable `div`, an icon button with no name, an input without a label, a removed focus outline, an error shown only in red. This skill finds them in the changed UI, works without a browser, and adds an automated scan and a keyboard pass when a headless browser is available.
+
+The project's own rules come first: its component library (which may already handle focus and ARIA), its lint rules (`eslint-plugin-jsx-a11y`, `eslint-plugin-vuejs-accessibility`, Svelte's compiler warnings, Angular's template checks), its tests and any stated conformance target. Visual design rules are covered by the `web-interface-guidelines` and `design-review` skills; this skill does not repeat them.
+
+## Process
+
+### 1. Scope
+
+List the UI the change touches: components, templates, styles, routes. Include states the change adds (loading, empty, error, disabled, expanded) and anything that appears on top (dialogs, menus, toasts, tooltips).
+
+### 2. Check the code
+
+Go through the list below for every changed component. Examples are plain HTML; the same rules apply to JSX, Vue, Svelte and Angular templates (`htmlFor` in React, `:aria-label` bindings in Vue, and so on). Full criteria and longer patterns: [references/wcag-checks.md](references/wcag-checks.md).
+
+**Names and semantics (1.1.1, 1.3.1, 2.4.4, 4.1.2)**
+
+- Use native elements: `<button>` for actions, `<a href>` for navigation, `<input>`, `<select>`, `<dialog>`. A `div` with a click handler is not focusable and does not respond to Enter or Space.
+- Every interactive element has an accessible name: visible text, `aria-label` or `aria-labelledby`. Icon-only buttons need one; the icon itself gets `aria-hidden="true"`.
+- The visible label is part of the accessible name (2.5.3): a button showing "Save" must not be labelled "Submit form".
+- Images: meaningful ones get alt text that says what matters; decorative ones get `alt=""`.
+- Link text makes sense out of context ("Download invoice", not "click here").
+- Headings follow the page structure without skipping levels for styling; lists are lists; data tables have `<th>` with scope or headers.
+
+Wrong, then right:
+
+```html
+<div class="icon-btn" onclick="remove()"><svg>...</svg></div>
+
+<button type="button" aria-label="Remove item"><svg aria-hidden="true">...</svg></button>
+```
+
+**Keyboard and focus (2.1.1, 2.1.2, 2.4.3, 2.4.7, 2.4.11)**
+
+- Everything a mouse can do, the keyboard can do. Custom widgets (menus, tabs, comboboxes, sliders) follow the WAI-ARIA Authoring Practices key patterns, or better, come from the project's component library.
+- No traps: Tab and Shift+Tab can leave every component; dialogs trap focus only while open and Escape closes them.
+- Focus order follows the visual order. No positive `tabindex`.
+- Focus is managed: opening a dialog moves focus into it, closing returns it to the trigger; deleting an item moves focus somewhere sensible; client-side route changes move focus to the new content or its heading.
+- Focus is visible. `outline: none` without a replacement style is a bug. Use `:focus-visible` with a style that contrasts at least 3:1 with its background.
+- Sticky headers, footers and banners do not cover the focused element (`scroll-margin` or `scroll-padding` helps).
+
+**Colour and contrast (1.4.1, 1.4.3, 1.4.11)**
+
+- Text contrast at least 4.5:1; large text (at least 24 px, or 18.66 px bold) at least 3:1.
+- Control boundaries, focus indicators, icons that carry meaning and chart elements at least 3:1 against what is next to them.
+- Colour is never the only signal: errors also get text or an icon, links in body text are underlined or otherwise distinct, chart series also differ by label or pattern.
+- Check placeholder text, disabled-looking text that is still important, and text over images or gradients. Compute contrast from the design tokens when you can; say when you estimated.
+
+**Forms and errors (1.3.5, 3.3.1, 3.3.2, 3.3.3, 3.3.7, 3.3.8)**
+
+- Every input has a programmatic label (`<label for>` or a wrapping label). A placeholder is not a label.
+- Personal data fields have the right `autocomplete` value (`email`, `name`, `current-password`, `new-password`, `one-time-code`).
+- Errors: text next to the field that says what is wrong and how to fix it, linked with `aria-describedby`, the field marked `aria-invalid="true"`, and focus moved to the first invalid field (or an error summary) on submit.
+- Required fields are marked in text, not only with colour or an asterisk without explanation.
+- Do not block paste in password or code fields, and offer password manager friendly fields (3.3.8). Do not ask again for data the user already entered in the same flow (3.3.7).
+
+```html
+<label for="email">Email</label>
+<input id="email" type="email" autocomplete="email"
+       aria-invalid="true" aria-describedby="email-error">
+<p id="email-error">Enter an email address like name@example.com.</p>
+```
+
+**Dynamic content (4.1.3)**
+
+- Status messages that appear without a focus change (saved, copied, 3 results, upload finished) are announced: put them in a `role="status"` (polite) or `role="alert"` (urgent, errors) region that exists in the page before the message is inserted.
+- Loading states say so in text, not only with a spinner.
+
+**Pointer, motion and timing (2.2.1, 2.3.1, 2.5.7, 2.5.8)**
+
+- Targets are at least 24 by 24 CSS pixels, or spaced so a 24 px circle around each does not overlap another (inline text links are exempt). Touch-first layouts usually want 44 px.
+- Anything done by dragging also works with single clicks or taps (move up and down buttons, a menu, an input).
+- Animations respect `prefers-reduced-motion`; nothing flashes more than three times a second; auto-playing media can be paused.
+- Time limits can be extended, and sessions warn before expiring.
+
+**Page level (2.4.1, 2.4.2, 3.1.1)**
+
+- `<html lang>` is set; each route has a descriptive `<title>` (single-page apps must update it).
+- Landmarks (`header`, `nav`, `main`, `footer`) and a skip link or equivalent let keyboard users bypass repeated navigation.
+
+**ARIA misuse (4.1.2)**
+
+- No ARIA is better than wrong ARIA. Flag `aria-label` on a `div` or `span` with no role, `aria-hidden="true"` on focusable elements or their parents, `role="button"` without keyboard handling, `aria-expanded` or `aria-selected` that never updates, and duplicate `id`s that break label references.
+
+### 3. Run what the project already has
+
+Accessibility lint rules, component or E2E tests with axe, `pa11y` or Lighthouse CI configs, Storybook accessibility checks. Run them on the changed files or pages. Do not install new tools to do this.
+
+### 4. Optional: scan and keyboard pass in a headless browser
+
+When the app can be started (see the `ui-testing` skill):
+
+- **axe:** the headless check in the `ui-testing` skill (its `references/headless-check.md`) runs axe-core on each page when the project already has the `axe-core` package. If the project has `@axe-core/playwright`, use it in its own tests instead. Never download axe or a browser just for this.
+- **Keyboard pass:** use the snippet in [references/wcag-checks.md](references/wcag-checks.md#keyboard-pass-in-a-headless-browser) as the check's `steps` to record the focus order, whether each focused element shows a visible focus style, and whether Escape closes the open dialog and focus returns. The pass is recorded for the task like any browser run: set the check's title to "Keyboard pass" and its purpose to what you checked.
+
+Automated tools find roughly a third of WCAG problems. Zero axe violations is not conformance; a violation in third-party markup you do not control is still worth naming, but separately.
+
+### 5. Fix or report
+
+In a code step, fix with the smallest change that uses the project's components and patterns: a real `<button>` instead of a clickable `div`, a label, a focus style from the design tokens. Do not add ARIA to paper over the wrong element.
+
+In a review or test step, report. Rate each finding:
+
+- **Blocker:** someone cannot complete the flow (keyboard trap, unlabeled or unreachable control in a core flow, focus lost in a dialog, form errors not perceivable).
+- **Serious:** harder but possible (low contrast on body text, missing status announcements, no visible focus on some controls).
+- **Moderate:** friction (heading order, redundant alt text, small targets in secondary places).
+
+A test-step verdict fails on blockers in the changed flow, and on serious findings the change introduced.
+
+## Report
+
+```
+Accessibility: <checked from code | code + axe | code + axe + keyboard>
+Findings:
+- [Blocker] src/components/DeleteButton.vue:12 icon-only button has no accessible name (4.1.2). Fix: aria-label="Delete project", icon aria-hidden.
+- [Serious] ...
+Not checked: <screen reader output, real devices, pages behind login, and why>
+```
+
+Mention WCAG criterion numbers so findings can be looked up, and say which findings were measured (axe, computed contrast) and which come from reading the code.
+
+## Common mistakes
+
+- Adding `role="button"` and `tabindex="0"` to a `div` instead of using `<button>`.
+- `aria-label` that differs from the visible text, or labels like "button" and "icon".
+- Removing focus outlines for looks.
+- Treating a clean axe run as proof of accessibility.
+- Checking only the default state, not errors, loading and open dialogs.
+- Hiding content with `display: none` when it should stay available to screen readers (use a visually-hidden class), or leaving off-screen menus focusable.
+
+## Done when
+
+- Every changed interactive element has a name, a role, keyboard support and visible focus.
+- Forms label inputs and explain errors in text tied to the field.
+- Colour is never the only signal and contrast meets AA where you could compute it.
+- Findings carry file, line, WCAG criterion, severity and a concrete fix; what could not be checked is listed.
+
+Adapted from addyosmani/web-quality-skills `skills/accessibility` (MIT, commit afa8da942115f2961fdbfa80807ea0b232ff6c00, Copyright (c) 2026 Addy Osmani). Changed: rewritten as a review process for unattended runs, framework-neutral notes added, DevTools MCP and Lighthouse steps replaced by optional headless axe and keyboard checks, large-text threshold corrected to 24 px or 18.66 px bold, severity rules for verdicts added.