test(a11y): add axe-core WCAG A/AA scans to accessibility suite

package.json

@@ -145,6 +145,7 @@
     "uuid": "^11.1.1"
   },
   "devDependencies": {
+    "@axe-core/playwright": "^4.12.1",
     "@next/bundle-analyzer": "^16.2.10",
     "@tailwindcss/postcss": "^4.3.2",
     "@types/node": "^26.1.1",

tests/ui-accessibility.spec.ts

@@ -1,4 +1,5 @@
-import { expect, test, type Page } from "playwright/test";
+import AxeBuilder from "@axe-core/playwright";
+import { expect, test, type Page, type TestInfo } from "playwright/test";
 
 const readySetupChecks = [
   { id: "env", label: ".env.local configured", status: "ready", detail: "Test environment ready." },
@@ -70,6 +71,29 @@ async function openScopeControl(page: Page) {
   });
 }
 
+const axeWcagTags = ["wcag2a", "wcag2aa", "wcag21a", "wcag21aa"];
+// Advisory gate: only fail on the impacts a clinician-facing release must not ship.
+// Lower-impact findings stay visible in the attached report without blocking the lane.
+const axeBlockingImpacts = new Set(["critical", "serious"]);
+
+async function expectNoBlockingAxeViolations(page: Page, testInfo: TestInfo, options?: { disableRules?: string[] }) {
+  const builder = new AxeBuilder({ page }).withTags(axeWcagTags);
+  if (options?.disableRules?.length) builder.disableRules(options.disableRules);
+  const results = await builder.analyze();
+
+  await testInfo.attach("axe-violations", {
+    body: JSON.stringify(results.violations, null, 2),
+    contentType: "application/json",
+  });
+
+  const blocking = results.violations.filter((violation) => axeBlockingImpacts.has(violation.impact ?? ""));
+  const summary = blocking.map(
+    (violation) =>
+      `${violation.id} (${violation.impact}): ${violation.help} — ${violation.nodes.length} node(s), see ${violation.helpUrl}`,
+  );
+  expect(summary, "axe found critical/serious WCAG A/AA violations").toEqual([]);
+}
+
 test.describe("Clinical KB accessibility media smoke", () => {
   test.describe.configure({ timeout: 60_000 });
 
@@ -106,4 +130,27 @@ test.describe("Clinical KB accessibility media smoke", () => {
     await expectDashboardUsable(page);
     await expectNoPageHorizontalOverflow(page);
   });
+
+  test("dashboard passes axe WCAG A/AA scan with default colors", async ({ page }, testInfo) => {
+    await page.setViewportSize({ width: 1280, height: 800 });
+    await mockMinimalDashboardApi(page);
+    await gotoApp(page);
+
+    // Scan only after the usability gate: the shell double-renders during hydration and a
+    // premature scan reports duplicated-landmark false positives.
+    await expectDashboardUsable(page);
+    await expectNoBlockingAxeViolations(page, testInfo);
+  });
+
+  test("dashboard passes axe WCAG A/AA scan with forced colors", async ({ page }, testInfo) => {
+    await page.emulateMedia({ forcedColors: "active" });
+    await page.setViewportSize({ width: 390, height: 844 });
+    await mockMinimalDashboardApi(page);
+    await gotoApp(page);
+
+    await expectDashboardUsable(page);
+    // color-contrast is unreliable under forced-colors emulation (the OS palette overrides
+    // author colors); contrast is asserted by the default-colors scan instead.
+    await expectNoBlockingAxeViolations(page, testInfo, { disableRules: ["color-contrast"] });
+  });
 });