automatica11y 0.3.2 → 0.3.3

package/README.md

@@ -44,10 +44,11 @@ A local `.html` file is served over `http://localhost`, never `file://`. A stati
 
 ## What it checks.
 
-Three tiers run by default. Use `--tiers` to pick fewer.
+Four 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.
+- **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.
 - **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.
@@ -59,7 +60,7 @@ 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,vsr` | all | Which tiers run. |
+| `--tiers rules,interactions,computed,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. |
@@ -134,4 +135,12 @@ The run exits 1 when the check trips. Needs-review items never trip it.
 
 ## License.
 
-MIT. See [LICENSE](LICENSE).
+MIT. See [LICENSE](LICENSE). The WCAG data below has its own terms.
+
+## 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.
+
+Source: [Web Content Accessibility Guidelines (WCAG) 2.2](https://www.w3.org/TR/WCAG22/), W3C. The JSON is used under the [terms in the W3C WCAG repository](https://github.com/w3c/wcag/blob/main/11ty/json/README.md): the source is credited with a link, and the content isn't changed. See also the [W3C Document License](https://www.w3.org/copyright/document-license/) and [W3C Intellectual Rights](https://www.w3.org/copyright/intellectual-rights/). The links that reports build to each criterion are added by automatica11y and aren't part of the W3C data.
+
+Every report repeats this credit in its closing section. To refresh the data, run `npm run update-wcag`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "automatica11y",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Test and compare the accessibility of web pages, Storybook builds, and npm component libraries.",
   "license": "MIT",
   "type": "module",
@@ -19,6 +19,7 @@
   "scripts": {
     "test": "node --test test/*.test.js",
     "lint": "tsc -p jsconfig.json",
+    "update-wcag": "node scripts/update-wcag.js",
     "prepublishOnly": "npm run lint"
   },
   "dependencies": {

package/skills/automatica11y-runner/SKILL.md

@@ -59,7 +59,7 @@ 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,vsr` | all three | The user wants fewer checks. |
+| `--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. |
 | `--lib-a11y on,off` | both | Only for libraries with opt-in accessibility features. |
 | `--mapping <file>` | none | You wrote or edited a mapping file. |
@@ -163,7 +163,9 @@ Write the narrative from `results.json`. Never write from memory, and never repe
 9. Treat a gap, a not-testable result, an error, or a failed target as a finding. It never counts as a pass.
 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. 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.
+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.
 
 Use the structure of `report.md`. Quote selectors and rule IDs exactly as `results.json` has them.
 
@@ -175,7 +177,8 @@ Say these things plainly. Don't soften them, and don't fill in a result.
 - **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.
-- **Error.** An interaction check couldn't finish. It's untested, not failed.
+- **Error.** An interaction or computed check couldn't finish. It's untested, not failed.
+- **Undetermined.** A computed check found a gradient, an image, or transparency behind the control, so it can't reduce the page to one color. It's untested, not clean.
 - **Failed target.** The target can't be reached, isn't a web page, or couldn't be built. The tool records it as failed with a reason. Tell the user which target failed, using the reason from `results.json`. Don't retry with guesses. If an npm target failed with a network or install error (for example `ETARGET`), you may run the same command once more. If it fails again, report it. If every target failed (exit code 4), stop. If others ran, report them, and list the failed target as a gap in coverage.
 
 ## 8. Stay out of setup

package/src/commands/common.js

@@ -237,7 +237,7 @@ 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, vsr. Default all three.
+  --tiers <list>              rules, interactions, computed, vsr. Default all four.
   --engine <list>             axe, ibm. Default both.
   --archetypes <list>         Limit npm and Storybook targets to these archetypes.
   --lib-a11y <list>           on, off. Default both.

package/src/data/README.md

@@ -0,0 +1,19 @@
+# WCAG data.
+
+`wcag-2.2.json` is the W3C's published JSON serialization of WCAG 2.2, copied without changes from <https://www.w3.org/WAI/WCAG22/wcag.json>. `wcag-2.2.source.json` records where and when it was downloaded, and the SHA-256 of the file. A test fails if the file and that hash disagree.
+
+automatica11y reads criterion numbers, names, levels, and versions from this file. It doesn't edit or extend the data. The links it builds from each criterion's `id` are added by automatica11y and aren't part of the W3C data.
+
+## Attribution.
+
+Source: [Web Content Accessibility Guidelines (WCAG) 2.2](https://www.w3.org/TR/WCAG22/), W3C. The JSON is published under the [terms in the W3C WCAG repository](https://github.com/w3c/wcag/blob/main/11ty/json/README.md): attribute the original source with a link, and don't change the content. See also the [W3C Document License](https://www.w3.org/copyright/document-license/) and [W3C Intellectual Rights](https://www.w3.org/copyright/intellectual-rights/).
+
+Copyright © World Wide Web Consortium. W3C® liability, trademark and permissive document license rules apply.
+
+## Updating.
+
+```bash
+npm run update-wcag
+```
+
+The W3C publishes new versions monthly. The script downloads the file, checks that it has principles and terms, and writes it unchanged.