feat: establish automated and manual accessibility gates

.gitignore

@@ -9,4 +9,5 @@ artifacts/**/*.json
 artifacts/**/*.xml
 artifacts/**/*.txt
 artifacts/**/*.sarif
+artifacts/tests/e2e/
 !artifacts/**/.gitkeep

artifacts/tests/a11y-manual/APP_HOME.md

@@ -0,0 +1,15 @@
+# APP_HOME accessibility review
+
+Status: pending-manual-review
+
+Reviewer:
+
+Keyboard: automated tab-order fixture passed; human review pending.
+
+Focus: automated visible-focus fixture passed; route-change review pending.
+
+Screen reader: pending.
+
+Reduced motion: automated media-query fixture passed; human review pending.
+
+Color signal: pending.

docs/accessibility/manual-checklist.md

@@ -0,0 +1,17 @@
+# Manual accessibility review checklist
+
+Automated axe checks do not establish WCAG conformance. A human reviewer must
+copy this checklist to `artifacts/tests/a11y-manual/<route-id>.md`, execute it
+on the release candidate, and sign it.
+
+- Status: `pending` or `reviewed`
+- Reviewer and reviewed-at timestamp
+- Keyboard: all actions reachable in logical order
+- Focus: visible, route changes deterministic, modal restore verified
+- Screen reader: headings, live regions, errors, and actions announced once
+- Reduced motion: non-essential animation suppressed
+- Color signal: every state has text/icon/structure in addition to color
+- Notes and linked defect IDs
+
+Passing the automated threshold means only that the tested pages had zero
+critical/serious axe findings under the recorded browser run.

package.json

@@ -21,7 +21,8 @@
     "test:component": "vitest run tests/component --reporter=default --reporter=junit --outputFile.junit=artifacts/tests/component.xml",
     "test:integration": "vitest run tests/integration --reporter=default --reporter=junit --outputFile.junit=artifacts/tests/integration.xml",
     "test:e2e": "playwright test",
-    "test:a11y": "playwright test --grep @a11y",
+    "test:a11y": "playwright test --grep @a11y && node scripts/write-a11y-report.mjs",
+    "review:a11y-manual": "node scripts/verify-a11y-manual.mjs",
     "test:sample-removal": "node scripts/test-sample-removal.mjs",
     "test:all": "pnpm test:runtime-schema && pnpm test:unit && pnpm test:component && pnpm test:integration"
   },

playwright.config.js

@@ -13,7 +13,7 @@ export default defineConfig({
     screenshot: "only-on-failure",
   },
   webServer: {
-    command: "pnpm dev --host 127.0.0.1",
+    command: "corepack pnpm dev --host 127.0.0.1",
     url: "http://127.0.0.1:5173",
     reuseExistingServer: !process.env.CI,
   },

scripts/verify-a11y-manual.mjs

@@ -0,0 +1,25 @@
+import { readFile } from "node:fs/promises";
+
+const evidence = await readFile(
+  "artifacts/tests/a11y-manual/APP_HOME.md",
+  "utf8",
+);
+
+const required = [
+  "Status: reviewed",
+  "Reviewer:",
+  "Keyboard:",
+  "Focus:",
+  "Screen reader:",
+  "Reduced motion:",
+  "Color signal:",
+];
+
+const missing = required.filter((marker) => !evidence.includes(marker));
+if (missing.length > 0) {
+  process.stderr.write(
+    `Manual accessibility evidence is incomplete: ${missing.join(", ")}\n`,
+  );
+  process.exit(1);
+}
+process.stdout.write("Manual accessibility evidence: PASS\n");

scripts/write-a11y-report.mjs

@@ -0,0 +1,18 @@
+import { mkdir, writeFile } from "node:fs/promises";
+
+await mkdir("artifacts/tests", { recursive: true });
+await writeFile(
+  "artifacts/tests/a11y.json",
+  `${JSON.stringify(
+    {
+      schemaVersion: 1,
+      generatedAt: new Date().toISOString(),
+      scope: ["APP_HOME", "SAMPLE_RESOURCE_LIST", "NOT_FOUND"],
+      threshold: { critical: 0, serious: 0 },
+      automatedStatus: "passed",
+      manualReview: "see artifacts/tests/a11y-manual/APP_HOME.md",
+    },
+    null,
+    2,
+  )}\n`,
+);

src/presentation/components/async-surface.jsx

@@ -1,7 +1,12 @@
 /** @param {{ label?: string }} props */
 export function LoadingSurface({ label = "불러오는 중" }) {
   return (
-    <section aria-busy="true" aria-label={label}>
+    <section
+      aria-busy="true"
+      aria-label={label}
+      aria-live="polite"
+      aria-atomic="true"
+    >
       <div className="ui-skeleton" aria-hidden="true" />
       <span className="sr-only">{label}</span>
     </section>
@@ -11,7 +16,7 @@ export function LoadingSurface({ label = "불러오는 중" }) {
 /** @param {{ title?: string, action?: React.ReactNode }} props */
 export function EmptySurface({ title = "표시할 항목이 없습니다.", action }) {
   return (
-    <section className="ui-empty">
+    <section className="ui-empty" aria-live="polite">
       <p>{title}</p>
       {action}
     </section>

tests/e2e/accessibility.spec.js

@@ -0,0 +1,37 @@
+import AxeBuilder from "@axe-core/playwright";
+import { expect, test } from "@playwright/test";
+
+for (const route of ["/", "/sample/resources", "/not-found"]) {
+  test(`@a11y ${route} has no critical or serious axe violations`, async ({
+    page,
+  }) => {
+    await page.goto(route);
+    await expect(page.getByRole("main")).toBeVisible();
+    const results = await new AxeBuilder({ page })
+      .withTags(["wcag2a", "wcag2aa", "wcag21a", "wcag21aa"])
+      .analyze();
+    const blocking = results.violations.filter((violation) =>
+      ["critical", "serious"].includes(violation.impact ?? ""),
+    );
+    expect(blocking).toEqual([]);
+  });
+}
+
+test("@a11y keyboard reaches the primary route action with visible focus", async ({
+  page,
+}) => {
+  await page.goto("/");
+  await page.keyboard.press("Tab");
+  const action = page.getByRole("link", { name: "샘플 리소스" });
+  await expect(action).toBeFocused();
+  await expect(action).toHaveCSS("outline-style", "solid");
+});
+
+test("@a11y reduced-motion policy disables long animation", async ({ page }) => {
+  await page.emulateMedia({ reducedMotion: "reduce" });
+  await page.goto("/");
+  const duration = await page
+    .locator("body")
+    .evaluate((body) => getComputedStyle(body).animationDuration);
+  expect(["0s", "0.00001s", "1e-05s"]).toContain(duration);
+});