From 899d5bbe1abc61a9ccdbdada9ad818e29bfccd1c Mon Sep 17 00:00:00 2001
From: Maris Popens <maris@popens.lv>
Date: Sat, 17 Oct 2026 17:52:43 +0300
Subject: [PATCH 1/3] fix(a11y): fix contrast, labels and heading order, and
 scan both UIs in CI

---
 .github/dependabot.yml                |  10 +
 .github/workflows/ci.yml              |  28 ++-
 docs/code-patterns.md                 |   1 +
 internal/web/static/css/tokens.css    |  14 +-
 internal/web/static/css/utilities.css |   5 +-
 internal/web/templates/brokers.html   |   3 +
 internal/web/templates/history.html   |   2 +-
 internal/web/templates/layout.html    |  12 +-
 internal/web/templates/tasks.html     |  20 +-
 scripts/a11y/.gitignore               |   1 +
 scripts/a11y/package-lock.json        | 286 ++++++++++++++++++++++++++
 scripts/a11y/package.json             |  10 +
 scripts/a11y/run.sh                   |  25 +++
 scripts/a11y/scan.mjs                 |  33 +++
 scripts/a11y/seed/main.go             |  84 ++++++++
 site/layouts/brokers/list.html        |   4 +-
 site/static/css/site.css              |   8 +-
 17 files changed, 518 insertions(+), 28 deletions(-)
 create mode 100644 scripts/a11y/.gitignore
 create mode 100644 scripts/a11y/package-lock.json
 create mode 100644 scripts/a11y/package.json
 create mode 100755 scripts/a11y/run.sh
 create mode 100644 scripts/a11y/scan.mjs
 create mode 100644 scripts/a11y/seed/main.go

diff --git a/.github/dependabot.yml b/.github/dependabot.yml
index 30eaa6a..8967a8a 100644
--- a/.github/dependabot.yml
+++ b/.github/dependabot.yml
@@ -25,3 +25,13 @@ updates:
     groups:
       actions:
         patterns: ["*"]
+
+  - package-ecosystem: "npm"
+    cooldown:
+      default-days: 7
+    directory: "/scripts/a11y"
+    schedule:
+      interval: "weekly"
+    groups:
+      a11y:
+        patterns: ["*"]
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index e734c1a..c9bf2c0 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -79,6 +79,32 @@ jobs:
       - name: Build the site
         run: ./site/build.sh
 
+  # axe-core (WCAG 2.2 A/AA, light and dark) over the website and the web UI
+  # running against fictional seed data. See scripts/a11y/run.sh.
+  a11y:
+    name: Accessibility
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+          fetch-depth: 0 # the versioned docs read every release tag
+
+      - uses: actions/setup-go@v7
+        with:
+          go-version-file: go.mod
+
+      - uses: peaceiris/actions-hugo@2752ce1d29631191ea3f27c23495fa06139a5b78 # v3.2.1
+        with:
+          hugo-version: "0.165.0"
+
+      - uses: actions/setup-node@v7
+        with:
+          node-version: "24"
+
+      - run: scripts/a11y/run.sh
+
   # The shared go-ci job covers Linux amd64. Release binaries also ship for
   # macOS, Windows and Linux arm64, so run the tests there too (no -race:
   # that needs cgo, and the release builds don't use it).
@@ -134,7 +160,7 @@ jobs:
   required-checks-passed:
     name: Required checks passed
     runs-on: ubuntu-latest
-    needs: [ci, zizmor, coverage, site, cross-platform, vulncheck]
+    needs: [ci, zizmor, coverage, site, a11y, cross-platform, vulncheck]
     if: always()
     steps:
       - if: contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled')
diff --git a/docs/code-patterns.md b/docs/code-patterns.md
index 1c21ad6..408d1d6 100644
--- a/docs/code-patterns.md
+++ b/docs/code-patterns.md
@@ -10,6 +10,7 @@
 - **History startup**: CLI commands use `openHistoryStore`, which opens the schema and runs the versioned, transactional saved-reply migration via `inbox.MigrateNoDataResponses`. Keep new entry points on this helper so upgrades do not require visiting the web UI. The migration is local-only and retryable after a rollback.
 - **Pipeline UI**: counts and pending rows share `history.GetActionItems`; use it for Pipeline and Action Needed together. The Pipeline URL carries view, status, response type, search, review, and page filters. Response search filters the active profile in SQLite before pagination, including stored email bodies.
 - **Multi-profile scoping**: any new `history.Store` method that reads/writes per-user data should take a `profileID string` first parameter and filter by it (see [multi-profile.md](multi-profile.md)) - the two deliberate exceptions are `ClearBrokerResponses`/`GetAllBrokerResponses`, which operate on the one shared inbox across all profiles.
+- **Accessibility**: CI runs axe-core (WCAG 2.2 A/AA, light and dark) over the website and the web UI against fictional seed data: `scripts/a11y/run.sh` runs the same thing locally (needs Go, Hugo, Node and Chrome). Add a new web UI page to the URL list in that script. Rules of thumb it enforces: every `<select>`/icon-only control needs an `aria-label`, links inside body text need an underline, text must hit 4.5:1 in both themes. In the web UI use `--accent` for text and borders and `--accent-solid` for fills behind white text, since the dark theme needs a lighter accent for text than for buttons. Headings step down one level at a time (`h1` then `h2`), never by tag size.
 
 ## Known quirks
 
diff --git a/internal/web/static/css/tokens.css b/internal/web/static/css/tokens.css
index 23a375b..5b7fd62 100644
--- a/internal/web/static/css/tokens.css
+++ b/internal/web/static/css/tokens.css
@@ -14,8 +14,10 @@
     --bg-elevated: #1a1a1d;
     --bg-glass: rgba(19, 19, 21, 0.9);
 
-    --accent: #6366f1;
-    --accent-hover: #818cf8;
+    --accent: #818cf8;
+    --accent-hover: #a5b4fc;
+    --accent-solid: #4f46e5;
+    --accent-solid-hover: #4338ca;
     --accent-muted: rgba(99, 102, 241, 0.12);
     --accent-glow: rgba(99, 102, 241, 0.3);
 
@@ -25,7 +27,7 @@
 
     --text-primary: #e4e4e7;
     --text-secondary: #a1a1aa;
-    --text-muted: #6b6b71;
+    --text-muted: #8b8b93;
 
     --border: #232326;
     --border-subtle: #1a1a1d;
@@ -44,7 +46,9 @@
     --bg-glass: rgba(255, 255, 255, 0.9);
 
     --accent: #4f46e5;
-    --accent-hover: #6366f1;
+    --accent-hover: #4338ca;
+    --accent-solid: #4f46e5;
+    --accent-solid-hover: #4338ca;
     --accent-muted: rgba(79, 70, 229, 0.08);
     --accent-glow: rgba(79, 70, 229, 0.25);
 
@@ -54,7 +58,7 @@
 
     --text-primary: #18181b;
     --text-secondary: #52525b;
-    --text-muted: #a1a1aa;
+    --text-muted: #666670;
 
     --border: #e4e4e7;
     --border-subtle: #f4f4f5;
diff --git a/internal/web/static/css/utilities.css b/internal/web/static/css/utilities.css
index 21f7d9a..fdf0a0d 100644
--- a/internal/web/static/css/utilities.css
+++ b/internal/web/static/css/utilities.css
@@ -901,7 +901,7 @@ img,video {
 }
 
 .bg-\[var\(--accent\)\] {
-    background-color:var(--accent);
+    background-color:var(--accent-solid);
 }
 
 .bg-\[var\(--bg-elevated\)\] {
@@ -1126,8 +1126,7 @@ img,video {
 }
 
 .text-accent {
-    --tw-text-opacity:1;
-    color:rgb(99 102 241/var(--tw-text-opacity,1));
+    color:var(--accent);
 }
 
 .text-white {
diff --git a/internal/web/templates/brokers.html b/internal/web/templates/brokers.html
index b60e977..d6f0d6c 100644
--- a/internal/web/templates/brokers.html
+++ b/internal/web/templates/brokers.html
@@ -102,6 +102,7 @@ <h1 class="font-display text-3xl font-bold text-primary">Data Brokers</h1>
             <div class="flex flex-wrap items-center gap-3">
                 <select
                     name="status"
+                    aria-label="Status"
                     class="input w-auto min-w-[120px]"
                     hx-get="/api/brokers"
                     hx-trigger="change"
@@ -115,6 +116,7 @@ <h1 class="font-display text-3xl font-bold text-primary">Data Brokers</h1>
                 </select>
                 <select
                     name="category"
+                    aria-label="Category"
                     class="input w-auto min-w-[140px]"
                     hx-get="/api/brokers"
                     hx-trigger="change"
@@ -128,6 +130,7 @@ <h1 class="font-display text-3xl font-bold text-primary">Data Brokers</h1>
                 </select>
                 <select
                     name="region"
+                    aria-label="Region"
                     class="input w-auto min-w-[120px]"
                     hx-get="/api/brokers"
                     hx-trigger="change"
diff --git a/internal/web/templates/history.html b/internal/web/templates/history.html
index 50946f9..122898b 100644
--- a/internal/web/templates/history.html
+++ b/internal/web/templates/history.html
@@ -148,7 +148,7 @@ <h1 class="font-display text-3xl font-bold text-primary">Request History</h1>
                     <div class="flex-1 min-w-0">
                         <div class="flex items-start justify-between gap-4">
                             <div>
-                                <h3 class="font-medium text-primary">{{.BrokerName}}</h3>
+                                <h2 class="font-medium text-primary">{{.BrokerName}}</h2>
                                 <p class="text-sm text-muted">{{.Email}}</p>
                             </div>
                             <div class="text-right flex-shrink-0">
diff --git a/internal/web/templates/layout.html b/internal/web/templates/layout.html
index 0acab21..028dd27 100644
--- a/internal/web/templates/layout.html
+++ b/internal/web/templates/layout.html
@@ -158,12 +158,12 @@
         }
 
         .btn-primary {
-            background: var(--accent);
+            background: var(--accent-solid);
             color: white;
         }
 
         .btn-primary:hover {
-            background: var(--accent-hover);
+            background: var(--accent-solid-hover);
         }
 
         .btn-secondary {
@@ -189,7 +189,7 @@
 
         .btn-danger {
             background: rgba(239, 68, 68, 0.12);
-            color: var(--error);
+            color: #f87171;
             border: 1px solid rgba(239, 68, 68, 0.3);
         }
 
@@ -267,6 +267,12 @@
             color: var(--error);
         }
 
+        .light .badge-success { color: #166534; }
+        .light .badge-warning { color: #92400e; }
+        .light .badge-error { color: #b91c1c; }
+        .light .btn-danger { color: #b91c1c; }
+        .text-muted a { text-decoration: underline; }
+
         .badge-neutral {
             background: var(--bg-elevated);
             color: var(--text-secondary);
diff --git a/internal/web/templates/tasks.html b/internal/web/templates/tasks.html
index 4c2778b..6f3109a 100644
--- a/internal/web/templates/tasks.html
+++ b/internal/web/templates/tasks.html
@@ -146,7 +146,7 @@ <h1 class="font-display text-3xl font-bold text-primary">Action Needed</h1>
                     <!-- Details -->
                     <div class="flex-1 min-w-0">
                         <div class="flex items-center gap-2">
-                            <h3 class="text-sm font-semibold text-primary">{{.BrokerName}}</h3>
+                            <h2 class="text-sm font-semibold text-primary">{{.BrokerName}}</h2>
                             <span class="rounded-full chip chip-info">Form</span>
                         </div>
                         {{if .EmailSubject}}
@@ -233,7 +233,7 @@ <h3 class="text-sm font-semibold text-primary">{{.BrokerName}}</h3>
                     <!-- Task Details -->
                     <div class="flex-1 min-w-0">
                         <div class="flex items-center gap-2">
-                            <h3 class="text-sm font-semibold text-primary">{{.BrokerName}}</h3>
+                            <h2 class="text-sm font-semibold text-primary">{{.BrokerName}}</h2>
                             <span class="rounded-full
                                 {{if eq .TaskType "captcha"}}chip chip-warning
                                 {{else if eq .TaskType "manual_form"}}chip chip-info
@@ -308,7 +308,7 @@ <h3 class="text-sm font-semibold text-primary">{{.BrokerName}}</h3>
                     <!-- Details -->
                     <div class="flex-1 min-w-0">
                         <div class="flex items-center gap-2">
-                            <h3 class="text-sm font-semibold text-primary">{{.BrokerName}}</h3>
+                            <h2 class="text-sm font-semibold text-primary">{{.BrokerName}}</h2>
                             <span class="rounded-full chip chip-warning">Needs Review</span>
                         </div>
                         <p class="text-xs text-muted mt-1 truncate">{{.EmailSubject}}</p>
@@ -355,7 +355,7 @@ <h3 class="text-sm font-semibold text-primary">{{.BrokerName}}</h3>
                     </div>
                     <div class="flex-1 min-w-0">
                         <div class="flex items-center gap-2">
-                            <h3 class="text-sm font-semibold text-primary">{{.BrokerName}}</h3>
+                            <h2 class="text-sm font-semibold text-primary">{{.BrokerName}}</h2>
                             <span class="rounded-full chip chip-success">Completed</span>
                         </div>
                         <p class="text-xs text-muted mt-1">Task completed</p>
@@ -385,7 +385,7 @@ <h3 class="text-sm font-semibold text-primary">{{.BrokerName}}</h3>
                     </div>
                     <div class="flex-1 min-w-0">
                         <div class="flex items-center gap-2">
-                            <h3 class="text-sm font-semibold text-primary">{{.BrokerName}}</h3>
+                            <h2 class="text-sm font-semibold text-primary">{{.BrokerName}}</h2>
                             <span class="rounded-full chip chip-success">Completed</span>
                         </div>
                         <p class="text-xs text-muted mt-1">Form submitted successfully</p>
@@ -409,7 +409,7 @@ <h3 class="text-sm font-semibold text-primary">{{.BrokerName}}</h3>
                         <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 12l2 2 4-4m6 2a9 9 0 11-18 0 9 9 0 0118 0z"/>
                     </svg>
                 </div>
-                <h3 class="text-lg font-semibold text-primary mb-2">All caught up!</h3>
+                <h2 class="text-lg font-semibold text-primary mb-2">All caught up!</h2>
                 <p class="text-secondary">No pending action items at the moment.</p>
                 <a href="/pipeline" class="btn btn-secondary mt-4">View Pipeline</a>
             </div>
@@ -419,7 +419,7 @@ <h3 class="text-lg font-semibold text-primary mb-2">All caught up!</h3>
 
     <!-- Instructions Card -->
     <div class="card p-6">
-        <h3 class="font-display text-lg font-semibold text-primary mb-4">How to Complete Tasks</h3>
+        <h2 class="font-display text-lg font-semibold text-primary mb-4">How to Complete Tasks</h2>
         <div class="grid grid-cols-1 md:grid-cols-3 gap-4">
             <div class="p-4 rounded-lg" style="background: var(--bg-elevated);">
                 <div class="w-8 h-8 icon-box icon-box-info mb-3">
@@ -427,7 +427,7 @@ <h3 class="font-display text-lg font-semibold text-primary mb-4">How to Complete
                         <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 12h6m-6 4h6m2 5H7a2 2 0 01-2-2V5a2 2 0 012-2h5.586a1 1 0 01.707.293l5.414 5.414a1 1 0 01.293.707V19a2 2 0 01-2 2z"/>
                     </svg>
                 </div>
-                <h4 class="text-sm font-semibold text-primary mb-1">Opt-Out Forms</h4>
+                <h3 class="text-sm font-semibold text-primary mb-1">Opt-Out Forms</h3>
                 <p class="text-xs text-secondary">Some brokers require filling out an online form. Click "Open Form", enter your details, and submit.</p>
             </div>
             <div class="p-4 rounded-lg" style="background: var(--bg-elevated);">
@@ -436,7 +436,7 @@ <h4 class="text-sm font-semibold text-primary mb-1">Opt-Out Forms</h4>
                         <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 12l2 2 4-4m5.618-4.016A11.955 11.955 0 0112 2.944a11.955 11.955 0 01-8.618 3.04A12.02 12.02 0 003 9c0 5.591 3.824 10.29 9 11.622 5.176-1.332 9-6.03 9-11.622 0-1.042-.133-2.052-.382-3.016z"/>
                     </svg>
                 </div>
-                <h4 class="text-sm font-semibold text-primary mb-1">CAPTCHA Forms</h4>
+                <h3 class="text-sm font-semibold text-primary mb-1">CAPTCHA Forms</h3>
                 <p class="text-xs text-secondary">Click "Solve CAPTCHA" for a helper page with copy buttons for your info. Complete the CAPTCHA, then paste your details.</p>
             </div>
             <div class="p-4 rounded-lg" style="background: var(--bg-elevated);">
@@ -445,7 +445,7 @@ <h4 class="text-sm font-semibold text-primary mb-1">CAPTCHA Forms</h4>
                         <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M3 8l7.89 5.26a2 2 0 002.22 0L21 8M5 19h14a2 2 0 002-2V7a2 2 0 00-2-2H5a2 2 0 00-2 2v10a2 2 0 002 2z"/>
                     </svg>
                 </div>
-                <h4 class="text-sm font-semibold text-primary mb-1">Email Confirmations</h4>
+                <h3 class="text-sm font-semibold text-primary mb-1">Email Confirmations</h3>
                 <p class="text-xs text-secondary">Check your email for confirmation links from brokers. Click the link to verify your removal request.</p>
             </div>
         </div>
diff --git a/scripts/a11y/.gitignore b/scripts/a11y/.gitignore
new file mode 100644
index 0000000..c2658d7
--- /dev/null
+++ b/scripts/a11y/.gitignore
@@ -0,0 +1 @@
+node_modules/
diff --git a/scripts/a11y/package-lock.json b/scripts/a11y/package-lock.json
new file mode 100644
index 0000000..ecf2c76
--- /dev/null
+++ b/scripts/a11y/package-lock.json
@@ -0,0 +1,286 @@
+{
+  "name": "eraser-a11y",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "eraser-a11y",
+      "dependencies": {
+        "axe-core": "^4.14.0",
+        "puppeteer-core": "^25.14.0"
+      }
+    },
+    "node_modules/@puppeteer/browsers": {
+      "version": "3.2.5",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "modern-tar": "^0.8.5",
+        "yargs": "^18.0.0"
+      },
+      "bin": {
+        "browsers": "lib/main-cli.js"
+      },
+      "engines": {
+        "node": ">=22.12.0"
+      },
+      "peerDependencies": {
+        "proxy-agent": ">=8.0.1",
+        "yauzl": "^2.10.0 || ^3.4.0"
+      },
+      "peerDependenciesMeta": {
+        "proxy-agent": {
+          "optional": true
+        },
+        "yauzl": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/ansi-regex": {
+      "version": "6.4.0",
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/ansi-regex?sponsor=1"
+      }
+    },
+    "node_modules/ansi-styles": {
+      "version": "6.2.3",
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/ansi-styles?sponsor=1"
+      }
+    },
+    "node_modules/axe-core": {
+      "version": "4.14.0",
+      "license": "MPL-2.0",
+      "engines": {
+        "node": ">=4"
+      }
+    },
+    "node_modules/chromium-bidi": {
+      "version": "157.0.8090-0",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "mitt": "^3.0.1",
+        "zod": "^4.6.5"
+      },
+      "engines": {
+        "node": ">=20.19.0 <22.0.0 || >=22.12.0"
+      },
+      "peerDependencies": {
+        "devtools-protocol": "*"
+      }
+    },
+    "node_modules/cliui": {
+      "version": "9.0.1",
+      "license": "ISC",
+      "dependencies": {
+        "string-width": "^7.2.0",
+        "strip-ansi": "^7.1.0",
+        "wrap-ansi": "^9.0.0"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "node_modules/cliui/node_modules/string-width": {
+      "version": "7.2.0",
+      "license": "MIT",
+      "dependencies": {
+        "emoji-regex": "^10.3.0",
+        "get-east-asian-width": "^1.0.0",
+        "strip-ansi": "^7.1.0"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/devtools-protocol": {
+      "version": "0.0.1696802",
+      "license": "BSD-3-Clause"
+    },
+    "node_modules/emoji-regex": {
+      "version": "10.6.0",
+      "license": "MIT"
+    },
+    "node_modules/escalade": {
+      "version": "3.2.0",
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/get-caller-file": {
+      "version": "2.0.5",
+      "license": "ISC",
+      "engines": {
+        "node": "6.* || 8.* || >= 10.*"
+      }
+    },
+    "node_modules/get-east-asian-width": {
+      "version": "1.7.0",
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/mitt": {
+      "version": "3.0.1",
+      "license": "MIT"
+    },
+    "node_modules/modern-tar": {
+      "version": "0.8.6",
+      "license": "MIT",
+      "engines": {
+        "node": ">=18.0.0"
+      }
+    },
+    "node_modules/puppeteer-core": {
+      "version": "25.14.0",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@puppeteer/browsers": "3.2.5",
+        "chromium-bidi": "157.0.8090-0",
+        "devtools-protocol": "0.0.1696802",
+        "typed-query-selector": "^2.12.3",
+        "webdriver-bidi-protocol": "1.0.1",
+        "ws": "^8.22.0"
+      },
+      "engines": {
+        "node": ">=22.12.0"
+      }
+    },
+    "node_modules/string-width": {
+      "version": "8.3.0",
+      "license": "MIT",
+      "dependencies": {
+        "get-east-asian-width": "^1.5.0",
+        "strip-ansi": "^7.1.2"
+      },
+      "engines": {
+        "node": ">=20"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/strip-ansi": {
+      "version": "7.2.0",
+      "license": "MIT",
+      "dependencies": {
+        "ansi-regex": "^6.2.2"
+      },
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/strip-ansi?sponsor=1"
+      }
+    },
+    "node_modules/typed-query-selector": {
+      "version": "2.12.3",
+      "license": "MIT"
+    },
+    "node_modules/webdriver-bidi-protocol": {
+      "version": "1.0.1",
+      "license": "Apache-2.0"
+    },
+    "node_modules/wrap-ansi": {
+      "version": "9.0.2",
+      "license": "MIT",
+      "dependencies": {
+        "ansi-styles": "^6.2.1",
+        "string-width": "^7.0.0",
+        "strip-ansi": "^7.1.0"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/wrap-ansi?sponsor=1"
+      }
+    },
+    "node_modules/wrap-ansi/node_modules/string-width": {
+      "version": "7.2.0",
+      "license": "MIT",
+      "dependencies": {
+        "emoji-regex": "^10.3.0",
+        "get-east-asian-width": "^1.0.0",
+        "strip-ansi": "^7.1.0"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/ws": {
+      "version": "8.22.0",
+      "license": "MIT",
+      "engines": {
+        "node": ">=10.0.0"
+      },
+      "peerDependencies": {
+        "bufferutil": "^4.0.1",
+        "utf-8-validate": ">=5.0.2"
+      },
+      "peerDependenciesMeta": {
+        "bufferutil": {
+          "optional": true
+        },
+        "utf-8-validate": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/y18n": {
+      "version": "5.0.8",
+      "license": "ISC",
+      "engines": {
+        "node": ">=10"
+      }
+    },
+    "node_modules/yargs": {
+      "version": "18.2.0",
+      "license": "MIT",
+      "dependencies": {
+        "cliui": "^9.0.1",
+        "escalade": "^3.1.1",
+        "get-caller-file": "^2.0.5",
+        "string-width": "^8.2.1",
+        "y18n": "^5.0.5",
+        "yargs-parser": "^22.0.0"
+      },
+      "engines": {
+        "node": "^20.19.0 || ^22.12.0 || >=23"
+      }
+    },
+    "node_modules/yargs-parser": {
+      "version": "22.0.0",
+      "license": "ISC",
+      "engines": {
+        "node": "^20.19.0 || ^22.12.0 || >=23"
+      }
+    },
+    "node_modules/zod": {
+      "version": "4.6.7",
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/sponsors/colinhacks"
+      }
+    }
+  }
+}
diff --git a/scripts/a11y/package.json b/scripts/a11y/package.json
new file mode 100644
index 0000000..c4c97d2
--- /dev/null
+++ b/scripts/a11y/package.json
@@ -0,0 +1,10 @@
+{
+  "name": "eraser-a11y",
+  "private": true,
+  "type": "module",
+  "description": "axe-core accessibility scan of the website and the web UI",
+  "dependencies": {
+    "axe-core": "^4.14.0",
+    "puppeteer-core": "^25.14.0"
+  }
+}
diff --git a/scripts/a11y/run.sh b/scripts/a11y/run.sh
new file mode 100755
index 0000000..547f8d8
--- /dev/null
+++ b/scripts/a11y/run.sh
@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+# Builds the website and the web UI against fictional data, then runs the
+# axe-core scan over both. usage: scripts/a11y/run.sh [chrome-binary]
+set -euo pipefail
+root=$(cd "$(dirname "$0")/../.." && pwd)
+work=$(mktemp -d)
+pids=()
+trap 'kill "${pids[@]}" 2>/dev/null || true; rm -rf "$work"' EXIT
+
+chrome=${1:-${CHROME:-$(command -v google-chrome || command -v chromium || echo "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome")}}
+
+"$root/site/build.sh" -d "$work/site" >/dev/null
+(cd "$root" && go build -o "$work/eraser" ./cmd/eraser && go run ./scripts/a11y/seed "$work/home")
+(cd "$root/scripts/a11y" && npm ci --silent)
+
+python3 -m http.server 4000 --directory "$work/site" >/dev/null 2>&1 & pids+=($!)
+HOME="$work/home" "$work/eraser" serve -p 3999 >"$work/serve.log" 2>&1 & pids+=($!)
+for port in 4000 3999; do
+  for _ in $(seq 50); do curl -fs -o /dev/null "localhost:$port/" && break; sleep 0.2; done
+done
+
+site=http://localhost:4000 ui=http://localhost:3999
+node "$root/scripts/a11y/scan.mjs" "$chrome" \
+  $site/ $site/brokers/ $site/guides/ $site/docs/next/ $site/docs/next/mcp/ $site/authorities/ $site/privacy/ \
+  $ui/ $ui/brokers $ui/pipeline "$ui/pipeline?view=actions" $ui/history $ui/tasks $ui/settings $ui/automation
diff --git a/scripts/a11y/scan.mjs b/scripts/a11y/scan.mjs
new file mode 100644
index 0000000..5d7bc94
--- /dev/null
+++ b/scripts/a11y/scan.mjs
@@ -0,0 +1,33 @@
+// Runs axe-core (WCAG 2.x A/AA) over the given URLs in light and dark mode.
+// usage: node scan.mjs <chrome> <url>...   exit 1 on any violation
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import puppeteer from "puppeteer-core";
+
+const require = createRequire(import.meta.url);
+const axe = readFileSync(require.resolve("axe-core/axe.min.js"), "utf8");
+const [chrome, ...urls] = process.argv.slice(2);
+const browser = await puppeteer.launch({ executablePath: chrome, headless: true, args: ["--no-sandbox"] });
+let failed = 0;
+for (const url of urls) {
+  for (const scheme of ["light", "dark"]) {
+    const page = await browser.newPage();
+    await page.setBypassCSP(true);
+    await page.emulateMediaFeatures([{ name: "prefers-color-scheme", value: scheme }, { name: "prefers-reduced-motion", value: "reduce" }]);
+    await page.evaluateOnNewDocument((s) => { try { localStorage.setItem("eraser-theme", s); } catch {} }, scheme);
+    await page.goto(url, { waitUntil: "networkidle0" });
+    await new Promise((r) => setTimeout(r, 1000)); // let entrance animations settle, axe reads mid-fade colours
+    await page.evaluate(axe);
+    const { violations } = await page.evaluate(() =>
+      axe.run({ runOnly: { type: "tag", values: ["wcag2a", "wcag2aa", "wcag21a", "wcag21aa", "wcag22aa"] } }));
+    for (const v of violations) {
+      failed++;
+      console.log(`${url} [${scheme}] ${v.id} (${v.impact}): ${v.help}`);
+      for (const n of v.nodes.slice(0, 3)) console.log(`    ${n.target.join(" ")}\n    ${n.failureSummary.split("\n").slice(0, 2).join(" | ")}`);
+    }
+    await page.close();
+  }
+}
+await browser.close();
+console.log(failed ? `${failed} violation(s)` : "no violations");
+process.exit(failed ? 1 : 0);
diff --git a/scripts/a11y/seed/main.go b/scripts/a11y/seed/main.go
new file mode 100644
index 0000000..b25c1fa
--- /dev/null
+++ b/scripts/a11y/seed/main.go
@@ -0,0 +1,84 @@
+// Seeds a throwaway HOME with a fictional profile and a spread of history so
+// the accessibility scan sees every status colour, badge and task type.
+// usage: go run ./scripts/a11y/seed <home-dir>
+package main
+
+import (
+	"fmt"
+	"log"
+	"os"
+	"path/filepath"
+	"time"
+
+	"github.com/drumandbytes/eraser/internal/history"
+)
+
+const cfg = `profiles:
+  - id: default
+    first_name: Jane
+    last_name: Doe
+    email: jane@example.com
+    country: Latvia
+email:
+  provider: smtp
+  from: jane@example.com
+  smtp:
+    host: smtp.example.com
+    port: 465
+    username: jane@example.com
+    password: xxxxxxxxxxxxxxxx
+    use_tls: true
+options:
+  template: gdpr
+  send_mode: manual
+`
+
+func main() {
+	if len(os.Args) != 2 {
+		log.Fatal("usage: seed <home-dir>")
+	}
+	dir := filepath.Join(os.Args[1], ".eraser")
+	must(os.MkdirAll(dir, 0o700))
+	must(os.WriteFile(filepath.Join(dir, "config.yaml"), []byte(cfg), 0o600))
+	s, err := history.NewStore(filepath.Join(dir, "history.db"))
+	must(err)
+	defer func() { must(s.Close()) }()
+
+	now := time.Now()
+	rows := []struct {
+		id     string
+		status history.Status
+		stage  history.PipelineStatus
+	}{
+		{"spokeo", history.StatusSent, history.PipelineAwaitingResponse},
+		{"beenverified", history.StatusSent, history.PipelineAwaitingResponse},
+		{"whitepages", history.StatusSent, history.PipelineConfirmed},
+		{"intelius", history.StatusSent, history.PipelineConfirmed},
+		{"radaris", history.StatusSent, history.PipelineNoData},
+		{"peoplefinders", history.StatusSent, history.PipelineRejected},
+		{"acme", history.StatusSent, history.PipelineFormRequired},
+		{"globex", history.StatusFailed, history.PipelineFailed},
+	}
+	for _, r := range rows {
+		rec := &history.Record{ProfileID: "default", BrokerID: r.id, BrokerName: r.id, Email: "privacy@" + r.id + ".test",
+			Template: "gdpr", Status: r.status, SentAt: now, SentMethod: "manual"}
+		if r.status == history.StatusFailed {
+			rec.Error = "connection refused"
+		}
+		must(s.Add(rec))
+		must(s.UpdatePipelineStatus("default", r.id, r.stage))
+	}
+	for i, t := range []history.TaskType{history.TaskManualForm, history.TaskCaptcha, history.TaskConfirm, history.TaskReview} {
+		must(s.AddPendingTask(&history.PendingTask{ProfileID: "default", BrokerID: rows[6].id, BrokerName: fmt.Sprintf("Example Data Co %d", i+1),
+			TaskType: t, FormURL: "https://privacy.example-data.test/optout", Status: "pending", ReviewReason: "reply is ambiguous"}))
+	}
+	must(s.CreateBatchApproval(history.BatchApproval{PlanID: "b7c0f3e91d2a4c58", ProfileID: "default", Digest: "d",
+		Preview: `{"profile_fields":{"first_name":"Jane"},"forms":[{"broker":"Example Data Co","url":"https://privacy.example-data.test/optout"}],"emails":[]}`,
+		ExpiresAt: now.Add(15 * time.Minute)}))
+}
+
+func must(err error) {
+	if err != nil {
+		log.Fatal(err)
+	}
+}
diff --git a/site/layouts/brokers/list.html b/site/layouts/brokers/list.html
index 83b7261..00b315a 100644
--- a/site/layouts/brokers/list.html
+++ b/site/layouts/brokers/list.html
@@ -22,8 +22,8 @@ <h2>Opt-out guides</h2>
   <h2>Full broker list</h2>
   <div class="filters">
     <input type="search" id="q" placeholder="Filter by name…" autocomplete="off">
-    <select id="region"><option value="">All regions</option><option>us</option><option>eu</option><option>global</option></select>
-    <select id="cat"><option value="">All categories</option></select>
+    <select id="region" aria-label="Region"><option value="">All regions</option><option>us</option><option>eu</option><option>global</option></select>
+    <select id="cat" aria-label="Category"><option value="">All categories</option></select>
     <label><input type="checkbox" id="curatedonly"> Guides only</label>
   </div>
   <p class="meta"><span id="count">Loading…</span></p>
diff --git a/site/static/css/site.css b/site/static/css/site.css
index 38da9ea..8140849 100644
--- a/site/static/css/site.css
+++ b/site/static/css/site.css
@@ -41,8 +41,10 @@ body {
   color: var(--ink);
   font: 16px/1.65 -apple-system, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
 }
-a { color: var(--accent); text-decoration: none; }
-a:hover { color: var(--accent-hover); text-decoration: underline; }
+a { color: var(--accent); text-decoration: underline; text-underline-offset: .15em; }
+a:hover { color: var(--accent-hover); text-decoration-thickness: 2px; }
+.brand, .topbar nav a, .btn { text-decoration: none; }
+.topbar nav a:hover, .btn:hover { text-decoration: underline; }
 
 .topbar {
   display: flex; align-items: baseline; gap: 1.5rem;
@@ -65,7 +67,7 @@ a:hover { color: var(--accent-hover); text-decoration: underline; }
   display: inline-block; padding: .6rem 1.1rem; border-radius: 8px;
   background: var(--accent); color: var(--on-accent); font-weight: 600;
 }
-.btn:hover { background: var(--accent-hover); color: var(--on-accent); text-decoration: none; }
+.btn:hover { background: var(--accent-hover); color: var(--on-accent); }
 .btn.ghost { background: transparent; color: var(--accent); border: 1px solid var(--border); }
 
 .cols { display: grid; grid-template-columns: 1fr 1fr; gap: 2.5rem; margin-top: 3.5rem; }

From f0c5b0bc981ebec32d7287e22fcf223691f6ea4e Mon Sep 17 00:00:00 2001
From: Maris Popens <maris@popens.lv>
Date: Sat, 17 Oct 2026 17:53:45 +0300
Subject: [PATCH 2/3] style(a11y): gofmt the seed script

---
 scripts/a11y/seed/main.go | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/scripts/a11y/seed/main.go b/scripts/a11y/seed/main.go
index b25c1fa..e187860 100644
--- a/scripts/a11y/seed/main.go
+++ b/scripts/a11y/seed/main.go
@@ -73,7 +73,7 @@ func main() {
 			TaskType: t, FormURL: "https://privacy.example-data.test/optout", Status: "pending", ReviewReason: "reply is ambiguous"}))
 	}
 	must(s.CreateBatchApproval(history.BatchApproval{PlanID: "b7c0f3e91d2a4c58", ProfileID: "default", Digest: "d",
-		Preview: `{"profile_fields":{"first_name":"Jane"},"forms":[{"broker":"Example Data Co","url":"https://privacy.example-data.test/optout"}],"emails":[]}`,
+		Preview:   `{"profile_fields":{"first_name":"Jane"},"forms":[{"broker":"Example Data Co","url":"https://privacy.example-data.test/optout"}],"emails":[]}`,
 		ExpiresAt: now.Add(15 * time.Minute)}))
 }
 

From 9aea9b4e3e713755edca9ab9f0795a5a58084fdf Mon Sep 17 00:00:00 2001
From: Maris Popens <maris@popens.lv>
Date: Sat, 17 Oct 2026 18:00:55 +0300
Subject: [PATCH 3/3] fix(a11y): darken error and warning text tokens for the
 CI-found contrast failures

---
 internal/web/static/css/tokens.css | 6 +++---
 internal/web/templates/layout.html | 5 +----
 2 files changed, 4 insertions(+), 7 deletions(-)

diff --git a/internal/web/static/css/tokens.css b/internal/web/static/css/tokens.css
index 5b7fd62..75d14a5 100644
--- a/internal/web/static/css/tokens.css
+++ b/internal/web/static/css/tokens.css
@@ -23,7 +23,7 @@
 
     --success: #22c55e;
     --warning: #eab308;
-    --error: #ef4444;
+    --error: #f87171;
 
     --text-primary: #e4e4e7;
     --text-secondary: #a1a1aa;
@@ -53,8 +53,8 @@
     --accent-glow: rgba(79, 70, 229, 0.25);
 
     --success: #16a34a;
-    --warning: #b45309;
-    --error: #dc2626;
+    --warning: #92400e;
+    --error: #b91c1c;
 
     --text-primary: #18181b;
     --text-secondary: #52525b;
diff --git a/internal/web/templates/layout.html b/internal/web/templates/layout.html
index 028dd27..a7ff69a 100644
--- a/internal/web/templates/layout.html
+++ b/internal/web/templates/layout.html
@@ -189,7 +189,7 @@
 
         .btn-danger {
             background: rgba(239, 68, 68, 0.12);
-            color: #f87171;
+            color: var(--error);
             border: 1px solid rgba(239, 68, 68, 0.3);
         }
 
@@ -268,9 +268,6 @@
         }
 
         .light .badge-success { color: #166534; }
-        .light .badge-warning { color: #92400e; }
-        .light .badge-error { color: #b91c1c; }
-        .light .btn-danger { color: #b91c1c; }
         .text-muted a { text-decoration: underline; }
 
         .badge-neutral {