feat: add web-accessibility skill (#32)

Closes #22
2026-09-11 19:47:12 +03:00 · 2026-07-13 04:48:50 -04:00
parent 172f3a12d4
commit 3472a88e71
18 changed files with 401 additions and 0 deletions
@@ -143,6 +143,7 @@ When the user mentions these keywords, load the corresponding skill:
 | "technology-radar", "technology radar" | [technology-radar](technology-radar/SKILL.md) |
 | "strategy", "strategic planning", "OKRs", "strategic narrative", "Five Forces", "Blue Ocean", "competitive positioning", "moat", "Ansoff", "Three Horizons", "market entry", "capital allocation", "M&A evaluation", "BCG Matrix", "portfolio management" | [strategy-frameworks](strategy-frameworks/SKILL.md) |
 | "verification-methodology", "verification methodology" | [verification-methodology](verification-methodology/SKILL.md) |
+| "accessibility", "a11y", "WCAG", "ARIA", "accessible name", "screen reader", "keyboard navigation", "focus management", "focus trap", "dialog", "modal", "combobox", "listbox", "accessible form", "form validation", "error recovery", "accessible authentication", "color contrast", "reduced motion", "target size", "accessibility testing" | [web-accessibility](web-accessibility/SKILL.md) |
 | "seo-audit", "seo audit" | [seo-audit](seo-audit/SKILL.md) |
 ## Use-When Sections

@@ -283,6 +283,10 @@ Transistor.fm podcast hosting from the terminal. Manage shows and episodes, view

 Replace completion claims with a disciplined evidence trail that shows what was checked, what passed, and what remains uncertain.

+### [web-accessibility](web-accessibility/SKILL.md)
+
+Design, build, and review accessible web interfaces through native semantics, keyboard and focus contracts, error recovery, adaptive UI, assistive-technology testing, and WCAG 2.2-informed evidence without mistaking automated scans for conformance.
+
 ### [woodpecker-ci](woodpecker-ci/SKILL.md)
 Operate self-hosted Woodpecker CI from installation through production troubleshooting. Covers Forgejo/Gitea integration, server and agent setup, Docker and Kubernetes backends, workflow syntax, secrets, plugins, matrices, CLI/local execution, upgrades, security, and incident response.

@@ -0,0 +1,42 @@
+# Web Accessibility
+
+Build web interfaces people can operate, understand, and recover from across keyboard, pointer, zoom, motion, and assistive technologies.
+
+## Why Install This Skill
+
+Visually polished interfaces can still strand people in a modal, hide focus behind sticky UI, make errors impossible to fix, or announce the wrong thing to a screen reader. This skill helps turn a feature's user flow into explicit accessibility requirements before code is written.
+
+It gives your agent a framework-neutral way to choose native controls, define custom-widget contracts only when needed, and collect evidence from automated checks and real manual tasks. It treats passing a scanner as useful but limited evidence, not a promise of accessibility or WCAG conformance.
+
+## What You Get
+
+| Path | What it provides |
+|---|---|
+| `SKILL.md` | Workflow, decision rules, routing, and reference guide. |
+| `references/source-index.md` | Primary sources with status, version, URL, and decision use. |
+| `references/` | Focused guidance for semantics, focus, forms, widgets, adaptive UI, testing, routing, and outcome probes. |
+| `assets/` | Reusable acceptance-criteria, design-review, implementation-review, and release-evidence templates. |
+
+## Quick Start
+
+Ask your agent to turn a feature flow into accessibility acceptance criteria before implementation. For example:
+
+```text
+Design an accessible profile editor modal. Define keyboard, focus, form recovery,
+and browser/AT verification requirements before writing code.
+```
+
+No API key, package, or framework is required.
+
+## Triggers
+
+- Accessibility, a11y, WCAG, ARIA, accessible name, screen reader, or assistive technology.
+- Keyboard navigation, focus order, focus trap, focus restoration, dialog, modal, disclosure, or responsive navigation.
+- Form labels, validation, errors, accessible authentication, live regions, or recovery.
+- Comboboxes, tabs, listboxes, menus, grids, target size, drag alternatives, zoom, reflow, contrast, or reduced motion.
+- Accessibility testing, axe, manual testing, accessibility review, or release evidence.
+
+## Requirements
+
+- Access to the interface and its supported browser/AT environment for meaningful verification.
+- Optional automated testing tools may provide bounded rule-level evidence; manual keyboard, accessibility-tree, and selected screen-reader testing remain required for interaction risk.
@@ -0,0 +1,62 @@
+---
+name: web-accessibility
+description: >-
+  Design, build, and review accessible web interfaces with native semantics,
+  keyboard and focus behavior, forms and recovery, responsive input, motion,
+  assistive-technology testing, and WCAG 2.2-informed evidence. Use for a11y,
+  WCAG, ARIA, screen-reader, keyboard, focus, dialog, form, widget, or
+  accessibility review work across frameworks.
+license: MIT
+compatibility: Works with any agent framework supporting the Agent Skills format; no runtime dependency.
+metadata:
+  wcag-status: "W3C Recommendation 2023-10-05"
+  aria-version: "WAI-ARIA 1.2"
+---
+
+# Web Accessibility
+
+Accessibility is successful task completion and recovery for disabled people, not a tool score. Define observable requirements before implementation, prefer native platform behavior where it fits, and gather bounded evidence in the supported browser and assistive-technology (AT) environment.
+
+## Workflow
+
+1. Define the task, users, supported browsers/AT, input methods, and failure recovery. Start with `assets/acceptance-criteria-template.md`.
+2. Choose native HTML first. Load `references/semantics-and-names.md` for structure, native controls, accessible names, descriptions, and dynamic updates.
+3. Specify every interactive state: trigger, role/name/state/value, keyboard commands, focus entry/exit/return, pointer alternative, errors, and visible feedback. Load the focused pattern reference.
+4. Design for visual and input adaptation using `references/visual-input-and-motion.md`; distinguish WCAG requirements from product goals and exceptions.
+5. Implement only after the contract is defined. For custom composite widgets, first evaluate a proven native or maintained component in the chosen stack; APG examples are informative guidance, not production proof.
+6. Verify with `references/testing-and-evidence.md` and the design, implementation, and release templates. Record tool, version, scope, manual tasks, actual browser/AT combinations, failures, and blocked or not-applicable items.
+7. Do not issue a WCAG conformance or general accessibility verdict from an automated scan. A conformance claim needs a complete, scoped evaluation outside this skill's automatic verdict.
+
+## Load On Demand
+
+| Need | Load |
+|---|---|
+| Standards status, source authority, or exact links | `references/source-index.md` |
+| Native semantics, labels, accessible names, landmarks, live updates | `references/semantics-and-names.md` |
+| Tab order, focus visibility, traps, restoration, route changes | `references/keyboard-focus-and-routing.md` |
+| Labels, validation, recoverable errors, authentication | `references/forms-errors-authentication.md` |
+| Modal dialogs, disclosure, responsive navigation | `references/dialogs-disclosures-navigation.md` |
+| Tabs, comboboxes, listboxes, grids, menus, other composites | `references/composite-widgets.md` |
+| Contrast, reflow, zoom, targets, drag, motion, media | `references/visual-input-and-motion.md` |
+| Automated checks, manual protocols, AT matrix, evidence | `references/testing-and-evidence.md` |
+| Framework or skill boundary | `references/routing.md` |
+| Validate common outcomes without claiming conformance | `references/outcome-probes.md` |
+
+## Decision Rules
+
+- Treat WCAG 2.2 success criteria, HTML/ARIA specifications, and informative tutorials/patterns as separate layers. See `references/source-index.md`.
+- Use WAI-ARIA 1.2 only when native host-language semantics do not provide the required behavior. ARIA changes semantics; it does not create keyboard behavior or visual presentation.
+- Use the Accessible Name and Description Computation 1.2 algorithm for edge cases. Do not substitute a priority mnemonic; inspect the computed accessibility tree and name.
+- For a modal, prefer `<dialog>.showModal()` when it supports the target environment. Keep background content unavailable/inert, choose initial focus for the content and task, provide a visible close path, and return focus logically. Do not hide a backdrop with `aria-hidden` or hide an ancestor of the dialog.
+- Treat ordinary responsive navigation as a disclosure over ordinary links, not an ARIA menu. Use menu semantics only with the application-menu keyboard contract.
+- Target Size (Minimum) is 24 by 24 CSS pixels at WCAG 2.2 AA, subject to its spacing, equivalent, inline, user-agent, and essential exceptions. A larger target may be a product goal.
+
+## Completion
+
+Stop when each acceptance criterion has direct evidence or a recorded failed, blocked, or not-applicable result. Report residual risk and the exact evidence boundary; do not turn absent testing into a pass.
+
+## When Not To Use
+
+- For Hugo template architecture, theme-wide layout, or CMS rendering concerns, use [hugo-theme](../hugo-theme/SKILL.md) and its [design/accessibility reference](../hugo-theme/references/design-accessibility.md).
+- For product workflow, discovery, or requirements outside accessibility, use [product-methodology](../product-methodology/SKILL.md). Keep this skill responsible for the accessibility interaction contract.
+- For framework or library APIs, consult the current official documentation after defining this skill's semantic and interaction contract.
@@ -0,0 +1,23 @@
+# Accessibility Acceptance Criteria
+
+## Flow
+
+- User goal:
+- Start state and trigger:
+- Supported browsers, AT, input methods, and relevant audience data:
+- Success state, failure states, and recovery:
+
+## Criteria
+
+- [ ] Native semantic structure and visible labels communicate purpose; computed role/name/state/value are recorded for custom or high-risk controls.
+- [ ] Keyboard-only users can start, complete, reverse, cancel, and recover from the task with visible, unobscured focus.
+- [ ] Pointer-only actions have an appropriate alternative, including drag where relevant.
+- [ ] Errors are identifiable, specific, associated, discoverable, and recoverable without losing entered data.
+- [ ] Dynamic changes, status, route changes, motion, media, zoom/reflow, contrast, and target size are addressed when applicable.
+- [ ] Composite widgets document their complete interaction contract and target browser/AT test plan.
+
+## Evidence Plan
+
+| Criterion | Method | Environment | Pass/fail/blocked/not applicable | Evidence link or note |
+|---|---|---|---|---|
+| | | | | |
@@ -0,0 +1,10 @@
+# Accessibility Design Review
+
+- [ ] User tasks, recovery, input methods, and support environment are known.
+- [ ] Information is not conveyed by color, position, or motion alone.
+- [ ] Text, controls, focus states, targets, responsive states, and overlays have been designed for contrast, zoom, reflow, and text spacing.
+- [ ] Focus is visible and cannot be hidden by sticky or modal UI.
+- [ ] Dialog initial focus, close behavior, and post-close destination are intentional.
+- [ ] Forms show labels, instructions, error recovery, preserved values, and success states.
+- [ ] Motion, flashing, media, drag, and autoplay have applicable alternatives or controls.
+- [ ] Custom widgets have a documented reason instead of a native or maintained alternative.
@@ -0,0 +1,10 @@
+# Accessibility Implementation Review
+
+- [ ] Native HTML provides the primary semantics; ARIA is used only where necessary and does not duplicate or contradict it.
+- [ ] Controls have intended computed role, name, state, value, and relationships in each key state.
+- [ ] Keyboard entry, operation, reverse navigation, exit, escape/cancel, focus visibility, and restoration work.
+- [ ] Modal background is unavailable/inert without hiding the dialog's ancestor or applying `aria-hidden` to a backdrop.
+- [ ] Forms use visible labels and native semantics where appropriate; error behavior is contextual and recoverable.
+- [ ] Responsive navigation remains ordinary links unless an application-menu keyboard contract is implemented.
+- [ ] Composite widgets have the full documented contract and no role-pattern mixing.
+- [ ] Adaptive layout, motion, media, target exceptions, and drag alternatives are implemented where applicable.
@@ -0,0 +1,27 @@
+# Accessibility Release Evidence
+
+## Scope
+
+- Release/version:
+- Features and states tested:
+- Supported browser/AT/input combinations:
+- Known exclusions:
+
+## Evidence
+
+| Check | Tool or protocol/version | Scope and result | Evidence |
+|---|---|---|---|
+| Automated rules | | | |
+| Keyboard tasks, including reverse/recovery | | | |
+| Accessibility-tree inspection | | | |
+| Screen reader tasks | | | |
+| Zoom/reflow/text spacing/contrast/motion/target/pointer | | | |
+| Disabled-user research, if used | | | |
+
+## Verdict
+
+| Acceptance criterion | Pass/fail/blocked/not applicable | Evidence and remaining risk |
+|---|---|---|
+| | | |
+
+Automated results are bounded evidence only. This template does not issue a WCAG conformance claim or an automatic accessibility verdict.
@@ -0,0 +1,23 @@
+# Composite Widgets
+
+Custom tabs, comboboxes, listboxes, grids, tree views, toolbars, sliders, radio groups, and application menus have a complete contract: role, name, state/value, relationships, keyboard commands, focus model, pointer behavior, disabled behavior, error/recovery behavior, and announced changes.
+
+## Decision Path
+
+1. Can a native element or ordinary disclosure solve the user task?
+2. Can a maintained component in the selected stack meet the requirements and support target environments?
+3. If custom behavior is necessary, use [APG](https://www.w3.org/WAI/ARIA/apg/) as informative pattern guidance, document the whole contract, and test the audience-relevant browser/AT combinations.
+
+## Pattern Contracts
+
+| Pattern | Minimum contract to define and verify |
+|---|---|
+| Tabs | `tablist`, named `tab` controls, `tabpanel` relationships, one selected tab, roving Tab stop, Left/Right navigation for horizontal tabs, orientation-aware keys, Home/End where supported, and manual versus automatic activation chosen from loading latency and task behavior. |
+| Combobox | Named input or button, synchronized expanded state, popup role and relationship, current option/value, editing behavior, filtering, selection, Escape/close behavior, and either DOM focus or `aria-activedescendant` managed consistently. |
+| Listbox | Label, options, single/multiple selection model, active option, arrow navigation, type-ahead where useful, selection-follow-focus decision, and entry/exit behavior. Do not use it for ordinary links or checkboxes. |
+| Application menu | Named menu button, expanded state, `menu`/`menuitem` structure, arrow-key movement, Home/End, Escape, focus entry/return, and activation. Ordinary site navigation is not this pattern. |
+| Grid/tree | Row/item structure, selection versus focus, roving or active-descendant model, directional navigation, editing mode, announcements, and a practical alternative if the interaction is too complex. |
+
+APG key assignments describe a pattern contract, not a reason to implement it. Account for writing direction and orientation, and do not make every descendant a Tab stop when the adopted composite pattern uses arrow-key navigation.
+
+Do not mix roles from different patterns or add ARIA roles merely to style an ordinary list. Accessibility-tree inspection and task testing are required because valid attributes alone do not prove usable interaction.
@@ -0,0 +1,15 @@
+# Dialogs, Disclosures, and Navigation
+
+## Modal Dialogs
+
+Prefer `<dialog>` with `showModal()` when it is supported by the target environment; otherwise implement the equivalent behavior deliberately and test it. A modal needs an accessible name, a visible close path, focus inside while open, unavailable/inert background content, and logical focus restoration.
+
+For native `<dialog>`, use its modal API rather than merely toggling `open`; define intentional initial focus, closing, cancellation, and return behavior, then verify the supported browser/AT implementations. For a custom modal, supply `dialog` semantics, set `aria-modal="true"` only when the UI is genuinely modal for every user, contain Tab and Shift+Tab, and make the rest of the application unavailable without hiding the dialog.
+
+Choose initial focus from content structure, viewport, reversibility, and the likely task. It is not always the first control. Return focus to the invoker unless it no longer exists or the workflow makes another target more appropriate. `aria-describedby` is optional and may make rich structural content harder to consume. Close requests, Escape, and light dismiss depend on the adopted pattern and product intent; define and test them. Do not put `aria-hidden` on a backdrop and never hide an ancestor containing the dialog.
+
+## Disclosures And Navigation
+
+Use a native `button` to control a disclosure and synchronize `aria-expanded`; connect it to the controlled region when useful. Responsive site navigation normally remains ordinary links within a navigation landmark. It is not an ARIA menu by default. Provide visible focus, logical open/close behavior, `aria-current="page"` for the current page, and target-size review including WCAG exceptions.
+
+Use `menu`/`menuitem` roles only for application-style menus and implement their full keyboard/focus contract. Outside-click dismissal is a product choice, not a universal requirement.
@@ -0,0 +1,24 @@
+# Forms, Errors, and Authentication
+
+Use a native `<form>` and semantic input types where they fit. Give each control a visible label, explain constraints before submission when useful, group related controls with `fieldset` and `legend`, and preserve entered values after recoverable errors.
+
+## Error Recovery
+
+- Identify errors in text and visually without color alone; make them specific enough to correct. Explain required formats and constraints before they cause avoidable failures.
+- Associate error and help text with the relevant field when that relationship helps. Set `aria-invalid` when a field is invalid; do not mechanically duplicate native `required` with `aria-required`.
+- Decide whether to use native validation, custom validation, or both for the product and environment. Do not universally add `novalidate`.
+- Choose an error summary, focus movement, and announcement behavior for the flow, then test with keyboard and target AT. `aria-errormessage` and assertive live regions are optional tools, not defaults. If focus moves to a summary, its links or references must lead to the affected controls.
+- Preserve valid and recoverable entries. Give destructive or consequential submissions review, confirmation, correction, or reversal appropriate to the risk.
+- Expose successful submission or saved status without interrupting unrelated work.
+
+## Input Purpose, Repetition, And Help
+
+Use native input types and autocomplete tokens when they accurately identify common user data. Keep help mechanisms in a consistent relative order when WCAG 3.2.6 applies. Within the same process, reuse or offer previously entered information when WCAG 3.3.7 applies, while respecting its security, essential-purpose, and stale-information exceptions.
+
+## Authentication
+
+WCAG 2.2 SC 3.3.8 is Accessible Authentication (Minimum), AA; SC 3.3.7 is Redundant Entry, A. Support password managers and paste. Read the criterion for alternatives and exceptions before evaluating CAPTCHA, biometrics, or cognitive-function tests; do not make categorical claims beyond its text.
+
+## Evidence Questions
+
+Can a keyboard and screen-reader user find instructions, submit, understand every error, correct it without re-entering recoverable data, and perceive success? Record the actual tested behavior rather than assumed ARIA output.
@@ -0,0 +1,18 @@
+# Keyboard, Focus, and Route Changes
+
+Keyboard behavior is a user-flow contract, not a `keydown` handler. Document how focus enters, operates within, exits, and recovers from every interactive state.
+
+## Baseline
+
+- Preserve logical DOM order; avoid positive `tabindex`. Make all functionality available without a pointer.
+- Ensure a visible focus indicator with sufficient contrast, including after themes, zoom, and sticky overlays are active.
+- Test forward and reverse navigation. Verify that focus is not obscured by sticky headers, footers, drawers, or virtual keyboard behavior. WCAG 2.4.11 is AA; 2.4.12 and 2.4.13 are AAA.
+- A focus trap is appropriate only for an actual modal. It needs a usable exit and logical restoration, not just cycling Tab.
+
+## Route And State Changes
+
+Before changing focus, answer: what changed, where can the user continue, and will the move lose work or context? For routes, preserve browser history behavior, expose the new page purpose, and test back/forward, validation failures, and deep links. Choose a main heading, main region, status, or retained control only when the flow supports it.
+
+## Manual Protocol
+
+Complete each task with keyboard alone: Tab, Shift+Tab, Enter, Space, Escape, and pattern-specific arrows/Home/End where applicable. Record order, visible focus, unexpected traps, restoration, and recovery from each failure state.
@@ -0,0 +1,23 @@
+# Outcome Probes
+
+Use these probes to check whether a proposed design or implementation follows this skill. They are review prompts, not automated conformance tests.
+
+## A. Modal Profile Editor
+
+Verify an accessible dialog name, context-appropriate initial focus, inert/unavailable background, custom-modal Tab containment where relevant, visible close path, logical focus restoration, native form semantics/error recovery, and recorded browser/AT evidence. Reject backdrop `aria-hidden` and mandatory `aria-describedby` assumptions.
+
+## B. Contact Form Recovery
+
+Verify visible labels, native semantics, clear instructions, identified and associated errors, preserved values, context-tested summary/focus/announcement behavior, exposed success, and keyboard/screen-reader task completion. Reject universal `novalidate`, `aria-required`, `aria-errormessage`, or `role="alert"` requirements.
+
+## C. Responsive Navigation
+
+Verify a native button, state synchronized through `aria-expanded`, useful control relationship, ordinary navigation links, visible focus, logical close/focus behavior, current-page state, and 24 by 24 CSS-pixel target criterion with documented exceptions. Reject application-menu semantics by default.
+
+## D. Custom Combobox
+
+Require a documented role/state/keyboard/focus/name contract, accessibility-tree inspection, target browser/AT testing, and consideration of a proven native or maintained component before custom code.
+
+## E. Release Verdict
+
+Require bounded automated evidence, manual protocols, actual tested combinations, and recorded blocked/not-applicable criteria. Reject WCAG conformance or accessibility claims based on an automated scan alone.
@@ -0,0 +1,13 @@
+# Routing
+
+Keep the semantic and interaction contract framework-agnostic first. Then use the current official documentation for the chosen framework or component library to implement it; do not assume a universal framework or library.
+
+| Situation | Route |
+|---|---|
+| Hugo template architecture, theme-wide layout, or CMS rendering | [hugo-theme](../../hugo-theme/SKILL.md) and its [design/accessibility reference](../../hugo-theme/references/design-accessibility.md) |
+| Product workflow, discovery, or requirements outside accessibility | [product-methodology](../../product-methodology/SKILL.md); keep the accessibility contract here |
+| Browser platform behavior | WHATWG HTML in `source-index.md` |
+| ARIA roles/pattern contracts | WAI-ARIA 1.2 and APG in `source-index.md` |
+| Framework-specific component API | Current official documentation after requirements are defined |
+
+Do not route to a library merely because it advertises accessibility. Confirm its behavior against the user task and target browser/AT support.
@@ -0,0 +1,22 @@
+# Semantics, Names, and Dynamic Updates
+
+Start with HTML that represents the content and action: headings for headings, lists for lists, links for navigation, buttons for actions, and native inputs with labels. Native controls reduce interaction code, but test their actual browser/AT behavior in the supported environment.
+
+## Structure And Names
+
+- Use meaningful heading hierarchy and landmarks to expose page structure. Provide a bypass mechanism where repeated blocks create real keyboard burden. Use headings for sections, not merely for visual sizing, and keep the DOM reading order meaningful when CSS is removed.
+- Mark data tables as tables, provide a useful caption when it helps identify purpose, and associate header cells with data cells. `scope` is usually sufficient for simple row or column headers; simplify complex tables or verify any `headers`/`id` mapping. Do not expose layout tables as data tables.
+- Give every interactive control a visible, understandable label where practical. Associate `<label for>` with form controls; name icon-only controls with visible text or a carefully chosen accessible label. A placeholder or tooltip is not a durable replacement for a label.
+- Decorative images use `alt=""`; informative images need an equivalent purpose or information. Describe a linked image by the destination/action. Complex graphics need the meaningful data or explanation nearby, not a filename-shaped alt string.
+- Keep visible label text in the accessible name when speech input may use it. Do not add redundant ARIA to native elements or override a useful native role.
+- Names and descriptions are different. Prefer native labeling and visible instructions. For difficult cases, use the full [AccName 1.2 algorithm](https://www.w3.org/TR/accname-1.2/) and inspect the browser accessibility tree rather than following a shortcut. Verify references resolve, names are not empty, and hidden or generated content contributes only as intended.
+
+## Dynamic Updates
+
+Move focus only when it helps the next task. Otherwise, use a pre-existing, appropriately polite status mechanism and verify what target screen readers announce. Avoid interrupting people with assertive announcements by default. For a single-page route change, update title, main content, route state, and focus according to the task; do not force a universal focus target.
+
+## Review Questions
+
+1. Can a user identify each region, control, purpose, and current state without visual inference?
+2. Does the computed accessibility tree expose the intended role, name, state, value, and relationships?
+3. Is a dynamic change perceivable without stealing context or relying on color alone?
@@ -0,0 +1,32 @@
+# Primary Source Index
+
+Use the source appropriate to the decision. Version/status matters: specifications define requirements or platform behavior, while APG and tutorials inform implementation and must be tested in the target environment.
+
+| Source | Type and exact status/version | Canonical URL | Decision use |
+|---|---|---|---|
+| Web Content Accessibility Guidelines (WCAG) 2.2 | W3C Recommendation, 2023-10-05 | https://www.w3.org/TR/WCAG22/ | Success criteria, conformance scope, levels, and exceptions. |
+| What's New in WCAG 2.2 | W3C WAI informative explainer, retrieved 2026-07-13 | https://www.w3.org/WAI/standards-guidelines/wcag/new-in-22/ | Check the nine additions and removed 4.1.1 Parsing criterion. |
+| WAI-ARIA 1.2 | W3C Recommendation, 2023-06-06 | https://www.w3.org/TR/wai-aria-1.2/ | Roles, states, properties, and native-host-language-first rule. |
+| ARIA Authoring Practices Guide | W3C WAI informative guidance, retrieved 2026-07-13 | https://www.w3.org/WAI/ARIA/apg/ | Pattern contracts and examples; validate with audience-relevant browser/AT combinations. |
+| Accessible Name and Description Computation 1.2 | W3C draft technical specification, retrieved 2026-07-13 | https://www.w3.org/TR/accname-1.2/ | Algorithmic name/description edge cases; verify document status before a standards claim and inspect computed results. |
+| HTML Living Standard | WHATWG Living Standard, retrieved 2026-07-13 | https://html.spec.whatwg.org/multipage/ | Native HTML behavior for dialog, details/summary, forms, inert, focus, and controls. |
+| WAI accessibility evaluation tools | W3C WAI informative guidance, retrieved 2026-07-13 | https://www.w3.org/WAI/test-evaluate/tools/ | Limits of tools and need for human evaluation. |
+| WAI involving users | W3C WAI informative guidance, retrieved 2026-07-13 | https://www.w3.org/WAI/test-evaluate/involving-users/ | When disabled-user research is proportionate to risk and context. |
+
+## WCAG 2.2 Changes To Apply
+
+WCAG 2.2 adds nine success criteria:
+
+- 2.4.11 Focus Not Obscured (Minimum), AA
+- 2.4.12 Focus Not Obscured (Enhanced), AAA
+- 2.4.13 Focus Appearance, AAA
+- 2.5.7 Dragging Movements, AA
+- 2.5.8 Target Size (Minimum), AA
+- 3.2.6 Consistent Help, A
+- 3.3.7 Redundant Entry, A
+- 3.3.8 Accessible Authentication (Minimum), AA
+- 3.3.9 Accessible Authentication (Enhanced), AAA
+
+It removes obsolete 4.1.1 Parsing.
+
+Read the criterion before applying it: do not rely on abbreviated lists for exceptions, applicability, or a conformance claim.
@@ -0,0 +1,35 @@
+# Hybrid Testing and Evidence
+
+Automated tools execute specific rules in a particular DOM, browser, and configuration. Record the tool, version, rule set, URL/state, and result. Treat findings as bounded evidence, not a semantic proof or an accessibility/WCAG verdict.
+
+## What Automation Can And Cannot Establish
+
+| Automated evidence can often detect | It usually cannot decide reliably |
+|---|---|
+| Missing or empty required attributes, invalid role/state combinations, some unnamed controls, some label relationships, some contrast failures, duplicate identifiers, and detectable DOM rule violations | Whether alternative text conveys purpose, headings and focus order make sense, a custom widget follows its full keyboard contract, status timing is understandable, errors are recoverable, target exceptions apply, screen-reader output is useful, or a disabled person can complete the task |
+
+Investigate every finding in context. Also inspect sampled passes: a rule can pass because it did not apply, did not reach a state, or could not determine the human judgment.
+
+## Manual Protocol
+
+1. Establish the supported browser, operating system, AT, input, viewport, language, and feature state. Use audience/support evidence rather than a universal matrix.
+2. Complete the primary task and its failure/recovery paths with keyboard alone, including reverse navigation. Record focus order, visibility, obscuring, traps, cancellation, restoration, and unexpected context changes.
+3. Inspect the browser accessibility tree in every material state. Record role, name, description, state, value, relationships, hidden/inert exposure, and live updates.
+4. With each selected screen-reader/browser combination, navigate by page structure, controls, and ordinary reading; enter and leave interaction modes as that AT requires; complete the task, trigger errors, recover, and verify changed states. Record actual speech/braille output where it matters.
+5. Test pointer and touch alternatives, drag replacement, target spacing, zoom/reflow, text spacing, contrast, reduced motion, media controls, responsive states, and platform settings relevant to the feature.
+6. Re-run automated checks in open/closed, valid/invalid, enabled/disabled, selected/unselected, loading/complete, and responsive states they otherwise miss.
+
+## Evidence Set
+
+| Method | What to record |
+|---|---|
+| Deterministic/static checks | Exact tool, version, rules, scope, state, findings, and acknowledged blind spots. |
+| Keyboard tasks | Forward/reverse navigation, visible focus, order, traps, Escape, state changes, and recovery. |
+| Accessibility tree | Browser/version and observed role, name, state, value, and relationships for each key state. |
+| Screen reader | Actual browser/AT/version combinations selected from audience/support data; tasks, results, and defects. |
+| Adaptive UI | Zoom/reflow, text spacing, contrast, motion, target, pointer, responsive, and drag-alternative checks. |
+| User research | Participant/task findings when product risk, audience, or novelty makes it warranted. |
+
+## Release Rule
+
+For each acceptance criterion, mark pass, fail, blocked, or not applicable and link evidence. A passing automated scan alone cannot produce a pass verdict for accessibility. Report untested combinations and residual risk plainly.
@@ -0,0 +1,17 @@
+# Visual Layout, Input, Motion, and Media
+
+## Layout And Input
+
+- Do not use color alone to convey status or instructions. For WCAG AA, ordinary text generally needs at least 4.5:1 contrast and large text at least 3:1, subject to criterion definitions and exceptions. User-interface components, meaningful states, and graphical objects generally need 3:1 against adjacent colors where SC 1.4.11 applies.
+- Test text resize to 200%, zoom/reflow at the WCAG 1.4.10 equivalent of 320 CSS pixels wide (or 256 CSS pixels high for vertical writing), and text-spacing overrides without loss of content or functionality. The SC 1.4.12 test values are line height 1.5 times the font size, paragraph spacing 2 times, letter spacing 0.12 times, and word spacing 0.16 times. Read each criterion for exceptions and applicable content.
+- Check content at supported responsive states and with platform font, contrast, and zoom settings. Avoid fixed dimensions that clip labels, errors, captions, or controls.
+- WCAG 2.2 AA Target Size (Minimum), SC 2.5.8, is 24 by 24 CSS pixels with spacing, equivalent, inline, user-agent, and essential exceptions. Document the applicable exception instead of treating every small target as a failure. Larger targets can be a product goal.
+- When a task uses dragging, provide a single-pointer alternative without dragging unless the movement is essential or user-agent controlled (SC 2.5.7). Test mouse, touch, keyboard, and assistive-technology paths as relevant.
+
+## Motion, Media, And Updates
+
+- Respect reduced-motion preferences, but do not assume that one media query satisfies every motion requirement. Give people control where moving, blinking, scrolling, autoplaying, or automatically updating content meets the applicable WCAG conditions.
+- Content that starts automatically, lasts more than five seconds, and appears alongside other content needs pause, stop, or hide behavior under SC 2.2.2 unless an exception applies. Auto-updating information needs pause, stop, hide, or update-frequency control under that criterion.
+- Avoid flashes that violate SC 2.3.1. A visual impression is not enough to assess frequency, area, and threshold.
+- Provide synchronized captions for prerecorded audio in synchronized media at Level A and audio description for prerecorded video content at Level AA when those criteria apply. Transcripts can improve access and may satisfy other needs, but are not a universal substitute for required captions or audio description.
+- Verify that animations, loading states, carousels, media controls, and dynamically inserted content do not obscure focus, remove controls, trigger unexpected context changes, or announce excessive updates.