chore(atomic-a11y): add shared foundation, and delta audit validation

knip.jsonc

@@ -80,6 +80,9 @@
     "utils/cdn": {
       "ignoreDependencies": ["@coveo/bueno", "local-web-server"]
     },
+    "packages/atomic-a11y": {
+      "entry": ["scripts/*.mjs", "src/index.ts", "src/audit/*.ts"]
+    },
 
     // Projects to enable bunch by bunch.
     // Projects using stencil don't really have a proper entry point because of stencil's magic so they have problems with knip.

packages/atomic-a11y/.gitignore

@@ -0,0 +1 @@
+.env

packages/atomic-a11y/README.md

@@ -58,6 +58,12 @@ Automated testing covers ~30-40% of WCAG criteria. The rest requires human revie
 
 **→ [Manual Audit Guide](docs/manual-audit-guide.md)**
 
+## AI audits
+
+The AI audit agent evaluates components against 21 WCAG 2.2 criteria that axe-core cannot automate — visual layout, focus visibility, semantic text quality, and more. Requires a GitHub token with Copilot access.
+
+**→ [AI Audit Guide](docs/ai-audit-guide.md)**
+
 ## Structure
 
 ```

packages/atomic-a11y/a11y/a11y-manual-criteria.json

@@ -0,0 +1,17 @@
+{
+  "criteria": [
+    "1.3.2-meaningful-sequence",
+    "1.3.3-sensory-characteristics",
+    "1.3.4-orientation",
+    "1.3.5-identify-input-purpose",
+    "1.4.4-resize-text",
+    "1.4.5-images-of-text",
+    "1.4.10-reflow",
+    "1.4.12-text-spacing",
+    "1.4.13-content-on-hover-focus",
+    "2.4.4-link-purpose",
+    "2.4.6-headings-and-labels",
+    "2.4.7-focus-visible",
+    "2.4.11-focus-not-obscured"
+  ]
+}

packages/atomic-a11y/a11y/a11y-overrides.json

@@ -1,9 +1,79 @@
 {
   "overrides": [
+    {
+      "criterion": "1.2.1",
+      "conformance": "not-applicable",
+      "reason": "Atomic components do not include prerecorded audio-only or video-only content."
+    },
+    {
+      "criterion": "1.2.2",
+      "conformance": "not-applicable",
+      "reason": "Atomic components do not include synchronized media requiring captions."
+    },
+    {
+      "criterion": "1.2.3",
+      "conformance": "not-applicable",
+      "reason": "Atomic components do not include prerecorded video content requiring audio descriptions."
+    },
+    {
+      "criterion": "1.2.4",
+      "conformance": "not-applicable",
+      "reason": "Atomic components do not include live audio content."
+    },
+    {
+      "criterion": "1.2.5",
+      "conformance": "not-applicable",
+      "reason": "Atomic components do not include prerecorded video content."
+    },
     {
       "criterion": "1.4.2",
       "conformance": "not-applicable",
       "reason": "Atomic components do not produce audio output."
+    },
+    {
+      "criterion": "2.4.1",
+      "conformance": "not-applicable",
+      "reason": "Bypass blocks is a page-level concern — skip links and landmark regions are the responsibility of the consuming application."
+    },
+    {
+      "criterion": "2.4.2",
+      "conformance": "not-applicable",
+      "reason": "Page titles are set at the document level by the consuming application, not by embedded components."
+    },
+    {
+      "criterion": "2.4.5",
+      "conformance": "not-applicable",
+      "reason": "Multiple ways to locate content is a site architecture concern — navigation mechanisms are the responsibility of the consuming application."
+    },
+    {
+      "criterion": "2.5.4",
+      "conformance": "not-applicable",
+      "reason": "Atomic components do not implement device motion-based interactions."
+    },
+    {
+      "criterion": "2.5.7",
+      "conformance": "not-applicable",
+      "reason": "Atomic components do not require dragging movements — all interactions have single-pointer alternatives."
+    },
+    {
+      "criterion": "3.2.6",
+      "conformance": "not-applicable",
+      "reason": "Consistent help mechanisms are an application-level concern — Atomic provides UI primitives, not help systems."
+    },
+    {
+      "criterion": "3.3.4",
+      "conformance": "not-applicable",
+      "reason": "Error prevention for legal, financial, or data transactions is a business logic concern handled by the consuming application."
+    },
+    {
+      "criterion": "3.3.7",
+      "conformance": "not-applicable",
+      "reason": "Redundant entry prevention for multi-step processes is an application-level concern — Atomic provides form primitives, not process flows."
+    },
+    {
+      "criterion": "3.3.8",
+      "conformance": "not-applicable",
+      "reason": "Atomic components do not implement authentication flows."
     }
   ]
 }

packages/atomic-a11y/docs/manual-audit-guide.md

@@ -20,6 +20,28 @@ packages/atomic-a11y/
 
 **Default directory**: `a11y/reports`
 
+## Human vs automation workflows
+
+There are two ways manual audit data enters the system:
+
+1. **Baseline files (QA workflow)** — edit `manual-audit-{category}.json` directly.
+2. **Delta files (automation workflow)** — generated by AI/automation and merged into baselines.
+
+**QA should only use baseline files.** Delta files are an internal pipeline detail used to
+validate and merge automated audit output.
+
+```
+packages/atomic-a11y/
+└── a11y/
+    └── reports/
+        ├── manual-audit-search.json
+        ├── manual-audit-commerce.json
+        ├── ...
+        └── deltas/                          ← automation-only
+            ├── delta-YYYY-MM-DD-<context>.json
+            └── archived/
+```
+
 ## File naming
 
 Files **must** match this pattern:
@@ -187,6 +209,8 @@ Additionally, individual criterion entries within `wcag22Criteria` are skipped i
 
 ## Workflow
 
+### QA workflow (baseline files)
+
 1. Pick a component category (search, commerce, etc.)
 2. Create or edit `a11y/reports/manual-audit-{category}.json`
 3. For each component you've audited:
@@ -201,6 +225,19 @@ Additionally, individual criterion entries within `wcag22Criteria` are skipped i
      → merges both → OpenACR YAML → VPAT markdown
 ```
 
+### Automation workflow (delta files)
+
+Automated audits (AI or scripted tooling) write **delta files** into
+`a11y/reports/deltas/`. These deltas are validated and merged into baseline
+files using:
+
+```
+node scripts/manual-audit-delta.mjs merge
+```
+
+This keeps human-edited baselines clean while allowing automated updates to be
+reviewed and merged safely.
+
 ## Tips
 
 - **Start with `"pending"`** — set `status` to `"pending"` while auditing, then flip to `"complete"` when done. Pending entries are safely ignored.

packages/atomic-a11y/scripts/manual-audit-delta.mjs

@@ -0,0 +1,6 @@
+import {main} from '../dist/audit/manual-audit-delta.js';
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});