Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions .github/CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/<path>.md` and the contract, and through `readPages()` for the contracts `nuxt.config.ts` lists and the MCP server. Each part's own `/raw/<path>.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 <component> 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:
Expand Down
4 changes: 3 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/<component>/` | The tested Vue 3 reference implementations, which every page shows as code |
Expand All @@ -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/<component>/` 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.
Expand All @@ -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 <title> - 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]`.
Expand Down
17 changes: 17 additions & 0 deletions content/changelog/accessibility-checklists.md
Original file line number Diff line number Diff line change
@@ -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.
2 changes: 2 additions & 0 deletions content/docs/4.accessibility/.navigation.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
title: Accessibility Checklists
icon: i-lucide-list-checks
56 changes: 56 additions & 0 deletions content/docs/4.accessibility/button-checklist.md
Original file line number Diff line number Diff line change
@@ -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
Loading