automatica11y 0.4.1 → 0.7.0

package/README.md

@@ -1,171 +1,78 @@
-# automatica11y.
+[![automatica11y Open Graph preview](https://automatica11y.dev/og.png)](https://automatica11y.dev/)
+
+# automatica11y
 
 Test and compare the accessibility of web pages, Storybook builds, and npm component libraries.
 
-automatica11y answers two questions:
+automatica11y helps answer two questions:
 
 - How accessible is this? (`audit`)
-- How do these compare? (`compare`, two or more targets)
-
-It's **not** an attestation or certification tool. Automated checks cover only part of WCAG, so a report says "no automated violations found" only where an engine found none, and never says "accessible." See [Limits](#limits).
+- How do these compare? (`compare`)
 
-## Quick start.
+## Quick start
 
-You need Node 20 or newer and Chrome or Chromium.
-
-Install it once, and `automatica11y` is on your `PATH`, with the short name `a11y` too:
+Run it from your terminal:
 
 ```bash
-npm i -g automatica11y
+npx -y automatica11y audit npm:@instructure/ui-buttons
 ```
 
-Then run it without `npx`:
+Install the [skill](skills/automatica11y/SKILL.md) and use it with an agent:
 
-```bash
-automatica11y doctor
-automatica11y audit https://example.com
-automatica11y compare radix=npm:@radix-ui/react-dialog aria=npm:react-aria-components
+```text
+/automatica11y compare "example.com/a.html" "example.com/b.html"
 ```
-
-You can skip the install and put `npx` in front instead, for example `npx automatica11y doctor`. `npx` fetches the tool the first time and checks the registry after that. A global install doesn't update itself, so run `npm i -g automatica11y@latest` to upgrade, and `automatica11y --version` to see what you have. The rest of this page writes the short form. Add `npx` if you didn't install it.
-
-`doctor` checks your setup. If it can't find a browser, it prints the command that installs one:
+Add it to your CD/CI pipeline:
 
 ```bash
-npx playwright-core install --only-shell chromium
+automatica11y audit ./dist --fail-on-axe serious
 ```
 
-Each run writes a folder (`./a11y-report` by default) with `report.md`, `results.json`, and `plan.json`.
-
-## Targets.
-
-A target is `[label=]<spec>`. The label is optional, and names the target in the report.
-
-| Target | Spec |
-|---|---|
-| 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`. 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."
-
-A local `.html` file is served over `http://localhost`, never `file://`. A static site audits its `index.html` only.
-
-## What it checks.
-
-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 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.
+**[Read the documentation](https://automatica11y.dev/)**
 
-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.
+## Why use it
 
-## Options.
+Most accessibility tools scan one page and hand back one score. automatica11y is built for the questions that come before and after that scan.
 
-| Option | Default | What it does |
-|---|---|---|
-| `--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,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. |
-| `--fail-on-axe <impact>` | off | Exit 1 if axe-core reports a violation at or above `minor`, `moderate`, `serious`, or `critical`. |
-| `--fail-on-ibm <1\|2\|3>` | off | Exit 1 if IBM reports a violation at or below that Toolkit level. |
-| `--fail-mode any\|all` | `any` | `any` trips when either engine's check trips. `all` trips only when both do, on the same target. |
-
-Run `automatica11y run --plan <plan.json>` to repeat a saved plan. It warns if tool versions have changed.
-
-## Output.
-
-- `report.md` is a complete report, written without any model. It opens with a coverage matrix, then lists findings, then ends with a method note.
-- `results.json` holds everything, including element selectors and announcement logs.
-- `plan.json` records what ran and the resolved tool and package versions.
-- `mapping.json` appears for npm targets. See below.
+### It compares
 
-## Exit codes.
+Pick two component libraries, two versions of one component, or two sites, and `compare` runs them under the same settings, side by side. "Is this library's dialog better than that one?" gets an answer you can check.
 
-| Code | Meaning |
-|---|---|
-| 0 | The run completed. Findings don't change this unless a fail flag is set. |
-| 1 | The run completed and a fail check tripped. |
-| 2 | The command line was wrong. |
-| 3 | An environment problem, such as a missing browser or an old Node. The message says how to fix it. |
-| 4 | No target produced results. |
+### It tests components, not just pages
 
-One failing target doesn't stop a comparison. It's recorded with its reason, and the others run.
+Point it at an npm package. It installs the package on its own, finds the components, builds the test fixtures it needs (React, Vue 3, Angular 22 and newer, Svelte 5 and newer, plain HTML, and web components), then opens the dialogs and menus and presses the keys.
 
-## npm packages and fixtures.
+### It's' composable
 
-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`.
+Out of the box it looks at standard accessibility interactions and archetypes (buttons, links, dialogs, contrast, etc.) and you can bring your own simple fixtures for more complex components.
 
-Each archetype's fixture comes from the first of these that applies:
+### An AI agent can run it
 
-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.
+The tool prints its own instructions, so you can ask an agent "how accessible is Radix Dialog?" and it knows what to do.
 
-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.
+## What a result looks like
 
-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.
+automatica11y generates a machine-readable json findings report, and a human-readable markdown version. Here's an excerpt from a real run on the carousel in shadcn/ui:
 
-## Use it with an AI agent.
-
-The tool prints its own guidance, so any agent that can run `npx` can learn to use it. If the tool is installed globally, the agent can run `automatica11y guide skill` instead of `npx automatica11y@latest guide skill`:
-
-```bash
-npx automatica11y@latest guide           # where to start (the AGENTS.md file)
-npx automatica11y@latest guide skill     # the full steps: build the command, run it, write the report
-npx automatica11y@latest guide fixtures  # how to write the fixtures an npm package needs
-```
-
-The guidance ships with the tool, so it always matches the version you run. Tell your agent to run `npx automatica11y@latest guide` and follow it, then ask for things like "How accessible is Radix Dialog?" or "Compare the accessibility of React Aria and Headless UI." The agent needs to run shell commands and read and write files. Nothing here is tied to one agent.
-
-**Skills.** If your agent loads skills from a folder, copy [`skills/automatica11y`](skills/automatica11y) into it. That's one small file, `SKILL.md`. It advertises the tool to the agent, and sends it to `guide skill`. It names no version, so it doesn't go stale. The full steps are the [`automatica11y-runner`](skills/automatica11y-runner) skill, which ships in the package and is what `guide skill` prints. Copy it too if you want the steps available without the network.
-
-**AGENTS.md.** [`AGENTS.md`](AGENTS.md) is for agents that read it but don't load skills. It points to the same steps, and tells contributors how to run and change the code.
-
-## Limits.
+| Check | Result | Detail |
+|---|---|---|
+| `focus-indicator-contrast` | fail | The border has 2.58:1 against what's next to it (needs 3:1). |
+| `forced-colors-focus-visible` | fail | With forced colors on, only four of 156 changed pixels reach 3:1 against their unfocused color. |
+| `boundary-contrast` | pass | The strongest mark is its icon stroke, at 19.79:1 (needs 3:1). |
 
-- 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, 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.
-- 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.
+> axe-core found no automated violations on that component. IBM Equal Access found one: the carousel's region has no label.
 
-## Using it in CI.
+## Limits
 
-```bash
-npx automatica11y audit ./dist --fail-on-axe serious --fail-on-ibm 1 --fail-mode any
-```
+automatica11y is not an attestation or certification tool. Automated checks cover only part of WCAG. They can't judge whether alt text is meaningful, whether the reading order makes sense, or how real screen readers behave, and the screen reader it runs is simulated. A person has to check those.
 
-The run exits 1 when the check trips. Needs-review items never trip it.
+A report says "no automated violations found" where an engine found none, and never says "accessible." A gap, an error, or a result that isn't testable is a finding, not a pass.
 
-## License.
+## License
 
 MIT. See [LICENSE](LICENSE). The WCAG data below has its own terms.
 
-## Attribution.
+## Attribution
 
 automatica11y reads WCAG criterion numbers, names, levels, and versions from the W3C's published JSON, [wcag.json](https://www.w3.org/WAI/WCAG22/wcag.json). The package ships that file in `src/data/` without changes.
 

package/package.json

@@ -1,7 +1,15 @@
 {
   "name": "automatica11y",
-  "version": "0.4.1",
+  "version": "0.7.0",
   "description": "Test and compare the accessibility of web pages, Storybook builds, and npm component libraries.",
+  "homepage": "https://automatica11y.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thedannywahl/automatica11y.git"
+  },
+  "bugs": {
+    "url": "https://github.com/thedannywahl/automatica11y/issues"
+  },
   "license": "MIT",
   "type": "module",
   "bin": {
@@ -21,6 +29,8 @@
     "test": "node --test test/*.test.js",
     "lint": "tsc -p jsconfig.json",
     "update-wcag": "node scripts/update-wcag.js",
+    "docs:build": "node scripts/build-docs.js",
+    "docs:preview": "node scripts/build-docs.js && npx --yes serve site",
     "prepublishOnly": "npm run lint"
   },
   "dependencies": {
@@ -33,11 +43,29 @@
     "valibot": "^1.5.0"
   },
   "devDependencies": {
+    "@angular/cdk": "^22.2.2",
+    "@angular/common": "^22.2.2",
+    "@angular/compiler": "^22.2.2",
+    "@angular/core": "^22.2.2",
+    "@angular/forms": "^22.2.2",
+    "@angular/material": "^22.2.2",
+    "@angular/platform-browser": "^22.2.2",
+    "@pantoken/components": "^2.0.2",
+    "@pantoken/css": "^0.4.3",
+    "@pantoken/plugin-custom-theme-colors": "^0.3.3",
+    "@shikijs/langs": "^4.5.0",
+    "@shikijs/themes": "^4.5.0",
     "@types/node": "^26.6.4",
+    "bits-ui": "^2.19.5",
+    "marked": "^18.1.0",
     "react": "^19.3.0",
     "react-dom": "^19.3.0",
+    "rxjs": "^7.8.2",
+    "shiki": "^4.5.0",
+    "svelte": "^5.57.2",
     "typescript": "^7.0.2",
-    "vue": "^3.5.43"
+    "vue": "^3.5.43",
+    "zone.js": "^0.16.3"
   },
   "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.4.x**. Run:
+This skill works with automatica11y **0.7.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.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.
+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.7.`, stop. Tell the user the version you got and the series this copy expects (`0.7.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 user installed the tool globally (`npm i -g automatica11y`), `automatica11y` is on the `PATH` (so is the short name `a11y`), and it runs the same commands as `npx --yes automatica11y@latest`. Every command in this skill is written with `npx`, so replace that prefix with `automatica11y` only when `automatica11y --version` passes the check above. If the installed version is the wrong series, or nothing is installed, use `npx`.
 
@@ -54,6 +54,19 @@ Use `audit` for one target and `compare` for two or more, even when they're diff
 
 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.
 
+**Plain HTML libraries.** A library with no framework, such as a stylesheet package and a script package, is tested by naming the files the page should load as sub-paths: `npm:pkg/base.css,pkg/components.css,other/behavior.iife.js`. A sub-path ending in `.css` is a stylesheet, and one ending in `.js` or `.mjs` is a script. Read the package's documentation or its `exports` to find the right files, and ask the user which stylesheets and scripts they use when the documentation doesn't say. Nothing is generated for plain HTML. Button, link, form-field, dialog, accordion, live-region, menu, and tooltip have templates of bare native markup, so they run with no fixture, and the report says what that does and doesn't show. Say so plainly: a pass on a native template never means the package's own components pass. Tabs, combobox, and chart need a fixture (`fixtures/<id>/<archetype>.html`) or they're gaps. To test the package's own components, write a fixture from its documentation.
+
+**One target can be several packages.** Some libraries ship in pieces, such as a stylesheet package and a script package. Join them with commas and no spaces: `npm:@scope/components,@scope/interactions`. They install into one folder and are tested as one target. The first is the primary: it names the target and decides the framework. Every other package is a companion. Each entry can have its own version and sub-path (`npm:a@1.2,b/button`). A list with a space, an empty entry, or the same package twice is rejected. Targets themselves are separated by spaces, as before.
+
+**Reading a comparison in plain language.** People write "compare A, B and C and D." Work out the targets before you build the command:
+
+- A comma joins packages into one target. The words "and", "vs", "versus", "against", and "compared with" separate targets. So "compare A, B and C and D" is three targets: `A,B`, `C`, and `D`.
+- Give each target a short label that says what it is, such as `pantoken-html=npm:A,B instui=npm:C pantoken-wc=npm:D`. Use the framework or the library's own name, so the report reads clearly.
+- Packages from the same organization are separate targets when they're alternatives for the same job (a React build and a web component build of one design system). They belong in one target only when the user says they work together, or when one package is the stylesheet or script half of the other.
+- Don't guess when the grouping is unclear. "A, B and C" could be one target of three packages, a target of two beside a third, or three targets. A comma list with no "and", a package that might be a companion or an alternative, and "with" or "plus" between packages are all unclear.
+- Always show the grouping before you run, as a short table of label, packages, and role. If the grouping came from anything but an obvious reading, ask the user to confirm it, with your best reading offered as the default, in the same message as your other questions.
+- Run the same archetypes on every target in a comparison. Say in the report which targets are made of several packages.
+
 Options you can set, and nothing else:
 
 | Option | Default | Use it when |
@@ -206,7 +219,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, 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.
+- **Unsupported framework.** The package needs a framework other than React, Vue 3, Angular 22 and newer, Svelte 5 and newer, plain HTML, or web components. Name it, and say which version is unsupported (Vue 2, Svelte 4, or Angular 21, for example). This version covers React, Vue 3, Angular 22 and newer, Svelte 5 and newer, plain HTML, 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

@@ -46,6 +46,30 @@ For React, JSX works without importing React. Import the library from its packag
 
 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 Angular 22 and newer, a fixture is a plain `.js` file with no decorator syntax. Define each component by calling the decorator as a function, and make the component class the default export. The tool loads Angular's runtime compiler, so libraries that ship partly compiled work as they are. Import what you use in the component's `imports` list, and export `providers` (an array) when the library needs application providers. State lives in signals. For example:
+
+```js
+import { Component, signal } from "@angular/core";
+import { MatMenu, MatMenuItem, MatMenuTrigger } from "@angular/material/menu";
+
+class Fixture { shown = signal(false); }
+Component({
+  selector: "app-fixture",
+  imports: [MatMenu, MatMenuItem, MatMenuTrigger],
+  template: `<button type="button" data-a11y-trigger [matMenuTriggerFor]="m">Actions</button>
+    <mat-menu #m="matMenu"><button mat-menu-item>Copy</button></mat-menu>`,
+})(Fixture);
+export default Fixture;
+```
+
+An Angular fixture can also be TypeScript (`fixtures/<target id>/<archetype>.ts`) with `@Component({ ... })` decorators. The tool strips the types, but it can't emit constructor parameter metadata, so get services with `inject(Service)` and not through constructor parameters. A missing provider or an unknown element is reported in a plain sentence with Angular's error code.
+
+Angular libraries split their parts across sub-paths, so audit them with a sub-path target, for example `npm:@angular/material/menu`.
+
+For Svelte 5 and newer, a fixture is a `.svelte` file (`fixtures/<target id>/<archetype>.svelte`). Import the library from its package name and write the markup with the library's components, for example `<Dialog.Root>` with `<Dialog.Trigger data-a11y-trigger>`. State uses runes (`let open = $state(false)`), and `lang="ts"` works. A component that takes content takes it as children between its tags. Some Svelte libraries give you builders and not components: you create an object in the script (`const dialog = new Dialog()`) and spread its attributes onto your own elements (`<button {...dialog.trigger} data-a11y-trigger>`). Nothing is generated for those, so write the fixture from the documentation. A fixture can also declare `let { libA11y } = $props()` to receive the library accessibility option. Svelte libraries ship `.svelte` source, and the tool compiles it, so a library that imports SvelteKit-only modules (`$app/...`) can't run.
+
+For plain HTML, a fixture is a `.html` file of markup (`fixtures/<target id>/<archetype>.html`). It's a snippet, not a whole page: no `<html>` or `<body>`. Put `data-a11y-trigger` and `data-a11y-root` on the right elements yourself. The target says what loads, as sub-paths in a list: `npm:pkg/base.css,pkg/components.css,other/behavior.iife.js`. Stylesheets load with the page, the markup goes on next, and the scripts load last, so a script that wires up its elements when it starts finds them. A `<script>` inside the snippet runs. Use the classes and attributes the library's documentation names, and don't invent them.
+
 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

package/src/cli.js

@@ -7,6 +7,7 @@ import { ownVersion } from "./env/versions.js";
 
 const COMMANDS = {
   audit: auditCommand,
+  check: auditCommand,
   compare: compareCommand,
   run: runSavedPlan,
   doctor: doctorCommand,

package/src/commands/common.js

@@ -14,7 +14,7 @@ export const EXIT = { OK: 0, FAIL_THRESHOLD: 1, USAGE: 2, ENVIRONMENT: 3, ALL_TA
 export class UsageError extends Error {}
 
 /**
- * @typedef {{ stdout: { write(text: string): unknown }, stderr: { write(text: string): unknown }, cwd: string, env: NodeJS.ProcessEnv, fetch?: import("../plan/classify.js").FetchLike, npmView?: (spec: string) => Promise<any>, installPackage?: Function, platform?: NodeJS.Platform }} Io
+ * @typedef {{ stdout: { write(text: string): unknown }, stderr: { write(text: string): unknown }, cwd: string, env: NodeJS.ProcessEnv, fetch?: import("../plan/classify.js").FetchLike, npmView?: (spec: string) => Promise<unknown>, installPackage?: Function, platform?: NodeJS.Platform }} Io
  */
 
 const OPTION_DEFS = /** @type {const} */ ({
@@ -62,7 +62,8 @@ export function parseRunArgs(command, argv) {
   } catch (error) {
     throw new UsageError(error instanceof Error ? error.message.split(". ")[0] : String(error));
   }
-  const { values, positionals } = parsed;
+  const values = /** @type {{ [K in keyof typeof OPTION_DEFS]?: typeof OPTION_DEFS[K]["type"] extends "boolean" ? boolean : string }} */ (parsed.values);
+  const { positionals } = parsed;
   if (values.help) return { help: true, targets: [], planOnly: false, options: null };
 
   if (command === "audit" && positionals.length !== 1) {
@@ -99,16 +100,16 @@ export function parseRunArgs(command, argv) {
     const ibm = ibmFlag === undefined ? null : Number(parseChoice("fail-on-ibm", ibmFlag, TOOLKIT_LEVELS.map(String)));
     if (axe && !engines.includes("axe")) throw new UsageError("--fail-on-axe needs the axe engine. Add axe to --engine or drop the flag.");
     if (ibm && !engines.includes("ibm")) throw new UsageError("--fail-on-ibm needs the ibm engine. Add ibm to --engine or drop the flag.");
-    fail = { mode: /** @type {"any" | "all"} */ (modeFlag === undefined ? "any" : parseChoice("fail-mode", modeFlag, FAIL_MODES)), axe: /** @type {any} */ (axe), ibm: /** @type {any} */ (ibm) };
+    fail = { mode: /** @type {"any" | "all"} */ (modeFlag === undefined ? "any" : parseChoice("fail-mode", modeFlag, FAIL_MODES)), axe, ibm };
   }
 
   const options = {
-    wcag: /** @type {any} */ (values.wcag === undefined ? "2.2" : parseChoice("wcag", values.wcag, WCAG_VERSIONS)),
-    level: /** @type {any} */ (values.level === undefined ? "AA" : parseChoice("level", values.level, LEVELS)),
-    tiers: /** @type {any} */ (tiers),
-    engines: /** @type {any} */ (engines),
-    libA11y: /** @type {any} */ (libA11y),
-    archetypes: /** @type {any} */ (archetypes),
+    wcag: values.wcag === undefined ? "2.2" : parseChoice("wcag", values.wcag, WCAG_VERSIONS),
+    level: values.level === undefined ? "AA" : parseChoice("level", values.level, LEVELS),
+    tiers,
+    engines,
+    libA11y,
+    archetypes,
     mapping: values.mapping ?? null,
     maxStories,
     generate: !values["no-generate"],
@@ -122,7 +123,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.subpath ? `/${r.subpath}` : ""}${r.framework ? ` (${r.framework})` : ""}`;
+  if (target.kind?.startsWith("npm")) return `${r.name}@${r.version ?? r.requested ?? "latest"}${r.subpath ? `/${r.subpath}` : ""}${target.companions?.length ? ` with ${target.companions.map((c) => `${c.name}@${c.version ?? c.requested ?? "latest"}${c.subpath ? `/${c.subpath}` : ""}`).join(", ")}` : ""}${r.framework ? ` (${r.framework})` : ""}`;
   return r.url ?? r.path ?? "";
 }
 
@@ -256,7 +257,8 @@ const FLAGS = `Options:
 /** @param {string} [command] */
 export function usage(command) {
   const header = {
-    audit: "Usage: automatica11y audit <target> [options]\n\nCheck how accessible one target is.\n\n",
+    audit: "Usage: automatica11y audit <target> [options]\n       automatica11y check <target> [options]\n\nCheck how accessible one target is.\n\n",
+    check: "Usage: automatica11y audit <target> [options]\n       automatica11y check <target> [options]\n\nCheck how accessible one target is.\n\n",
     compare: "Usage: automatica11y compare <target> <target> [<target>...] [options]\n\nCompare two or more targets.\n\n",
     run: "Usage: automatica11y run --plan <plan.json>\n\nRe-run a saved plan.\n",
   }[command ?? ""];
@@ -266,6 +268,7 @@ export function usage(command) {
   }
   return `Usage:
   automatica11y audit <target> [options]
+  automatica11y check <target> [options]
   automatica11y compare <target> <target> [<target>...] [options]
   automatica11y run --plan <plan.json>
   automatica11y doctor

package/src/frameworks/angular-errors.js

@@ -0,0 +1,27 @@
+/**
+ * Angular's own errors are written for someone with a stack trace and the source open. A report is read without either, so the
+ * ones a fixture is likely to hit get a plain sentence that keeps Angular's code and the name it reports. Anything else passes through.
+ * @param {string} text The first line of an error.
+ * @returns {string}
+ */
+export function explainAngularError(text) {
+  const code = /\bNG0*(\d+)\b/.exec(text)?.[1];
+  if (!code) return text;
+  const quoted = /`([^`]+)`|'([^']+)'|"([^"]+)"/.exec(text);
+  const name = quoted?.[1] ?? quoted?.[2] ?? quoted?.[3];
+  switch (code) {
+    case "201":
+    case "200":
+      return `the fixture is missing a provider that the library needs${name ? ` (${name})` : ""}. Add it to the fixture's \`providers\` export, or put the part that provides it around this one (NG0${code})`;
+    case "303":
+    case "304":
+    case "8002":
+      return `the template uses an element or input that the library doesn't define${name ? ` (${name})` : ""}, or the component isn't in the template's imports (NG0${code})`;
+    case "5105":
+      return "the library animates with a legacy animations package that isn't installed in the fixture (NG05105)";
+    case "908":
+      return "Angular couldn't find the root element to start from (NG0908)";
+    default:
+      return text;
+  }
+}

package/src/frameworks/angular-selectors.js

@@ -0,0 +1,36 @@
+/**
+ * Angular describes what turns a component or directive on with selectors. At runtime a class carries them in Ivy's own form:
+ * each alternative is an array that starts with the element name (empty for an attribute-only selector), followed by
+ * attribute names and values: `button[matButton]` is `["button", "matButton", ""]`. Numbers in the array mark class names,
+ * `:not()` parts, and other forms that a template can't write from a name alone, so those alternatives are skipped.
+ */
+
+/** Is this alternative plain: an element name and attributes, nothing else? */
+const isPlain = (alternative) => Array.isArray(alternative) && alternative.length % 2 === 1 && alternative.every((part) => typeof part === "string");
+
+/**
+ * The simplest element and attributes that match one of the selectors, preferring a given element.
+ * An attribute-only selector (`[uiTooltip]`) gets the preferred element, or `fallback` when none is preferred.
+ * @param {unknown[][]} selectors
+ * @param {{ prefer?: string, fallback?: string }} [options]
+ * @returns {{ tag: string, attrs: Array<[string, string]> } | null}
+ */
+export function markupFor(selectors, { prefer, fallback } = {}) {
+  const plain = (selectors ?? []).filter(isPlain).map((alt) => ({ tag: alt[0], attrs: pairs(alt) }));
+  const choose = (list) => list.sort((a, b) => a.attrs.length - b.attrs.length)[0] ?? null;
+  const match = prefer ? choose(plain.filter((alt) => alt.tag === prefer)) ?? choose(plain.filter((alt) => alt.tag === "")) : choose(plain.filter((alt) => alt.tag !== "")) ?? choose(plain);
+  if (!match) return null;
+  const tag = match.tag || prefer || fallback;
+  return tag ? { tag, attrs: match.attrs } : null;
+}
+
+function pairs(alternative) {
+  const out = [];
+  for (let i = 1; i < alternative.length; i += 2) out.push([alternative[i], alternative[i + 1]]);
+  return out;
+}
+
+/** The attributes as they're written in a template: `matButton`, or `kind="primary"`. */
+export function attributeText(attrs) {
+  return attrs.map(([name, value]) => (value ? `${name}="${String(value).replace(/"/g, "&quot;")}"` : name)).join(" ");
+}