automatica11y 0.3.3 → 0.4.0

package/README.md

@@ -36,7 +36,7 @@ A target is `[label=]<spec>`. The label is optional, and names the target in the
 | A live page | `https://example.com/page` |
 | A local page or site | `./page.html` or `./dist`. A path with no prefix is relative to the working folder, so `dist` means `./dist`. Prefixes `../`, `/`, `~`, and `file:` work too. |
 | A Storybook | Its URL, or a local folder with `index.json` or `stories.json`. |
-| An npm package | `npm:name`, `npm:@scope/name`, or `npm:name@version`. React and web component libraries work. |
+| An npm package | `npm:name`, `npm:@scope/name`, or `npm:name@version`. Add a sub-path to test one entry of a package: `npm:@scope/pkg/button` or `npm:@scope/pkg@1.2.3/button/v2`. React, Vue 3, and web component libraries work. |
 
 A bare word such as `button` is a path: the folder or file `./button`. Write `npm:button` to pick the package. The prefix is what chooses a package, so a folder with the same name never gets in the way. A bare word that isn't a path fails with a hint, such as "If you meant the npm package, write npm:react."
 
@@ -44,11 +44,21 @@ A local `.html` file is served over `http://localhost`, never `file://`. A stati
 
 ## What it checks.
 
-Four tiers run by default. Use `--tiers` to pick fewer.
+Five tiers run by default. Use `--tiers` to pick fewer.
 
 - **Rules.** axe-core and IBM Equal Access run side by side. They overlap, and each catches things the other misses. Their findings are reported separately and never added together. axe-core reports an impact (`minor` to `critical`). IBM reports its Toolkit level, a staged adoption scale where level 1 is essential, high-impact requirements. The two scales aren't comparable.
-- **Interactions.** Keyboard and focus checks for nine archetypes: button, link, dialog, menu, tabs, combobox, form-field, accordion, and tooltip. Each check runs on a fresh page.
+- **Interactions.** Keyboard and focus checks for ten archetypes: button, link, dialog, menu, tabs, combobox, form-field, accordion, tooltip, and live-region (a message that appears or changes without moving focus, such as an alert or status message). Each check runs on a fresh page.
 - **Computed checks.** automatica11y's own measurements from resolved styles in the browser, for the trigger of each archetype fixture: text contrast in rest, hover, keyboard focus, and pressed states (1.4.3), the contrast of the control's edge, fill, or icon (1.4.11), and the contrast and thickness of the focus indicator (1.4.11, and 2.4.13 at level AAA). A page that uses a gradient, an image, or transparency behind the control can't be reduced to one color, so that check reports `undetermined`, which is a gap and never a pass. These results are reported on their own and never added to the rule engines' counts.
+- **Conditions.** How the page holds up under a user's settings and environment. Each check opens fresh copies of the page and says what happened:
+  - `prefers-reduced-motion: reduce` (2.3.3, 2.2.2): do animations that move or repeat stop or go away? Motion driven by JavaScript timers isn't visible to this check.
+  - `prefers-color-scheme: dark` (1.4.3): if the page changes in dark mode, does every piece of text keep its contrast? A page that doesn't adapt isn't failed.
+  - `prefers-contrast: more` (1.4.3, 1.4.6): if the page responds, does the lowest text contrast stay above the minimum and not drop? The check says whether enhanced contrast (7:1) is reached. `prefers-contrast: less` (1.4.3): if the page softens, does text stay above the minimum? A page that doesn't respond isn't failed.
+  - `prefers-reduced-transparency: reduce` (1.4.3, 1.4.11): do surfaces that hold text stop being see-through (translucent backgrounds, backdrop blur)? This preference isn't a WCAG requirement. It matters because see-through backgrounds make text contrast unpredictable.
+  - Forced colors (1.4.11, 2.4.7): is the focus indicator still visible? A ring drawn with `box-shadow` disappears in forced colors, so use an outline.
+  - Reflow at 320 CSS pixels (1.4.10): does the page scroll sideways, or does anything reach past the right edge? Two-dimensional content such as data tables and maps is exempt, so a person judges those.
+  - Text spacing (1.4.12): with the spacing the criterion names, does any element cut off its text? Overlapping text isn't checked.
+
+  Conditions run on whole pages and on component fixtures. Storybook stories are reported as not applicable.
 - **Virtual screen reader.** The announcements a simulated screen reader makes, recorded as data. The output is simulated. It isn't a real screen reader, and real ones announce things differently.
 
 Every result says what it ran, or why it didn't. A gap, a failure, or a result that can't be tested is a finding. It never counts as a pass.
@@ -60,10 +70,11 @@ Every result says what it ran, or why it didn't. A gap, a failure, or a result t
 | `--wcag 2.0\|2.1\|2.2` | `2.2` | The WCAG version. |
 | `--level A\|AA\|AAA` | `AA` | The conformance level. IBM Equal Access has no AAA rules, so it runs its AA rules and says so. |
 | `--engine axe,ibm` | both | Which rule engines run. |
-| `--tiers rules,interactions,computed,vsr` | all | Which tiers run. |
+| `--tiers rules,interactions,computed,conditions,vsr` | all | Which tiers run. |
 | `--archetypes a,b` | all | Limit npm and Storybook targets to these archetypes. |
 | `--lib-a11y on,off` | both | For libraries with opt-in accessibility features. See [the fixture guide](skills/automatica11y-runner/references/fixtures.md). |
 | `--mapping <file>` | none | A mapping file for npm targets. |
+| `--no-generate` | off | Don't build fixtures for npm packages. Only authored fixtures and the `button` and `link` templates run. |
 | `--max-stories <n>` | `200` | The Storybook story cap. The cap spreads over components. |
 | `--out <dir>` | `./a11y-report` | Where results go. |
 | `--plan` | off | Classify the targets and write `plan.json`, then stop. Nothing installs and no browser launches. |
@@ -96,7 +107,14 @@ One failing target doesn't stop a comparison. It's recorded with its reason, and
 
 The tool installs each package into its own temporary folder (with install scripts turned off), loads it in the browser, and finds its exports or custom elements. It writes its guesses to `mapping.json`.
 
-It builds `button` and `link` tests on its own. Every other archetype is built from parts that differ by library (`Dialog.Root`, `Dialog.Trigger`, and so on), so it needs a **fixture**: a small file you or your agent write, following [the fixture guide](skills/automatica11y-runner/references/fixtures.md). Put fixtures at `fixtures/<target id>/<archetype>.jsx` (`.js` for web components) and run again. An archetype without a fixture is a gap in the report.
+Each archetype's fixture comes from the first of these that applies:
+
+1. **Authored.** A file you or your agent write at `fixtures/<target id>/<archetype>.jsx` (`.js` for web components). The same `.jsx` works for React and for Vue 3, following [the fixture guide](skills/automatica11y-runner/references/fixtures.md). It always wins.
+2. **Template.** The tool builds `button` and `link` tests from the export name alone.
+3. **Generated.** For dialog, menu, tooltip, tabs, accordion, combobox, form-field, and live-region, the tool builds candidate fixtures from what the package exports. It looks for compound parts by common names (a root, a trigger, a content part, a title, a close part, and so on), either as `Dialog.Root` or as `DialogRoot`, and it tries the usual ways of switching a component on (an `open` prop and a close handler). For web components it reads what each element says about itself: its observed attributes, its members, and its slots. It then bundles each candidate, loads it, and checks that exactly one element is the trigger, that nothing logged an error, that activating the trigger shows a root, and that the root carries a role that fits. The first candidate that passes is used. If none does, the archetype is a gap, and the report lists what was tried and why each attempt failed.
+4. **Gap.** Anything else is a gap in the report.
+
+A generated fixture is a guess about how the library is meant to be assembled, so a failure may come from how it was wired and not from the library. Reports mark generated results and treat them as lower evidence than an authored fixture. The source of each generated fixture is written to `generated/<target id>/<archetype>.jsx` beside the report. Copy one to `fixtures/<target id>/` and edit it to make it an authored fixture. Use `--no-generate` to turn generation off, for example when you want a strict comparison of authored fixtures only.
 
 Fixtures are code that the tool bundles and runs in a browser on your machine. Write them from the library's documentation, and read ones you didn't write.
 
@@ -119,9 +137,9 @@ The guidance ships with the tool, so it always matches the version you run. Tell
 ## Limits.
 
 - Automated rules find only part of what WCAG covers. They can't judge whether alt text is meaningful, whether link and heading text make sense in context, cognitive load, real focus and reading order in use, or how real screen readers behave. A person has to check those.
-- Components are tested in the states a fixture shows. Dialogs, menus, tooltips, and comboboxes run closed and open. Other states aren't visited.
+- Components are tested in the states a fixture shows. Dialogs, menus, tooltips, and comboboxes run closed and open, and live regions run before and after the message. Other states aren't visited.
 - Content on a canvas with no alternative, or inside a closed shadow root, can't be tested, and the report says so. The virtual screen reader can't read inside shadow roots at all.
-- Vue, Svelte, Angular, and other frameworks report "unsupported framework."
+- Svelte, Angular, Vue 2, and other frameworks report "unsupported framework." Their Storybooks work, because a Storybook renders stories in a page whatever the framework.
 - Native screen readers aren't part of this version.
 - Results are a snapshot. The tools run at their latest versions, and the report records them.
 

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "automatica11y",
-  "version": "0.3.3",
+  "version": "0.4.0",
   "description": "Test and compare the accessibility of web pages, Storybook builds, and npm component libraries.",
   "license": "MIT",
   "type": "module",
   "bin": {
-    "automatica11y": "bin/automatica11y.js"
+    "automatica11y": "bin/automatica11y.js",
+    "a11y": "bin/automatica11y.js"
   },
   "files": [
     "bin",
@@ -35,7 +36,8 @@
     "@types/node": "^26.6.4",
     "react": "^19.3.0",
     "react-dom": "^19.3.0",
-    "typescript": "^7.0.2"
+    "typescript": "^7.0.2",
+    "vue": "^3.5.43"
   },
   "publishConfig": {
     "access": "public"

package/skills/automatica11y-runner/SKILL.md

@@ -16,13 +16,13 @@ The tool is **not** an attestation or certification tool. Automated checks cover
 
 Do sections 1 and 2 before you run an audit. A question to the user about a missing target or an unsupported setting (section 3) can come before or after them.
 
-This skill works with automatica11y **0.3.x**. Run:
+This skill works with automatica11y **0.4.x**. Run:
 
 ```bash
 npx --yes automatica11y@latest --version
 ```
 
-If the command exits with an error or prints nothing, tell the user it failed, include the error text, and stop. If the output doesn't start with `0.3.`, stop. Tell the user the version you got and the series this copy expects (`0.3.x`). If this copy came from a file, offer to read the matching steps with `npx --yes automatica11y@latest guide skill`. Don't run an audit until the user confirms how to proceed.
+If the command exits with an error or prints nothing, tell the user it failed, include the error text, and stop. If the output doesn't start with `0.4.`, stop. Tell the user the version you got and the series this copy expects (`0.4.x`). If this copy came from a file, offer to read the matching steps with `npx --yes automatica11y@latest guide skill`. Don't run an audit until the user confirms how to proceed.
 
 ## 2. Check the setup
 
@@ -48,7 +48,7 @@ Use `audit` for one target and `compare` for two or more, even when they're diff
 | A live page | `https://example.com/page` |
 | A local page or site | `./page.html` or `./dist`. A path with no prefix is relative to the working folder. |
 | A Storybook | its URL, or a local folder with `index.json` |
-| An npm package | `npm:name`, `npm:@scope/name`, or `npm:name@version` |
+| An npm package | `npm:name`, `npm:@scope/name`, or `npm:name@version`. To test one entry of a package, add a sub-path after the version: `npm:@scope/pkg/button` or `npm:@scope/pkg@1.2.3/button/v2`. The sub-path is what a person would import (`import ... from "@scope/pkg/button"`), and it has to be something the package exports. |
 
 A bare word such as `button` is a path: the folder or file `./button`. Always write an npm package with the `npm:` prefix. If a word could mean a package or a folder, ask the user which one before you run anything.
 
@@ -59,10 +59,11 @@ Options you can set, and nothing else:
 | `--wcag 2.0\|2.1\|2.2` | `2.2` | The user names a WCAG version. |
 | `--level A\|AA\|AAA` | `AA` | The user names a level. IBM Equal Access has no AAA rules, so it runs its AA rules and says so. |
 | `--engine axe,ibm` | both | The user wants one rule engine. |
-| `--tiers rules,interactions,computed,vsr` | all four | The user wants fewer checks. |
-| `--archetypes a,b` | all | The user cares about some components. Choose from button, link, dialog, menu, tabs, combobox, form-field, accordion, tooltip, chart. |
+| `--tiers rules,interactions,computed,conditions,vsr` | all five | The user wants fewer checks. |
+| `--archetypes a,b` | all | The user cares about some components. Choose from button, link, dialog, menu, tabs, combobox, form-field, accordion, tooltip, live-region, chart. |
 | `--lib-a11y on,off` | both | Only for libraries with opt-in accessibility features. |
 | `--mapping <file>` | none | You wrote or edited a mapping file. |
+| `--no-generate` | off | The user wants only authored fixtures and the `button` and `link` templates, with no generated ones. |
 | `--max-stories <n>` | 200 | A large Storybook. |
 | `--out <dir>` | `./a11y-report` | The user names a folder. |
 | `--plan` | off | You want to see how targets classify without running anything. |
@@ -80,20 +81,26 @@ Don't set the fail flags unless the user asks for gating. They change the exit c
 
 ## 4. npm packages need fixtures
 
-A package's components can't be guessed from its name. The first run installs the package, loads it in the browser, finds its exports (or custom elements), and writes a candidate mapping to `<out>/mapping.json`. It tests `button` and `link` from a template. Every other archetype needs a **fixture**, a small file that assembles the component the way the library intends.
+A package's components can't be guessed from its name alone. The first run installs the package, loads it in the browser, finds its exports (or custom elements), and writes a candidate mapping to `<out>/mapping.json`. It then fills each archetype from the first source that applies:
 
-1. Run the audit once. Read `<out>/mapping.json` and the report's **Archetypes** table.
+- **Authored.** A **fixture** you write: a small file that assembles the component the way the library intends. It always wins.
+- **Template.** The tool builds `button` and `link` from the export name.
+- **Generated.** For dialog, menu, tooltip, tabs, accordion, combobox, form-field, and live-region, the tool builds candidates from the package's compound parts (or from what a custom element says about itself), runs each in the browser, and keeps the first that behaves: one trigger, no errors, a root that appears with a fitting role. The `--no-generate` option turns this off.
+- **Gap.** If none of those worked, the report lists what was tried and why each attempt failed.
+
+1. Run the audit once. Read `<out>/mapping.json` and the report's **Archetypes** table, which has a **Fixture** column.
 2. Treat the mapping as a guess. Check each `export` or `tag` against what the user asked about.
-3. Each archetype in `mapping.json` has a status. `needs-fixture` means the tool found the component but can't build it from a template. `no-match` means no export or custom element looks like that archetype. For each archetype marked `needs-fixture` that matters to the request, write `fixtures/<target id>/<archetype>.jsx` (`.js` for web components) in the working directory. Follow the contract and the examples below. `references/fixtures.md` has more: the mapping file, states, and library accessibility options. It should sit next to this file. If you can't open it, run `npx --yes automatica11y@latest guide fixtures` to print it. The contract here is enough for the first fixture.
+3. Each archetype in `mapping.json` has a status. `generated` means the tool built a fixture that passed its checks, and the source is in `<out>/generated/`. `needs-fixture` means the tool found the component but couldn't build a working fixture. `no-match` means no export or custom element looks like that archetype. For each archetype marked `needs-fixture` that matters to the request, write `fixtures/<target id>/<archetype>.jsx` (`.js` for web components) in the working directory. Follow the contract and the examples below. `references/fixtures.md` has more: the mapping file, states, and library accessibility options. It should sit next to this file. If you can't open it, run `npx --yes automatica11y@latest guide fixtures` to print it. The contract here is enough for the first fixture.
 4. Run the same command again. The tool finds fixtures in that folder without `--mapping`.
-5. Don't invent fixtures for archetypes the user didn't ask about. For a `no-match` archetype, write a fixture only if the library's documentation names a component, or a documented way, to make it. Otherwise leave it as a gap. A gap is an honest result.
+5. For an archetype that matters, read the generated source before you rely on it. If it looks wrong for the library, write an authored fixture from the documentation. To keep a generated one, copy it from `<out>/generated/<target id>/` into `fixtures/<target id>/`.
+6. Don't invent fixtures for archetypes the user didn't ask about. For a `no-match` archetype, write a fixture only if the library's documentation names a component, or a documented way, to make it. Otherwise leave it as a gap. A gap is an honest result.
 
 **The fixture contract, in brief.**
 
 - The default export renders the archetype in its starting state. For web components, the default export is the function `mount(container)`.
 - Mark **exactly one** element `data-a11y-trigger`. It's what a person would focus and activate. If nothing can be activated, as with a chart, put both attributes on the same outermost element.
 - Mark the main surface `data-a11y-root`, on the element that carries the role (`dialog`, `menu`, `tooltip`), not on an overlay or portal wrapper. It may appear only after the trigger fires, and it may render in a portal.
-- Mount without console errors. Don't import CSS.
+- Mount without console errors. If the library's documentation says to load a stylesheet, import it. When it comes from another package, list that package under `install` in the mapping file (`references/fixtures.md` has the shape).
 - The attributes have to reach the DOM. If a component drops unknown props, use the library's documented way to render your own element in its place (such as `asChild` in Radix, or the `as` prop in Headless UI), and mark that element. If the library has none, leave the archetype as a gap. Don't wrap the library's component in an element you add and mark that.
 
 A React fixture. JSX works without importing React. Import the library from its package name, and the tool installs it:
@@ -118,6 +125,28 @@ export default function Fixture() {
 }
 ```
 
+A Vue 3 fixture. It's also JSX, and a function default export is a functional component. The tool turns JSX into `h()` calls and supplies `h` and `Fragment`, so **don't import `h`**. Children become the default slot. A fixture that needs a plugin or global setup can also export `setup(app)`, which runs before the app mounts. Import the library from its package name, and the tool installs it along with Vue:
+
+```jsx
+import { DialogClose, DialogContent, DialogDescription, DialogOverlay, DialogPortal, DialogRoot, DialogTitle, DialogTrigger } from "reka-ui";
+
+export default function Fixture() {
+  return (
+    <DialogRoot>
+      <DialogTrigger data-a11y-trigger>Open dialog</DialogTrigger>
+      <DialogPortal>
+        <DialogOverlay />
+        <DialogContent data-a11y-root>
+          <DialogTitle>Edit profile</DialogTitle>
+          <DialogDescription>Update your details.</DialogDescription>
+          <DialogClose>Close</DialogClose>
+        </DialogContent>
+      </DialogPortal>
+    </DialogRoot>
+  );
+}
+```
+
 A web component fixture. The tool imports the package first, so its elements are defined before `mount` runs. The `data-a11y-trigger` and `data-a11y-root` attributes can sit on a host, a slotted child, or an element inside an open shadow root. A closed shadow root hides its content from every tool:
 
 ```js
@@ -164,8 +193,10 @@ Write the narrative from `results.json`. Never write from memory, and never repe
 10. If the comparison mixes component targets and page targets, open with a warning that the evidence isn't equivalent.
 11. Label every rule finding with its engine. Report axe-core and IBM Equal Access separately. Never add their counts together. Impact is axe-core's own label. IBM Toolkit level is IBM's staged adoption scale (1 is essential, high-impact requirements). Don't convert one into the other.
 12. Report computed checks (contrast measured from resolved styles) in their own section. Give the measured ratio next to the ratio the criterion needs, and name the state or the method. Never add them to axe-core or IBM counts. Treat `undetermined` as a gap, never as a pass. When a control has visible text and a pale edge, the result is `not-applicable`, because the text identifies the control. Say that, and leave it for a person to confirm.
-13. When you name a WCAG criterion, use the number and name exactly as `report.md` prints them, and keep its "WCAG data" credit to the W3C. Don't write criterion names or levels from memory.
-14. End with a plain method note. Say what automated tools can't catch: whether alt text is meaningful, whether link and heading text make sense in context, cognitive load, real focus and reading order in use, and how real screen readers behave. Those need a person.
+13. Report conditions checks (reduced motion, dark mode, more and less contrast, reduced transparency, forced colors, reflow at 320 pixels, text spacing) in their own section, with the numbers from `results.json`. Never add them to axe-core or IBM counts. "Not applicable" means the page doesn't use the feature, such as a page with no dark theme, so don't list it as a failure or a pass. Say what each check can't see: JavaScript-driven motion, overlapping text, and two-dimensional content that WCAG exempts from reflow.
+14. Say which results come from generated fixtures. A generated fixture is a guess about how the library is assembled, so a failure may come from the wiring and not from the library. Call those results lower evidence than an authored fixture, name the recipe from the **Fixture** column, and don't compare a generated result with an authored one as if they were equal. If the user wants a result to stand on its own, write an authored fixture for it.
+15. When you name a WCAG criterion, use the number and name exactly as `report.md` prints them, and keep its "WCAG data" credit to the W3C. Don't write criterion names or levels from memory.
+16. End with a plain method note. Say what automated tools can't catch: whether alt text is meaningful, whether link and heading text make sense in context, cognitive load, real focus and reading order in use, and how real screen readers behave. Those need a person.
 
 Use the structure of `report.md`. Quote selectors and rule IDs exactly as `results.json` has them.
 
@@ -173,7 +204,7 @@ Use the structure of `report.md`. Quote selectors and rule IDs exactly as `resul
 
 Say these things plainly. Don't soften them, and don't fill in a result.
 
-- **Unsupported framework.** The package needs a framework other than React or web components. Name it. v1 covers React and web components.
+- **Unsupported framework.** The package needs a framework other than React, Vue 3, or web components. Name it, and say which version is unsupported (Vue 2, for example). This version covers React, Vue 3, and web components. A Storybook for the library still works, whatever the framework.
 - **Not applicable.** The package has no rendering surface, such as a utility library. There's nothing to test.
 - **Not testable.** The content is a canvas with no alternative, or sits in a closed shadow root. The rule engines can't see it, so the result is untested, not clean. The virtual screen reader also can't read open shadow roots.
 - **Gap.** The archetype has no usable fixture or no matching export. Say what the archetype needs.

package/skills/automatica11y-runner/references/fixtures.md

@@ -6,7 +6,7 @@ Write fixtures from the library's public documentation. Don't copy from memory w
 
 ## Where fixtures go
 
-`fixtures/<target id>/<archetype>.jsx` for React, in the working folder: the folder where you run `automatica11y audit` or `automatica11y compare`. Use `.js` for web components. The target id is the label (`radix=npm:@radix-ui/react-dialog` has the id `radix`), or the package name with `/` turned into `-`, such as `radix-ui-react-dialog`. The report's **Targets** list shows each id.
+`fixtures/<target id>/<archetype>.jsx` for React and Vue 3, in the working folder: the folder where you run `automatica11y audit` or `automatica11y compare`. Use `.js` for web components. The target id is the label (`radix=npm:@radix-ui/react-dialog` has the id `radix`), or the package name with `/` turned into `-`, such as `radix-ui-react-dialog`. The report's **Targets** list shows each id.
 
 To keep a fixture somewhere else, name it in a mapping file and pass `--mapping`:
 
@@ -21,13 +21,19 @@ To keep a fixture somewhere else, name it in a mapping file and pass `--mapping`
 
 The keys are target ids, then archetypes. `export` (React) or `tag` (web components) changes which export or element a template uses.
 
+## Start from a generated fixture
+
+You often don't need to write a fixture from nothing. For dialog, menu, tooltip, tabs, accordion, combobox, form-field, and live-region, the tool tries to build one from the package's exports and keeps it only if it works. The source is written to `<out>/generated/<target id>/<archetype>.jsx` (`.js` for web components). To make one an authored fixture, copy it to `fixtures/<target id>/` and edit it. It will carry a block of marking code at the top (`startMarking`). That code marks the trigger and root by role, because a generated fixture can't know how the library forwards props. In an authored fixture you can drop it and put `data-a11y-trigger` and `data-a11y-root` on the right elements yourself, which is clearer and doesn't depend on timing.
+
+If the tool couldn't build a working fixture, the report's **Archetypes** table says what it tried and why each attempt failed. That's a good place to start reading.
+
 ## The contract
 
 1. The file's default export renders the archetype in its **initial state**.
 2. Mark **exactly one** element with `data-a11y-trigger`. This is what a person would focus and activate: the button that opens a dialog, the first tab, the combobox input, the form control. If nothing in the archetype can be activated, as with a chart, put `data-a11y-trigger` and `data-a11y-root` on the same element: the outermost one the library renders.
 3. Mark the **primary surface** with `data-a11y-root`. Put it on the element that carries the role (`role="dialog"`, `role="menu"`, `role="tooltip"`), not on an overlay or a portal wrapper. It's fine if the root doesn't exist until the trigger fires, and fine if it renders in a portal. The tool looks in the whole document.
 4. Mount without console errors. The tool treats errors as a broken fixture.
-5. Don't import CSS. The tool doesn't link it.
+5. A stylesheet the fixture imports is bundled and linked. If the library needs one (a token file, a theme) and its documentation says to load it, import it. If that stylesheet is in another package, list the package under `install` in the mapping (see below). Without the stylesheet the library renders unstyled, and the results describe that, not the library.
 6. Include every part the library's documentation marks as required (for example, a dialog's title and description), so the component doesn't log warnings.
 
 The attributes have to reach the DOM. Pass `data-a11y-trigger` to the component that renders the real element. If a component drops unknown props, use the library's documented way to render your own element in its place (for example, `asChild` in Radix, or the `as` prop in Headless UI), and put the attribute on that native element. If the library has no such way, leave the archetype as a gap. Don't wrap the library's component in an element you add and mark that element, because the fixture would then test your element and not the library.
@@ -38,6 +44,8 @@ A React example and a web component example are in `SKILL.md`, in the section on
 
 For React, JSX works without importing React. Import the library from its package name. The tool installs it for you.
 
+For Vue 3, a fixture is also JSX, and the default export is a component: a function that returns JSX is a functional component, or you can export a component object. The tool turns JSX into `h()` calls and supplies `h` and `Fragment` itself, so don't import them. Importing `h` fails the bundle with "symbol already declared". JSX children become the default slot. Vue's reactivity works, so `import { ref } from "vue"` for state, and wrap the JSX in `defineComponent({ setup() { ... return () => (<jsx/>) } })`. A library that needs a plugin, a theme, or global components can export a function named `setup(app)`, which runs before the app mounts, for example `export function setup(app) { app.use(plugin) }`. Named slots and `v-model` aren't JSX syntax. Pass a slots object as the children, or set `modelValue` and `onUpdate:modelValue` with a spread, for example `{...{ "onUpdate:open": (next) => (open.value = next) }}`.
+
 For web components, make `mount(container)` the file's default export. It adds the archetype to the container. The tool imports the package first, so its elements are defined before `mount` runs. The `data-a11y-trigger` and `data-a11y-root` attributes can sit on a host element, a slotted child, or an element inside an **open** shadow root. A **closed** shadow root hides its content from every tool, so the report lists it as not testable.
 
 ## Library accessibility options
@@ -50,10 +58,38 @@ export default function Fixture({ libA11y }) {
 }
 ```
 
+## Companion packages
+
+Some libraries need another package beside them, such as a design token stylesheet or a theme. Name it under `install` in the mapping file, next to `fixture`. The first key is the target id, and the second is the archetype. The tool installs it into the same folder as the library, with install scripts off, and the fixture can import it:
+
+```json
+{
+  "lib": {
+    "live-region": { "fixture": "fixtures/lib/live-region.js", "install": ["@scope/tokens"] }
+  }
+}
+```
+
+```js
+import "@scope/tokens/style.css";
+```
+
+List only what the library's documentation asks you to load. Each entry has to be a package name with an optional version. Flags, paths, and URLs are refused.
+
 ## States
 
 For a dialog, menu, tooltip, or combobox, the tool tests the closed state, then activates the trigger and tests the open state. For an accordion it tests collapsed, then expanded. The tool activates the trigger by clicking it. For a tooltip it focuses the trigger instead, so a tooltip has to open on focus. If it opens only on pointer hover, the open state never appears. Make sure activating the trigger really opens the surface, and that the element with `data-a11y-root` is then attached to the document, isn't `display: none` or `hidden`, and isn't `visibility: hidden`. The tool also counts the surface as open if the trigger has `aria-expanded="true"`. If neither holds, the open state is reported as failed, with the reason. The interaction checks also press keys and hover, but they don't change how the open state is reached.
 
+## Live regions
+
+The `live-region` archetype covers any message that appears, changes, or goes away without moving focus: alerts, status messages, toasts, snackbars, and other `role="alert"`, `role="status"`, `role="log"`, or `aria-live` content. A library's alert component is a fixture for this archetype. The archetype isn't named after any one component.
+
+- `data-a11y-trigger` goes on the control that makes the message appear or change, such as a "Save" button. It can't be the message itself. A message that's on the page from the start has nothing to announce, so the tool reports a gap and asks for a trigger.
+- `data-a11y-root` goes on the message: the element that carries the role, or the element whose text changes. It may already be in the page and empty, or the trigger may insert it.
+- If the message has a dismiss control, put it inside the root. The tool presses Enter on it and checks that the message goes away and that focus lands somewhere sensible.
+- The tool checks that the message sits in a live region, that the region was in the page before the message arrived (except for `role="alert"`, which is announced on insertion), that the politeness fits the role, and that focus stays on the trigger.
+- The states are "before message" and "message shown". The tool activates the trigger by clicking it, then waits for the message to have text.
+
 ## Check your fixture
 
 Run the audit and look at the report's **Archetypes** table. `ran` means it worked. A `gap` row says what went wrong, such as "didn't render an element with data-a11y-trigger" or "didn't bundle." Fix the file and run again.

package/src/commands/common.js

@@ -26,6 +26,7 @@ const OPTION_DEFS = /** @type {const} */ ({
   "lib-a11y": { type: "string" },
   mapping: { type: "string" },
   plan: { type: "boolean" },
+  "no-generate": { type: "boolean" },
   out: { type: "string" },
   "max-stories": { type: "string" },
   "fail-on-axe": { type: "string" },
@@ -110,6 +111,7 @@ export function parseRunArgs(command, argv) {
     archetypes: /** @type {any} */ (archetypes),
     mapping: values.mapping ?? null,
     maxStories,
+    generate: !values["no-generate"],
     out: values.out ?? "./a11y-report",
     fail,
   };
@@ -120,7 +122,7 @@ export function parseRunArgs(command, argv) {
 export function describeTarget(target) {
   if (target.status === "failed") return `failed: ${target.reason}`;
   const r = target.resolved ?? {};
-  if (target.kind?.startsWith("npm")) return `${r.name}@${r.version ?? r.requested ?? "latest"}${r.framework ? ` (${r.framework})` : ""}`;
+  if (target.kind?.startsWith("npm")) return `${r.name}@${r.version ?? r.requested ?? "latest"}${r.subpath ? `/${r.subpath}` : ""}${r.framework ? ` (${r.framework})` : ""}`;
   return r.url ?? r.path ?? "";
 }
 
@@ -237,12 +239,13 @@ export async function runSavedPlan(argv, io) {
 const FLAGS = `Options:
   --wcag <2.0|2.1|2.2>        WCAG version. Default 2.2.
   --level <A|AA|AAA>          Conformance level. Default AA.
-  --tiers <list>              rules, interactions, computed, vsr. Default all four.
+  --tiers <list>              rules, interactions, computed, conditions, vsr. Default all five.
   --engine <list>             axe, ibm. Default both.
   --archetypes <list>         Limit npm and Storybook targets to these archetypes.
   --lib-a11y <list>           on, off. Default both.
   --mapping <file>            Archetype mapping file.
   --max-stories <n>           Storybook story cap. Default 200.
+  --no-generate               Don't build fixtures for npm packages. Only authored fixtures and the button and link templates run.
   --plan                      Resolve and print the plan, then stop.
   --out <dir>                 Output directory. Default ./a11y-report.
   --fail-on-axe <impact>      minor, moderate, serious, or critical.

package/src/frameworks/index.js

@@ -0,0 +1,42 @@
+/**
+ * The framework adapters. Each one says how to recognize a package built for its framework, install the framework's runtime,
+ * bundle and mount a fixture, list a package's exports, template the simple archetypes, generate the rest, and describe the
+ * result in a report. Everything after that (the browser, the tiers, the probe, the reports) knows nothing about a framework.
+ *
+ * To add a framework, write a module with the same shape as react.js, add it here, and add its id to FLAVORS and its kind to
+ * TARGET_KINDS in schema.js. A test checks that the two lists agree.
+ *
+ * @typedef {{
+ *   id: string,
+ *   label: string,
+ *   kind: string,
+ *   noun: string,
+ *   extension: string,
+ *   runtime: string[],
+ *   detect: (meta: any) => { kind: string, framework: string, reason: string } | null,
+ *   bundle: (workDir: string) => { alias: Record<string, string>, define?: Record<string, string>, esbuild: Record<string, any> },
+ *   entry: (fixturePath: string, pkg: string) => string,
+ *   discoverEntry: (pkg: string) => string,
+ *   template: (archetype: string, pkg: string, name?: string) => string | null,
+ *   generate: (input: any) => { candidates: Array<{ id: string, summary: string, source: string, used: string[] }>, reason: string | null },
+ *   describe: (npm: any) => string,
+ * }} Adapter
+ */
+import react from "./react.js";
+import vue from "./vue.js";
+import wc from "./wc.js";
+
+/** @type {Record<string, Adapter>} */
+export const ADAPTERS = { react, vue, wc };
+
+/** The adapter for a flavor (`react`, `vue`, or `wc`). */
+export function adapterFor(id) {
+  const adapter = ADAPTERS[id];
+  if (!adapter) throw new Error(`There's no adapter for "${id}".`);
+  return adapter;
+}
+
+/** The adapter for a plan target's kind, such as `npm-vue`, or null for a kind no adapter owns. */
+export function adapterForKind(kind) {
+  return Object.values(ADAPTERS).find((adapter) => adapter.kind === kind) ?? null;
+}

package/src/frameworks/react.js

@@ -0,0 +1,77 @@
+/**
+ * The React adapter: how to recognize a React package, mount a fixture, list its exports, template the simple archetypes,
+ * generate the rest, and tell esbuild to use one copy of React. Every framework adapter has this shape (see index.js).
+ */
+import { join } from "node:path";
+import { reactDialect } from "../harness/generate/dialects.js";
+import { generateJsx } from "../harness/generate/jsx.js";
+
+/** Mounts a fixture's default export. */
+export const entry = (fixturePath, _pkg) => `import { createElement } from "react";
+import { createRoot } from "react-dom/client";
+import Fixture from ${JSON.stringify(fixturePath)};
+const libA11y = new URLSearchParams(location.search).get("libA11y") === "on";
+createRoot(document.getElementById("root")).render(createElement(Fixture, { libA11y }));
+`;
+
+/** Loads the whole package, lists its exports, and records compound parts such as Dialog.Trigger. */
+export const discoverEntry = (pkg) => `import * as lib from ${JSON.stringify(pkg)};
+const out = [];
+for (const name of Object.keys(lib)) {
+  const value = lib[name];
+  const type = typeof value;
+  if (value === null || (type !== "function" && type !== "object")) continue;
+  const parts = Object.keys(value).filter((key) => /^[A-Z]/.test(key)).slice(0, 30);
+  out.push({ name, type, parts });
+}
+window.__a11yExports = out;
+`;
+
+/**
+ * A fixture for the simple archetypes, from the export name alone.
+ * Compound components (dialog, tabs, menu) can't be guessed, so they come from generation or from a fixture someone writes.
+ */
+export function template(archetype, pkg, exportName) {
+  const body = {
+    button: `<Component data-a11y-trigger data-a11y-root type="button">Save</Component>`,
+    link: `<Component data-a11y-trigger data-a11y-root href="#top">Read more</Component>`,
+  }[archetype];
+  if (!body) return null;
+  return `import { ${exportName} as Component } from ${JSON.stringify(pkg)};
+export default function Fixture() {
+  return ${body};
+}
+`;
+}
+
+export default {
+  id: "react",
+  label: "React",
+  kind: "npm-react",
+  /** What the mapping calls a thing the package provides. */
+  noun: "export",
+  /** The extension of an authored fixture. */
+  extension: "jsx",
+  /** Packages the fixture and the library must share one copy of, and that the install makes sure are there. */
+  runtime: ["react", "react-dom"],
+  /** Is this package React, from its registry metadata alone? */
+  detect(meta) {
+    const peers = meta.peerDependencies ?? {};
+    const deps = meta.dependencies ?? {};
+    if (!("react" in peers || "react-dom" in peers || "react" in deps)) return null;
+    const how = "react" in peers || "react-dom" in peers ? "peer dependency" : "dependency";
+    return { kind: "npm-react", framework: "React", reason: `The package lists react as a ${how}.` };
+  },
+  /** esbuild settings for this framework. */
+  bundle: (workDir) => ({
+    // One copy of React for the library and the fixture, or hooks break.
+    alias: { react: join(workDir, "node_modules", "react"), "react-dom": join(workDir, "node_modules", "react-dom") },
+    esbuild: { jsx: "automatic" },
+  }),
+  entry,
+  discoverEntry,
+  template,
+  generate: (input) => generateJsx(reactDialect, input),
+  /** One phrase for the report: what the package was run as. */
+  describe: (npm) => `React${npm.react ? ` (react ${npm.react})` : ""}`,
+};

package/src/frameworks/vue.js

@@ -0,0 +1,90 @@
+/**
+ * The Vue adapter, for Vue 3 packages. Libraries ship compiled components, so nothing here compiles single-file components.
+ * Fixtures are JSX that esbuild turns into `h()` calls (a small shim supplies Vue's `h` and `Fragment`, so a fixture doesn't import them),
+ * and a fixture's default export is a component. An optional `setup(app)` export installs plugins before the app mounts.
+ * Every framework adapter has this shape (see index.js).
+ */
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { vueDialect } from "../harness/generate/dialects.js";
+import { generateJsx } from "../harness/generate/jsx.js";
+
+/** Mounts a fixture's default export as the root component, after its optional setup(app) has installed what it needs. */
+export const entry = (fixturePath, _pkg) => `import { createApp } from "vue";
+import * as fixture from ${JSON.stringify(fixturePath)};
+const libA11y = new URLSearchParams(location.search).get("libA11y") === "on";
+const app = createApp(fixture.default, { libA11y });
+if (typeof fixture.setup === "function") await fixture.setup(app);
+app.mount(document.getElementById("root"));
+`;
+
+/** Loads the whole package, lists its exports, and records compound parts such as Dialog.Trigger. Same as for React. */
+export const discoverEntry = (pkg) => `import * as lib from ${JSON.stringify(pkg)};
+const out = [];
+for (const name of Object.keys(lib)) {
+  const value = lib[name];
+  const type = typeof value;
+  if (value === null || (type !== "function" && type !== "object")) continue;
+  const parts = Object.keys(value).filter((key) => /^[A-Z]/.test(key)).slice(0, 30);
+  out.push({ name, type, parts });
+}
+window.__a11yExports = out;
+`;
+
+/** A fixture for the simple archetypes, from the export name alone. A function default export is a functional component. */
+export function template(archetype, pkg, exportName) {
+  const body = {
+    button: `<Component data-a11y-trigger data-a11y-root type="button">Save</Component>`,
+    link: `<Component data-a11y-trigger data-a11y-root href="#top">Read more</Component>`,
+  }[archetype];
+  if (!body) return null;
+  return `import { ${exportName} as Component } from ${JSON.stringify(pkg)};
+export default function Fixture() {
+  return ${body};
+}
+`;
+}
+
+/** Vue 3 or later? A range like "^3.2.0 || ^2.7" counts when any part allows 3. A bare "*" counts too. */
+function allowsVue3(range) {
+  return String(range)
+    .split("||")
+    .some((part) => {
+      const major = /(\d+)/.exec(part);
+      return !major || Number(major[1]) >= 3 || /^[\s*x]*$/.test(part);
+    });
+}
+
+export default {
+  id: "vue",
+  label: "Vue",
+  kind: "npm-vue",
+  noun: "export",
+  extension: "jsx",
+  runtime: ["vue"],
+  detect(meta) {
+    const peers = meta.peerDependencies ?? {};
+    const deps = meta.dependencies ?? {};
+    const range = peers.vue ?? deps.vue;
+    if (range === undefined) return null;
+    if (!allowsVue3(range)) return { kind: "npm-unsupported", framework: "Vue 2", reason: `The package needs Vue ${range}. Only Vue 3 is supported.` };
+    return { kind: "npm-vue", framework: "Vue", reason: `The package lists vue as a ${"vue" in peers ? "peer dependency" : "dependency"}.` };
+  },
+  /** Writes the shim that supplies `h` and `Fragment`, then returns the settings. */
+  bundle(workDir) {
+    const shim = join(workDir, "a11y-vue-jsx-shim.js");
+    writeFileSync(shim, 'export { h, Fragment } from "vue";\n');
+    return {
+      // One copy of Vue for the library and the fixture, or reactivity breaks.
+      alias: { vue: join(workDir, "node_modules", "vue") },
+      define: { __VUE_OPTIONS_API__: "true", __VUE_PROD_DEVTOOLS__: "false", __VUE_PROD_HYDRATION_MISMATCH_DETAILS__: "false" },
+      // Vue has no JSX runtime of its own, so JSX becomes h() calls. The shim is injected wherever h or Fragment is used without being declared.
+      esbuild: { jsx: "transform", jsxFactory: "h", jsxFragment: "Fragment", inject: [shim] },
+    };
+  },
+  entry,
+  discoverEntry,
+  template,
+  generate: (input) => generateJsx(vueDialect, input),
+  describe: (npm) => `Vue${npm.vue ? ` (vue ${npm.vue})` : ""}`,
+};

package/src/frameworks/wc.js

@@ -0,0 +1,55 @@
+/**
+ * The web component adapter: framework-free entries, templates, and generation from what an element says about itself.
+ * Every framework adapter has this shape (see index.js).
+ */
+import { generateWc } from "../harness/generate/wc-recipes.js";
+
+
+/** Loads the package so its custom elements get defined, then calls the fixture's default export, `mount(container)`. */
+export const entry = (fixturePath, pkg) => `// A package's own "sideEffects" list can mark its entry as removable, which would drop a bare import and leave its elements undefined.
+// Using the namespace keeps the package and its registration code.
+import * as library from ${JSON.stringify(pkg)};
+globalThis.__a11yLibrary = library;
+import mount from ${JSON.stringify(fixturePath)};
+const libA11y = new URLSearchParams(location.search).get("libA11y") === "on";
+await mount(document.getElementById("root"), { libA11y });
+`;
+
+/** Loads the whole package. The page's init script records every custom element the package defines. */
+export const discoverEntry = (pkg) => `import * as lib from ${JSON.stringify(pkg)};
+window.__a11yExports = Object.keys(lib).map((name) => ({ name, type: typeof lib[name], parts: [] }));
+`;
+
+/** A fixture for the simple archetypes, from the tag name alone. */
+export function template(archetype, _pkg, tag) {
+  const attrs = {
+    button: `el.textContent = "Save";`,
+    link: `el.setAttribute("href", "#top");\n  el.textContent = "Read more";`,
+  }[archetype];
+  if (!attrs) return null;
+  return `export default function mount(container) {
+  const el = document.createElement(${JSON.stringify(tag)});
+  el.setAttribute("data-a11y-trigger", "");
+  el.setAttribute("data-a11y-root", "");
+  ${attrs}
+  container.append(el);
+}
+`;
+}
+
+export default {
+  id: "wc",
+  label: "Web components",
+  kind: "npm-wc",
+  noun: "custom element",
+  extension: "js",
+  runtime: [],
+  /** A package is detected as web components by a manifest or a base library, which index.js orders against the other adapters. */
+  detect: () => null,
+  bundle: () => ({ alias: {}, esbuild: {} }),
+  entry,
+  discoverEntry,
+  template,
+  generate: (input) => generateWc(input),
+  describe: (npm) => `web components (${npm.tags?.length ? npm.tags.slice(0, 6).join(", ") : "no tags found"})`,
+};