docs: ATB-34 axe-core a11y implementation plan

Step-by-step plan: add axe-core + jsdom deps, create consolidated test
file with jsdom env pragma, one happy-path WCAG AA test per page route.

docs/plans/2026-02-27-axe-core-a11y.md

···
+# ATB-34: Axe-core Automated Accessibility Testing — Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Add a single consolidated test file to `apps/web` that runs axe-core against every full-page HTML route and asserts zero WCAG AA violations.
+
+**Architecture:** Vitest's `@vitest-environment jsdom` per-file pragma switches the test file to a jsdom environment, providing `DOMParser` and `document` globals. Each test calls the Hono route handler directly via `app.request()`, parses the HTML response with `DOMParser`, and passes the resulting `Document` to `axe.run()`. Module-level `vi.mock` intercepts `fetchApi` and `getSession` calls so no real network is needed.
+
+**Tech Stack:** `axe-core`, `jsdom`, Vitest, Hono (test via `app.request()`), `vi.mock` for module mocking
+
+**Design doc:** `docs/plans/2026-02-27-axe-core-a11y-design.md`
+
+**Known limitation:** jsdom has no CSS engine. Axe-core's `color-contrast` rules are automatically skipped. These tests cover structural/semantic WCAG AA rules only (landmark regions, heading hierarchy, form labels, aria attributes, link purpose). Color contrast requires manual or Playwright-based verification.
+
+---
+
+### Task 1: Add dependencies
+
+**Files:**
+- Modify: `apps/web/package.json`
+
+**Step 1: Add axe-core, jsdom, and vitest as devDependencies**
+
+Run from the repo root (requires devenv shell — `devenv shell` first):
+
+```bash
+PATH=/Users/jacob.zweifel/workspace/malpercio-dev/atbb-monorepo/.devenv/profile/bin:$PATH \
+  pnpm --filter @atbb/web add -D axe-core jsdom vitest
+```
+
+Expected: pnpm updates `apps/web/package.json` and `pnpm-lock.yaml`.
+
+**Step 2: Verify the additions appear in package.json**
+
+Check that `apps/web/package.json` now contains:
+```json
+"devDependencies": {
+  "axe-core": "...",
+  "jsdom": "...",
+  "vitest": "..."
+}
+```
+
+**Step 3: Commit**
+
+```bash
+git add apps/web/package.json pnpm-lock.yaml
+git commit -m "chore(web): add axe-core, jsdom, vitest as explicit devDependencies (ATB-34)"
+```
+
+---
+
+### Task 2: Create the test file skeleton
+
+**Files:**
+- Create: `apps/web/src/__tests__/a11y.test.ts`
+
+**Step 1: Create the file with the environment pragma, imports, and module mocks**
+
+```typescript
+// @vitest-environment jsdom
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import axe from "axe-core";
+
+// ── Module mocks ──────────────────────────────────────────────────────────────
+// Must be declared before any imports that use these modules.
+// vi.mock is hoisted to the top of the file by Vitest's transform.
+
+vi.mock("../lib/api.js", () => ({
+  fetchApi: vi.fn(),
+}));
+
+vi.mock("../lib/session.js", () => ({
+  getSession: vi.fn(),
+  getSessionWithPermissions: vi.fn(),
+  canLockTopics: vi.fn().mockReturnValue(false),
+  canModeratePosts: vi.fn().mockReturnValue(false),
+  canBanUsers: vi.fn().mockReturnValue(false),
+}));
+
+vi.mock("../lib/logger.js", () => ({
+  logger: {
+    debug: vi.fn(),
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    fatal: vi.fn(),
+  },
+}));
+
+// ── Import mocked modules so we can configure return values per test ──────────
+import { fetchApi } from "../lib/api.js";
+import { getSession, getSessionWithPermissions } from "../lib/session.js";
+
+// ── Route factories ───────────────────────────────────────────────────────────
+import { createHomeRoutes } from "../routes/home.js";
+import { createLoginRoutes } from "../routes/login.js";
+import { createBoardsRoutes } from "../routes/boards.js";
+import { createTopicsRoutes } from "../routes/topics.js";
+import { createNewTopicRoutes } from "../routes/new-topic.js";
+import { createNotFoundRoute } from "../routes/not-found.js";
+
+// ── Constants ─────────────────────────────────────────────────────────────────
+const APPVIEW_URL = "http://localhost:3000";
+
+// ── Typed mock handles ────────────────────────────────────────────────────────
+const mockFetchApi = vi.mocked(fetchApi);
+const mockGetSession = vi.mocked(getSession);
+const mockGetSessionWithPermissions = vi.mocked(getSessionWithPermissions);
+
+// ── Shared reset ──────────────────────────────────────────────────────────────
+beforeEach(() => {
+  mockFetchApi.mockReset();
+  // Default: unauthenticated session for all routes.
+  // Override in individual tests that need authenticated state.
+  mockGetSession.mockResolvedValue({ authenticated: false });
+  mockGetSessionWithPermissions.mockResolvedValue({
+    authenticated: false,
+    permissions: new Set<string>(),
+  });
+});
+
+// ── A11y helper ───────────────────────────────────────────────────────────────
+// NOTE: jsdom has no CSS engine, so axe-core's color-contrast rules are
+// skipped automatically. These tests cover structural/semantic WCAG AA rules
+// only (landmark regions, heading hierarchy, form labels, aria attributes).
+async function checkA11y(html: string): Promise<void> {
+  const doc = new DOMParser().parseFromString(html, "text/html");
+  const results = await axe.run(doc, {
+    runOnly: { type: "tag", values: ["wcag2a", "wcag2aa"] },
+  });
+  const summary = results.violations
+    .map(
+      (v) =>
+        `  [${v.id}] ${v.description}\n` +
+        v.nodes.map((n) => `    → ${n.html}`).join("\n")
+    )
+    .join("\n");
+  expect(
+    results.violations,
+    `WCAG AA violations found:\n${summary}`
+  ).toHaveLength(0);
+}
+
+describe("WCAG AA accessibility — one happy-path test per page route", () => {
+  // Tests go here in Task 3–8
+});
+```
+
+**Step 2: Verify the file can be collected by Vitest without errors**
+
+```bash
+PATH=/Users/jacob.zweifel/workspace/malpercio-dev/atbb-monorepo/.devenv/profile/bin:$PATH \
+  pnpm --filter @atbb/web exec vitest run src/__tests__/a11y.test.ts
+```
+
+Expected output: `0 tests` collected, no import/type errors. If you see a module resolution error, fix the import paths before proceeding.
+
+**Step 3: Commit**
+
+```bash
+git add apps/web/src/__tests__/a11y.test.ts
+git commit -m "test(web): scaffold a11y test file with jsdom environment and module mocks (ATB-34)"
+```
+
+---
+
+### Task 3: Home page test
+
+The home route calls `fetchApi` three times:
+1. `fetchApi("/forum")` and `fetchApi("/categories")` in parallel (stage 1)
+2. `fetchApi("/categories/1/boards")` for each category (stage 2)
+
+Use URL-pattern dispatch in `mockImplementation` so parallel calls resolve correctly regardless of call order.
+
+**Files:**
+- Modify: `apps/web/src/__tests__/a11y.test.ts`
+
+**Step 1: Add the home page test inside the `describe` block**
+
+```typescript
+it("home page / has no violations", async () => {
+  mockFetchApi.mockImplementation((path: string) => {
+    if (path === "/forum") {
+      return Promise.resolve({
+        id: "1",
+        did: "did:plc:forum",
+        name: "Test Forum",
+        description: "A test forum",
+        indexedAt: "2024-01-01T00:00:00.000Z",
+      });
+    }
+    if (path === "/categories") {
+      return Promise.resolve({
+        categories: [
+          {
+            id: "1",
+            did: "did:plc:forum",
+            name: "General",
+            description: null,
+            slug: "general",
+            sortOrder: 0,
+          },
+        ],
+      });
+    }
+    if (path === "/categories/1/boards") {
+      return Promise.resolve({
+        boards: [
+          {
+            id: "1",
+            did: "did:plc:forum",
+            name: "Test Board",
+            description: null,
+            slug: "test",
+            sortOrder: 0,
+          },
+        ],
+      });
+    }
+    return Promise.reject(new Error(`Unexpected fetchApi call: ${path}`));
+  });
+
+  const routes = createHomeRoutes(APPVIEW_URL);
+  const res = await routes.request("/");
+  expect(res.status).toBe(200);
+  await checkA11y(await res.text());
+});
+```
+
+**Step 2: Run just this test**
+
+```bash
+PATH=/Users/jacob.zweifel/workspace/malpercio-dev/atbb-monorepo/.devenv/profile/bin:$PATH \
+  pnpm --filter @atbb/web exec vitest run src/__tests__/a11y.test.ts -t "home page"
+```
+
+Expected: PASS. If axe reports violations, inspect the violation `[id]` and fix the corresponding HTML in `apps/web/src/routes/home.tsx` or `apps/web/src/layouts/base.tsx`.
+
+**Step 3: Commit once passing**
+
+```bash
+git add apps/web/src/__tests__/a11y.test.ts
+git commit -m "test(web): add WCAG AA test for home page (ATB-34)"
+```
+
+---
+
+### Task 4: Login page test
+
+The login route calls `getSession()` which returns early (no fetch) when no `atbb_session` cookie is present — which is the case here since we don't include a Cookie header. No `fetchApi` calls needed.
+
+**Files:**
+- Modify: `apps/web/src/__tests__/a11y.test.ts`
+
+**Step 1: Add the login page test**
+
+```typescript
+it("login page /login has no violations", async () => {
+  // getSession returns { authenticated: false } immediately with no cookie header.
+  // No fetchApi calls are made.
+  const routes = createLoginRoutes(APPVIEW_URL);
+  const res = await routes.request("/login");
+  expect(res.status).toBe(200);
+  await checkA11y(await res.text());
+});
+```
+
+**Step 2: Run just this test**
+
+```bash
+PATH=/Users/jacob.zweifel/workspace/malpercio-dev/atbb-monorepo/.devenv/profile/bin:$PATH \
+  pnpm --filter @atbb/web exec vitest run src/__tests__/a11y.test.ts -t "login page"
+```
+
+Expected: PASS.
+
+**Step 3: Commit once passing**
+
+```bash
+git add apps/web/src/__tests__/a11y.test.ts
+git commit -m "test(web): add WCAG AA test for login page (ATB-34)"
+```
+
+---
+
+### Task 5: Board page test
+
+The board route calls `fetchApi` three times in sequence:
+1. `fetchApi("/boards/1")` and `fetchApi("/boards/1/topics?offset=0&limit=25")` in parallel (stage 1)
+2. `fetchApi("/categories/1")` for the category breadcrumb (stage 2)
+
+**Files:**
+- Modify: `apps/web/src/__tests__/a11y.test.ts`
+
+**Step 1: Add the board page test**
+
+```typescript
+it("board page /boards/:id has no violations", async () => {
+  mockFetchApi.mockImplementation((path: string) => {
+    if (path === "/boards/1") {
+      return Promise.resolve({
+        id: "1",
+        did: "did:plc:forum",
+        uri: "at://did:plc:forum/space.atbb.forum.board/1",
+        name: "Test Board",
+        description: null,
+        slug: "test",
+        sortOrder: 0,
+        categoryId: "1",
+        categoryUri: null,
+        createdAt: "2024-01-01T00:00:00.000Z",
+        indexedAt: "2024-01-01T00:00:00.000Z",
+      });
+    }
+    if (path === "/boards/1/topics?offset=0&limit=25") {
+      return Promise.resolve({ topics: [], total: 0, offset: 0, limit: 25 });
+    }
+    if (path === "/categories/1") {
+      return Promise.resolve({
+        id: "1",
+        did: "did:plc:forum",
+        name: "General",
+        description: null,
+        slug: null,
+        sortOrder: null,
+        forumId: null,
+        createdAt: null,
+        indexedAt: null,
+      });
+    }
+    return Promise.reject(new Error(`Unexpected fetchApi call: ${path}`));
+  });
+
+  const routes = createBoardsRoutes(APPVIEW_URL);
+  const res = await routes.request("/boards/1");
+  expect(res.status).toBe(200);
+  await checkA11y(await res.text());
+});
+```
+
+**Step 2: Run just this test**
+
+```bash
+PATH=/Users/jacob.zweifel/workspace/malpercio-dev/atbb-monorepo/.devenv/profile/bin:$PATH \
+  pnpm --filter @atbb/web exec vitest run src/__tests__/a11y.test.ts -t "board page"
+```
+
+Expected: PASS.
+
+**Step 3: Commit once passing**
+
+```bash
+git add apps/web/src/__tests__/a11y.test.ts
+git commit -m "test(web): add WCAG AA test for board page (ATB-34)"
+```
+
+---
+
+### Task 6: Topic page test
+
+The topics route calls `getSessionWithPermissions()` (which sees no cookie → returns unauthenticated immediately). Then calls `fetchApi` three times:
+1. `fetchApi("/topics/1?offset=0&limit=25")` (stage 1 — the topic + replies)
+2. `fetchApi("/boards/1")` (stage 2 — board breadcrumb, non-fatal)
+3. `fetchApi("/categories/1")` (stage 3 — category breadcrumb, non-fatal)
+
+**Files:**
+- Modify: `apps/web/src/__tests__/a11y.test.ts`
+
+**Step 1: Add the topic page test**
+
+```typescript
+it("topic page /topics/:id has no violations", async () => {
+  mockFetchApi.mockImplementation((path: string) => {
+    if (path.startsWith("/topics/1")) {
+      return Promise.resolve({
+        topicId: "1",
+        locked: false,
+        pinned: false,
+        post: {
+          id: "1",
+          did: "did:plc:user",
+          rkey: "abc123",
+          title: "Test Topic Title",
+          text: "Hello world, this is a test post.",
+          forumUri: null,
+          boardUri: null,
+          boardId: "1",
+          parentPostId: null,
+          createdAt: "2024-01-01T00:00:00.000Z",
+          author: { did: "did:plc:user", handle: "alice.test" },
+        },
+        replies: [],
+        total: 0,
+        offset: 0,
+        limit: 25,
+      });
+    }
+    if (path === "/boards/1") {
+      return Promise.resolve({
+        id: "1",
+        did: "did:plc:forum",
+        uri: "at://did:plc:forum/space.atbb.forum.board/1",
+        name: "Test Board",
+        description: null,
+        slug: null,
+        sortOrder: null,
+        categoryId: "1",
+        categoryUri: null,
+        createdAt: null,
+        indexedAt: null,
+      });
+    }
+    if (path === "/categories/1") {
+      return Promise.resolve({
+        id: "1",
+        did: "did:plc:forum",
+        name: "General",
+        description: null,
+        slug: null,
+        sortOrder: null,
+        forumId: null,
+        createdAt: null,
+        indexedAt: null,
+      });
+    }
+    return Promise.reject(new Error(`Unexpected fetchApi call: ${path}`));
+  });
+
+  const routes = createTopicsRoutes(APPVIEW_URL);
+  const res = await routes.request("/topics/1");
+  expect(res.status).toBe(200);
+  await checkA11y(await res.text());
+});
+```
+
+**Step 2: Run just this test**
+
+```bash
+PATH=/Users/jacob.zweifel/workspace/malpercio-dev/atbb-monorepo/.devenv/profile/bin:$PATH \
+  pnpm --filter @atbb/web exec vitest run src/__tests__/a11y.test.ts -t "topic page"
+```
+
+Expected: PASS.
+
+**Step 3: Commit once passing**
+
+```bash
+git add apps/web/src/__tests__/a11y.test.ts
+git commit -m "test(web): add WCAG AA test for topic page (ATB-34)"
+```
+
+---
+
+### Task 7: New-topic page test (authenticated)
+
+The new-topic route requires authentication to show the form — the unauthenticated state renders only a plain "Log in to create a topic" paragraph, skipping the labeled inputs that are the primary a11y surface. Test the authenticated state.
+
+`getSession` is called with no `atbb_session` cookie in the default `beforeEach` mock. For this test only, override it to return an authenticated session.
+
+**Files:**
+- Modify: `apps/web/src/__tests__/a11y.test.ts`
+
+**Step 1: Add the new-topic page test**
+
+```typescript
+it("new-topic page /new-topic (authenticated) has no violations", async () => {
+  // Override the default unauthenticated session for this test only.
+  mockGetSession.mockResolvedValueOnce({
+    authenticated: true,
+    did: "did:plc:user",
+    handle: "alice.test",
+  });
+
+  mockFetchApi.mockImplementation((path: string) => {
+    if (path === "/boards/1") {
+      return Promise.resolve({
+        id: "1",
+        did: "did:plc:forum",
+        uri: "at://did:plc:forum/space.atbb.forum.board/1",
+        name: "Test Board",
+        description: null,
+        slug: null,
+        sortOrder: null,
+        categoryId: "1",
+        categoryUri: null,
+        createdAt: null,
+        indexedAt: null,
+      });
+    }
+    return Promise.reject(new Error(`Unexpected fetchApi call: ${path}`));
+  });
+
+  const routes = createNewTopicRoutes(APPVIEW_URL);
+  const res = await routes.request("/new-topic?boardId=1");
+  expect(res.status).toBe(200);
+  await checkA11y(await res.text());
+});
+```
+
+**Step 2: Run just this test**
+
+```bash
+PATH=/Users/jacob.zweifel/workspace/malpercio-dev/atbb-monorepo/.devenv/profile/bin:$PATH \
+  pnpm --filter @atbb/web exec vitest run src/__tests__/a11y.test.ts -t "new-topic"
+```
+
+Expected: PASS.
+
+**Step 3: Commit once passing**
+
+```bash
+git add apps/web/src/__tests__/a11y.test.ts
+git commit -m "test(web): add WCAG AA test for new-topic page (ATB-34)"
+```
+
+---
+
+### Task 8: Not-found page test
+
+The not-found catch-all renders without any API calls (no session cookie → `getSession` returns unauthenticated immediately with no fetch).
+
+**Files:**
+- Modify: `apps/web/src/__tests__/a11y.test.ts`
+
+**Step 1: Add the not-found page test**
+
+```typescript
+it("not-found page has no violations", async () => {
+  // No fetchApi or session calls — unauthenticated with no cookie.
+  const routes = createNotFoundRoute(APPVIEW_URL);
+  const res = await routes.request("/anything-that-does-not-exist");
+  expect(res.status).toBe(404);
+  await checkA11y(await res.text());
+});
+```
+
+**Step 2: Run the full a11y test suite**
+
+```bash
+PATH=/Users/jacob.zweifel/workspace/malpercio-dev/atbb-monorepo/.devenv/profile/bin:$PATH \
+  pnpm --filter @atbb/web exec vitest run src/__tests__/a11y.test.ts
+```
+
+Expected: 6 tests, all PASS. If any fail with axe violations:
+- Read the `[violation-id]` in the error message
+- Look up the rule at https://dequeuniversity.com/rules/axe/ to understand what's wrong
+- Fix the HTML in the relevant route file or `base.tsx`
+- Re-run until all 6 pass
+
+**Step 3: Run the full web test suite to confirm no regressions**
+
+```bash
+PATH=/Users/jacob.zweifel/workspace/malpercio-dev/atbb-monorepo/.devenv/profile/bin:$PATH \
+  pnpm --filter @atbb/web test
+```
+
+Expected: all tests pass.
+
+**Step 4: Commit**
+
+```bash
+git add apps/web/src/__tests__/a11y.test.ts
+git commit -m "test(web): add WCAG AA test for not-found page (ATB-34)"
+```
+
+---
+
+### Task 9: Mark complete and sync docs
+
+**Step 1: Update the Linear issue**
+
+- Go to https://linear.app/atbb/issue/ATB-34
+- Change status from Backlog → Done
+- Add a comment: "Implemented in `apps/web/src/__tests__/a11y.test.ts`. Six happy-path tests (one per page route) using axe-core + Vitest jsdom environment. Known limitation: color-contrast rules skipped (jsdom has no CSS engine). Tests run in CI as part of `pnpm test`."
+
+**Step 2: Move plan docs to complete**
+
+```bash
+mv docs/plans/2026-02-27-axe-core-a11y-design.md docs/plans/complete/
+mv docs/plans/2026-02-27-axe-core-a11y.md docs/plans/complete/
+git add docs/plans/
+git commit -m "docs: move ATB-34 plan docs to complete"
+```