diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 431c2f2..f0418e1 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -81,6 +81,14 @@ Every component page is split into parts, like the Button's, which stays the mod Agents still read a split page as one page, named after its folder, since a part's name isn't unique across `content/docs/` (every component would have a `ux`). `joinPage()` in `server/lib/raw.ts` joins the parts back where they came from, gathering each part's rules table under the Overview's `## Checklist`, as `### UX rules` like on every component page, and its questions into one `## FAQ` before `## Sources`, so the whole page keeps the Button's outline. It runs through `readPage()` for `/raw/.md` and the contract, and through `readPages()` for the contracts `nuxt.config.ts` lists and the MCP server. Each part's own `/raw/.md` serves the part alone, and the MCP server reads each card as a link to its part. Links from before the split, like one to the Button's `#loading`, land on the Overview, so `app/middleware/split-pages.global.ts` sends them on to the part with the section. Its map comes from the parts' headings when the site builds (`appConfig` in `nuxt.config.ts`), so a new heading needs nothing more, and `server/lib/raw.test.ts` checks it. A heading on more than one part, like the FAQ, goes to the part with the longest section under it, and a rules table's anchor on the whole page, like `#ux-rules`, to its heading on the part, `#ux-checklist`. In content, link to a part's section directly, as in `/docs/components/button/ux#loading`. +Each component also has an accessibility checklist, like `/docs/accessibility/button-checklist`, for people who search for one, like "accessible combobox checklist". `server/lib/checklists.ts` builds them into `content/docs/4.accessibility/` from the components' Checklist tables, so never edit them by hand: + +- A checklist holds every rule whose Basis names WCAG, WAI-ARIA or the APG, on all four layers. A rule whose Basis is only `HTML` or `Open Components` stays on its component's pages, since the Basis can't tell the ones about accessibility from the rest, like `HTML` for passing attributes through. +- Each row names the WCAG 2.2 criteria its Basis cites, with their short names and levels from `server/lib/wcag.ts`, and links to its rules table on the layer's page, since rows have no anchors of their own. `wcag.ts` holds only each criterion's number, short name, level and Understanding page, since WCAG's text isn't ours to copy, and a Basis that cites a criterion it doesn't have, or the wrong level, fails `pnpm test`. +- A checklist's `title` is `Accessible Checklist (WCAG)`, at most 42 characters, and it has no `seo.title`, since its markdown copy is headed by `seo.title` and the MCP server's by `title`, and `pnpm check-mcp` needs them to be the same. +- The folder has no `index.md`, since one would make the checklists into parts of a split page, and its pages carry no number, since they're named after their components. +- `server/lib/checklists.test.ts` fails when a page isn't what the tables build, or a page is missing or left over, so run `pnpm test server/lib/checklists.test.ts -u` to write them again after a rule changes. + The sidebar and the header's menu show a split page as a group whose label opens and closes it without navigating, so readers go to a page from the group. The group lists the Overview first, under the `navigation.title` of `index.md`, "Overview", then its layers. The group opens on any of its pages and closes once you leave them. Docus renders both with Nuxt UI's `UContentNavigation`, which keeps every group open, so `app/components/docs/DocsAsideLeftBody.vue` replaces Docus's sidebar, and `app/components/app/AppHeaderBody.vue` the menu's navigation, with `DocsNavigation.vue` and `DocsNavigationList.vue`, which keep Nuxt UI's theme for it. Keep them in step with Docus's and Nuxt UI's. How it shares the app with the homepage: diff --git a/AGENTS.md b/AGENTS.md index 69a790d..f0519a7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -34,6 +34,7 @@ Building needs Node 22.13 or later. Which checks to run depends on what you chan | Path | What it holds | | -------------------------------------------- | -------------------------------------------------------------------------------- | | `content/docs/` | The standard. Numbered files and folders set the sidebar order | +| `content/docs/4.accessibility/` | The accessibility checklists, generated from the components' Checklist tables | | `content/changelog/` | One entry per release of something readers will notice | | `content/blog/` | The blog's posts, which aren't part of the standard or the MCP server | | `app/reference//` | The tested Vue 3 reference implementations, which every page shows as code | @@ -50,6 +51,7 @@ Most of the site is generated from the docs, so a change in one place often need - **Reference implementations and their pages.** Every file in `app/reference//` is shown in a code block titled with its name, like ```` ```vue [Button.vue] ````, under the page's `## Reference implementation`. Change both, and `pnpm check-reference` confirms they match. - **Checklists.** Rules are rows of the tables under `### UI rules`, `### UX rules`, `### DX rules` and `### AX rules` (on a split page, `## UI Checklist` and so on, on each layer's page after its sections and before its FAQ: the join turns them back into `### UI rules`), with the columns Rule, Level, Scope, Requirement, Basis and Check, named exactly that. Every rule ID is unique, every rule has a Basis and every Check is one `mcp/lib/rules.ts` knows, or `pnpm test` fails. +- **Accessibility checklists.** `content/docs/4.accessibility/` holds a page per component, like `button-checklist.md`, built from its Checklist tables by `server/lib/checklists.ts`: every rule whose Basis names WCAG, WAI-ARIA or the APG, with the WCAG 2.2 criteria it cites, named from `server/lib/wcag.ts`. Never edit them by hand. After a rule, a component or a criterion changes, run `pnpm test server/lib/checklists.test.ts -u` to write them again, and `pnpm test` fails until you do. - **Contracts.** A contract is the YAML block under a page's `### Described`. When it gains a field, add it to `public/schemas/contract.json` in the same change, since `pnpm test` validates every contract against it. - **Prompts.** The prompts on the pages (the Button's `### Prompts` on its AX page, the Design Tokens' `### Prompts`), the MCP prompts in `mcp/lib/prompts.ts` and the plugin's skills ask for the same things. `prompts.test.ts` checks the first two, so change all three together. - **Skills.** The plugin's skills name tools, pages, section headings, frameworks and rule IDs, and `pnpm test` checks that they all exist. Renaming a heading a skill reads, like "Developer Experience (DX)", fails it. @@ -65,7 +67,7 @@ The MCP server reads the same markdown as the site, and knows less MDC syntax th - Every page has a `title` and a `description`, and a file name that's unique across `content/docs/` once its number is dropped. The parts of a split page, below, count as one page. - Every description runs 70 to 160 characters, the length search results show. Where a page's `description` runs longer, give it a shorter `seo.description`. - Every layer page has a `seo.title` that names its component in at most 42 characters, like "Checkbox Group - Developer Experience (DX)", since its `title` is only its layer and the site adds " - Open Components". Every Overview has a `seo.title` of `Accessible - Guidelines`, like "Accessible Button - Guidelines", since people search for "accessible button" and its `title` is only the component's name. A `seo.title` is in title case, unlike a heading, so it reads like the layers' names in the titles beside it. Its markdown copy and its `llms.txt` link keep that name, "Button", because the MCP server heads the whole page with it. `pnpm check-seo` fails on a title or description that's too long or used twice. -- Number the folders and the pages outside `3.components/` to order them in the sidebar, and leave component folders without one, like `3.components/card/`, so the sidebar lists them by name. It sorts file names as text, which would put a `10.` before a `2.`, and two component branches open at once would reach for the same number. +- Number the folders and the pages outside `3.components/` to order them in the sidebar, and leave component folders without one, like `3.components/card/`, so the sidebar lists them by name. It sorts file names as text, which would put a `10.` before a `2.`, and two component branches open at once would reach for the same number. The generated pages in `4.accessibility/` carry none either, since they're named after their components, like `button-checklist.md`. - Every component page is split into parts, like the Button's in `3.components/button/`, which stays the model: its Overview in `index.md`, with link cards to the parts, and a page per layer, numbered to set their order inside the folder. A part's `title` is the heading it has on the whole page, its `before` names the Overview's section it goes before, and its headings sit a level higher. After its sections come its rules table, under `## UI Checklist` and so on, then its questions, if it has any, under `## FAQ`. Agents still read one page, which `server/lib/raw.ts` joins back together with one Checklist and one FAQ, and links from before the split go on to the right part (`app/middleware/split-pages.global.ts`). [The docs](./.github/CONTRIBUTING.md#the-docs) has the details. - Headings are plain text and inline code, with no links, emphasis, HTML, components or `{#id}`. - Use block components, `:roadmap-check` and `{external=""}` on links, and nothing else inline, like `:badge[New]`. diff --git a/content/changelog/accessibility-checklists.md b/content/changelog/accessibility-checklists.md new file mode 100644 index 0000000..ec6ca75 --- /dev/null +++ b/content/changelog/accessibility-checklists.md @@ -0,0 +1,17 @@ +--- +title: Accessibility checklists +description: Every component now has an accessibility checklist of its own, with the WCAG 2.2 success criteria behind each rule and a link back to it. +date: 2026-11-19 +category: Components +link: + label: Read the Button's accessibility checklist + to: /docs/accessibility/button-checklist +--- + +Each component's rules that rest on WCAG 2.2, WAI-ARIA or the APG are now on a page of their own, so you can check a component's accessibility without reading all four of its layers. We build each list from the component's checklists, so it always says what they say. + +## New + +- Each of the 17 components has an accessibility checklist, under Accessibility Checklists in the sidebar. +- Every row names the WCAG 2.2 success criteria behind its rule, with their level, and links each one to its Understanding page. +- Every rule links back to its table on the component's page, where we explain why it's there. diff --git a/content/docs/4.accessibility/.navigation.yml b/content/docs/4.accessibility/.navigation.yml new file mode 100644 index 0000000..f1bccb1 --- /dev/null +++ b/content/docs/4.accessibility/.navigation.yml @@ -0,0 +1,2 @@ +title: Accessibility Checklists +icon: i-lucide-list-checks diff --git a/content/docs/4.accessibility/button-checklist.md b/content/docs/4.accessibility/button-checklist.md new file mode 100644 index 0000000..96aaefa --- /dev/null +++ b/content/docs/4.accessibility/button-checklist.md @@ -0,0 +1,56 @@ +--- +title: Accessible Button Checklist (WCAG) +description: Every Button rule that WCAG 2.2, WAI-ARIA or the APG backs, in one checklist, with the success criteria behind each rule and their level. +navigation: + title: Button +--- + +Here's every rule for the [Button](/docs/components/button) that WCAG 2.2, WAI-ARIA or the APG backs, in one list you can work through when you build or review one. Each row names the WCAG 2.2 success criteria behind its rule, with their level, and links to the rule's table on its layer's page, where we explain why it's there. A rule that rests on WAI-ARIA or the APG alone says "None". + +We build this list from the Button's checklists, so it always matches them. It leaves out the rules that rest only on HTML and the ones that are our own, so you'll find every rule in the [Button's checklist](/docs/components/button#checklist). + +## UI rules + +| Rule | Level | Requirement | WCAG 2.2 | Basis | +| ---- | ----- | ----------- | -------- | ----- | +| [`button/intent-colors`](/docs/components/button/ui#ui-checklist) | Must | Colours describe the action's intent rather than a hue, and never carry that meaning on their own | [1.4.1 Use of Color](https://www.w3.org/WAI/WCAG22/Understanding/use-of-color.html) (A) | WCAG 1.4.1 (A), Open Components | +| [`button/contrast`](/docs/components/button/ui#ui-checklist) | Must | The label has a contrast of 4.5:1 at rest, on hover and when pressed, in every variant, and the focus ring has 3:1 against the page | [1.4.3 Contrast (Minimum)](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html) (AA), [1.4.11 Non-text Contrast](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast.html) (AA) | WCAG 1.4.3, 1.4.11 (AA) | +| [`button/link-underlined`](/docs/components/button/ui#ui-checklist) | Must | The `link` variant is underlined at rest, so it doesn't rely on colour alone to stand out from the text around it | [1.4.1 Use of Color](https://www.w3.org/WAI/WCAG22/Understanding/use-of-color.html) (A) | Open Components, beyond WCAG 1.4.1 (A) | +| [`button/focus-visible`](/docs/components/button/ui#ui-checklist) | Must | Keyboard focus shows an `outline` at least 2px thick, offset from the button, on `:focus-visible` | [2.4.7 Focus Visible](https://www.w3.org/WAI/WCAG22/Understanding/focus-visible.html) (AA), [2.4.13 Focus Appearance](https://www.w3.org/WAI/WCAG22/Understanding/focus-appearance.html) (AAA) | WCAG 2.4.7 (AA), 2.4.13 (AAA) | +| [`button/target-size`](/docs/components/button/ui#ui-checklist) | Must | The button is at least 24 × 24px, unless it's a `link` inside a sentence, with a 44 × 44px hit area on touch screens | [2.5.8 Target Size (Minimum)](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html) (AA), [2.5.5 Target Size (Enhanced)](https://www.w3.org/WAI/WCAG22/Understanding/target-size-enhanced.html) (AAA) | WCAG 2.5.8 (AA), 2.5.5 (AAA) | +| [`button/resizable`](/docs/components/button/ui#ui-checklist) | Must | The button is sized with `min-height` and padding in `rem`, and its label wraps instead of being clipped or truncated | [1.4.4 Resize Text](https://www.w3.org/WAI/WCAG22/Understanding/resize-text.html) (AA), [1.4.10 Reflow](https://www.w3.org/WAI/WCAG22/Understanding/reflow.html) (AA), [1.4.12 Text Spacing](https://www.w3.org/WAI/WCAG22/Understanding/text-spacing.html) (AA) | Open Components, beyond WCAG 1.4.4, 1.4.10, 1.4.12 (AA) | +| [`button/reduced-motion`](/docs/components/button/ui#ui-checklist) | Must | Nothing turns or slides when `prefers-reduced-motion: reduce` is set | [2.3.3 Animation from Interactions](https://www.w3.org/WAI/WCAG22/Understanding/animation-from-interactions.html) (AAA) | WCAG 2.3.3 (AAA) | + +## UX rules + +| Rule | Level | Requirement | WCAG 2.2 | Basis | +| ---- | ----- | ----------- | -------- | ----- | +| [`button/native-element`](/docs/components/button/ux#ux-checklist) | Must | It's a native `<button>`, or an `<a href>` for navigation, but never a `<div>` or a `<span>` | [2.1.1 Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html) (A), [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) (A) | Open Components, beyond WCAG 2.1.1, 4.1.2 (A) | +| [`button/accessible-name`](/docs/components/button/ux#ux-checklist) | Must | Every button has a name, and an icon-only button has a visually hidden label | [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) (A) | WCAG 4.1.2 (A), Open Components | +| [`button/label-in-name`](/docs/components/button/ux#ux-checklist) | Must | An `aria-label` or `aria-labelledby` includes the visible label, ideally at the start | [2.5.3 Label in Name](https://www.w3.org/WAI/WCAG22/Understanding/label-in-name.html) (A) | WCAG 2.5.3 (A) | +| [`button/decorative-icons`](/docs/components/button/ux#ux-checklist) | Must | Icons are hidden from assistive technologies with `aria-hidden`, so they don't add to the button's name | [1.1.1 Non-text Content](https://www.w3.org/WAI/WCAG22/Understanding/non-text-content.html) (A) | WCAG 1.1.1 (A) | +| [`button/keyboard`](/docs/components/button/ux#ux-checklist) | Must | `Enter` and `Space` activate a button, while `Enter` follows a link | [2.1.1 Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html) (A) | WCAG 2.1.1 (A), APG | +| [`button/activate-on-click`](/docs/components/button/ux#ux-checklist) | Must | Actions run on `click`, never on `mousedown`, `pointerdown` or `touchstart` | [2.5.2 Pointer Cancellation](https://www.w3.org/WAI/WCAG22/Understanding/pointer-cancellation.html) (A) | Open Components, beyond WCAG 2.5.2 (A) | +| [`button/dom-order`](/docs/components/button/ux#ux-checklist) | Must | Buttons come in the same order in the DOM as on screen, without `order` or `row-reverse` | [1.3.2 Meaningful Sequence](https://www.w3.org/WAI/WCAG22/Understanding/meaningful-sequence.html) (A), [2.4.3 Focus Order](https://www.w3.org/WAI/WCAG22/Understanding/focus-order.html) (A) | Open Components, beyond WCAG 1.3.2, 2.4.3 (A) | +| [`button/disabled-inert`](/docs/components/button/ux#ux-checklist) | Must | A disabled or loading button does nothing, so there's no event, no submission and no navigation | None | HTML, WAI-ARIA | +| [`button/loading`](/docs/components/button/ux#ux-checklist) | Must | Loading keeps the button's size and name, blocks repeated activation and is announced | [4.1.3 Status Messages](https://www.w3.org/WAI/WCAG22/Understanding/status-messages.html) (AA) | WCAG 4.1.3 (AA), Open Components | +| [`button/announce-outcome`](/docs/components/button/ux#ux-checklist) | Should | The page announces the action's outcome with a status message | [4.1.3 Status Messages](https://www.w3.org/WAI/WCAG22/Understanding/status-messages.html) (AA) | Open Components, beyond WCAG 4.1.3 (AA) | +| [`button/toggle-pressed`](/docs/components/button/ux#ux-checklist) | Must | A toggle button sets `aria-pressed` and keeps its label | [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) (A) | WCAG 4.1.2 (A), APG | +| [`button/popup-expanded`](/docs/components/button/ux#ux-checklist) | Must | A button that opens a popup sets `aria-haspopup` and `aria-expanded` | [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) (A) | WCAG 4.1.2 (A), APG | +| [`button/focus-after`](/docs/components/button/ux#ux-checklist) | Should | After activation, focus moves as the APG describes, and never falls back to the top of the page | None | APG | +| [`button/focus-not-obscured`](/docs/components/button/ux#ux-checklist) | Must | Sticky headers and footers never cover a focused button, for example thanks to `scroll-padding` | [2.4.11 Focus Not Obscured (Minimum)](https://www.w3.org/WAI/WCAG22/Understanding/focus-not-obscured-minimum.html) (AA), [2.4.12 Focus Not Obscured (Enhanced)](https://www.w3.org/WAI/WCAG22/Understanding/focus-not-obscured-enhanced.html) (AAA) | WCAG 2.4.11 (AA), 2.4.12 (AAA) | +| [`button/destructive`](/docs/components/button/ux#ux-checklist) | Should | A destructive action uses `error`, names what it destroys, and can either be undone or asks for confirmation | [3.3.4 Error Prevention (Legal, Financial, Data)](https://www.w3.org/WAI/WCAG22/Understanding/error-prevention-legal-financial-data.html) (AA) | Open Components, beyond WCAG 3.3.4 (AA) | + +## AX rules + +| Rule | Level | Requirement | WCAG 2.2 | Basis | +| ---- | ----- | ----------- | -------- | ----- | +| [`button/role-and-name`](/docs/components/button/ax#ax-checklist) | Must | It can be found by its role and name alone, with `getByRole("button", { name })` | [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) (A) | WCAG 4.1.2 (A) | + +## Sources + +- [Web Content Accessibility Guidelines (WCAG) 2.2](https://www.w3.org/TR/WCAG22/), for each success criterion's number, short name and level +- [Understanding WCAG 2.2](https://www.w3.org/WAI/WCAG22/Understanding/), which each criterion links to +- [Accessible Rich Internet Applications (WAI-ARIA) 1.2](https://www.w3.org/TR/wai-aria-1.2/) +- [WAI-ARIA Authoring Practices Guide (APG)](https://www.w3.org/WAI/ARIA/apg/) +- [Button](/docs/components/button), where each rule is explained, with the sources it draws on diff --git a/content/docs/4.accessibility/card-checklist.md b/content/docs/4.accessibility/card-checklist.md new file mode 100644 index 0000000..f77bd0b --- /dev/null +++ b/content/docs/4.accessibility/card-checklist.md @@ -0,0 +1,49 @@ +--- +title: Accessible Card Checklist (WCAG) +description: Every Card rule that WCAG 2.2, WAI-ARIA or the APG backs, in one checklist, with the success criteria behind each rule and their level. +navigation: + title: Card +--- + +Here's every rule for the [Card](/docs/components/card) that WCAG 2.2, WAI-ARIA or the APG backs, in one list you can work through when you build or review one. Each row names the WCAG 2.2 success criteria behind its rule, with their level, and links to the rule's table on its layer's page, where we explain why it's there. A rule that rests on WAI-ARIA or the APG alone says "None". + +We build this list from the Card's checklists, so it always matches them. It leaves out the rules that rest only on HTML and the ones that are our own, so you'll find every rule in the [Card's checklist](/docs/components/card#checklist). + +## UI rules + +| Rule | Level | Requirement | WCAG 2.2 | Basis | +| ---- | ----- | ----------- | -------- | ----- | +| [`card/contrast`](/docs/components/card/ui#ui-checklist) | Must | The text, the eyebrow and the footer included, has a contrast of 4.5:1 against the card, and the focus ring has 3:1 against the page | [1.4.3 Contrast (Minimum)](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html) (AA), [1.4.11 Non-text Contrast](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast.html) (AA) | WCAG 1.4.3, 1.4.11 (AA) | +| [`card/focus-visible`](/docs/components/card/ui#ui-checklist) | Must | When its link has keyboard focus, an `outline` at least 2px thick shows around the whole card, outside its border | [2.4.7 Focus Visible](https://www.w3.org/WAI/WCAG22/Understanding/focus-visible.html) (AA), [2.4.13 Focus Appearance](https://www.w3.org/WAI/WCAG22/Understanding/focus-appearance.html) (AAA) | WCAG 2.4.7 (AA), 2.4.13 (AAA) | +| [`card/resizable`](/docs/components/card/ui#ui-checklist) | Must | Nothing in the card has a fixed height, so it grows with its text, and long words wrap instead of overflowing it | [1.4.4 Resize Text](https://www.w3.org/WAI/WCAG22/Understanding/resize-text.html) (AA), [1.4.12 Text Spacing](https://www.w3.org/WAI/WCAG22/Understanding/text-spacing.html) (AA) | Open Components, beyond WCAG 1.4.4, 1.4.12 (AA) | +| [`card/reduced-motion`](/docs/components/card/ui#ui-checklist) | Must | Nothing moves on hover or focus when `prefers-reduced-motion: reduce` is set | [2.3.3 Animation from Interactions](https://www.w3.org/WAI/WCAG22/Understanding/animation-from-interactions.html) (AAA) | WCAG 2.3.3 (AAA) | +| [`card/reflow`](/docs/components/card/ui#ui-checklist) | Must | Cards in a grid get narrower rather than overflow, so the page never scrolls sideways at 320px wide | [1.4.10 Reflow](https://www.w3.org/WAI/WCAG22/Understanding/reflow.html) (AA) | WCAG 1.4.10 (AA) | + +## UX rules + +| Rule | Level | Requirement | WCAG 2.2 | Basis | +| ---- | ----- | ----------- | -------- | ----- | +| [`card/semantic-element`](/docs/components/card/ux#ux-checklist) | Must | It's an `<article>` by default, or a `<section>`, `<div>` or `<li>` with `as`, and never a link or a button | [1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) (A) | Open Components, beyond WCAG 1.3.1 (A) | +| [`card/list-of-cards`](/docs/components/card/ux#ux-checklist) | Should | A set of cards is a list, with each card an `<li>` | [1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) (A) | WCAG 1.3.1 (A) | +| [`card/heading`](/docs/components/card/ux#ux-checklist) | Must | Every card has a heading that says what it's about, at the level that fits the page's outline | [1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) (A), [2.4.6 Headings and Labels](https://www.w3.org/WAI/WCAG22/Understanding/headings-and-labels.html) (AA) | WCAG 1.3.1 (A), 2.4.6 (AA) | +| [`card/stretched-link`](/docs/components/card/ux#ux-checklist) | Must | A card that's a link has one link, in its heading, stretched over the card with a pseudo-element, and never a wrapping `<a>`, `role="link"` or a click handler on the card | [2.1.1 Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html) (A), [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) (A) | Open Components, beyond WCAG 2.1.1, 4.1.2 (A) | +| [`card/link-name`](/docs/components/card/ux#ux-checklist) | Must | The link is named by the heading alone | [2.4.4 Link Purpose (In Context)](https://www.w3.org/WAI/WCAG22/Understanding/link-purpose-in-context.html) (A) | WCAG 2.4.4 (A) | +| [`card/link-purpose`](/docs/components/card/ux#ux-checklist) | Should | Headings say where the link goes, differ from card to card, and there's no separate "Read more" link | [2.4.4 Link Purpose (In Context)](https://www.w3.org/WAI/WCAG22/Understanding/link-purpose-in-context.html) (A), [2.4.9 Link Purpose (Link Only)](https://www.w3.org/WAI/WCAG22/Understanding/link-purpose-link-only.html) (AAA) | WCAG 2.4.4 (A), 2.4.9 (AAA) | +| [`card/keyboard`](/docs/components/card/ux#ux-checklist) | Must | `Tab` reaches the card's link once and then its actions, and `Enter` follows the link | [2.1.1 Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html) (A), [2.4.3 Focus Order](https://www.w3.org/WAI/WCAG22/Understanding/focus-order.html) (A) | WCAG 2.1.1, 2.4.3 (A) | +| [`card/media-alt`](/docs/components/card/ux#ux-checklist) | Must | An image that only illustrates the heading has `alt=""`, and one that shows more has alt text that says what | [1.1.1 Non-text Content](https://www.w3.org/WAI/WCAG22/Understanding/non-text-content.html) (A) | WCAG 1.1.1 (A) | +| [`card/static-media`](/docs/components/card/ux#ux-checklist) | Must | The media holds nothing people can focus, since it's shown above the heading but comes after it in the DOM | [1.3.2 Meaningful Sequence](https://www.w3.org/WAI/WCAG22/Understanding/meaningful-sequence.html) (A), [2.4.3 Focus Order](https://www.w3.org/WAI/WCAG22/Understanding/focus-order.html) (A) | WCAG 1.3.2, 2.4.3 (A) | +| [`card/dom-order`](/docs/components/card/ux#ux-checklist) | Must | Cards come in the same order in the DOM as on screen, without `order`, `row-reverse` or a `dense` grid | [1.3.2 Meaningful Sequence](https://www.w3.org/WAI/WCAG22/Understanding/meaningful-sequence.html) (A), [2.4.3 Focus Order](https://www.w3.org/WAI/WCAG22/Understanding/focus-order.html) (A) | Open Components, beyond WCAG 1.3.2, 2.4.3 (A) | +| [`card/focus-not-obscured`](/docs/components/card/ux#ux-checklist) | Must | Sticky headers and footers never cover a focused card, for example thanks to `scroll-padding` | [2.4.11 Focus Not Obscured (Minimum)](https://www.w3.org/WAI/WCAG22/Understanding/focus-not-obscured-minimum.html) (AA), [2.4.12 Focus Not Obscured (Enhanced)](https://www.w3.org/WAI/WCAG22/Understanding/focus-not-obscured-enhanced.html) (AAA) | WCAG 2.4.11 (AA), 2.4.12 (AAA) | +| [`card/announce-results`](/docs/components/card/ux#ux-checklist) | Should | Cards that load after something people did, like a search, are announced with a status message | [4.1.3 Status Messages](https://www.w3.org/WAI/WCAG22/Understanding/status-messages.html) (AA) | WCAG 4.1.3 (AA) | + +## AX rules + +| Rule | Level | Requirement | WCAG 2.2 | Basis | +| ---- | ----- | ----------- | -------- | ----- | +| [`card/role-and-name`](/docs/components/card/ax#ax-checklist) | Must | It can be found by its heading, with `getByRole("heading", { name })`, and a card that's a link by `getByRole("link", { name })` | [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) (A) | WCAG 4.1.2 (A) | + +## Sources + +- [Web Content Accessibility Guidelines (WCAG) 2.2](https://www.w3.org/TR/WCAG22/), for each success criterion's number, short name and level +- [Understanding WCAG 2.2](https://www.w3.org/WAI/WCAG22/Understanding/), which each criterion links to +- [Card](/docs/components/card), where each rule is explained, with the sources it draws on diff --git a/content/docs/4.accessibility/checkbox-checklist.md b/content/docs/4.accessibility/checkbox-checklist.md new file mode 100644 index 0000000..01d8955 --- /dev/null +++ b/content/docs/4.accessibility/checkbox-checklist.md @@ -0,0 +1,53 @@ +--- +title: Accessible Checkbox Checklist (WCAG) +description: Every Checkbox rule that WCAG 2.2, WAI-ARIA or the APG backs, in one checklist, with the success criteria behind each rule and their level. +navigation: + title: Checkbox +--- + +Here's every rule for the [Checkbox](/docs/components/checkbox) that WCAG 2.2, WAI-ARIA or the APG backs, in one list you can work through when you build or review one. Each row names the WCAG 2.2 success criteria behind its rule, with their level, and links to the rule's table on its layer's page, where we explain why it's there. A rule that rests on WAI-ARIA or the APG alone says "None". + +We build this list from the Checkbox's checklists, so it always matches them. It leaves out the rules that rest only on HTML and the ones that are our own, so you'll find every rule in the [Checkbox's checklist](/docs/components/checkbox#checklist). + +## UI rules + +| Rule | Level | Requirement | WCAG 2.2 | Basis | +| ---- | ----- | ----------- | -------- | ----- | +| [`checkbox/contrast`](/docs/components/checkbox/ui#ui-checklist) | Must | The label has a contrast of 4.5:1, and the focus ring has 3:1 against the page | [1.4.3 Contrast (Minimum)](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html) (AA), [1.4.11 Non-text Contrast](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast.html) (AA) | WCAG 1.4.3, 1.4.11 (AA) | +| [`checkbox/boundary-contrast`](/docs/components/checkbox/ui#ui-checklist) | Must | The box's border and a checked box's fill have 3:1 against the page, and the check and the dash have 3:1 against the fill | [1.4.11 Non-text Contrast](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast.html) (AA) | WCAG 1.4.11 (AA) | +| [`checkbox/focus-visible`](/docs/components/checkbox/ui#ui-checklist) | Must | Keyboard focus shows an `outline` at least 2px thick around the box, outside its border, on `:focus-visible` | [2.4.7 Focus Visible](https://www.w3.org/WAI/WCAG22/Understanding/focus-visible.html) (AA), [2.4.13 Focus Appearance](https://www.w3.org/WAI/WCAG22/Understanding/focus-appearance.html) (AAA) | WCAG 2.4.7 (AA), 2.4.13 (AAA) | +| [`checkbox/target-size`](/docs/components/checkbox/ui#ui-checklist) | Must | The box has a hit area of at least 24 × 24px that toggles it, without counting its label | [2.5.8 Target Size (Minimum)](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html) (AA) | Open Components, beyond WCAG 2.5.8 (AA) | +| [`checkbox/distinct-marks`](/docs/components/checkbox/ui#ui-checklist) | Must | Checked shows a check and indeterminate a dash, so the two never rely on colour to tell them apart | [1.4.1 Use of Color](https://www.w3.org/WAI/WCAG22/Understanding/use-of-color.html) (A) | WCAG 1.4.1 (A) | +| [`checkbox/resizable`](/docs/components/checkbox/ui#ui-checklist) | Must | The box, its gap and its hit area are sized in `rem`, and the label wraps beside the box instead of being clipped | [1.4.4 Resize Text](https://www.w3.org/WAI/WCAG22/Understanding/resize-text.html) (AA), [1.4.12 Text Spacing](https://www.w3.org/WAI/WCAG22/Understanding/text-spacing.html) (AA) | Open Components, beyond WCAG 1.4.4, 1.4.12 (AA) | + +## UX rules + +| Rule | Level | Requirement | WCAG 2.2 | Basis | +| ---- | ----- | ----------- | -------- | ----- | +| [`checkbox/native-element`](/docs/components/checkbox/ux#ux-checklist) | Must | It's a native `<input type="checkbox">`, never an element with `role="checkbox"` | [2.1.1 Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html) (A), [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) (A) | Open Components, beyond WCAG 2.1.1, 4.1.2 (A) | +| [`checkbox/label-toggles`](/docs/components/checkbox/ux#ux-checklist) | Must | Its `<label>` wraps the box and its text, so the text names it and a press on the text toggles it, unless it's read-only | [1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) (A), [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) (A) | WCAG 1.3.1, 4.1.2 (A), HTML | +| [`checkbox/visible-label`](/docs/components/checkbox/ux#ux-checklist) | Must | Every checkbox has visible text, unless its context names it, like a row in a table, in which case it has an `aria-label` | [1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) (A), [3.3.2 Labels or Instructions](https://www.w3.org/WAI/WCAG22/Understanding/labels-or-instructions.html) (A), [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) (A) | WCAG 1.3.1, 3.3.2, 4.1.2 (A) | +| [`checkbox/label-in-name`](/docs/components/checkbox/ux#ux-checklist) | Must | An `aria-label` or `aria-labelledby` includes the visible text, ideally at the start | [2.5.3 Label in Name](https://www.w3.org/WAI/WCAG22/Understanding/label-in-name.html) (A) | WCAG 2.5.3 (A) | +| [`checkbox/described`](/docs/components/checkbox/ux#ux-checklist) | Should | Hints sit outside the label and are linked with `aria-describedby` | [1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) (A) | WCAG 1.3.1 (A) | +| [`checkbox/decorative-indicator`](/docs/components/checkbox/ux#ux-checklist) | Must | The check and the dash are hidden from assistive technologies with `aria-hidden`, so the name is the label alone | [1.1.1 Non-text Content](https://www.w3.org/WAI/WCAG22/Understanding/non-text-content.html) (A), [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) (A) | WCAG 1.1.1, 4.1.2 (A) | +| [`checkbox/keyboard`](/docs/components/checkbox/ux#ux-checklist) | Must | `Tab` reaches the box, `Space` checks or unchecks it unless it's read-only, and `Enter` never toggles it | [2.1.1 Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html) (A) | WCAG 2.1.1 (A), APG | +| [`checkbox/indeterminate`](/docs/components/checkbox/ux#ux-checklist) | Must | The mixed state is set as the `<input>`'s `indeterminate` property, so it's announced as mixed, and it clears on the first click | [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) (A) | WCAG 4.1.2 (A), HTML | +| [`checkbox/required`](/docs/components/checkbox/ux#ux-checklist) | Should | A box people have to check has `required`, which lands on the `<input>`, while optional boxes don't | [3.3.2 Labels or Instructions](https://www.w3.org/WAI/WCAG22/Understanding/labels-or-instructions.html) (A) | HTML, WCAG 3.3.2 (A) | +| [`checkbox/error-message`](/docs/components/checkbox/ux#ux-checklist) | Must | An invalid checkbox has an error message, in text and linked with `aria-describedby`, that says why it needs checking | [1.4.1 Use of Color](https://www.w3.org/WAI/WCAG22/Understanding/use-of-color.html) (A), [3.3.1 Error Identification](https://www.w3.org/WAI/WCAG22/Understanding/error-identification.html) (A), [3.3.3 Error Suggestion](https://www.w3.org/WAI/WCAG22/Understanding/error-suggestion.html) (AA) | WCAG 1.4.1, 3.3.1 (A), 3.3.3 (AA) | +| [`checkbox/invalid-state`](/docs/components/checkbox/ux#ux-checklist) | Must | A checkbox sets `aria-invalid="true"` while its error message shows, and only looks invalid when it does | [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) (A) | WCAG 4.1.2 (A), Open Components | +| [`checkbox/read-only`](/docs/components/checkbox/ux#ux-checklist) | Must | A read-only checkbox sets `aria-readonly="true"`, stays focusable and is sent with its form, while a click, its label or `Space` never change it | None | WAI-ARIA, Open Components | +| [`checkbox/focus-not-obscured`](/docs/components/checkbox/ux#ux-checklist) | Must | Sticky headers and footers never cover a focused checkbox, for example thanks to `scroll-padding` | [2.4.11 Focus Not Obscured (Minimum)](https://www.w3.org/WAI/WCAG22/Understanding/focus-not-obscured-minimum.html) (AA), [2.4.12 Focus Not Obscured (Enhanced)](https://www.w3.org/WAI/WCAG22/Understanding/focus-not-obscured-enhanced.html) (AAA) | WCAG 2.4.11 (AA), 2.4.12 (AAA) | + +## AX rules + +| Rule | Level | Requirement | WCAG 2.2 | Basis | +| ---- | ----- | ----------- | -------- | ----- | +| [`checkbox/role-and-name`](/docs/components/checkbox/ax#ax-checklist) | Must | It can be found by its role and label alone, with `getByRole("checkbox", { name })`, and reports checked, unchecked or mixed | [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) (A) | WCAG 4.1.2 (A) | + +## Sources + +- [Web Content Accessibility Guidelines (WCAG) 2.2](https://www.w3.org/TR/WCAG22/), for each success criterion's number, short name and level +- [Understanding WCAG 2.2](https://www.w3.org/WAI/WCAG22/Understanding/), which each criterion links to +- [Accessible Rich Internet Applications (WAI-ARIA) 1.2](https://www.w3.org/TR/wai-aria-1.2/) +- [WAI-ARIA Authoring Practices Guide (APG)](https://www.w3.org/WAI/ARIA/apg/) +- [Checkbox](/docs/components/checkbox), where each rule is explained, with the sources it draws on diff --git a/content/docs/4.accessibility/checkbox-group-checklist.md b/content/docs/4.accessibility/checkbox-group-checklist.md new file mode 100644 index 0000000..2516650 --- /dev/null +++ b/content/docs/4.accessibility/checkbox-group-checklist.md @@ -0,0 +1,45 @@ +--- +title: Accessible Checkbox Group Checklist (WCAG) +description: Every Checkbox Group rule that WCAG 2.2, WAI-ARIA or the APG backs, in one checklist, with the success criteria behind each rule and their level. +navigation: + title: Checkbox Group +--- + +Here's every rule for the [Checkbox Group](/docs/components/checkbox-group) that WCAG 2.2, WAI-ARIA or the APG backs, in one list you can work through when you build or review one. Each row names the WCAG 2.2 success criteria behind its rule, with their level, and links to the rule's table on its layer's page, where we explain why it's there. A rule that rests on WAI-ARIA or the APG alone says "None". + +We build this list from the Checkbox Group's checklists, so it always matches them. It leaves out the rules that rest only on HTML and the ones that are our own, so you'll find every rule in the [Checkbox Group's checklist](/docs/components/checkbox-group#checklist). + +## UI rules + +| Rule | Level | Requirement | WCAG 2.2 | Basis | +| ---- | ----- | ----------- | -------- | ----- | +| [`checkbox-group/legend-contrast`](/docs/components/checkbox-group/ui#ui-checklist) | Must | The legend has a contrast of 4.5:1 against the page | [1.4.3 Contrast (Minimum)](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html) (AA) | WCAG 1.4.3 (AA) | +| [`checkbox-group/resizable`](/docs/components/checkbox-group/ui#ui-checklist) | Must | The legend, the gaps and the indent are sized in `rem`, and the legend and a row of options wrap instead of being clipped or scrolling sideways | [1.4.4 Resize Text](https://www.w3.org/WAI/WCAG22/Understanding/resize-text.html) (AA), [1.4.10 Reflow](https://www.w3.org/WAI/WCAG22/Understanding/reflow.html) (AA), [1.4.12 Text Spacing](https://www.w3.org/WAI/WCAG22/Understanding/text-spacing.html) (AA) | Open Components, beyond WCAG 1.4.4, 1.4.10, 1.4.12 (AA) | + +## UX rules + +| Rule | Level | Requirement | WCAG 2.2 | Basis | +| ---- | ----- | ----------- | -------- | ----- | +| [`checkbox-group/fieldset`](/docs/components/checkbox-group/ux#ux-checklist) | Must | It's a `<fieldset>` whose first child is the `<legend>` that names it, so it has the `group` role and the legend as its name | [1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) (A), [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) (A) | WCAG 1.3.1, 4.1.2 (A), HTML | +| [`checkbox-group/legend-question`](/docs/components/checkbox-group/ux#ux-checklist) | Must | Every group has a visible legend that says what its options are for, ideally as the question they answer | [1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) (A), [3.3.2 Labels or Instructions](https://www.w3.org/WAI/WCAG22/Understanding/labels-or-instructions.html) (A) | WCAG 1.3.1, 3.3.2 (A) | +| [`checkbox-group/described`](/docs/components/checkbox-group/ux#ux-checklist) | Should | A hint and an error message sit outside the legend and are linked to the `<fieldset>` with `aria-describedby`, the hint's ID first | [1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) (A) | WCAG 1.3.1 (A), APG | +| [`checkbox-group/keyboard`](/docs/components/checkbox-group/ux#ux-checklist) | Must | `Tab` reaches each box in turn, select-all box included, `Space` toggles the focused one, and the arrow keys never move focus between them | [2.1.1 Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html) (A) | WCAG 2.1.1 (A), APG | +| [`checkbox-group/select-all-state`](/docs/components/checkbox-group/ux#ux-checklist) | Must | The select-all box is checked when every option is, unchecked when none is, and mixed when only some are, worked out from them whenever they change | [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) (A) | WCAG 4.1.2 (A), APG | +| [`checkbox-group/select-all-action`](/docs/components/checkbox-group/ux#ux-checklist) | Must | Checking the select-all box, from unchecked or mixed, checks every option, and unchecking it clears them all, without going back to an earlier selection | None | APG, Open Components | +| [`checkbox-group/at-least-one`](/docs/components/checkbox-group/ux#ux-checklist) | Must | A group people have to pick from says so in its legend or hint, and is checked in code when the form is sent, never with `required` on its boxes | [3.3.2 Labels or Instructions](https://www.w3.org/WAI/WCAG22/Understanding/labels-or-instructions.html) (A) | HTML, WCAG 3.3.2 (A) | +| [`checkbox-group/error-message`](/docs/components/checkbox-group/ux#ux-checklist) | Must | An invalid group has an error message, in text and linked to the `<fieldset>` with `aria-describedby`, that says what to pick | [1.4.1 Use of Color](https://www.w3.org/WAI/WCAG22/Understanding/use-of-color.html) (A), [3.3.1 Error Identification](https://www.w3.org/WAI/WCAG22/Understanding/error-identification.html) (A), [3.3.3 Error Suggestion](https://www.w3.org/WAI/WCAG22/Understanding/error-suggestion.html) (AA) | WCAG 1.4.1, 3.3.1 (A), 3.3.3 (AA) | +| [`checkbox-group/invalid-state`](/docs/components/checkbox-group/ux#ux-checklist) | Must | The group sets `aria-invalid="true"` while its error message shows, and each of its options looks and reads invalid with it | [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) (A) | WCAG 4.1.2 (A), Open Components | +| [`checkbox-group/focus-on-error`](/docs/components/checkbox-group/ux#ux-checklist) | Should | A failed submit moves focus to the group's first box, once the error is in the page | [3.3.1 Error Identification](https://www.w3.org/WAI/WCAG22/Understanding/error-identification.html) (A) | Open Components, beyond WCAG 3.3.1 (A) | + +## AX rules + +| Rule | Level | Requirement | WCAG 2.2 | Basis | +| ---- | ----- | ----------- | -------- | ----- | +| [`checkbox-group/role-and-name`](/docs/components/checkbox-group/ax#ax-checklist) | Must | It can be found by its legend alone, with `getByRole("group", { name })`, and each option inside it with `getByRole("checkbox", { name })` | [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) (A) | WCAG 4.1.2 (A) | + +## Sources + +- [Web Content Accessibility Guidelines (WCAG) 2.2](https://www.w3.org/TR/WCAG22/), for each success criterion's number, short name and level +- [Understanding WCAG 2.2](https://www.w3.org/WAI/WCAG22/Understanding/), which each criterion links to +- [WAI-ARIA Authoring Practices Guide (APG)](https://www.w3.org/WAI/ARIA/apg/) +- [Checkbox Group](/docs/components/checkbox-group), where each rule is explained, with the sources it draws on diff --git a/content/docs/4.accessibility/combobox-checklist.md b/content/docs/4.accessibility/combobox-checklist.md new file mode 100644 index 0000000..e7e21f7 --- /dev/null +++ b/content/docs/4.accessibility/combobox-checklist.md @@ -0,0 +1,56 @@ +--- +title: Accessible Combobox Checklist (WCAG) +description: Every Combobox rule that WCAG 2.2, WAI-ARIA or the APG backs, in one checklist, with the success criteria behind each rule and their level. +navigation: + title: Combobox +--- + +Here's every rule for the [Combobox](/docs/components/combobox) that WCAG 2.2, WAI-ARIA or the APG backs, in one list you can work through when you build or review one. Each row names the WCAG 2.2 success criteria behind its rule, with their level, and links to the rule's table on its layer's page, where we explain why it's there. A rule that rests on WAI-ARIA or the APG alone says "None". + +We build this list from the Combobox's checklists, so it always matches them. It leaves out the rules that rest only on HTML and the ones that are our own, so you'll find every rule in the [Combobox's checklist](/docs/components/combobox#checklist). + +## UI rules + +| Rule | Level | Requirement | WCAG 2.2 | Basis | +| ---- | ----- | ----------- | -------- | ----- | +| [`combobox/visible-focus`](/docs/components/combobox/ui#ui-checklist) | Must | The field shows a focus ring while its text has focus, and the highlighted option an outline at least 2px thick | [2.4.7 Focus Visible](https://www.w3.org/WAI/WCAG22/Understanding/focus-visible.html) (AA) | WCAG 2.4.7 (AA) | +| [`combobox/selected-not-colour`](/docs/components/combobox/ui#ui-checklist) | Must | A picked option shows a check mark as well as its weight, and its tag, with `multiple` | [1.4.1 Use of Color](https://www.w3.org/WAI/WCAG22/Understanding/use-of-color.html) (A) | WCAG 1.4.1 (A) | +| [`combobox/contrast`](/docs/components/combobox/ui#ui-checklist) | Must | The text, the placeholder and "No results" have 4.5:1, and the border, the chevron and the focus ring 3:1, in light and dark mode | [1.4.3 Contrast (Minimum)](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html) (AA), [1.4.11 Non-text Contrast](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast.html) (AA) | WCAG 1.4.3, 1.4.11 (AA) | +| [`combobox/target-size`](/docs/components/combobox/ui#ui-checklist) | Must | The toggle and each remove button are at least 24 × 24px to press, and 44px tall where a pointer is coarse, like the options | [2.5.8 Target Size (Minimum)](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html) (AA) | Open Components, beyond WCAG 2.5.8 (AA) | +| [`combobox/reflow`](/docs/components/combobox/ui#ui-checklist) | Must | The field and the panel fit a 320px-wide screen without scrolling sideways, and long labels wrap | [1.4.10 Reflow](https://www.w3.org/WAI/WCAG22/Understanding/reflow.html) (AA) | WCAG 1.4.10 (AA) | +| [`combobox/reduced-motion`](/docs/components/combobox/ui#ui-checklist) | Should | The chevron and the panel don't animate when people ask for less motion | [2.3.3 Animation from Interactions](https://www.w3.org/WAI/WCAG22/Understanding/animation-from-interactions.html) (AAA) | WCAG 2.3.3 (AAA) | + +## UX rules + +| Rule | Level | Requirement | WCAG 2.2 | Basis | +| ---- | ----- | ----------- | -------- | ----- | +| [`combobox/editable-pattern`](/docs/components/combobox/ux#ux-checklist) | Must | The text field has the `combobox` role, `aria-autocomplete="list"`, `aria-expanded` and `aria-controls`, which points at a `listbox` | None | APG | +| [`combobox/focus-in-text`](/docs/components/combobox/ux#ux-checklist) | Must | Focus stays in the text field, and `aria-activedescendant` points at the highlighted option while the panel is open | None | APG | +| [`combobox/name`](/docs/components/combobox/ux#ux-checklist) | Must | It has a visible label, from a Field or a `<label for>` | [1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) (A), [3.3.2 Labels or Instructions](https://www.w3.org/WAI/WCAG22/Understanding/labels-or-instructions.html) (A) | WCAG 1.3.1, 3.3.2 (A) | +| [`combobox/keyboard`](/docs/components/combobox/ux#ux-checklist) | Must | Every key in the contract does what it says, and nothing needs a pointer | [2.1.1 Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html) (A) | WCAG 2.1.1 (A) | +| [`combobox/typing-edits`](/docs/components/combobox/ux#ux-checklist) | Must | Letters, `Space`, `Home`, `End` and the side arrows edit the text, and never move the highlight | None | APG | +| [`combobox/escape`](/docs/components/combobox/ux#ux-checklist) | Must | `Escape` closes the panel, then clears the text, and goes no further, so a Dialog around it stays open | None | APG | +| [`combobox/no-results`](/docs/components/combobox/ux#ux-checklist) | Must | With no match, the panel says so, in text that isn't an option, and screen readers hear it | [4.1.3 Status Messages](https://www.w3.org/WAI/WCAG22/Understanding/status-messages.html) (AA) | WCAG 4.1.3 (AA) | +| [`combobox/result-count`](/docs/components/combobox/ux#ux-checklist) | Should | The number of matches is announced once typing pauses, never on every key | [4.1.3 Status Messages](https://www.w3.org/WAI/WCAG22/Understanding/status-messages.html) (AA) | WCAG 4.1.3 (AA) | +| [`combobox/removable-tags`](/docs/components/combobox/ux#ux-checklist) | Must | With `multiple`, each tag has a named button that removes it, focus moves on to the next one, and `Backspace` in empty text removes the last | [2.1.1 Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html) (A), [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) (A) | WCAG 2.1.1, 4.1.2 (A) | +| [`combobox/announce-removal`](/docs/components/combobox/ux#ux-checklist) | Should | Removing a value is announced | [4.1.3 Status Messages](https://www.w3.org/WAI/WCAG22/Understanding/status-messages.html) (AA) | WCAG 4.1.3 (AA) | +| [`combobox/autocomplete`](/docs/components/combobox/ux#ux-checklist) | Should | `autocomplete` names the field's purpose where it asks people about themselves, and stays `off` elsewhere | [1.3.5 Identify Input Purpose](https://www.w3.org/WAI/WCAG22/Understanding/identify-input-purpose.html) (AA) | WCAG 1.3.5 (AA) | + +## DX rules + +| Rule | Level | Requirement | WCAG 2.2 | Basis | +| ---- | ----- | ----------- | -------- | ----- | +| [`combobox/in-a-field`](/docs/components/combobox/dx#dx-checklist) | Must | In a Field, it takes the label, description, invalid and disabled state | [1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) (A) | WCAG 1.3.1 (A) | + +## AX rules + +| Rule | Level | Requirement | WCAG 2.2 | Basis | +| ---- | ----- | ----------- | -------- | ----- | +| [`combobox/role-and-name`](/docs/components/combobox/ax#ax-checklist) | Must | It can be found with `getByRole("combobox", { name })`, and its options with `getByRole("option", { name })` | [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) (A) | WCAG 4.1.2 (A) | + +## Sources + +- [Web Content Accessibility Guidelines (WCAG) 2.2](https://www.w3.org/TR/WCAG22/), for each success criterion's number, short name and level +- [Understanding WCAG 2.2](https://www.w3.org/WAI/WCAG22/Understanding/), which each criterion links to +- [WAI-ARIA Authoring Practices Guide (APG)](https://www.w3.org/WAI/ARIA/apg/) +- [Combobox](/docs/components/combobox), where each rule is explained, with the sources it draws on diff --git a/content/docs/4.accessibility/dialog-checklist.md b/content/docs/4.accessibility/dialog-checklist.md new file mode 100644 index 0000000..2cf4496 --- /dev/null +++ b/content/docs/4.accessibility/dialog-checklist.md @@ -0,0 +1,47 @@ +--- +title: Accessible Dialog Checklist (WCAG) +description: Every Dialog rule that WCAG 2.2, WAI-ARIA or the APG backs, in one checklist, with the success criteria behind each rule and their level. +navigation: + title: Dialog +--- + +Here's every rule for the [Dialog](/docs/components/dialog) that WCAG 2.2, WAI-ARIA or the APG backs, in one list you can work through when you build or review one. Each row names the WCAG 2.2 success criteria behind its rule, with their level, and links to the rule's table on its layer's page, where we explain why it's there. A rule that rests on WAI-ARIA or the APG alone says "None". + +We build this list from the Dialog's checklists, so it always matches them. It leaves out the rules that rest only on HTML and the ones that are our own, so you'll find every rule in the [Dialog's checklist](/docs/components/dialog#checklist). + +## UI rules + +| Rule | Level | Requirement | WCAG 2.2 | Basis | +| ---- | ----- | ----------- | -------- | ----- | +| [`dialog/contrast`](/docs/components/dialog/ui#ui-checklist) | Must | The title, the description and the content have a contrast of 4.5:1 against the panel | [1.4.3 Contrast (Minimum)](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html) (AA) | WCAG 1.4.3 (AA) | +| [`dialog/fits-screen`](/docs/components/dialog/ui#ui-checklist) | Must | It's never wider or taller than the screen, less a margin, down to 320px wide | [1.4.10 Reflow](https://www.w3.org/WAI/WCAG22/Understanding/reflow.html) (AA) | WCAG 1.4.10 (AA) | +| [`dialog/resizable`](/docs/components/dialog/ui#ui-checklist) | Must | It's sized in `rem`, so it grows with its text, and its title wraps rather than getting cut off | [1.4.4 Resize Text](https://www.w3.org/WAI/WCAG22/Understanding/resize-text.html) (AA), [1.4.12 Text Spacing](https://www.w3.org/WAI/WCAG22/Understanding/text-spacing.html) (AA) | Open Components, beyond WCAG 1.4.4, 1.4.12 (AA) | +| [`dialog/reduced-motion`](/docs/components/dialog/ui#ui-checklist) | Should | It only animates as it opens when `prefers-reduced-motion` is `no-preference` | [2.3.3 Animation from Interactions](https://www.w3.org/WAI/WCAG22/Understanding/animation-from-interactions.html) (AAA) | WCAG 2.3.3 (AAA) | + +## UX rules + +| Rule | Level | Requirement | WCAG 2.2 | Basis | +| ---- | ----- | ----------- | -------- | ----- | +| [`dialog/native-element`](/docs/components/dialog/ux#ux-checklist) | Must | It's a native `<dialog>`, opened with `showModal()`, and never a `<div>` with `role="dialog"` | [2.1.2 No Keyboard Trap](https://www.w3.org/WAI/WCAG22/Understanding/no-keyboard-trap.html) (A), [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) (A) | Open Components, beyond WCAG 2.1.2, 4.1.2 (A) | +| [`dialog/modal`](/docs/components/dialog/ux#ux-checklist) | Must | While it's open, it's in the top layer and the rest of the page is inert, so nothing behind it can be focused, clicked or read | None | APG | +| [`dialog/contain-focus`](/docs/components/dialog/ux#ux-checklist) | Must | `Tab` and `Shift+Tab` never move focus to the page behind an open dialog | [2.4.3 Focus Order](https://www.w3.org/WAI/WCAG22/Understanding/focus-order.html) (A) | WCAG 2.4.3 (A), APG | +| [`dialog/named`](/docs/components/dialog/ux#ux-checklist) | Must | It's named by its title, with `aria-labelledby` | [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) (A) | WCAG 4.1.2 (A) | +| [`dialog/visible-title`](/docs/components/dialog/ux#ux-checklist) | Must | Every dialog has a visible title that says what it's for, like "Delete project?" | [1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) (A), [2.4.6 Headings and Labels](https://www.w3.org/WAI/WCAG22/Understanding/headings-and-labels.html) (AA) | WCAG 1.3.1 (A), 2.4.6 (AA) | +| [`dialog/described`](/docs/components/dialog/ux#ux-checklist) | Should | A short description is linked with `aria-describedby`, while longer content, like a form, isn't | None | APG | +| [`dialog/initial-focus`](/docs/components/dialog/ux#ux-checklist) | Must | Opening it moves focus inside, to the control marked with `data-autofocus`, or else the first in its body, then its first action | [2.4.3 Focus Order](https://www.w3.org/WAI/WCAG22/Understanding/focus-order.html) (A) | WCAG 2.4.3 (A), APG | +| [`dialog/safe-focus`](/docs/components/dialog/ux#ux-checklist) | Must | An alert dialog's initial focus is on its least destructive action | None | APG | +| [`dialog/return-focus`](/docs/components/dialog/ux#ux-checklist) | Must | Closing it moves focus back to the control that opened it, or to a logical place when that control is gone | [2.4.3 Focus Order](https://www.w3.org/WAI/WCAG22/Understanding/focus-order.html) (A) | WCAG 2.4.3 (A), APG | +| [`dialog/escape`](/docs/components/dialog/ux#ux-checklist) | Must | `Escape` asks to close every dialog, alert dialogs included, unless a control inside handles it first | None | APG | + +## AX rules + +| Rule | Level | Requirement | WCAG 2.2 | Basis | +| ---- | ----- | ----------- | -------- | ----- | +| [`dialog/role-and-name`](/docs/components/dialog/ax#ax-checklist) | Must | It can be found by its role and title alone, with `getByRole("dialog", { name })`, or `"alertdialog"` | [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) (A) | WCAG 4.1.2 (A) | + +## Sources + +- [Web Content Accessibility Guidelines (WCAG) 2.2](https://www.w3.org/TR/WCAG22/), for each success criterion's number, short name and level +- [Understanding WCAG 2.2](https://www.w3.org/WAI/WCAG22/Understanding/), which each criterion links to +- [WAI-ARIA Authoring Practices Guide (APG)](https://www.w3.org/WAI/ARIA/apg/) +- [Dialog](/docs/components/dialog), where each rule is explained, with the sources it draws on diff --git a/content/docs/4.accessibility/field-checklist.md b/content/docs/4.accessibility/field-checklist.md new file mode 100644 index 0000000..60e9872 --- /dev/null +++ b/content/docs/4.accessibility/field-checklist.md @@ -0,0 +1,44 @@ +--- +title: Accessible Field Checklist (WCAG) +description: Every Field rule that WCAG 2.2, WAI-ARIA or the APG backs, in one checklist, with the success criteria behind each rule and their level. +navigation: + title: Field +--- + +Here's every rule for the [Field](/docs/components/field) that WCAG 2.2, WAI-ARIA or the APG backs, in one list you can work through when you build or review one. Each row names the WCAG 2.2 success criteria behind its rule, with their level, and links to the rule's table on its layer's page, where we explain why it's there. A rule that rests on WAI-ARIA or the APG alone says "None". + +We build this list from the Field's checklists, so it always matches them. It leaves out the rules that rest only on HTML and the ones that are our own, so you'll find every rule in the [Field's checklist](/docs/components/field#checklist). + +## UI rules + +| Rule | Level | Requirement | WCAG 2.2 | Basis | +| ---- | ----- | ----------- | -------- | ----- | +| [`field/text-contrast`](/docs/components/field/ui#ui-checklist) | Must | The label, the hint and the error have a contrast of 4.5:1 against the page | [1.4.3 Contrast (Minimum)](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html) (AA) | WCAG 1.4.3 (AA) | +| [`field/error-in-text`](/docs/components/field/ui#ui-checklist) | Must | An error is a message in text, never a colour alone | [1.4.1 Use of Color](https://www.w3.org/WAI/WCAG22/Understanding/use-of-color.html) (A) | WCAG 1.4.1 (A) | +| [`field/resizable`](/docs/components/field/ui#ui-checklist) | Must | Its text and spacing are set in `rem`, so they grow with the text size rather than clip | [1.4.4 Resize Text](https://www.w3.org/WAI/WCAG22/Understanding/resize-text.html) (AA), [1.4.12 Text Spacing](https://www.w3.org/WAI/WCAG22/Understanding/text-spacing.html) (AA) | Open Components, beyond WCAG 1.4.4, 1.4.12 (AA) | + +## UX rules + +| Rule | Level | Requirement | WCAG 2.2 | Basis | +| ---- | ----- | ----------- | -------- | ----- | +| [`field/visible-label`](/docs/components/field/ux#ux-checklist) | Must | Every text control and switch in a Field has a visible label that says what to fill in | [1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) (A), [3.3.2 Labels or Instructions](https://www.w3.org/WAI/WCAG22/Understanding/labels-or-instructions.html) (A), [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) (A), [2.4.6 Headings and Labels](https://www.w3.org/WAI/WCAG22/Understanding/headings-and-labels.html) (AA) | WCAG 1.3.1, 3.3.2, 4.1.2 (A), 2.4.6 (AA) | +| [`field/label-for`](/docs/components/field/ux#ux-checklist) | Must | The label's `for` is the control's `id`, so a click on it focuses or toggles the control | [1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) (A) | WCAG 1.3.1 (A) | +| [`field/one-name`](/docs/components/field/ux#ux-checklist) | Must | A Checkbox, a Checkbox Group and a Radio Group get no label from the Field, so each keeps its own name | [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) (A) | WCAG 4.1.2 (A) | +| [`field/group-legend`](/docs/components/field/ux#ux-checklist) | Must | A Checkbox Group and a Radio Group are named by a legend that asks the question their options answer | [1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) (A) | WCAG 1.3.1 (A) | +| [`field/described`](/docs/components/field/ux#ux-checklist) | Must | The control's `aria-describedby` lists the hint, then the error, then the control's own | [1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) (A) | WCAG 1.3.1 (A) | +| [`field/error-message`](/docs/components/field/ux#ux-checklist) | Must | An error says what's wrong and how to fix it, in text | [3.3.1 Error Identification](https://www.w3.org/WAI/WCAG22/Understanding/error-identification.html) (A), [3.3.3 Error Suggestion](https://www.w3.org/WAI/WCAG22/Understanding/error-suggestion.html) (AA) | WCAG 3.3.1 (A), 3.3.3 (AA) | +| [`field/invalid-state`](/docs/components/field/ux#ux-checklist) | Must | The Field sets `aria-invalid="true"` on the control while it has an error, and never sets it otherwise | [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) (A) | WCAG 4.1.2 (A) | +| [`field/required-in-words`](/docs/components/field/ux#ux-checklist) | Should | Required or optional fields are marked in words, on whichever there are fewer of, like "(optional)" in the label | [3.3.2 Labels or Instructions](https://www.w3.org/WAI/WCAG22/Understanding/labels-or-instructions.html) (A) | Open Components, beyond WCAG 3.3.2 (A) | +| [`field/status-message`](/docs/components/field/ux#ux-checklist) | Should | A failed submit says what happened in a status message that screen readers announce | [4.1.3 Status Messages](https://www.w3.org/WAI/WCAG22/Understanding/status-messages.html) (AA) | WCAG 4.1.3 (AA) | + +## AX rules + +| Rule | Level | Requirement | WCAG 2.2 | Basis | +| ---- | ----- | ----------- | -------- | ----- | +| [`field/role-and-name`](/docs/components/field/ax#ax-checklist) | Must | Its control can be found by its role and the Field's label, or by its own label or legend, with `getByRole` | [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) (A) | WCAG 4.1.2 (A) | + +## Sources + +- [Web Content Accessibility Guidelines (WCAG) 2.2](https://www.w3.org/TR/WCAG22/), for each success criterion's number, short name and level +- [Understanding WCAG 2.2](https://www.w3.org/WAI/WCAG22/Understanding/), which each criterion links to +- [Field](/docs/components/field), where each rule is explained, with the sources it draws on diff --git a/content/docs/4.accessibility/input-checklist.md b/content/docs/4.accessibility/input-checklist.md new file mode 100644 index 0000000..5d0650f --- /dev/null +++ b/content/docs/4.accessibility/input-checklist.md @@ -0,0 +1,51 @@ +--- +title: Accessible Input Checklist (WCAG) +description: Every Input rule that WCAG 2.2, WAI-ARIA or the APG backs, in one checklist, with the success criteria behind each rule and their level. +navigation: + title: Input +--- + +Here's every rule for the [Input](/docs/components/input) that WCAG 2.2, WAI-ARIA or the APG backs, in one list you can work through when you build or review one. Each row names the WCAG 2.2 success criteria behind its rule, with their level, and links to the rule's table on its layer's page, where we explain why it's there. A rule that rests on WAI-ARIA or the APG alone says "None". + +We build this list from the Input's checklists, so it always matches them. It leaves out the rules that rest only on HTML and the ones that are our own, so you'll find every rule in the [Input's checklist](/docs/components/input#checklist). + +## UI rules + +| Rule | Level | Requirement | WCAG 2.2 | Basis | +| ---- | ----- | ----------- | -------- | ----- | +| [`input/contrast`](/docs/components/input/ui#ui-checklist) | Must | The value, the placeholder, prefixes and suffixes have a contrast of 4.5:1, and the focus ring has 3:1 against the page | [1.4.3 Contrast (Minimum)](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html) (AA), [1.4.11 Non-text Contrast](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast.html) (AA) | WCAG 1.4.3, 1.4.11 (AA) | +| [`input/boundary-contrast`](/docs/components/input/ui#ui-checklist) | Must | The border has a contrast of 3:1 against the page, so an empty input stays visible | [1.4.11 Non-text Contrast](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast.html) (AA) | WCAG 1.4.11 (AA) | +| [`input/focus-visible`](/docs/components/input/ui#ui-checklist) | Must | Focus shows an `outline` at least 2px thick around the whole field, outside its border | [2.4.7 Focus Visible](https://www.w3.org/WAI/WCAG22/Understanding/focus-visible.html) (AA), [2.4.13 Focus Appearance](https://www.w3.org/WAI/WCAG22/Understanding/focus-appearance.html) (AAA) | WCAG 2.4.7 (AA), 2.4.13 (AAA) | +| [`input/target-size`](/docs/components/input/ui#ui-checklist) | Must | The field is at least 24px tall, with a hit area at least 44px tall on touch screens | [2.5.8 Target Size (Minimum)](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html) (AA), [2.5.5 Target Size (Enhanced)](https://www.w3.org/WAI/WCAG22/Understanding/target-size-enhanced.html) (AAA) | WCAG 2.5.8 (AA), 2.5.5 (AAA) | +| [`input/resizable`](/docs/components/input/ui#ui-checklist) | Must | The field is sized with `min-height` and padding in `rem`, so it grows with its text instead of clipping it | [1.4.4 Resize Text](https://www.w3.org/WAI/WCAG22/Understanding/resize-text.html) (AA), [1.4.12 Text Spacing](https://www.w3.org/WAI/WCAG22/Understanding/text-spacing.html) (AA) | Open Components, beyond WCAG 1.4.4, 1.4.12 (AA) | +| [`input/fits-value`](/docs/components/input/ui#ui-checklist) | Should | Its width fits the value it expects, like a short one for a postcode, and never outgrows the screen | [1.4.10 Reflow](https://www.w3.org/WAI/WCAG22/Understanding/reflow.html) (AA) | Open Components, beyond WCAG 1.4.10 (AA) | + +## UX rules + +| Rule | Level | Requirement | WCAG 2.2 | Basis | +| ---- | ----- | ----------- | -------- | ----- | +| [`input/native-element`](/docs/components/input/ux#ux-checklist) | Must | It's a native `<input>`, and never a `contenteditable` element | [2.1.1 Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html) (A), [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) (A) | Open Components, beyond WCAG 2.1.1, 4.1.2 (A) | +| [`input/visible-label`](/docs/components/input/ux#ux-checklist) | Must | Every input has a visible `<label>`, linked with `for`, rather than a placeholder alone, unless it's a search next to its Search button, named with `aria-label` | [1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) (A), [3.3.2 Labels or Instructions](https://www.w3.org/WAI/WCAG22/Understanding/labels-or-instructions.html) (A), [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) (A) | WCAG 1.3.1, 3.3.2, 4.1.2 (A) | +| [`input/label-in-name`](/docs/components/input/ux#ux-checklist) | Must | An `aria-label` or `aria-labelledby` includes the visible label, ideally at the start | [2.5.3 Label in Name](https://www.w3.org/WAI/WCAG22/Understanding/label-in-name.html) (A) | WCAG 2.5.3 (A) | +| [`input/described`](/docs/components/input/ux#ux-checklist) | Should | Hints, like the format it expects, are linked with `aria-describedby`, and a placeholder only ever shows an example | [1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) (A) | WCAG 1.3.1 (A), Open Components | +| [`input/decorative-slots`](/docs/components/input/ux#ux-checklist) | Must | `leading` and `trailing` are hidden from assistive technologies with `aria-hidden`, while `actions` stay reachable | [1.1.1 Non-text Content](https://www.w3.org/WAI/WCAG22/Understanding/non-text-content.html) (A) | WCAG 1.1.1 (A) | +| [`input/units-in-label`](/docs/components/input/ux#ux-checklist) | Must | A prefix or a suffix, like a currency or a unit, is in the label or the hint as well | [1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) (A) | WCAG 1.3.1 (A) | +| [`input/input-purpose`](/docs/components/input/ux#ux-checklist) | Must | An input that asks about the person filling it in has the matching `autocomplete`, like `email` or `tel` | [1.3.5 Identify Input Purpose](https://www.w3.org/WAI/WCAG22/Understanding/identify-input-purpose.html) (AA) | WCAG 1.3.5 (AA) | +| [`input/keyboard`](/docs/components/input/ux#ux-checklist) | Must | `Tab` reaches the input and then its actions, and the browser's text editing keys work as they do in any text field | [2.1.1 Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html) (A) | WCAG 2.1.1 (A) | +| [`input/allow-paste`](/docs/components/input/ux#ux-checklist) | Must | Pasting, autofill and password managers are never blocked | [3.3.8 Accessible Authentication (Minimum)](https://www.w3.org/WAI/WCAG22/Understanding/accessible-authentication-minimum.html) (AA) | WCAG 3.3.8 (AA) | +| [`input/error-message`](/docs/components/input/ux#ux-checklist) | Must | An invalid input has an error message, in text and linked with `aria-describedby`, that says what's wrong and how to fix it | [1.4.1 Use of Color](https://www.w3.org/WAI/WCAG22/Understanding/use-of-color.html) (A), [3.3.1 Error Identification](https://www.w3.org/WAI/WCAG22/Understanding/error-identification.html) (A), [3.3.3 Error Suggestion](https://www.w3.org/WAI/WCAG22/Understanding/error-suggestion.html) (AA) | WCAG 1.4.1, 3.3.1 (A), 3.3.3 (AA) | +| [`input/invalid-state`](/docs/components/input/ux#ux-checklist) | Must | An input sets `aria-invalid="true"` while its error message shows, and only looks invalid when it does | [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) (A) | WCAG 4.1.2 (A), Open Components | +| [`input/action-buttons`](/docs/components/input/ux#ux-checklist) | Must | Buttons in `actions` are named Buttons that `Tab` reaches after the input, and one that goes away moves focus back to the input | [2.1.1 Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html) (A), [2.4.3 Focus Order](https://www.w3.org/WAI/WCAG22/Understanding/focus-order.html) (A), [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) (A) | WCAG 2.1.1, 2.4.3, 4.1.2 (A) | +| [`input/focus-not-obscured`](/docs/components/input/ux#ux-checklist) | Must | Sticky headers and footers never cover a focused input, for example thanks to `scroll-padding` | [2.4.11 Focus Not Obscured (Minimum)](https://www.w3.org/WAI/WCAG22/Understanding/focus-not-obscured-minimum.html) (AA), [2.4.12 Focus Not Obscured (Enhanced)](https://www.w3.org/WAI/WCAG22/Understanding/focus-not-obscured-enhanced.html) (AAA) | WCAG 2.4.11 (AA), 2.4.12 (AAA) | + +## AX rules + +| Rule | Level | Requirement | WCAG 2.2 | Basis | +| ---- | ----- | ----------- | -------- | ----- | +| [`input/role-and-name`](/docs/components/input/ax#ax-checklist) | Must | It can be found by its role and label alone, with `getByRole("textbox", { name })`, or with `getByLabel` for a password | [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) (A) | WCAG 4.1.2 (A) | + +## Sources + +- [Web Content Accessibility Guidelines (WCAG) 2.2](https://www.w3.org/TR/WCAG22/), for each success criterion's number, short name and level +- [Understanding WCAG 2.2](https://www.w3.org/WAI/WCAG22/Understanding/), which each criterion links to +- [Input](/docs/components/input), where each rule is explained, with the sources it draws on diff --git a/content/docs/4.accessibility/popover-checklist.md b/content/docs/4.accessibility/popover-checklist.md new file mode 100644 index 0000000..f82b372 --- /dev/null +++ b/content/docs/4.accessibility/popover-checklist.md @@ -0,0 +1,47 @@ +--- +title: Accessible Popover Checklist (WCAG) +description: Every Popover rule that WCAG 2.2, WAI-ARIA or the APG backs, in one checklist, with the success criteria behind each rule and their level. +navigation: + title: Popover +--- + +Here's every rule for the [Popover](/docs/components/popover) that WCAG 2.2, WAI-ARIA or the APG backs, in one list you can work through when you build or review one. Each row names the WCAG 2.2 success criteria behind its rule, with their level, and links to the rule's table on its layer's page, where we explain why it's there. A rule that rests on WAI-ARIA or the APG alone says "None". + +We build this list from the Popover's checklists, so it always matches them. It leaves out the rules that rest only on HTML and the ones that are our own, so you'll find every rule in the [Popover's checklist](/docs/components/popover#checklist). + +## UI rules + +| Rule | Level | Requirement | WCAG 2.2 | Basis | +| ---- | ----- | ----------- | -------- | ----- | +| [`popover/contrast`](/docs/components/popover/ui#ui-checklist) | Must | The title and the content have a contrast of 4.5:1 against the panel | [1.4.3 Contrast (Minimum)](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html) (AA) | WCAG 1.4.3 (AA) | +| [`popover/fits-screen`](/docs/components/popover/ui#ui-checklist) | Must | It's never wider or taller than the screen less 16px on each side, down to 320px wide, and its body scrolls when its content doesn't fit | [1.4.10 Reflow](https://www.w3.org/WAI/WCAG22/Understanding/reflow.html) (AA) | WCAG 1.4.10 (AA) | +| [`popover/resizable`](/docs/components/popover/ui#ui-checklist) | Must | It's sized in `rem`, so it grows with its text, and its title wraps rather than getting cut off | [1.4.4 Resize Text](https://www.w3.org/WAI/WCAG22/Understanding/resize-text.html) (AA), [1.4.12 Text Spacing](https://www.w3.org/WAI/WCAG22/Understanding/text-spacing.html) (AA) | Open Components, beyond WCAG 1.4.4, 1.4.12 (AA) | +| [`popover/reduced-motion`](/docs/components/popover/ui#ui-checklist) | Should | It only animates as it opens when `prefers-reduced-motion` is `no-preference` | [2.3.3 Animation from Interactions](https://www.w3.org/WAI/WCAG22/Understanding/animation-from-interactions.html) (AAA) | WCAG 2.3.3 (AAA) | + +## UX rules + +| Rule | Level | Requirement | WCAG 2.2 | Basis | +| ---- | ----- | ----------- | -------- | ----- | +| [`popover/native-popover`](/docs/components/popover/ux#ux-checklist) | Must | It's an element with `popover="auto"`, which a `popovertarget` button opens before any script loads, and never a scripted overlay | [2.1.1 Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html) (A) | Open Components, beyond WCAG 2.1.1 (A) | +| [`popover/non-modal`](/docs/components/popover/ux#ux-checklist) | Must | The page around it keeps working: nothing is inert, nothing is `aria-modal`, and `Tab` can leave it | [2.1.2 No Keyboard Trap](https://www.w3.org/WAI/WCAG22/Understanding/no-keyboard-trap.html) (A) | WAI-ARIA, WCAG 2.1.2 (A) | +| [`popover/named`](/docs/components/popover/ux#ux-checklist) | Must | It's `role="dialog"`, named by its title with `aria-labelledby` | [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) (A) | WCAG 4.1.2 (A) | +| [`popover/visible-title`](/docs/components/popover/ux#ux-checklist) | Must | Every popover has a title that says what it holds, like "Filters" | [1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) (A), [2.4.6 Headings and Labels](https://www.w3.org/WAI/WCAG22/Understanding/headings-and-labels.html) (AA) | WCAG 1.3.1 (A), 2.4.6 (AA) | +| [`popover/trigger`](/docs/components/popover/ux#ux-checklist) | Must | Its trigger is a button that points at it with `popovertarget`, and sets `aria-haspopup="dialog"` | [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) (A) | WCAG 4.1.2 (A), HTML | +| [`popover/trigger-expanded`](/docs/components/popover/ux#ux-checklist) | Must | It keeps `aria-expanded` on its trigger in step with whether it's open, `true` only on the trigger that opened it | [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) (A) | WCAG 4.1.2 (A) | +| [`popover/after-trigger`](/docs/components/popover/ux#ux-checklist) | Should | It's rendered right after its trigger, so `Tab` and screen readers reach it next | [1.3.2 Meaningful Sequence](https://www.w3.org/WAI/WCAG22/Understanding/meaningful-sequence.html) (A), [2.4.3 Focus Order](https://www.w3.org/WAI/WCAG22/Understanding/focus-order.html) (A) | WCAG 1.3.2, 2.4.3 (A) | +| [`popover/initial-focus`](/docs/components/popover/ux#ux-checklist) | Must | Opening it moves focus inside, to the control marked with `data-autofocus`, or else the first in its body, then its close button | [2.4.3 Focus Order](https://www.w3.org/WAI/WCAG22/Understanding/focus-order.html) (A) | WCAG 2.4.3 (A) | +| [`popover/return-focus`](/docs/components/popover/ux#ux-checklist) | Must | Closing it while focus is inside moves focus back to its trigger, and a press outside leaves focus where people pressed | [2.4.3 Focus Order](https://www.w3.org/WAI/WCAG22/Understanding/focus-order.html) (A) | WCAG 2.4.3 (A), HTML | +| [`popover/escape`](/docs/components/popover/ux#ux-checklist) | Must | `Escape` closes it, with focus in it, on its trigger or anywhere else on the page | [2.4.11 Focus Not Obscured (Minimum)](https://www.w3.org/WAI/WCAG22/Understanding/focus-not-obscured-minimum.html) (AA) | HTML, WCAG 2.4.11 (AA) | + +## AX rules + +| Rule | Level | Requirement | WCAG 2.2 | Basis | +| ---- | ----- | ----------- | -------- | ----- | +| [`popover/role-and-name`](/docs/components/popover/ax#ax-checklist) | Must | It can be found by its role and title alone, with `getByRole("dialog", { name })` | [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) (A) | WCAG 4.1.2 (A) | + +## Sources + +- [Web Content Accessibility Guidelines (WCAG) 2.2](https://www.w3.org/TR/WCAG22/), for each success criterion's number, short name and level +- [Understanding WCAG 2.2](https://www.w3.org/WAI/WCAG22/Understanding/), which each criterion links to +- [Accessible Rich Internet Applications (WAI-ARIA) 1.2](https://www.w3.org/TR/wai-aria-1.2/) +- [Popover](/docs/components/popover), where each rule is explained, with the sources it draws on diff --git a/content/docs/4.accessibility/radio-group-checklist.md b/content/docs/4.accessibility/radio-group-checklist.md new file mode 100644 index 0000000..c93f820 --- /dev/null +++ b/content/docs/4.accessibility/radio-group-checklist.md @@ -0,0 +1,49 @@ +--- +title: Accessible Radio Group Checklist (WCAG) +description: Every Radio Group rule that WCAG 2.2, WAI-ARIA or the APG backs, in one checklist, with the success criteria behind each rule and their level. +navigation: + title: Radio Group +--- + +Here's every rule for the [Radio Group](/docs/components/radio-group) that WCAG 2.2, WAI-ARIA or the APG backs, in one list you can work through when you build or review one. Each row names the WCAG 2.2 success criteria behind its rule, with their level, and links to the rule's table on its layer's page, where we explain why it's there. A rule that rests on WAI-ARIA or the APG alone says "None". + +We build this list from the Radio Group's checklists, so it always matches them. It leaves out the rules that rest only on HTML and the ones that are our own, so you'll find every rule in the [Radio Group's checklist](/docs/components/radio-group#checklist). + +## UI rules + +| Rule | Level | Requirement | WCAG 2.2 | Basis | +| ---- | ----- | ----------- | -------- | ----- | +| [`radio-group/contrast`](/docs/components/radio-group/ui#ui-checklist) | Must | The legend, labels, hint and error message have a contrast of 4.5:1, and the focus ring has 3:1 against the page | [1.4.3 Contrast (Minimum)](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html) (AA), [1.4.11 Non-text Contrast](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast.html) (AA) | WCAG 1.4.3, 1.4.11 (AA) | +| [`radio-group/indicator-contrast`](/docs/components/radio-group/ui#ui-checklist) | Must | The ring of an unchecked radio and the fill of a checked one have a contrast of 3:1 against the page | [1.4.11 Non-text Contrast](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast.html) (AA) | WCAG 1.4.11 (AA) | +| [`radio-group/checked-shape`](/docs/components/radio-group/ui#ui-checklist) | Must | A checked radio differs from an unchecked one by its shape, like a dot, and not by its colour alone | [1.4.1 Use of Color](https://www.w3.org/WAI/WCAG22/Understanding/use-of-color.html) (A) | WCAG 1.4.1 (A) | +| [`radio-group/focus-visible`](/docs/components/radio-group/ui#ui-checklist) | Must | Focus shows an `outline` at least 2px thick around the indicator, outside it | [2.4.7 Focus Visible](https://www.w3.org/WAI/WCAG22/Understanding/focus-visible.html) (AA), [2.4.13 Focus Appearance](https://www.w3.org/WAI/WCAG22/Understanding/focus-appearance.html) (AAA) | WCAG 2.4.7 (AA), 2.4.13 (AAA) | +| [`radio-group/target-size`](/docs/components/radio-group/ui#ui-checklist) | Must | Each radio's label is part of its target, which is at least 24 × 24px, and each row is at least 44px tall on touch screens | [2.5.8 Target Size (Minimum)](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html) (AA), [2.5.5 Target Size (Enhanced)](https://www.w3.org/WAI/WCAG22/Understanding/target-size-enhanced.html) (AAA) | WCAG 2.5.8 (AA), 2.5.5 (AAA) | +| [`radio-group/resizable`](/docs/components/radio-group/ui#ui-checklist) | Must | Rows are sized with `min-height` in `rem`, so they grow with their text, and long labels wrap beside the indicator | [1.4.4 Resize Text](https://www.w3.org/WAI/WCAG22/Understanding/resize-text.html) (AA), [1.4.12 Text Spacing](https://www.w3.org/WAI/WCAG22/Understanding/text-spacing.html) (AA) | Open Components, beyond WCAG 1.4.4, 1.4.12 (AA) | + +## UX rules + +| Rule | Level | Requirement | WCAG 2.2 | Basis | +| ---- | ----- | ----------- | -------- | ----- | +| [`radio-group/native-radios`](/docs/components/radio-group/ux#ux-checklist) | Must | Each radio is a native `<input type="radio">`, and never an element with `role="radio"` | [2.1.1 Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html) (A), [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) (A) | Open Components, beyond WCAG 2.1.1, 4.1.2 (A) | +| [`radio-group/fieldset-legend`](/docs/components/radio-group/ux#ux-checklist) | Must | The radios sit in a `<fieldset>` that its `<legend>` names | [1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) (A), [3.3.2 Labels or Instructions](https://www.w3.org/WAI/WCAG22/Understanding/labels-or-instructions.html) (A) | WCAG 1.3.1, 3.3.2 (A) | +| [`radio-group/labelled-radios`](/docs/components/radio-group/ux#ux-checklist) | Must | Every radio has a visible label, which names it and checks it when pressed | [1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) (A), [3.3.2 Labels or Instructions](https://www.w3.org/WAI/WCAG22/Understanding/labels-or-instructions.html) (A), [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) (A) | WCAG 1.3.1, 3.3.2, 4.1.2 (A) | +| [`radio-group/described`](/docs/components/radio-group/ux#ux-checklist) | Should | A hint for the whole group is linked to it with `aria-describedby` | [1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) (A) | WCAG 1.3.1 (A) | +| [`radio-group/keyboard`](/docs/components/radio-group/ux#ux-checklist) | Must | `Tab` stops once per group, on the checked radio or the first one, the arrow keys move focus and check, wrapping round, and `Space` checks | [2.1.1 Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html) (A) | APG, WCAG 2.1.1 (A) | +| [`radio-group/no-change-on-input`](/docs/components/radio-group/ux#ux-checklist) | Must | Checking a radio never submits its form, opens another page or moves focus | [3.2.2 On Input](https://www.w3.org/WAI/WCAG22/Understanding/on-input.html) (A) | WCAG 3.2.2 (A) | +| [`radio-group/error-message`](/docs/components/radio-group/ux#ux-checklist) | Must | An invalid group has an error message, in text, that says what to do | [1.4.1 Use of Color](https://www.w3.org/WAI/WCAG22/Understanding/use-of-color.html) (A), [3.3.1 Error Identification](https://www.w3.org/WAI/WCAG22/Understanding/error-identification.html) (A), [3.3.3 Error Suggestion](https://www.w3.org/WAI/WCAG22/Understanding/error-suggestion.html) (AA) | WCAG 1.4.1, 3.3.1 (A), 3.3.3 (AA) | +| [`radio-group/invalid-state`](/docs/components/radio-group/ux#ux-checklist) | Must | While it has an error message, the group has `role="radiogroup"` and `aria-invalid="true"`, is described by the message and only looks invalid then | [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) (A) | WCAG 4.1.2 (A), WAI-ARIA | +| [`radio-group/focus-not-obscured`](/docs/components/radio-group/ux#ux-checklist) | Must | Sticky headers and footers never cover a focused radio, for example thanks to `scroll-padding` | [2.4.11 Focus Not Obscured (Minimum)](https://www.w3.org/WAI/WCAG22/Understanding/focus-not-obscured-minimum.html) (AA), [2.4.12 Focus Not Obscured (Enhanced)](https://www.w3.org/WAI/WCAG22/Understanding/focus-not-obscured-enhanced.html) (AAA) | WCAG 2.4.11 (AA), 2.4.12 (AAA) | + +## AX rules + +| Rule | Level | Requirement | WCAG 2.2 | Basis | +| ---- | ----- | ----------- | -------- | ----- | +| [`radio-group/role-and-name`](/docs/components/radio-group/ax#ax-checklist) | Must | It can be found by its role and legend alone, with `getByRole("radiogroup", { name })`, and each radio with `getByRole("radio", { name })` | [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) (A) | WCAG 4.1.2 (A) | + +## Sources + +- [Web Content Accessibility Guidelines (WCAG) 2.2](https://www.w3.org/TR/WCAG22/), for each success criterion's number, short name and level +- [Understanding WCAG 2.2](https://www.w3.org/WAI/WCAG22/Understanding/), which each criterion links to +- [Accessible Rich Internet Applications (WAI-ARIA) 1.2](https://www.w3.org/TR/wai-aria-1.2/) +- [WAI-ARIA Authoring Practices Guide (APG)](https://www.w3.org/WAI/ARIA/apg/) +- [Radio Group](/docs/components/radio-group), where each rule is explained, with the sources it draws on diff --git a/content/docs/4.accessibility/select-checklist.md b/content/docs/4.accessibility/select-checklist.md new file mode 100644 index 0000000..2642a95 --- /dev/null +++ b/content/docs/4.accessibility/select-checklist.md @@ -0,0 +1,59 @@ +--- +title: Accessible Select Checklist (WCAG) +description: Every Select rule that WCAG 2.2, WAI-ARIA or the APG backs, in one checklist, with the success criteria behind each rule and their level. +navigation: + title: Select +--- + +Here's every rule for the [Select](/docs/components/select) that WCAG 2.2, WAI-ARIA or the APG backs, in one list you can work through when you build or review one. Each row names the WCAG 2.2 success criteria behind its rule, with their level, and links to the rule's table on its layer's page, where we explain why it's there. A rule that rests on WAI-ARIA or the APG alone says "None". + +We build this list from the Select's checklists, so it always matches them. It leaves out the rules that rest only on HTML and the ones that are our own, so you'll find every rule in the [Select's checklist](/docs/components/select#checklist). + +## UI rules + +| Rule | Level | Requirement | WCAG 2.2 | Basis | +| ---- | ----- | ----------- | -------- | ----- | +| [`select/target-size`](/docs/components/select/ui#ui-checklist) | Must | The field, each option and each remove button are at least 24 × 24px, and at least 44px tall on a touch screen | [2.5.8 Target Size (Minimum)](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html) (AA) | WCAG 2.5.8 (AA) | +| [`select/focus-visible`](/docs/components/select/ui#ui-checklist) | Must | Focus shows a ring around the field, and the highlighted option an outline of its own | [2.4.7 Focus Visible](https://www.w3.org/WAI/WCAG22/Understanding/focus-visible.html) (AA) | WCAG 2.4.7 (AA) | +| [`select/contrast`](/docs/components/select/ui#ui-checklist) | Must | Text has at least 4.5:1 and the field's border at least 3:1 against what's behind them | [1.4.3 Contrast (Minimum)](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html) (AA), [1.4.11 Non-text Contrast](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast.html) (AA) | WCAG 1.4.3, 1.4.11 (AA) | +| [`select/not-colour-alone`](/docs/components/select/ui#ui-checklist) | Must | A selected option has a check mark and a heavier weight, not only a colour | [1.4.1 Use of Color](https://www.w3.org/WAI/WCAG22/Understanding/use-of-color.html) (A) | WCAG 1.4.1 (A) | +| [`select/decorative-icons`](/docs/components/select/ui#ui-checklist) | Must | Icons in the panel, the field and the tags are hidden from assistive technologies, so the label alone names each option | [1.1.1 Non-text Content](https://www.w3.org/WAI/WCAG22/Understanding/non-text-content.html) (A) | WCAG 1.1.1 (A) | + +## UX rules + +| Rule | Level | Requirement | WCAG 2.2 | Basis | +| ---- | ----- | ----------- | -------- | ----- | +| [`select/combobox-pattern`](/docs/components/select/ux#ux-checklist) | Must | The control is a `<button role="combobox">` linked to a `listbox` with `aria-expanded`, `aria-controls` and `aria-activedescendant` | None | WAI-ARIA, APG, ARIA in HTML | +| [`select/has-a-name`](/docs/components/select/ux#ux-checklist) | Must | It has a name, from a Field's label or an `aria-label`, and the panel has the same name | [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) (A), [3.3.2 Labels or Instructions](https://www.w3.org/WAI/WCAG22/Understanding/labels-or-instructions.html) (A) | WCAG 4.1.2 (A), 3.3.2 (A) | +| [`select/reads-its-value`](/docs/components/select/ux#ux-checklist) | Must | The control's text is its value, as a label, a list of labels or a count past three | [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) (A) | WCAG 4.1.2 (A) | +| [`select/keyboard`](/docs/components/select/ux#ux-checklist) | Must | Every key in the keyboard tables does what they say | [2.1.1 Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html) (A) | WCAG 2.1.1 (A), APG | +| [`select/typeahead`](/docs/components/select/ux#ux-checklist) | Must | Letters typed in quick succession search the enabled options, spaces included, and one letter repeated cycles through them | None | APG | +| [`select/focus-stays`](/docs/components/select/ux#ux-checklist) | Must | DOM focus stays on the control, and `aria-activedescendant` follows the highlighted option | [2.4.3 Focus Order](https://www.w3.org/WAI/WCAG22/Understanding/focus-order.html) (A) | APG, WCAG 2.4.3 (A) | +| [`select/tab-commits`](/docs/components/select/ux#ux-checklist) | Should | `Tab` picks the highlighted single option, or keeps what's toggled, and moves on | None | APG | +| [`select/escape`](/docs/components/select/ux#ux-checklist) | Must | `Escape` closes the panel without changing the value and stops there | None | Open Components, APG | +| [`select/remove-tag`](/docs/components/select/ux#ux-checklist) | Must | A value can be removed by pointer and by keyboard, with `Backspace` on the closed control too | [2.1.1 Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html) (A) | WCAG 2.1.1 (A) | +| [`select/focus-after-remove`](/docs/components/select/ux#ux-checklist) | Must | Focus goes to the next remove button, or the control when there's none after it | [2.4.3 Focus Order](https://www.w3.org/WAI/WCAG22/Understanding/focus-order.html) (A) | WCAG 2.4.3 (A) | +| [`select/announce-removal`](/docs/components/select/ux#ux-checklist) | Should | A removed value is announced through a polite live region | [4.1.3 Status Messages](https://www.w3.org/WAI/WCAG22/Understanding/status-messages.html) (AA) | WCAG 4.1.3 (AA) | +| [`select/panel-fits`](/docs/components/select/ux#ux-checklist) | Must | The panel flips and shrinks to stay inside the screen, down to 320px wide | [1.4.10 Reflow](https://www.w3.org/WAI/WCAG22/Understanding/reflow.html) (AA) | WCAG 1.4.10 (AA) | +| [`select/reduced-motion`](/docs/components/select/ux#ux-checklist) | Should | The arrow and the panel don't animate for people who asked for less motion | [2.3.3 Animation from Interactions](https://www.w3.org/WAI/WCAG22/Understanding/animation-from-interactions.html) (AAA) | WCAG 2.3.3 (AAA) | + +## DX rules + +| Rule | Level | Requirement | WCAG 2.2 | Basis | +| ---- | ----- | ----------- | -------- | ----- | +| [`select/in-a-field`](/docs/components/select/dx#dx-checklist) | Must | In a Field, it takes the label, description, invalid and disabled state in both renderings | [1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) (A) | WCAG 1.3.1 (A) | + +## AX rules + +| Rule | Level | Requirement | WCAG 2.2 | Basis | +| ---- | ----- | ----------- | -------- | ----- | +| [`select/role-and-name`](/docs/components/select/ax#ax-checklist) | Must | It can be found with `getByRole("combobox", { name })`, in both renderings | [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) (A) | WCAG 4.1.2 (A) | + +## Sources + +- [Web Content Accessibility Guidelines (WCAG) 2.2](https://www.w3.org/TR/WCAG22/), for each success criterion's number, short name and level +- [Understanding WCAG 2.2](https://www.w3.org/WAI/WCAG22/Understanding/), which each criterion links to +- [Accessible Rich Internet Applications (WAI-ARIA) 1.2](https://www.w3.org/TR/wai-aria-1.2/) +- [WAI-ARIA Authoring Practices Guide (APG)](https://www.w3.org/WAI/ARIA/apg/) +- [ARIA in HTML](https://www.w3.org/TR/html-aria/) +- [Select](/docs/components/select), where each rule is explained, with the sources it draws on diff --git a/content/docs/4.accessibility/spinner-checklist.md b/content/docs/4.accessibility/spinner-checklist.md new file mode 100644 index 0000000..98e05ff --- /dev/null +++ b/content/docs/4.accessibility/spinner-checklist.md @@ -0,0 +1,32 @@ +--- +title: Accessible Spinner Checklist (WCAG) +description: Every Spinner rule that WCAG 2.2, WAI-ARIA or the APG backs, in one checklist, with the success criteria behind each rule and their level. +navigation: + title: Spinner +--- + +Here's every rule for the [Spinner](/docs/components/spinner) that WCAG 2.2, WAI-ARIA or the APG backs, in one list you can work through when you build or review one. Each row names the WCAG 2.2 success criteria behind its rule, with their level, and links to the rule's table on its layer's page, where we explain why it's there. A rule that rests on WAI-ARIA or the APG alone says "None". + +We build this list from the Spinner's checklists, so it always matches them. It leaves out the rules that rest only on HTML and the ones that are our own, so you'll find every rule in the [Spinner's checklist](/docs/components/spinner#checklist). + +## UI rules + +| Rule | Level | Requirement | WCAG 2.2 | Basis | +| ---- | ----- | ----------- | -------- | ----- | +| [`spinner/contrast`](/docs/components/spinner/ui#ui-checklist) | Must | The indicator has a contrast of 3:1 against what's behind it | [1.4.11 Non-text Contrast](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast.html) (AA) | WCAG 1.4.11 (AA) | +| [`spinner/reduced-motion`](/docs/components/spinner/ui#ui-checklist) | Must | It doesn't turn when `prefers-reduced-motion: reduce` is set, but still shows that something's happening, like with a pulse | [2.3.3 Animation from Interactions](https://www.w3.org/WAI/WCAG22/Understanding/animation-from-interactions.html) (AAA) | WCAG 2.3.3 (AAA), Open Components | + +## UX rules + +| Rule | Level | Requirement | WCAG 2.2 | Basis | +| ---- | ----- | ----------- | -------- | ----- | +| [`spinner/decorative`](/docs/components/spinner/ux#ux-checklist) | Must | It's hidden from assistive technologies with `aria-hidden`, and has no role or name of its own | [1.1.1 Non-text Content](https://www.w3.org/WAI/WCAG22/Understanding/non-text-content.html) (A) | WCAG 1.1.1 (A) | +| [`spinner/say-what-loads`](/docs/components/spinner/ux#ux-checklist) | Must | Whatever shows it says what's loading, in a status message that's already in the page or with a label it announces, like the Button's `loadingLabel` | [4.1.3 Status Messages](https://www.w3.org/WAI/WCAG22/Understanding/status-messages.html) (AA) | WCAG 4.1.3 (AA) | +| [`spinner/announce-outcome`](/docs/components/spinner/ux#ux-checklist) | Should | When the wait ends, the page says how it went, in the same status message, or in an alert for an error that needs attention straight away | [4.1.3 Status Messages](https://www.w3.org/WAI/WCAG22/Understanding/status-messages.html) (AA) | Open Components, beyond WCAG 4.1.3 (AA) | +| [`spinner/remove-when-done`](/docs/components/spinner/ux#ux-checklist) | Must | It's taken out as soon as the wait ends or fails, so it never turns with nothing to wait for | [2.2.2 Pause, Stop, Hide](https://www.w3.org/WAI/WCAG22/Understanding/pause-stop-hide.html) (A) | Open Components, beyond WCAG 2.2.2 (A) | + +## Sources + +- [Web Content Accessibility Guidelines (WCAG) 2.2](https://www.w3.org/TR/WCAG22/), for each success criterion's number, short name and level +- [Understanding WCAG 2.2](https://www.w3.org/WAI/WCAG22/Understanding/), which each criterion links to +- [Spinner](/docs/components/spinner), where each rule is explained, with the sources it draws on diff --git a/content/docs/4.accessibility/switch-checklist.md b/content/docs/4.accessibility/switch-checklist.md new file mode 100644 index 0000000..cd9da59 --- /dev/null +++ b/content/docs/4.accessibility/switch-checklist.md @@ -0,0 +1,52 @@ +--- +title: Accessible Switch Checklist (WCAG) +description: Every Switch rule that WCAG 2.2, WAI-ARIA or the APG backs, in one checklist, with the success criteria behind each rule and their level. +navigation: + title: Switch +--- + +Here's every rule for the [Switch](/docs/components/switch) that WCAG 2.2, WAI-ARIA or the APG backs, in one list you can work through when you build or review one. Each row names the WCAG 2.2 success criteria behind its rule, with their level, and links to the rule's table on its layer's page, where we explain why it's there. A rule that rests on WAI-ARIA or the APG alone says "None". + +We build this list from the Switch's checklists, so it always matches them. It leaves out the rules that rest only on HTML and the ones that are our own, so you'll find every rule in the [Switch's checklist](/docs/components/switch#checklist). + +## UI rules + +| Rule | Level | Requirement | WCAG 2.2 | Basis | +| ---- | ----- | ----------- | -------- | ----- | +| [`switch/contrast`](/docs/components/switch/ui#ui-checklist) | Must | The track and the thumb have a contrast of 3:1 against what's next to them, on and off, and so does the focus ring | [1.4.11 Non-text Contrast](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast.html) (AA) | WCAG 1.4.11 (AA) | +| [`switch/more-than-colour`](/docs/components/switch/ui#ui-checklist) | Must | On and off differ by more than colour: the thumb moves to the other end, and the track fills | [1.4.1 Use of Color](https://www.w3.org/WAI/WCAG22/Understanding/use-of-color.html) (A) | WCAG 1.4.1 (A) | +| [`switch/focus-visible`](/docs/components/switch/ui#ui-checklist) | Must | Focus shows an `outline` at least 2px thick around the track, outside it | [2.4.7 Focus Visible](https://www.w3.org/WAI/WCAG22/Understanding/focus-visible.html) (AA), [2.4.13 Focus Appearance](https://www.w3.org/WAI/WCAG22/Understanding/focus-appearance.html) (AAA) | WCAG 2.4.7 (AA), 2.4.13 (AAA) | +| [`switch/target-size`](/docs/components/switch/ui#ui-checklist) | Must | The hit area is at least 24 × 24px, and at least 44 × 44px on touch screens | [2.5.8 Target Size (Minimum)](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html) (AA), [2.5.5 Target Size (Enhanced)](https://www.w3.org/WAI/WCAG22/Understanding/target-size-enhanced.html) (AAA) | WCAG 2.5.8 (AA), 2.5.5 (AAA) | +| [`switch/resizable`](/docs/components/switch/ui#ui-checklist) | Must | The track and the thumb are sized in `rem`, so they grow with the text | [1.4.4 Resize Text](https://www.w3.org/WAI/WCAG22/Understanding/resize-text.html) (AA) | Open Components, beyond WCAG 1.4.4 (AA) | +| [`switch/reduced-motion`](/docs/components/switch/ui#ui-checklist) | Must | The thumb doesn't slide when `prefers-reduced-motion: reduce` is set | [2.3.3 Animation from Interactions](https://www.w3.org/WAI/WCAG22/Understanding/animation-from-interactions.html) (AAA) | WCAG 2.3.3 (AAA) | + +## UX rules + +| Rule | Level | Requirement | WCAG 2.2 | Basis | +| ---- | ----- | ----------- | -------- | ----- | +| [`switch/native-element`](/docs/components/switch/ux#ux-checklist) | Must | It's a native `<input type="checkbox">` with `role="switch"`, and never a `<div>` | [2.1.1 Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html) (A), [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) (A) | APG, Open Components, beyond WCAG 2.1.1, 4.1.2 (A) | +| [`switch/checked-state`](/docs/components/switch/ux#ux-checklist) | Must | Its state is the checkbox's own `checked`, announced as on or off, with no pressed or mixed state | None | WAI-ARIA, APG | +| [`switch/visible-label`](/docs/components/switch/ux#ux-checklist) | Must | Every switch has a visible `<label>`, linked with `for` | [1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) (A), [3.3.2 Labels or Instructions](https://www.w3.org/WAI/WCAG22/Understanding/labels-or-instructions.html) (A), [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) (A) | WCAG 1.3.1, 3.3.2, 4.1.2 (A) | +| [`switch/label-in-name`](/docs/components/switch/ux#ux-checklist) | Must | An `aria-label` or `aria-labelledby` includes the visible label, ideally at the start | [2.5.3 Label in Name](https://www.w3.org/WAI/WCAG22/Understanding/label-in-name.html) (A) | WCAG 2.5.3 (A) | +| [`switch/stable-label`](/docs/components/switch/ux#ux-checklist) | Must | The label names the setting and stays the same whether the switch is on or off | None | APG | +| [`switch/described`](/docs/components/switch/ux#ux-checklist) | Should | Hints, like what the setting changes, are linked with `aria-describedby` | [1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) (A) | WCAG 1.3.1 (A) | +| [`switch/keyboard`](/docs/components/switch/ux#ux-checklist) | Must | `Tab` reaches the switch, and `Space` and a click on its label flip it | [2.1.1 Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html) (A) | WCAG 2.1.1 (A), APG | +| [`switch/announce-saved`](/docs/components/switch/ux#ux-checklist) | Should | While its change is saved, it keeps its new state and stays enabled, and a status message says when it's saved | [4.1.3 Status Messages](https://www.w3.org/WAI/WCAG22/Understanding/status-messages.html) (AA) | WCAG 4.1.3 (AA), Open Components | +| [`switch/no-context-change`](/docs/components/switch/ux#ux-checklist) | Must | Flipping it never moves focus, opens a page or submits a form, unless its hint says so first | [3.2.2 On Input](https://www.w3.org/WAI/WCAG22/Understanding/on-input.html) (A) | WCAG 3.2.2 (A) | +| [`switch/error-message`](/docs/components/switch/ux#ux-checklist) | Must | An invalid switch has an error message, in text and linked with `aria-describedby`, that says what happened and what to do | [1.4.1 Use of Color](https://www.w3.org/WAI/WCAG22/Understanding/use-of-color.html) (A), [3.3.1 Error Identification](https://www.w3.org/WAI/WCAG22/Understanding/error-identification.html) (A) | WCAG 1.4.1, 3.3.1 (A) | +| [`switch/invalid-state`](/docs/components/switch/ux#ux-checklist) | Must | A switch sets `aria-invalid="true"` while its error message shows, and only looks invalid when it does | [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) (A) | WCAG 4.1.2 (A), Open Components | +| [`switch/read-only`](/docs/components/switch/ux#ux-checklist) | Must | A read-only switch can be focused and is sent with its form, but doesn't flip, and sets `aria-readonly="true"` | None | WAI-ARIA | + +## AX rules + +| Rule | Level | Requirement | WCAG 2.2 | Basis | +| ---- | ----- | ----------- | -------- | ----- | +| [`switch/role-and-name`](/docs/components/switch/ax#ax-checklist) | Must | It can be found by its role, its label and its state alone, with `getByRole("switch", { name, checked })` | [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) (A) | WCAG 4.1.2 (A) | + +## Sources + +- [Web Content Accessibility Guidelines (WCAG) 2.2](https://www.w3.org/TR/WCAG22/), for each success criterion's number, short name and level +- [Understanding WCAG 2.2](https://www.w3.org/WAI/WCAG22/Understanding/), which each criterion links to +- [Accessible Rich Internet Applications (WAI-ARIA) 1.2](https://www.w3.org/TR/wai-aria-1.2/) +- [WAI-ARIA Authoring Practices Guide (APG)](https://www.w3.org/WAI/ARIA/apg/) +- [Switch](/docs/components/switch), where each rule is explained, with the sources it draws on diff --git a/content/docs/4.accessibility/tag-checklist.md b/content/docs/4.accessibility/tag-checklist.md new file mode 100644 index 0000000..bba8cb9 --- /dev/null +++ b/content/docs/4.accessibility/tag-checklist.md @@ -0,0 +1,43 @@ +--- +title: Accessible Tag Checklist (WCAG) +description: Every Tag rule that WCAG 2.2, WAI-ARIA or the APG backs, in one checklist, with the success criteria behind each rule and their level. +navigation: + title: Tag +--- + +Here's every rule for the [Tag](/docs/components/tag) that WCAG 2.2, WAI-ARIA or the APG backs, in one list you can work through when you build or review one. Each row names the WCAG 2.2 success criteria behind its rule, with their level, and links to the rule's table on its layer's page, where we explain why it's there. A rule that rests on WAI-ARIA or the APG alone says "None". + +We build this list from the Tag's checklists, so it always matches them. It leaves out the rules that rest only on HTML and the ones that are our own, so you'll find every rule in the [Tag's checklist](/docs/components/tag#checklist). + +## UI rules + +| Rule | Level | Requirement | WCAG 2.2 | Basis | +| ---- | ----- | ----------- | -------- | ----- | +| [`tag/target-size`](/docs/components/tag/ui#ui-checklist) | Must | The remove button and a link label each take a press over at least 24 × 24px, and at least 44px tall on a touch screen | [2.5.8 Target Size (Minimum)](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html) (AA), [2.5.5 Target Size (Enhanced)](https://www.w3.org/WAI/WCAG22/Understanding/target-size-enhanced.html) (AAA) | WCAG 2.5.8 (AA), 2.5.5 (AAA) | +| [`tag/contrast`](/docs/components/tag/ui#ui-checklist) | Must | The label has at least 4.5:1 against the tag's background, and the focus ring at least 3:1 against what's behind it | [1.4.3 Contrast (Minimum)](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html) (AA), [1.4.11 Non-text Contrast](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast.html) (AA) | WCAG 1.4.3, 1.4.11 (AA) | +| [`tag/focus-visible`](/docs/components/tag/ui#ui-checklist) | Must | The link and the remove button show an outline at least 2px thick on `:focus-visible` | [2.4.7 Focus Visible](https://www.w3.org/WAI/WCAG22/Understanding/focus-visible.html) (AA) | WCAG 2.4.7 (AA) | +| [`tag/resizable`](/docs/components/tag/ui#ui-checklist) | Must | The tag is sized with a `min-height` in `rem`, so it grows with its text | [1.4.4 Resize Text](https://www.w3.org/WAI/WCAG22/Understanding/resize-text.html) (AA) | Open Components, beyond WCAG 1.4.4 (AA) | +| [`tag/decorative-icons`](/docs/components/tag/ui#ui-checklist) | Must | The leading icon and the remove button's icon are hidden from assistive technologies | [1.1.1 Non-text Content](https://www.w3.org/WAI/WCAG22/Understanding/non-text-content.html) (A) | WCAG 1.1.1 (A) | +| [`tag/link-distinct`](/docs/components/tag/ui#ui-checklist) | Should | A link tag looks different from a plain one by more than its colour, like a border | [1.4.1 Use of Color](https://www.w3.org/WAI/WCAG22/Understanding/use-of-color.html) (A) | Open Components, beyond WCAG 1.4.1 (A) | + +## UX rules + +| Rule | Level | Requirement | WCAG 2.2 | Basis | +| ---- | ----- | ----------- | -------- | ----- | +| [`tag/plain-text`](/docs/components/tag/ux#ux-checklist) | Must | A tag without a link or a remove button has no role and isn't focusable | None | WAI-ARIA | +| [`tag/remove-button`](/docs/components/tag/ux#ux-checklist) | Must | Removal is a native `<button type="button">`, which `Enter` and `Space` press | [2.1.1 Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html) (A) | HTML, WCAG 2.1.1 (A) | +| [`tag/remove-name`](/docs/components/tag/ux#ux-checklist) | Must | The remove button's name includes the tag's text, like "Remove Bug" | [2.4.6 Headings and Labels](https://www.w3.org/WAI/WCAG22/Understanding/headings-and-labels.html) (AA), [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) (A) | WCAG 2.4.6 (AA), 4.1.2 (A) | +| [`tag/disabled`](/docs/components/tag/ux#ux-checklist) | Must | `disabled` drops the remove button, and a link loses its `href` and takes `aria-disabled="true"` | None | HTML, WAI-ARIA | + +## AX rules + +| Rule | Level | Requirement | WCAG 2.2 | Basis | +| ---- | ----- | ----------- | -------- | ----- | +| [`tag/role-and-name`](/docs/components/tag/ax#ax-checklist) | Must | It can be found by its parts' roles and names, with `getByRole("button", { name: "Remove Bug" })` and, as a link, `getByRole("link", { name: "Bug" })` | [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) (A) | WCAG 4.1.2 (A) | + +## Sources + +- [Web Content Accessibility Guidelines (WCAG) 2.2](https://www.w3.org/TR/WCAG22/), for each success criterion's number, short name and level +- [Understanding WCAG 2.2](https://www.w3.org/WAI/WCAG22/Understanding/), which each criterion links to +- [Accessible Rich Internet Applications (WAI-ARIA) 1.2](https://www.w3.org/TR/wai-aria-1.2/) +- [Tag](/docs/components/tag), where each rule is explained, with the sources it draws on diff --git a/content/docs/4.accessibility/tag-group-checklist.md b/content/docs/4.accessibility/tag-group-checklist.md new file mode 100644 index 0000000..134339a --- /dev/null +++ b/content/docs/4.accessibility/tag-group-checklist.md @@ -0,0 +1,40 @@ +--- +title: Accessible Tag Group Checklist (WCAG) +description: Every Tag Group rule that WCAG 2.2, WAI-ARIA or the APG backs, in one checklist, with the success criteria behind each rule and their level. +navigation: + title: Tag Group +--- + +Here's every rule for the [Tag Group](/docs/components/tag-group) that WCAG 2.2, WAI-ARIA or the APG backs, in one list you can work through when you build or review one. Each row names the WCAG 2.2 success criteria behind its rule, with their level, and links to the rule's table on its layer's page, where we explain why it's there. A rule that rests on WAI-ARIA or the APG alone says "None". + +We build this list from the Tag Group's checklists, so it always matches them. It leaves out the rules that rest only on HTML and the ones that are our own, so you'll find every rule in the [Tag Group's checklist](/docs/components/tag-group#checklist). + +## UI rules + +| Rule | Level | Requirement | WCAG 2.2 | Basis | +| ---- | ----- | ----------- | -------- | ----- | +| [`tag-group/wrap`](/docs/components/tag-group/ui#ui-checklist) | Must | Tags wrap onto as many rows as they need, with no horizontal scroll at 320px wide | [1.4.10 Reflow](https://www.w3.org/WAI/WCAG22/Understanding/reflow.html) (AA) | WCAG 1.4.10 (AA) | +| [`tag-group/row-gap`](/docs/components/tag-group/ui#ui-checklist) | Must | Rows sit at least 24px minus the tag's height apart, and 44px minus it on a touch screen, so no tag's hit area covers a tag on the next row | [2.5.8 Target Size (Minimum)](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html) (AA), [2.5.5 Target Size (Enhanced)](https://www.w3.org/WAI/WCAG22/Understanding/target-size-enhanced.html) (AAA) | WCAG 2.5.8 (AA), 2.5.5 (AAA) | +| [`tag-group/contrast`](/docs/components/tag-group/ui#ui-checklist) | Must | The empty state's text has at least 4.5:1 against what's behind it, and its focus ring at least 3:1 | [1.4.3 Contrast (Minimum)](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html) (AA), [1.4.11 Non-text Contrast](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast.html) (AA) | WCAG 1.4.3, 1.4.11 (AA) | + +## UX rules + +| Rule | Level | Requirement | WCAG 2.2 | Basis | +| ---- | ----- | ----------- | -------- | ----- | +| [`tag-group/list`](/docs/components/tag-group/ux#ux-checklist) | Must | The tags are a `<ul>` with one `<li>` per tag, which keeps its list role where its bullets are removed | [1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) (A) | WCAG 1.3.1 (A) | +| [`tag-group/name`](/docs/components/tag-group/ux#ux-checklist) | Must | The list has a name, from `label` or from a visible heading through `aria-labelledby` | [1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) (A) | Open Components, beyond WCAG 1.3.1 (A) | +| [`tag-group/tab-stops`](/docs/components/tag-group/ux#ux-checklist) | Must | Each link and remove button is a stop in the tab order, in order, with no roving focus and no arrow keys | [2.1.1 Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html) (A) | WCAG 2.1.1 (A) | +| [`tag-group/focus-after-remove`](/docs/components/tag-group/ux#ux-checklist) | Must | Once a removed tag has gone, focus that was on it moves to the next tag's remove button, then `fallbackFocus`, then the previous tag's remove button, then the empty state, or the list when tags are left that can't be removed | [2.4.3 Focus Order](https://www.w3.org/WAI/WCAG22/Understanding/focus-order.html) (A) | WCAG 2.4.3 (A) | +| [`tag-group/announce-removal`](/docs/components/tag-group/ux#ux-checklist) | Should | Once a tag whose remove button was pressed has gone, a polite live region announces it, like "Bug removed" | [4.1.3 Status Messages](https://www.w3.org/WAI/WCAG22/Understanding/status-messages.html) (AA) | WCAG 4.1.3 (AA) | + +## AX rules + +| Rule | Level | Requirement | WCAG 2.2 | Basis | +| ---- | ----- | ----------- | -------- | ----- | +| [`tag-group/role-and-name`](/docs/components/tag-group/ax#ax-checklist) | Must | It can be found by its role and name, with `getByRole("list", { name: "Labels" })`, and each tag by its parts', like `getByRole("button", { name: "Remove Bug" })` | [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) (A) | WCAG 4.1.2 (A) | + +## Sources + +- [Web Content Accessibility Guidelines (WCAG) 2.2](https://www.w3.org/TR/WCAG22/), for each success criterion's number, short name and level +- [Understanding WCAG 2.2](https://www.w3.org/WAI/WCAG22/Understanding/), which each criterion links to +- [Tag Group](/docs/components/tag-group), where each rule is explained, with the sources it draws on diff --git a/content/docs/4.accessibility/textarea-checklist.md b/content/docs/4.accessibility/textarea-checklist.md new file mode 100644 index 0000000..61a4668 --- /dev/null +++ b/content/docs/4.accessibility/textarea-checklist.md @@ -0,0 +1,50 @@ +--- +title: Accessible Textarea Checklist (WCAG) +description: Every Textarea rule that WCAG 2.2, WAI-ARIA or the APG backs, in one checklist, with the success criteria behind each rule and their level. +navigation: + title: Textarea +--- + +Here's every rule for the [Textarea](/docs/components/textarea) that WCAG 2.2, WAI-ARIA or the APG backs, in one list you can work through when you build or review one. Each row names the WCAG 2.2 success criteria behind its rule, with their level, and links to the rule's table on its layer's page, where we explain why it's there. A rule that rests on WAI-ARIA or the APG alone says "None". + +We build this list from the Textarea's checklists, so it always matches them. It leaves out the rules that rest only on HTML and the ones that are our own, so you'll find every rule in the [Textarea's checklist](/docs/components/textarea#checklist). + +## UI rules + +| Rule | Level | Requirement | WCAG 2.2 | Basis | +| ---- | ----- | ----------- | -------- | ----- | +| [`textarea/contrast`](/docs/components/textarea/ui#ui-checklist) | Must | The text, the placeholder and the count have a contrast of 4.5:1, and the focus ring has 3:1 against the page | [1.4.3 Contrast (Minimum)](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html) (AA), [1.4.11 Non-text Contrast](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast.html) (AA) | WCAG 1.4.3, 1.4.11 (AA) | +| [`textarea/boundary-contrast`](/docs/components/textarea/ui#ui-checklist) | Must | The border has a contrast of 3:1 against the page, so an empty textarea stays visible | [1.4.11 Non-text Contrast](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast.html) (AA) | WCAG 1.4.11 (AA) | +| [`textarea/focus-visible`](/docs/components/textarea/ui#ui-checklist) | Must | Focus shows an `outline` at least 2px thick around the field, outside its border | [2.4.7 Focus Visible](https://www.w3.org/WAI/WCAG22/Understanding/focus-visible.html) (AA), [2.4.13 Focus Appearance](https://www.w3.org/WAI/WCAG22/Understanding/focus-appearance.html) (AAA) | WCAG 2.4.7 (AA), 2.4.13 (AAA) | +| [`textarea/target-size`](/docs/components/textarea/ui#ui-checklist) | Must | The field is at least 24px tall, and at least 44px tall on touch screens | [2.5.8 Target Size (Minimum)](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html) (AA), [2.5.5 Target Size (Enhanced)](https://www.w3.org/WAI/WCAG22/Understanding/target-size-enhanced.html) (AAA) | WCAG 2.5.8 (AA), 2.5.5 (AAA) | +| [`textarea/resizable`](/docs/components/textarea/ui#ui-checklist) | Must | Its height is a minimum, in lines of its own line height plus padding in `rem`, so it grows with its text instead of clipping it | [1.4.4 Resize Text](https://www.w3.org/WAI/WCAG22/Understanding/resize-text.html) (AA), [1.4.12 Text Spacing](https://www.w3.org/WAI/WCAG22/Understanding/text-spacing.html) (AA) | Open Components, beyond WCAG 1.4.4, 1.4.12 (AA) | +| [`textarea/fits-text`](/docs/components/textarea/ui#ui-checklist) | Should | Its `rows` fit the text it expects, and it's never wider than its column | [1.4.10 Reflow](https://www.w3.org/WAI/WCAG22/Understanding/reflow.html) (AA) | Open Components, beyond WCAG 1.4.10 (AA) | + +## UX rules + +| Rule | Level | Requirement | WCAG 2.2 | Basis | +| ---- | ----- | ----------- | -------- | ----- | +| [`textarea/native-element`](/docs/components/textarea/ux#ux-checklist) | Must | It's a native `<textarea>`, and never a `contenteditable` element or a `role="textbox"` | [2.1.1 Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html) (A), [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) (A) | Open Components, beyond WCAG 2.1.1, 4.1.2 (A) | +| [`textarea/visible-label`](/docs/components/textarea/ux#ux-checklist) | Must | Every textarea has a visible `<label>`, linked with `for`, rather than a placeholder alone | [1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) (A), [3.3.2 Labels or Instructions](https://www.w3.org/WAI/WCAG22/Understanding/labels-or-instructions.html) (A), [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) (A) | WCAG 1.3.1, 3.3.2, 4.1.2 (A) | +| [`textarea/label-in-name`](/docs/components/textarea/ux#ux-checklist) | Must | An `aria-label` or `aria-labelledby` includes the visible label, ideally at the start | [2.5.3 Label in Name](https://www.w3.org/WAI/WCAG22/Understanding/label-in-name.html) (A) | WCAG 2.5.3 (A) | +| [`textarea/described`](/docs/components/textarea/ux#ux-checklist) | Should | Hints, like what to include, are linked with `aria-describedby`, and a placeholder only ever shows a short example | [1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) (A) | WCAG 1.3.1 (A), Open Components | +| [`textarea/keyboard`](/docs/components/textarea/ux#ux-checklist) | Must | `Tab` moves focus to and from it, and the browser's text editing keys work as they do in any textarea | [2.1.1 Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html) (A), [2.1.2 No Keyboard Trap](https://www.w3.org/WAI/WCAG22/Understanding/no-keyboard-trap.html) (A) | WCAG 2.1.1, 2.1.2 (A) | +| [`textarea/limit-in-hint`](/docs/components/textarea/ux#ux-checklist) | Should | A limit is stated in the hint, linked with `aria-describedby`, before people start writing | [3.3.2 Labels or Instructions](https://www.w3.org/WAI/WCAG22/Understanding/labels-or-instructions.html) (A) | WCAG 3.3.2 (A) | +| [`textarea/count`](/docs/components/textarea/ux#ux-checklist) | Should | The count says how many characters are left, or how many too many, describes the textarea, and over the limit sets `aria-invalid="true"` | [3.3.1 Error Identification](https://www.w3.org/WAI/WCAG22/Understanding/error-identification.html) (A) | WCAG 3.3.1 (A), Open Components | +| [`textarea/announce-count`](/docs/components/textarea/ux#ux-checklist) | Should | The count is announced through one polite live region once people pause near the limit, and never on every keystroke | [4.1.3 Status Messages](https://www.w3.org/WAI/WCAG22/Understanding/status-messages.html) (AA) | WCAG 4.1.3 (AA), Open Components | +| [`textarea/input-purpose`](/docs/components/textarea/ux#ux-checklist) | Must | A textarea that asks for the person's own address has `autocomplete="street-address"` | [1.3.5 Identify Input Purpose](https://www.w3.org/WAI/WCAG22/Understanding/identify-input-purpose.html) (AA) | WCAG 1.3.5 (AA) | +| [`textarea/error-message`](/docs/components/textarea/ux#ux-checklist) | Must | An invalid textarea has an error message, in text and linked with `aria-describedby`, that says what's wrong and how to fix it | [1.4.1 Use of Color](https://www.w3.org/WAI/WCAG22/Understanding/use-of-color.html) (A), [3.3.1 Error Identification](https://www.w3.org/WAI/WCAG22/Understanding/error-identification.html) (A), [3.3.3 Error Suggestion](https://www.w3.org/WAI/WCAG22/Understanding/error-suggestion.html) (AA) | WCAG 1.4.1, 3.3.1 (A), 3.3.3 (AA) | +| [`textarea/invalid-state`](/docs/components/textarea/ux#ux-checklist) | Must | A textarea sets `aria-invalid="true"` while its error message shows, and only looks invalid when it does | [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) (A) | WCAG 4.1.2 (A), Open Components | +| [`textarea/focus-not-obscured`](/docs/components/textarea/ux#ux-checklist) | Must | Sticky headers and footers never cover a focused textarea, for example thanks to `scroll-padding` | [2.4.11 Focus Not Obscured (Minimum)](https://www.w3.org/WAI/WCAG22/Understanding/focus-not-obscured-minimum.html) (AA), [2.4.12 Focus Not Obscured (Enhanced)](https://www.w3.org/WAI/WCAG22/Understanding/focus-not-obscured-enhanced.html) (AAA) | WCAG 2.4.11 (AA), 2.4.12 (AAA) | + +## AX rules + +| Rule | Level | Requirement | WCAG 2.2 | Basis | +| ---- | ----- | ----------- | -------- | ----- | +| [`textarea/role-and-name`](/docs/components/textarea/ax#ax-checklist) | Must | It can be found by its role and label alone, with `getByRole("textbox", { name })` | [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) (A) | WCAG 4.1.2 (A) | + +## Sources + +- [Web Content Accessibility Guidelines (WCAG) 2.2](https://www.w3.org/TR/WCAG22/), for each success criterion's number, short name and level +- [Understanding WCAG 2.2](https://www.w3.org/WAI/WCAG22/Understanding/), which each criterion links to +- [Textarea](/docs/components/textarea), where each rule is explained, with the sources it draws on diff --git a/content/docs/4.accessibility/tooltip-checklist.md b/content/docs/4.accessibility/tooltip-checklist.md new file mode 100644 index 0000000..b3f069b --- /dev/null +++ b/content/docs/4.accessibility/tooltip-checklist.md @@ -0,0 +1,44 @@ +--- +title: Accessible Tooltip Checklist (WCAG) +description: Every Tooltip rule that WCAG 2.2, WAI-ARIA or the APG backs, in one checklist, with the success criteria behind each rule and their level. +navigation: + title: Tooltip +--- + +Here's every rule for the [Tooltip](/docs/components/tooltip) that WCAG 2.2, WAI-ARIA or the APG backs, in one list you can work through when you build or review one. Each row names the WCAG 2.2 success criteria behind its rule, with their level, and links to the rule's table on its layer's page, where we explain why it's there. A rule that rests on WAI-ARIA or the APG alone says "None". + +We build this list from the Tooltip's checklists, so it always matches them. It leaves out the rules that rest only on HTML and the ones that are our own, so you'll find every rule in the [Tooltip's checklist](/docs/components/tooltip#checklist). + +## UI rules + +| Rule | Level | Requirement | WCAG 2.2 | Basis | +| ---- | ----- | ----------- | -------- | ----- | +| [`tooltip/contrast`](/docs/components/tooltip/ui#ui-checklist) | Must | Its text has a contrast of 4.5:1 against its fill | [1.4.3 Contrast (Minimum)](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html) (AA) | WCAG 1.4.3 (AA) | +| [`tooltip/wraps`](/docs/components/tooltip/ui#ui-checklist) | Should | Long text wraps at a maximum width set in `ch`, and is never cut off or scrolled | [1.4.4 Resize Text](https://www.w3.org/WAI/WCAG22/Understanding/resize-text.html) (AA), [1.4.10 Reflow](https://www.w3.org/WAI/WCAG22/Understanding/reflow.html) (AA) | WCAG 1.4.4, 1.4.10 (AA) | +| [`tooltip/reduced-motion`](/docs/components/tooltip/ui#ui-checklist) | Must | With `prefers-reduced-motion: reduce`, it fades in without growing or moving | [2.3.3 Animation from Interactions](https://www.w3.org/WAI/WCAG22/Understanding/animation-from-interactions.html) (AAA) | WCAG 2.3.3 (AAA), Open Components | + +## UX rules + +| Rule | Level | Requirement | WCAG 2.2 | Basis | +| ---- | ----- | ----------- | -------- | ----- | +| [`tooltip/focus-opens`](/docs/components/tooltip/ux#ux-checklist) | Must | Keyboard focus on its trigger opens it at once | [2.1.1 Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html) (A) | WCAG 2.1.1 (A) | +| [`tooltip/hoverable`](/docs/components/tooltip/ux#ux-checklist) | Must | The pointer can cross from the trigger onto the tooltip, within a short grace period, without closing it | [1.4.13 Content on Hover or Focus](https://www.w3.org/WAI/WCAG22/Understanding/content-on-hover-or-focus.html) (AA) | WCAG 1.4.13 (AA) | +| [`tooltip/persistent`](/docs/components/tooltip/ux#ux-checklist) | Must | It stays open while its trigger has hover or focus, and never hides on a timer | [1.4.13 Content on Hover or Focus](https://www.w3.org/WAI/WCAG22/Understanding/content-on-hover-or-focus.html) (AA) | WCAG 1.4.13 (AA) | +| [`tooltip/dismiss-with-escape`](/docs/components/tooltip/ux#ux-checklist) | Must | `Escape` dismisses it without moving focus or the pointer | [1.4.13 Content on Hover or Focus](https://www.w3.org/WAI/WCAG22/Understanding/content-on-hover-or-focus.html) (AA) | WCAG 1.4.13 (AA) | +| [`tooltip/focusable-trigger`](/docs/components/tooltip/ux#ux-checklist) | Must | Its trigger is focusable, and a disabled one uses `aria-disabled` rather than `disabled` | [2.1.1 Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html) (A) | Open Components, beyond WCAG 2.1.1 (A) | + +## AX rules + +| Rule | Level | Requirement | WCAG 2.2 | Basis | +| ---- | ----- | ----------- | -------- | ----- | +| [`tooltip/describes`](/docs/components/tooltip/ax#ax-checklist) | Must | With `type="description"`, it's `role="tooltip"`, and its trigger points to its `id` with `aria-describedby` | None | WAI-ARIA | +| [`tooltip/shows-label`](/docs/components/tooltip/ax#ax-checklist) | Must | With `type="label"`, it's `aria-hidden`, nothing points to it, and the trigger keeps its own name | [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) (A) | WCAG 4.1.2 (A), Open Components | +| [`tooltip/named-trigger`](/docs/components/tooltip/ax#ax-checklist) | Must | Its trigger has an accessible name of its own, like an icon-only Button's hidden label | [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) (A) | WCAG 4.1.2 (A) | +| [`tooltip/in-the-dom`](/docs/components/tooltip/ax#ax-checklist) | Must | It stays in the DOM while it's closed, so its trigger's description is always there | None | WAI-ARIA | + +## Sources + +- [Web Content Accessibility Guidelines (WCAG) 2.2](https://www.w3.org/TR/WCAG22/), for each success criterion's number, short name and level +- [Understanding WCAG 2.2](https://www.w3.org/WAI/WCAG22/Understanding/), which each criterion links to +- [Accessible Rich Internet Applications (WAI-ARIA) 1.2](https://www.w3.org/TR/wai-aria-1.2/) +- [Tooltip](/docs/components/tooltip), where each rule is explained, with the sources it draws on diff --git a/server/lib/checklists.test.ts b/server/lib/checklists.test.ts new file mode 100644 index 0000000..4e3c530 --- /dev/null +++ b/server/lib/checklists.test.ts @@ -0,0 +1,263 @@ +// @vitest-environment node +import { readdirSync, readFileSync } from "node:fs"; +import { join } from "node:path"; +import { describe, expect, it } from "vitest"; +import { parse } from "yaml"; +import { FRAMEWORKS } from "../../app/data/frameworks"; +import { buildStandard } from "../../mcp/lib/standard"; +import { brokenLinks, checklistPage, CHECKLISTS, citedCriteria, COMPONENTS, layerRows, picked, readChecklists } from "./checklists"; +import { docsPath, rawPage, rawTitle } from "./raw"; +import { WCAG } from "./wcag"; + +const DOCS = "content/docs"; +const checklists = readChecklists(DOCS); +const frontmatter = (source: string) => parse(source.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n/)?.[1] ?? "") ?? {}; + +// A layer page's source, with a rules table of the given rows, each +// [rule, level, requirement, basis]. +const layer = (name: string, rows: string[][], ...before: string[]) => + [ + "---", + "title: A layer", + "description: A layer page.", + "---", + "", + ...before, + `## ${name} Checklist`, + "", + "| Rule | Level | Scope | Requirement | Basis | Check |", + "| ---- | ----- | ----- | ----------- | ----- | ----- |", + ...rows.map(([rule, level, requirement, basis]) => `| \`${rule}\` | ${level} | Component | ${requirement} | ${basis} | Review |`), + "", + "## FAQ", + "", + "| Not | A | Rule |", + "", + ].join("\n"); + +// The content gate for the checklists: each page in content/docs/4.accessibility/ +// is what the generator builds from its component's tables, so the two can't +// drift. After a rule changes, `pnpm test -u server/lib/checklists.test.ts` +// writes the pages again. CI never writes them, so it fails on any difference. +describe("The accessibility checklists", () => { + it.each([...checklists])("%s is built from its component's Checklist tables", async (file, page) => { + await expect(page).toMatchFileSnapshot(join("../..", DOCS, file)); + }); + + it("has a page for every component, and nothing else", () => { + const components = readdirSync(join(DOCS, COMPONENTS), { withFileTypes: true }).filter((entry) => entry.isDirectory()); + const files = readdirSync(join(DOCS, CHECKLISTS)).filter((file) => file.endsWith(".md")); + expect(checklists.size).toBe(components.length); + expect(files.map((file) => join(CHECKLISTS, file)).sort()).toEqual([...checklists.keys()].sort()); + }); + + // Every docs page's own source, by its path, the parts of a split page each + // under their own, as the site serves them. + const site = new Map( + readdirSync(DOCS, { recursive: true, encoding: "utf8" }) + .filter((file) => file.endsWith(".md")) + .map((file) => [docsPath(file), readFileSync(join(DOCS, file), "utf8")]), + ); + it.each([...checklists])("%s links to sections that exist", (_, page) => { + expect(brokenLinks(page, site)).toEqual([]); + }); + + it.each([...checklists])("%s has a title that fits in search results, and a description that does too", (_, page) => { + const { title, description, seo } = frontmatter(page); + // The site adds " - Open Components", and check-seo allows 60 characters. + expect(title.length).toBeLessThanOrEqual(42); + expect(description.length).toBeGreaterThanOrEqual(70); + expect(description.length).toBeLessThanOrEqual(160); + // A seo.title would head the /raw copy but not the MCP server's, which + // check-mcp requires to be the same bytes. + expect(seo).toBeUndefined(); + }); + + it("gives every page a title and a description of its own", () => { + const pages = [...checklists.values()].map(frontmatter); + expect(new Set(pages.map((page) => page.title)).size).toBe(pages.length); + expect(new Set(pages.map((page) => page.description)).size).toBe(pages.length); + }); + + const { standard } = buildStandard({ root: process.cwd(), site: "https://opencomponents.dev", frameworks: FRAMEWORKS }); + const served = standard.pages.filter((page) => page.path.startsWith(docsPath(`${CHECKLISTS}/`))); + + it("serves every page on the MCP server as the same bytes as its /raw copy, and adds no rules", () => { + expect(served.map((page) => page.path).sort()).toEqual([...checklists.keys()].map(docsPath).sort()); + for (const page of served) { + const file = [...checklists.keys()].find((key) => docsPath(key) === page.path)!; + const source = readFileSync(join(DOCS, file), "utf8"); + const { title, description, seo } = frontmatter(source); + expect(page.raw).toBe(rawPage({ title: rawTitle({ stem: `docs/${file.replace(/\.md$/, "")}`, title, seo }), description }, source)); + expect(page.contract).toBeUndefined(); + } + expect(standard.rules.filter((rule) => rule.url.includes(docsPath(`${CHECKLISTS}/`)))).toEqual([]); + }); + + it("holds every rule whose Basis names WCAG, WAI-ARIA or the APG, and no other", () => { + const pages = [...checklists.values()].join("\n"); + const listed = [...pages.matchAll(/^\| \[`([a-z-]+\/[a-z0-9-]+)`\]/gm)].map((match) => match[1]); + // The contracts read the same tables on their own, Basis included. + const expected = standard.pages + .filter((page) => page.contract?.kind === "component") + .flatMap((page) => (parse(page.contract!.yaml).rules as { id: string; basis: string }[]).filter((rule) => picked(rule.basis))) + .map((rule) => rule.id); + expect(expected.length).toBeGreaterThan(0); + expect([...listed].sort()).toEqual([...expected].sort()); + }); +}); + +describe("picked", () => { + it.each([ + ["WCAG 1.4.3, 1.4.11 (AA)", true], + ["Open Components, beyond WCAG 2.5.8 (AA)", true], + ["APG", true], + ["WAI-ARIA, Open Components", true], + ["HTML, WCAG 3.3.2 (A)", true], + ["HTML", false], + ["Open Components", false], + ["HTML, Open Components", false], + ["Open Components, beyond HTML", false], + ["ARIA in HTML", false], + ])("decides %s is %s", (basis, expected) => { + expect(picked(basis)).toBe(expected); + }); +}); + +describe("citedCriteria", () => { + const cited = (basis: string) => citedCriteria(basis).map(({ number, level }) => `${number} ${level}`); + + it("gives each criterion the level after the last of its run", () => { + expect(cited("WCAG 1.3.1, 3.3.2, 4.1.2 (A), 2.4.6 (AA)")).toEqual(["1.3.1 A", "3.3.2 A", "4.1.2 A", "2.4.6 AA"]); + expect(cited("WCAG 2.4.7 (AA), 2.4.13 (AAA)")).toEqual(["2.4.7 AA", "2.4.13 AAA"]); + }); + + it("reads WCAG wherever it is in the Basis, and stops at what isn't a criterion", () => { + expect(cited("Open Components, beyond WCAG 1.4.4, 1.4.12 (AA)")).toEqual(["1.4.4 AA", "1.4.12 AA"]); + expect(cited("HTML, WCAG 3.3.2 (A)")).toEqual(["3.3.2 A"]); + expect(cited("WCAG 4.1.2 (A), Open Components")).toEqual(["4.1.2 A"]); + expect(cited("APG, Open Components, beyond WCAG 2.1.1, 4.1.2 (A)")).toEqual(["2.1.1 A", "4.1.2 A"]); + }); + + it("names each criterion once", () => { + expect(cited("WCAG 4.1.2 (A), WCAG 4.1.2 (A)")).toEqual(["4.1.2 A"]); + }); + + it("finds none in a Basis without WCAG", () => { + expect(cited("WAI-ARIA, APG")).toEqual([]); + }); + + it("names a criterion by its WCAG 2.2 name", () => { + expect(citedCriteria("WCAG 1.4.3 (AA)")[0]).toEqual({ number: "1.4.3", ...WCAG["1.4.3"] }); + }); + + it.each([ + ["WCAG 4.1.1 (A)", /4\.1\.1, which isn't a WCAG 2.2 success criterion/], + ["WCAG 9.9.9 (AA)", /9\.9\.9, which isn't/], + ["WCAG 1.4.3 (A)", /gives WCAG 1\.4\.3 level A, but it's at level AA/], + ["WCAG 1.4.3, 1.4.11", /cites WCAG 1\.4\.3, 1\.4\.11 without a level/], + ["WCAG 1.4.3 (AA), 1.4.11, Open Components", /cites WCAG 1\.4\.11 without a level/], + ])("throws on %s", (basis, message) => { + expect(() => citedCriteria(basis)).toThrow(message); + }); +}); + +describe("layerRows", () => { + const FILE = "3.components/widget/2.ux.md"; + + it("picks the rows by their Basis, in the table's order, with a link to the table", () => { + const { name, rows } = layerRows( + FILE, + layer("UX", [ + ["widget/one", "Must", "It has a name", "WCAG 4.1.2 (A)"], + ["widget/two", "Should", "It uses arrow keys", "APG"], + ["widget/three", "Must", "It's a native element", "HTML"], + ["widget/four", "Should", "It stays put", "Open Components"], + ["widget/five", "Must", "It's bigger", "Open Components, beyond WCAG 2.5.8 (AA)"], + ]), + )!; + expect(name).toBe("UX"); + expect(rows.map((row) => [row.rule, row.level, row.basis, row.criteria.map((criterion) => criterion.number)])).toEqual([ + ["widget/one", "Must", "WCAG 4.1.2 (A)", ["4.1.2"]], + ["widget/two", "Should", "APG", []], + ["widget/five", "Must", "Open Components, beyond WCAG 2.5.8 (AA)", ["2.5.8"]], + ]); + expect(new Set(rows.map((row) => row.link))).toEqual(new Set(["/docs/components/widget/ux#ux-checklist"])); + }); + + it("links to the anchor the site gives the table's heading", () => { + // A heading with the same text earlier on the page takes the plain anchor. + const source = layer("UX", [["widget/one", "Must", "It has a name", "WCAG 4.1.2 (A)"]], "### UX Checklist", ""); + expect(layerRows(FILE, source)!.rows[0]!.link).toBe("/docs/components/widget/ux#ux-checklist-1"); + }); + + it("keeps a pipe in a Requirement, and escapes it again on the page", () => { + const { rows } = layerRows(FILE, layer("UX", [["widget/one", "Must", "It reads `a \\| b`", "WCAG 4.1.2 (A)"]]))!; + expect(rows[0]!.requirement).toBe("It reads `a | b`"); + expect(checklistPage({ title: "Widget", path: "/docs/components/widget" }, [{ name: "UX", rows }])).toContain( + "| It reads `a \\| b` |", + ); + }); + + it("gives none for a layer with no rows to pick, or no table", () => { + expect(layerRows(FILE, layer("DX", [["widget/one", "Must", "It types", "Open Components"]]))).toBeUndefined(); + expect(layerRows(FILE, "---\ntitle: A\n---\n\n## Something\n\nText.\n")).toBeUndefined(); + }); + + it("ignores a table heading inside code", () => { + const source = layer("UX", [["widget/one", "Must", "It has a name", "WCAG 4.1.2 (A)"]], "```md", "## UI Checklist", "```", ""); + expect(layerRows(FILE, source)!.name).toBe("UX"); + }); + + it("names the file of a Basis it can't read", () => { + expect(() => layerRows(FILE, layer("UX", [["widget/one", "Must", "It has a name", "WCAG 4.1.2 (AA)"]]))).toThrow( + /^3\.components\/widget\/2\.ux\.md: The Basis "WCAG 4\.1\.2 \(AA\)"/, + ); + }); + + it("names a column the table is missing", () => { + const source = "## UX Checklist\n\n| Rule | Level | Requirement |\n| - | - | - |\n| `widget/one` | Must | It has a name |\n"; + expect(() => layerRows(FILE, source)).toThrow(/has no Basis column/); + }); +}); + +describe("checklistPage", () => { + const COMPONENT = { title: "Widget", path: "/docs/components/widget" }; + const rows = (basis: string) => layerRows("3.components/widget/1.ui.md", layer("UI", [["widget/one", "Must", "It has contrast", basis]]))!; + + it("heads each layer with rows, and leaves out the rest", () => { + const page = checklistPage(COMPONENT, [rows("WCAG 1.4.3 (AA)")]); + expect(page.match(/^## .+$/gm)).toEqual(["## UI rules", "## Sources"]); + }); + + it("names, levels and links each criterion, and says None when there's none", () => { + expect(checklistPage(COMPONENT, [rows("WCAG 1.4.3, 1.4.11 (AA)")])).toContain( + "| [`widget/one`](/docs/components/widget/ui#ui-checklist) | Must | It has contrast | [1.4.3 Contrast (Minimum)](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html) (AA), [1.4.11 Non-text Contrast](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast.html) (AA) | WCAG 1.4.3, 1.4.11 (AA) |", + ); + expect(checklistPage(COMPONENT, [rows("WAI-ARIA, APG")])).toContain("| It has contrast | None | WAI-ARIA, APG |"); + }); + + it("lists WAI-ARIA and the APG under Sources only when a rule names them", () => { + const sources = (basis: string) => checklistPage(COMPONENT, [rows(basis)]).split("## Sources")[1]!; + expect(sources("WCAG 1.4.3 (AA)")).not.toMatch(/WAI-ARIA|APG/); + expect(sources("WAI-ARIA, APG")).toMatch(/\(WAI-ARIA\) 1\.2[\s\S]*Authoring Practices Guide \(APG\)/); + }); +}); + +describe("brokenLinks", () => { + const pages = new Map([ + ["/docs/components/widget", "---\ntitle: Widget\n---\n\n## Checklist\n"], + // The table's heading isn't `## UX Checklist`, so a link to #ux-checklist lands nowhere. + ["/docs/components/widget/ux", "---\ntitle: UX\n---\n\n## UX rules\n"], + ]); + + it("finds a link to a section the page doesn't have, or a page that doesn't exist", () => { + const page = [ + "[Widget](/docs/components/widget#checklist)", + "[one](/docs/components/widget/ux#ux-checklist)", + "[two](/docs/components/gadget#checklist)", + "[out](https://www.w3.org/TR/WCAG22/)", + ].join("\n"); + expect(brokenLinks(page, pages)).toEqual(["/docs/components/widget/ux#ux-checklist", "/docs/components/gadget#checklist"]); + }); +}); diff --git a/server/lib/checklists.ts b/server/lib/checklists.ts new file mode 100644 index 0000000..e5084d9 --- /dev/null +++ b/server/lib/checklists.ts @@ -0,0 +1,256 @@ +/** + * The accessibility checklists, content/docs/4.accessibility/<component>-checklist.md, + * one per component, served at /docs/accessibility/<component>-checklist. Each is + * built from its component's Checklist tables, the `## UI Checklist` to + * `## AX Checklist` on its layer pages, so it can't say anything they don't. + * checklists.test.ts fails when a page in content/docs/4.accessibility/ isn't what + * this builds, and `pnpm test -u server/lib/checklists.test.ts` writes them again. + * + * A checklist holds every rule whose Basis names WCAG, WAI-ARIA or the APG, on all + * four layers, and names each WCAG 2.2 criterion the Basis cites, from wcag.ts. The + * rules that rest only on HTML, or are Open Components' own, stay on the component's + * pages: the Basis can't tell the accessibility ones among them from the rest. + * + * Like raw.ts, it doesn't use Nitro's auto-imports. + */ + +import { readdirSync, readFileSync } from "node:fs"; +import { join } from "node:path"; +import { parse } from "yaml"; +import { anchors, cells, heading, scan } from "../../mcp/lib/markdown"; +import { docsPath } from "./raw"; +import { type Criterion, understandingUrl, WCAG, type WcagLevel } from "./wcag"; + +/** Where the checklists live in content/docs/, and where the components do. */ +export const CHECKLISTS = "4.accessibility"; +export const COMPONENTS = "3.components"; + +const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---\r?\n/; +// A layer page's rules table is under a heading like `## UX Checklist`. +const RULES = /^(\w+) Checklist$/; +// The rules a checklist holds: their Basis names one of these. +const PICKED = /\b(WCAG|WAI-ARIA|APG)\b/; +const COLUMNS = ["Rule", "Level", "Requirement", "Basis"] as const; + +export interface ChecklistRow { + /** The rule's ID, like `button/contrast`. */ + rule: string; + level: string; + requirement: string; + basis: string; + /** The WCAG 2.2 criteria its Basis cites, in the order it cites them. */ + criteria: (Criterion & { number: string })[]; + /** Its rules table on its layer page, like /docs/components/button/ui#ui-checklist. */ + link: string; +} + +export interface ChecklistLayer { + /** The layer's short name, like UI. */ + name: string; + rows: ChecklistRow[]; +} + +/** Whether a rule with this Basis goes on the accessibility checklist. */ +export function picked(basis: string): boolean { + return PICKED.test(basis); +} + +/** + * The WCAG 2.2 criteria a Basis cites, with the level each is at. A Basis names + * its criteria after `WCAG`, and gives their level after the last of each run, so + * `WCAG 1.3.1, 3.3.2, 4.1.2 (A), 2.4.6 (AA)` is three criteria at A and one at AA. + * It throws on a criterion that isn't in WCAG 2.2, a level that isn't the + * criterion's, or a run with no level, so a slip in a new rule fails `pnpm test` + * rather than reaching the page. + */ +export function citedCriteria(basis: string): (Criterion & { number: string })[] { + const found: (Criterion & { number: string })[] = []; + for (const match of basis.matchAll(/\bWCAG\s+/g)) { + let rest = basis.slice(match.index + match[0].length); + let pending: string[] = []; + for (;;) { + const next = rest.match(/^(\d+\.\d+\.\d+)(?:\s+\((A{1,3})\))?(?:,\s*|\s*$)/); + if (!next) break; + pending.push(next[1]!); + rest = rest.slice(next[0].length); + const level = next[2] as WcagLevel | undefined; + if (!level) continue; + for (const number of pending) { + const criterion = WCAG[number]; + if (!criterion) throw new Error(`The Basis "${basis}" cites WCAG ${number}, which isn't a WCAG 2.2 success criterion`); + if (criterion.level !== level) { + throw new Error(`The Basis "${basis}" gives WCAG ${number} level ${level}, but it's at level ${criterion.level} in WCAG 2.2`); + } + if (!found.some((other) => other.number === number)) found.push({ number, ...criterion }); + } + pending = []; + } + if (pending.length) throw new Error(`The Basis "${basis}" cites WCAG ${pending.join(", ")} without a level, like (A)`); + } + return found; +} + +/** + * The rules a layer page's table holds that go on the checklist, in the table's + * order, with the link to the table. `file` is the page's file in content/docs/, + * like 3.components/button/1.ui.md, and `source` its text. A page with no table, + * or none of whose rules go on the checklist, gives none. + */ +export function layerRows(file: string, source: string): ChecklistLayer | undefined { + const lines = scan(source.replace(FRONTMATTER, "")); + const slug = anchors(); + let layer: { name: string; anchor: string; columns?: Record<(typeof COLUMNS)[number], number> } | undefined; + const rows: ChecklistRow[] = []; + for (const { text, code } of lines) { + if (code) continue; + const match = heading(text); + if (match) { + // Every heading gets its anchor, in order, as the site gives them. + const anchor = slug(match.text); + if (match.level !== 2) continue; + if (layer) break; + const rules = match.text.match(RULES); + if (rules) layer = { name: rules[1]!, anchor }; + continue; + } + if (!layer || !text.startsWith("|")) continue; + const row = cells(text); + if (!layer.columns) { + const columns = Object.fromEntries(COLUMNS.map((name) => [name, row.indexOf(name)])); + const missing = COLUMNS.filter((name) => columns[name] === -1); + if (missing.length) throw new Error(`${file}: the ${layer.name} Checklist table has no ${missing.join(", ")} column`); + layer.columns = columns as Record<(typeof COLUMNS)[number], number>; + continue; + } + // The line under the header row. + if (row.every((cell) => /^:?-+:?$/.test(cell))) continue; + const basis = row[layer.columns.Basis]!; + if (!picked(basis)) continue; + let criteria: ChecklistRow["criteria"]; + try { + criteria = citedCriteria(basis); + } catch (error) { + throw new Error(`${file}: ${(error as Error).message}`); + } + rows.push({ + rule: row[layer.columns.Rule]!.replaceAll("`", ""), + level: row[layer.columns.Level]!, + requirement: row[layer.columns.Requirement]!, + basis, + criteria, + link: `${docsPath(file)}#${layer.anchor}`, + }); + } + return layer && rows.length ? { name: layer.name, rows } : undefined; +} + +/** + * A component's accessibility checklist page, from its title, like "Checkbox Group", + * the path of its Overview, like /docs/components/checkbox-group, and its layers' + * rows, in layer order. + */ +export function checklistPage(component: { title: string; path: string }, layers: ChecklistLayer[]): string { + const { title, path } = component; + const rows = layers.flatMap((layer) => layer.rows); + const cites = (pattern: RegExp) => rows.some((row) => pattern.test(row.basis)); + const sources = [ + `- [Web Content Accessibility Guidelines (WCAG) 2.2](https://www.w3.org/TR/WCAG22/), for each success criterion's number, short name and level`, + `- [Understanding WCAG 2.2](https://www.w3.org/WAI/WCAG22/Understanding/), which each criterion links to`, + ...(cites(/\bWAI-ARIA\b/) ? [`- [Accessible Rich Internet Applications (WAI-ARIA) 1.2](https://www.w3.org/TR/wai-aria-1.2/)`] : []), + ...(cites(/\bAPG\b/) ? [`- [WAI-ARIA Authoring Practices Guide (APG)](https://www.w3.org/WAI/ARIA/apg/)`] : []), + ...(cites(/\bARIA in HTML\b/) ? [`- [ARIA in HTML](https://www.w3.org/TR/html-aria/)`] : []), + `- [${title}](${path}), where each rule is explained, with the sources it draws on`, + ]; + return [ + "---", + `title: Accessible ${title} Checklist (WCAG)`, + `description: Every ${title} rule that WCAG 2.2, WAI-ARIA or the APG backs, in one checklist, with the success criteria behind each rule and their level.`, + "navigation:", + ` title: ${title}`, + "---", + "", + `Here's every rule for the [${title}](${path}) that WCAG 2.2, WAI-ARIA or the APG backs, in one list you can work through when you build or review one. Each row names the WCAG 2.2 success criteria behind its rule, with their level, and links to the rule's table on its layer's page, where we explain why it's there. A rule that rests on WAI-ARIA or the APG alone says "None".`, + "", + `We build this list from the ${title}'s checklists, so it always matches them. It leaves out the rules that rest only on HTML and the ones that are our own, so you'll find every rule in the [${title}'s checklist](${path}#checklist).`, + "", + ...layers.flatMap((layer) => [ + `## ${layer.name} rules`, + "", + "| Rule | Level | Requirement | WCAG 2.2 | Basis |", + "| ---- | ----- | ----------- | -------- | ----- |", + ...layer.rows.map((row) => + [ + `[\`${row.rule}\`](${row.link})`, + row.level, + row.requirement, + row.criteria.length + ? row.criteria.map((criterion) => `[${criterion.number} ${criterion.name}](${understandingUrl(criterion)}) (${criterion.level})`).join(", ") + : "None", + row.basis, + ] + .map((cell) => cell.replaceAll("|", "\\|")) + .join(" | "), + ).map((row) => `| ${row} |`), + "", + ]), + "## Sources", + "", + ...sources, + "", + ].join("\n"); +} + +/** + * Every component's checklist, by its file in content/docs/ (`docs`), like + * 4.accessibility/button-checklist.md, built from the component's folder in + * 3.components/: its Overview's title and its layer pages, 1.ui.md to 4.ax.md. + */ +export function readChecklists(docs: string): Map<string, string> { + const pages = new Map<string, string>(); + const folders = readdirSync(join(docs, COMPONENTS), { withFileTypes: true }) + .filter((entry) => entry.isDirectory()) + .map((entry) => entry.name) + .sort(); + for (const folder of folders) { + const dir = join(COMPONENTS, folder); + const index = readFileSync(join(docs, dir, "index.md"), "utf8"); + const { title } = (parse(index.match(FRONTMATTER)?.[1] ?? "") ?? {}) as { title?: unknown }; + if (typeof title !== "string") throw new Error(`${dir}/index.md has no title`); + const layers = readdirSync(join(docs, dir)) + .filter((name) => /^\d+\..+\.md$/.test(name)) + .sort((a, b) => a.localeCompare(b, "en", { numeric: true })) + .flatMap((name) => layerRows(join(dir, name), readFileSync(join(docs, dir, name), "utf8")) ?? []); + pages.set(join(CHECKLISTS, `${folder}-checklist.md`), checklistPage({ title, path: docsPath(join(dir, "index.md")) }, layers)); + } + return pages; +} + +/** + * The links in a page's markdown to a docs page that doesn't exist, or to a + * section it doesn't have. `pages` holds every docs page's source by its path on + * the site, a split page's parts each under their own, as the site serves them. + */ +export function brokenLinks(markdown: string, pages: Map<string, string>): string[] { + const broken: string[] = []; + for (const { text, code } of scan(markdown.replace(FRONTMATTER, ""))) { + if (code) continue; + for (const [, path, anchor] of text.matchAll(/\]\((\/docs\/[^)#\s]*)(?:#([^)\s]+))?\)/g)) { + const source = pages.get(path!); + if (source === undefined) { + broken.push(`${path}${anchor ? `#${anchor}` : ""}`); + continue; + } + if (anchor && !headingAnchors(source).includes(anchor)) broken.push(`${path}#${anchor}`); + } + } + return broken; +} + +// Every heading's anchor on a page, as the site gives them. +function headingAnchors(source: string): string[] { + const slug = anchors(); + return scan(source.replace(FRONTMATTER, "")).flatMap(({ text, code }) => { + const match = !code && heading(text); + return match ? [slug(match.text)] : []; + }); +} diff --git a/server/lib/wcag.ts b/server/lib/wcag.ts new file mode 100644 index 0000000..a9f1a2d --- /dev/null +++ b/server/lib/wcag.ts @@ -0,0 +1,119 @@ +/** + * The success criteria of WCAG 2.2 (https://www.w3.org/TR/WCAG22/), by number: + * each one's short name, its level and the slug of its Understanding page, like + * https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html. The + * accessibility checklists (checklists.ts) name and link every criterion a rule's + * Basis cites from here. + * + * It holds nothing else from WCAG, since the guidelines are CC BY 4.0 and WCAG + * isn't: a criterion's number and short name are how everyone cites it. 4.1.1 + * Parsing isn't here, since WCAG 2.2 removed it. + * + * Like raw.ts, it doesn't use Nitro's auto-imports. + */ + +export type WcagLevel = "A" | "AA" | "AAA"; + +export interface Criterion { + name: string; + level: WcagLevel; + slug: string; +} + +export const WCAG: Readonly<Record<string, Criterion>> = { + "1.1.1": { name: "Non-text Content", level: "A", slug: "non-text-content" }, + "1.2.1": { name: "Audio-only and Video-only (Prerecorded)", level: "A", slug: "audio-only-and-video-only-prerecorded" }, + "1.2.2": { name: "Captions (Prerecorded)", level: "A", slug: "captions-prerecorded" }, + "1.2.3": { + name: "Audio Description or Media Alternative (Prerecorded)", + level: "A", + slug: "audio-description-or-media-alternative-prerecorded", + }, + "1.2.4": { name: "Captions (Live)", level: "AA", slug: "captions-live" }, + "1.2.5": { name: "Audio Description (Prerecorded)", level: "AA", slug: "audio-description-prerecorded" }, + "1.2.6": { name: "Sign Language (Prerecorded)", level: "AAA", slug: "sign-language-prerecorded" }, + "1.2.7": { name: "Extended Audio Description (Prerecorded)", level: "AAA", slug: "extended-audio-description-prerecorded" }, + "1.2.8": { name: "Media Alternative (Prerecorded)", level: "AAA", slug: "media-alternative-prerecorded" }, + "1.2.9": { name: "Audio-only (Live)", level: "AAA", slug: "audio-only-live" }, + "1.3.1": { name: "Info and Relationships", level: "A", slug: "info-and-relationships" }, + "1.3.2": { name: "Meaningful Sequence", level: "A", slug: "meaningful-sequence" }, + "1.3.3": { name: "Sensory Characteristics", level: "A", slug: "sensory-characteristics" }, + "1.3.4": { name: "Orientation", level: "AA", slug: "orientation" }, + "1.3.5": { name: "Identify Input Purpose", level: "AA", slug: "identify-input-purpose" }, + "1.3.6": { name: "Identify Purpose", level: "AAA", slug: "identify-purpose" }, + "1.4.1": { name: "Use of Color", level: "A", slug: "use-of-color" }, + "1.4.2": { name: "Audio Control", level: "A", slug: "audio-control" }, + "1.4.3": { name: "Contrast (Minimum)", level: "AA", slug: "contrast-minimum" }, + "1.4.4": { name: "Resize Text", level: "AA", slug: "resize-text" }, + "1.4.5": { name: "Images of Text", level: "AA", slug: "images-of-text" }, + "1.4.6": { name: "Contrast (Enhanced)", level: "AAA", slug: "contrast-enhanced" }, + "1.4.7": { name: "Low or No Background Audio", level: "AAA", slug: "low-or-no-background-audio" }, + "1.4.8": { name: "Visual Presentation", level: "AAA", slug: "visual-presentation" }, + "1.4.9": { name: "Images of Text (No Exception)", level: "AAA", slug: "images-of-text-no-exception" }, + "1.4.10": { name: "Reflow", level: "AA", slug: "reflow" }, + "1.4.11": { name: "Non-text Contrast", level: "AA", slug: "non-text-contrast" }, + "1.4.12": { name: "Text Spacing", level: "AA", slug: "text-spacing" }, + "1.4.13": { name: "Content on Hover or Focus", level: "AA", slug: "content-on-hover-or-focus" }, + "2.1.1": { name: "Keyboard", level: "A", slug: "keyboard" }, + "2.1.2": { name: "No Keyboard Trap", level: "A", slug: "no-keyboard-trap" }, + "2.1.3": { name: "Keyboard (No Exception)", level: "AAA", slug: "keyboard-no-exception" }, + "2.1.4": { name: "Character Key Shortcuts", level: "A", slug: "character-key-shortcuts" }, + "2.2.1": { name: "Timing Adjustable", level: "A", slug: "timing-adjustable" }, + "2.2.2": { name: "Pause, Stop, Hide", level: "A", slug: "pause-stop-hide" }, + "2.2.3": { name: "No Timing", level: "AAA", slug: "no-timing" }, + "2.2.4": { name: "Interruptions", level: "AAA", slug: "interruptions" }, + "2.2.5": { name: "Re-authenticating", level: "AAA", slug: "re-authenticating" }, + "2.2.6": { name: "Timeouts", level: "AAA", slug: "timeouts" }, + "2.3.1": { name: "Three Flashes or Below Threshold", level: "A", slug: "three-flashes-or-below-threshold" }, + "2.3.2": { name: "Three Flashes", level: "AAA", slug: "three-flashes" }, + "2.3.3": { name: "Animation from Interactions", level: "AAA", slug: "animation-from-interactions" }, + "2.4.1": { name: "Bypass Blocks", level: "A", slug: "bypass-blocks" }, + "2.4.2": { name: "Page Titled", level: "A", slug: "page-titled" }, + "2.4.3": { name: "Focus Order", level: "A", slug: "focus-order" }, + "2.4.4": { name: "Link Purpose (In Context)", level: "A", slug: "link-purpose-in-context" }, + "2.4.5": { name: "Multiple Ways", level: "AA", slug: "multiple-ways" }, + "2.4.6": { name: "Headings and Labels", level: "AA", slug: "headings-and-labels" }, + "2.4.7": { name: "Focus Visible", level: "AA", slug: "focus-visible" }, + "2.4.8": { name: "Location", level: "AAA", slug: "location" }, + "2.4.9": { name: "Link Purpose (Link Only)", level: "AAA", slug: "link-purpose-link-only" }, + "2.4.10": { name: "Section Headings", level: "AAA", slug: "section-headings" }, + "2.4.11": { name: "Focus Not Obscured (Minimum)", level: "AA", slug: "focus-not-obscured-minimum" }, + "2.4.12": { name: "Focus Not Obscured (Enhanced)", level: "AAA", slug: "focus-not-obscured-enhanced" }, + "2.4.13": { name: "Focus Appearance", level: "AAA", slug: "focus-appearance" }, + "2.5.1": { name: "Pointer Gestures", level: "A", slug: "pointer-gestures" }, + "2.5.2": { name: "Pointer Cancellation", level: "A", slug: "pointer-cancellation" }, + "2.5.3": { name: "Label in Name", level: "A", slug: "label-in-name" }, + "2.5.4": { name: "Motion Actuation", level: "A", slug: "motion-actuation" }, + "2.5.5": { name: "Target Size (Enhanced)", level: "AAA", slug: "target-size-enhanced" }, + "2.5.6": { name: "Concurrent Input Mechanisms", level: "AAA", slug: "concurrent-input-mechanisms" }, + "2.5.7": { name: "Dragging Movements", level: "AA", slug: "dragging-movements" }, + "2.5.8": { name: "Target Size (Minimum)", level: "AA", slug: "target-size-minimum" }, + "3.1.1": { name: "Language of Page", level: "A", slug: "language-of-page" }, + "3.1.2": { name: "Language of Parts", level: "AA", slug: "language-of-parts" }, + "3.1.3": { name: "Unusual Words", level: "AAA", slug: "unusual-words" }, + "3.1.4": { name: "Abbreviations", level: "AAA", slug: "abbreviations" }, + "3.1.5": { name: "Reading Level", level: "AAA", slug: "reading-level" }, + "3.1.6": { name: "Pronunciation", level: "AAA", slug: "pronunciation" }, + "3.2.1": { name: "On Focus", level: "A", slug: "on-focus" }, + "3.2.2": { name: "On Input", level: "A", slug: "on-input" }, + "3.2.3": { name: "Consistent Navigation", level: "AA", slug: "consistent-navigation" }, + "3.2.4": { name: "Consistent Identification", level: "AA", slug: "consistent-identification" }, + "3.2.5": { name: "Change on Request", level: "AAA", slug: "change-on-request" }, + "3.2.6": { name: "Consistent Help", level: "A", slug: "consistent-help" }, + "3.3.1": { name: "Error Identification", level: "A", slug: "error-identification" }, + "3.3.2": { name: "Labels or Instructions", level: "A", slug: "labels-or-instructions" }, + "3.3.3": { name: "Error Suggestion", level: "AA", slug: "error-suggestion" }, + "3.3.4": { name: "Error Prevention (Legal, Financial, Data)", level: "AA", slug: "error-prevention-legal-financial-data" }, + "3.3.5": { name: "Help", level: "AAA", slug: "help" }, + "3.3.6": { name: "Error Prevention (All)", level: "AAA", slug: "error-prevention-all" }, + "3.3.7": { name: "Redundant Entry", level: "A", slug: "redundant-entry" }, + "3.3.8": { name: "Accessible Authentication (Minimum)", level: "AA", slug: "accessible-authentication-minimum" }, + "3.3.9": { name: "Accessible Authentication (Enhanced)", level: "AAA", slug: "accessible-authentication-enhanced" }, + "4.1.2": { name: "Name, Role, Value", level: "A", slug: "name-role-value" }, + "4.1.3": { name: "Status Messages", level: "AA", slug: "status-messages" }, +}; + +/** The Understanding WCAG 2.2 page for a criterion, by its slug. */ +export function understandingUrl(criterion: Criterion): string { + return `https://www.w3.org/WAI/WCAG22/Understanding/${criterion.slug}.html`; +}