test: harden starter experience quality contract

.gitea/workflows/quality-gates.yml

@@ -53,9 +53,9 @@ jobs:
         run: |
           corepack enable
           corepack pnpm install --frozen-lockfile
-      - name: Install Chromium
+      - name: Install Playwright browsers
         if: ${{ matrix.browser }}
-        run: corepack pnpm exec playwright install --with-deps chromium
+        run: corepack pnpm exec playwright install --with-deps chromium firefox webkit
       - name: Run blocking gate
         run: corepack pnpm ci:gate -- ${{ matrix.gate }}
       - name: Upload gate evidence
@@ -91,9 +91,9 @@ jobs:
         run: |
           corepack enable
           corepack pnpm install --frozen-lockfile
-      - name: Install Chromium
+      - name: Install Playwright browsers
         if: ${{ matrix.browser }}
-        run: corepack pnpm exec playwright install --with-deps chromium
+        run: corepack pnpm exec playwright install --with-deps chromium firefox webkit
       - name: Run blocking gate
         run: corepack pnpm ci:gate -- ${{ matrix.gate }}
       - name: Upload gate evidence

README.md

@@ -16,6 +16,27 @@ corepack pnpm dev
 Runtime-public settings live in `public/config.json` and are validated before
 the product tree mounts. Client secrets are forbidden.
 
+## Included starter experience
+
+The default build mounts a domain-neutral application shell with a header,
+responsive sidebar, route focus management, session integration status, and a
+persistent `system` / `light` / `dark` theme selector.
+
+| Route | Purpose |
+| --- | --- |
+| `/` | implementation readiness and starter links |
+| `/examples/ui` | buttons, fields, cards, alerts, badges, modal, and tokens |
+| `/examples/states` | loading, refresh, empty, error, auth, forbidden, and not-found states |
+| `/examples/auth` | reactive external-auth integration seam |
+| `/sample/resources` | protected, domain-neutral integration route |
+
+`AUTH_MODE=demo` is credential-free and accepted only in local/development
+environments. Deployments use `AUTH_MODE=external` and provide the opaque auth
+owner described in
+[`docs/architecture/starter-experience.md`](docs/architecture/starter-experience.md).
+The client route policy is user experience only; server authorization remains
+authoritative.
+
 ## Architecture
 
 Dependencies point inward:
@@ -27,9 +48,11 @@ bootstrap composes concrete adapters
 contracts own cross-cutting registries
 ```
 
-See `docs/architecture/overview.md` and `docs/architecture/layers.md`. The
-removable sample slice is under `src/sample/contract-fixture`; product code is
-not allowed to import it.
+See `docs/architecture/overview.md`, `docs/architecture/layers.md`, and
+`docs/architecture/starter-experience.md`. The removable sample slice is under
+`src/sample/contract-fixture`; product code is not allowed to import it. The
+visible starter routes do not depend on that fixture and continue to build
+after it is removed.
 
 ## Verification
 
@@ -52,9 +75,17 @@ corepack pnpm drill:runbooks
 corepack pnpm check:ci
 ```
 
+Install the pinned Playwright browser engines before the first cross-browser
+run:
+
+```bash
+corepack pnpm exec playwright install --with-deps chromium firefox webkit
+```
+
 Two gates intentionally need external evidence:
 
-- `review:a11y-manual` needs a signed human keyboard/focus/screen-reader review.
+- `review:a11y-manual` needs a signed human keyboard/focus/screen-reader review
+  for all six registered routes.
 - `collect:web-vitals-evidence` stays `FAIL_UNVERIFIED` until a reviewed minimum
   eligible-sample threshold and 28 days of production data exist.
 

artifacts/tests/a11y-manual/EXAMPLES_AUTH.md

@@ -0,0 +1,18 @@
+# EXAMPLES_AUTH accessibility review
+
+Status: pending-manual-review
+Route ID: EXAMPLES_AUTH
+Release ID:
+Reviewer:
+Reviewed at:
+Signature:
+Attestation: pending
+M1 Keyboard: pending
+M2 Visible focus: pending
+M3 Route focus: pending
+M4 Modal focus: not-applicable (no modal on this route)
+M5 Error association: not-applicable (no form error on this route)
+M6 Color signal: pending
+M7 Reduced motion: pending
+Screen reader: pending
+Notes: Review session state announcements and unavailable external-integration behavior.

artifacts/tests/a11y-manual/EXAMPLES_STATES.md

@@ -0,0 +1,18 @@
+# EXAMPLES_STATES accessibility review
+
+Status: pending-manual-review
+Route ID: EXAMPLES_STATES
+Release ID:
+Reviewer:
+Reviewed at:
+Signature:
+Attestation: pending
+M1 Keyboard: pending
+M2 Visible focus: pending
+M3 Route focus: pending
+M4 Modal focus: not-applicable (no modal on this route)
+M5 Error association: not-applicable (no form error on this route)
+M6 Color signal: pending
+M7 Reduced motion: pending
+Screen reader: pending
+Notes: Review loading, refresh, empty, error, authentication, forbidden, and not-found announcements.

artifacts/tests/a11y-manual/EXAMPLES_UI.md

@@ -0,0 +1,18 @@
+# EXAMPLES_UI accessibility review
+
+Status: pending-manual-review
+Route ID: EXAMPLES_UI
+Release ID:
+Reviewer:
+Reviewed at:
+Signature:
+Attestation: pending
+M1 Keyboard: pending
+M2 Visible focus: pending
+M3 Route focus: pending
+M4 Modal focus: pending
+M5 Error association: pending
+M6 Color signal: pending
+M7 Reduced motion: pending
+Screen reader: pending
+Notes: Review the text-field error association and modal focus containment/restoration.

config/ci/gates.json

@@ -125,6 +125,9 @@
       "evidence": [
         "artifacts/tests/a11y.json",
         "artifacts/tests/a11y-manual/APP_HOME.md",
+        "artifacts/tests/a11y-manual/EXAMPLES_UI.md",
+        "artifacts/tests/a11y-manual/EXAMPLES_STATES.md",
+        "artifacts/tests/a11y-manual/EXAMPLES_AUTH.md",
         "artifacts/tests/a11y-manual/SAMPLE_RESOURCE_LIST.md",
         "artifacts/tests/a11y-manual/NOT_FOUND.md",
         "artifacts/tests/a11y-manual/report.json"

docs/accessibility/manual-checklist.md

@@ -1,10 +1,12 @@
 # Manual accessibility review checklist
 
 Automated axe checks do not establish WCAG conformance. A human reviewer must
-review all three route records in `artifacts/tests/a11y-manual/` against one
-release candidate and sign them. Copy the template fields exactly; the gate
-rejects blank identity/timestamp/signature fields, pending verdicts, mismatched
-release IDs, or missing routes.
+review all six route records in `artifacts/tests/a11y-manual/` against one
+release candidate and sign them. The required scope is derived from the route
+registry: `APP_HOME`, `EXAMPLES_UI`, `EXAMPLES_STATES`, `EXAMPLES_AUTH`,
+`SAMPLE_RESOURCE_LIST`, and `NOT_FOUND`. Copy the template fields exactly; the
+gate rejects blank identity/timestamp/signature fields, pending verdicts,
+mismatched release IDs, or missing routes.
 
 Allowed item verdicts:
 
@@ -43,5 +45,7 @@ The reviewer must verify:
 - M7: non-essential motion is suppressed with reduced-motion preference
 - Screen reader: headings, live regions, errors, and actions are announced once
 
-Passing automated evidence means only that tested pages had no critical or
-serious axe findings under the recorded browser run.
+`EXAMPLES_UI` requires real M4 modal and M5 field-error review; those items must
+not be marked not-applicable on that route. Passing automated evidence means
+only that tested pages had no critical or serious axe findings under the
+recorded Chromium, Firefox, and WebKit runs.

docs/architecture/overview.md

@@ -8,6 +8,8 @@ in `review-ledger.json`, not automatically to edits in this file.
 flowchart LR
   Bootstrap[bootstrap / composition root] --> Presentation[presentation]
   Bootstrap --> Adapters[adapters]
+  Presentation --> Shell[app shell and route surfaces]
+  Shell --> Providers[session and theme providers]
   Presentation --> Application[application]
   Adapters --> Application
   Application --> Domain[domain]
@@ -21,3 +23,9 @@ implement application ports, and only the composition root selects concrete
 adapters. Contract registries are the single named source for routes, API
 operations, environment values, storage keys, errors, queries, telemetry, and
 release tokens.
+
+The executable route tree is mounted only after runtime configuration and
+release-manifest coherence pass. It receives the composed query client,
+credential-opaque session port, storage port, telemetry port, and immutable
+build ID. Visible starter pages depend on those ports and contracts, never on a
+concrete adapter or the removable sample fixture.

docs/architecture/starter-experience.md

@@ -0,0 +1,69 @@
+# Starter experience contract
+
+The repository provides a runnable, domain-neutral application rather than
+only infrastructure contracts. The starter experience is intentionally
+replaceable at the page level while the shell, providers, boundaries,
+primitives, and state surfaces remain reusable.
+
+## Runtime composition
+
+```text
+validated config + coherent release manifest
+  -> concrete adapters
+  -> QueryClientProvider
+  -> ThemeProvider
+  -> SessionProvider
+  -> BrowserRouter
+  -> AppShell
+  -> lazy route boundary
+```
+
+Boot stops before product mount when configuration or release coherence fails.
+Each lazy page renders inside Suspense and a telemetry-aware route boundary.
+Route changes move focus to the new page heading; the skip link and landmarks
+remain stable in the shell.
+
+## Registered routes
+
+| ID | Path | Access | Surface |
+| --- | --- | --- | --- |
+| `APP_HOME` | `/` | public | readiness dashboard |
+| `EXAMPLES_UI` | `/examples/ui` | public | interactive primitives and tokens |
+| `EXAMPLES_STATES` | `/examples/states` | public | async and access state matrix |
+| `EXAMPLES_AUTH` | `/examples/auth` | public | session integration controls |
+| `SAMPLE_RESOURCE_LIST` | `/sample/resources` | integration-defined | protected integration seam |
+| `NOT_FOUND` | `*` | public | safe navigation recovery |
+
+Navigation labels and order come from `ROUTE_REGISTRY`; the sidebar does not
+maintain a second route list. The client access decision never claims to be
+authorization.
+
+## Authentication seam
+
+The session port exposes state subscription, sign-in start, sign-out,
+credential attachment, recovery, and unauthenticated notification. Credentials
+remain opaque to the application and presentation layers.
+
+- `demo`: local/development-only state transition with no credentials
+- `external`: delegates to `globalThis.__CA_FRONTEND_AUTH_OWNER__`
+- missing/invalid external owner: fails closed as `integration-failed`
+
+An external owner implements `readState`, `subscribe`, `beginSignIn`,
+`signOut`, `attachCredential`, `recoverSession`, and
+`notifyUnauthenticated`. It owns token acquisition and storage.
+
+## Extending the starter
+
+1. Register the route path, access hint, title, chunk, loading surface, error
+   surface, and optional navigation metadata in `src/contracts/routes.js`.
+2. Add a lazy page in `src/presentation/` and render it through `RouteSurface`.
+3. Use application ports or use cases; do not import concrete adapters.
+4. Use the semantic tokens, UI primitives, and state surfaces before adding a
+   project-specific variant.
+5. Add component behavior, all-engine E2E, automated axe, and signed manual
+   route evidence.
+6. Run `test:sample-removal` to prove the visible starter still builds without
+   `src/sample/contract-fixture`.
+
+Theme preference is the public `COLOR_SCHEME` storage contract. Authentication
+tokens and other secrets remain forbidden storage keys.

docs/operations/ci-quality-gates.md

@@ -30,6 +30,11 @@ registry: merge evidence through the PR decision, coherent release evidence
 through the next release promotion, drill evidence through the next production
 promotion, and field evidence through aggregation.
 
+Browser-backed merge gates install and execute the pinned Chromium, Firefox,
+and WebKit engines. This makes route behavior, reflow, native dialog semantics,
+theme persistence, and automated accessibility a cross-engine contract rather
+than a Chromium-only smoke check.
+
 Repository variables required by higher tiers:
 
 - `HOSTING_BASE_URL` for live header verification

docs/styling/design-tokens.md

@@ -1,8 +1,32 @@
 # Design-token styling contract
 
 `src/presentation/styles/theme.css` is the styling SSOT. Components consume
-semantic color, spacing, typography, and radius tokens through static Tailwind
-classes.
+semantic color, spacing, typography, status, and radius tokens through static
+classes. `/examples/ui` is the executable token and primitive gallery.
+
+## Theme contract
+
+The supported public preference is the closed set `system`, `light`, and
+`dark`. `ThemeProvider` reads and writes `COLOR_SCHEME` through the application
+storage port; it does not access a raw storage key. `system` subscribes to
+`prefers-color-scheme` changes. Bootstrap applies the persisted preference
+before React paints.
+
+Components use semantic tokens such as `--color-panel`, `--color-content`,
+`--color-border`, `--color-action`, and status surface/content/border triples.
+They must not hard-code a light-only panel or text color. Both light and dark
+surfaces are included in automated axe checks.
+
+## Included primitives
+
+- `Button`: primary, secondary, danger, and ghost intent
+- `TextField`: label, help text, required state, and associated validation error
+- `Card`: labelled surface with optional footer
+- `Alert` and `Badge`: non-color-only status feedback
+- `Dialog`: native modal semantics, Escape/backdrop close, and trigger focus
+  restoration
+- async and access state surfaces: loading, refresh, empty, terminal error,
+  auth required, forbidden, and not found
 
 Arbitrary-value policy:
 
@@ -13,5 +37,5 @@ Arbitrary-value policy:
 - user-controlled or runtime-composed class strings are forbidden
 - class variants must be selected from a closed static map
 
-The removable sample may demonstrate tokens, but product modules must not
-import from `src/sample/contract-fixture`.
+The removable sample may demonstrate tokens, but production starter modules do
+not import from `src/sample/contract-fixture`.

docs/testing/taxonomy.md

@@ -12,6 +12,13 @@ Each gate is blocking in its declared scope. Failures are not downgraded with
 | end-to-end | `pnpm test:e2e` | `artifacts/tests/e2e/` |
 | accessibility | `pnpm test:a11y` | `artifacts/tests/a11y.json` |
 
+End-to-end and automated accessibility scenarios run on the pinned Chromium,
+Firefox, and WebKit engines. The responsive contract explicitly exercises
+320px reflow, a mobile navigation drawer, and a wide two-column gallery.
+Theme scenarios verify persistence, operating-system changes, and dark-surface
+axe results. Native modal focus and validation association are exercised in
+both component and browser tests.
+
 A control is verified only when a positive fixture passes and its deliberately
 failing negative fixture is rejected. Generated evidence is retained by CI;
 the repository tracks only the evidence directory structure.

playwright.config.js

@@ -19,5 +19,7 @@ export default defineConfig({
   },
   projects: [
     { name: "chromium", use: { ...devices["Desktop Chrome"] } },
+    { name: "firefox", use: { ...devices["Desktop Firefox"] } },
+    { name: "webkit", use: { ...devices["Desktop Safari"] } },
   ],
 });

scripts/lib/manual-a11y-evidence.mjs

@@ -1,5 +1,8 @@
 export const MANUAL_A11Y_ROUTE_IDS = Object.freeze([
   "APP_HOME",
+  "EXAMPLES_UI",
+  "EXAMPLES_STATES",
+  "EXAMPLES_AUTH",
   "SAMPLE_RESOURCE_LIST",
   "NOT_FOUND",
 ]);

scripts/write-a11y-report.mjs

@@ -1,5 +1,7 @@
 import { mkdir, writeFile } from "node:fs/promises";
 
+import { MANUAL_A11Y_ROUTE_IDS } from "./lib/manual-a11y-evidence.mjs";
+
 await mkdir("artifacts/tests", { recursive: true });
 await writeFile(
   "artifacts/tests/a11y.json",
@@ -7,7 +9,7 @@ await writeFile(
     {
       schemaVersion: 1,
       generatedAt: new Date().toISOString(),
-      scope: ["APP_HOME", "SAMPLE_RESOURCE_LIST", "NOT_FOUND"],
+      scope: MANUAL_A11Y_ROUTE_IDS,
       threshold: { critical: 0, serious: 0 },
       automatedStatus: "passed",
       manualReview: "see artifacts/tests/a11y-manual/report.json",

src/application/policies/color-scheme.js

@@ -0,0 +1,21 @@
+export const COLOR_SCHEME_PREFERENCES = Object.freeze([
+  "system",
+  "light",
+  "dark",
+]);
+
+/** @param {unknown} value */
+export function normalizeColorSchemePreference(value) {
+  return COLOR_SCHEME_PREFERENCES.includes(/** @type {string} */ (value))
+    ? /** @type {"system" | "light" | "dark"} */ (value)
+    : "system";
+}
+
+/**
+ * @param {"system" | "light" | "dark"} preference
+ * @param {boolean} systemPrefersDark
+ */
+export function resolveColorScheme(preference, systemPrefersDark) {
+  if (preference === "system") return systemPrefersDark ? "dark" : "light";
+  return preference;
+}

src/bootstrap/initialize-color-scheme.js

@@ -0,0 +1,36 @@
+import {
+  normalizeColorSchemePreference,
+  resolveColorScheme,
+} from "../application/policies/color-scheme.js";
+
+/**
+ * Applies the persisted public preference before React paints.
+ *
+ * @param {import("../application/ports/storage-port.js").StoragePort} storage
+ * @param {{
+ *   documentElement?: HTMLElement,
+ *   matchMedia?: (query: string) => MediaQueryList
+ * }} [browser]
+ */
+export function initializeColorScheme(storage, browser = {}) {
+  const documentElement = browser.documentElement ?? document.documentElement;
+  const matchMedia =
+    browser.matchMedia ??
+    (typeof window.matchMedia === "function"
+      ? window.matchMedia.bind(window)
+      : () => /** @type {MediaQueryList} */ ({ matches: false }));
+  const stored = storage.read("COLOR_SCHEME");
+  const preference = normalizeColorSchemePreference(
+    stored.ok ? stored.value : undefined,
+  );
+  const resolved = resolveColorScheme(
+    preference,
+    matchMedia("(prefers-color-scheme: dark)").matches,
+  );
+
+  documentElement.dataset.theme = resolved;
+  documentElement.dataset.themePreference = preference;
+  documentElement.style.colorScheme = resolved;
+
+  return Object.freeze({ preference, resolved });
+}

src/bootstrap/main.jsx

@@ -5,6 +5,7 @@ import { QueryClientProvider } from "@tanstack/react-query";
 import { BootErrorShell } from "../presentation/boundaries/boot-error-shell.jsx";
 import { AppRouter } from "../presentation/routes/app-router.jsx";
 import { createRuntimeComposition } from "./create-runtime-composition.js";
+import { initializeColorScheme } from "./initialize-color-scheme.js";
 import { BootConfigError } from "./load-runtime-config.js";
 import { ReleaseManifestError } from "./load-release-manifest.js";
 import "../presentation/styles/theme.css";
@@ -20,6 +21,7 @@ const root = createRoot(rootElement);
 async function boot() {
   try {
     const composition = await createRuntimeComposition();
+    initializeColorScheme(composition.ports.storage);
     root.render(
       <StrictMode>
         <QueryClientProvider client={composition.ports.queryClient}>
@@ -27,6 +29,7 @@ async function boot() {
             authSession={composition.ports.authSession}
             basename={composition.config.build.routerBasePath}
             buildId={composition.release.buildId}
+            storage={composition.ports.storage}
             telemetry={composition.ports.telemetry}
           />
         </QueryClientProvider>

src/presentation/layouts/app-shell.jsx

@@ -3,6 +3,7 @@ import { NavLink, Outlet, useLocation } from "react-router-dom";
 
 import { NAVIGATION_ROUTES, routePath } from "../../contracts/routes.js";
 import { useSession } from "../providers/session-provider.jsx";
+import { useTheme } from "../providers/theme-provider.jsx";
 
 const SESSION_LABELS = Object.freeze({
   authenticated: "인증됨",
@@ -14,6 +15,7 @@ const SESSION_LABELS = Object.freeze({
 export function AppShell() {
   const location = useLocation();
   const { sessionState, beginSignIn, signOut, recover } = useSession();
+  const { preference, setPreference } = useTheme();
   const [navigationOpen, setNavigationOpen] = useState(false);
   const [sessionActionPending, setSessionActionPending] = useState(false);
   const [sessionActionFailed, setSessionActionFailed] = useState(false);
@@ -80,6 +82,25 @@ export function AppShell() {
           Frontend Skeleton
         </NavLink>
         <div className="app-shell__session">
+          <label className="visually-hidden" htmlFor="theme-preference">
+            색상 테마
+          </label>
+          <select
+            className="theme-selector"
+            id="theme-preference"
+            value={preference}
+            onChange={(event) =>
+              setPreference(
+                /** @type {"system" | "light" | "dark"} */ (
+                  event.currentTarget.value
+                ),
+              )
+            }
+          >
+            <option value="system">시스템 테마</option>
+            <option value="light">라이트 테마</option>
+            <option value="dark">다크 테마</option>
+          </select>
           <span className="session-status" data-state={sessionState}>
             {SESSION_LABELS[sessionState]}
           </span>

src/presentation/providers/theme-provider.jsx

@@ -0,0 +1,86 @@
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useState,
+} from "react";
+
+import {
+  normalizeColorSchemePreference,
+  resolveColorScheme,
+} from "../../application/policies/color-scheme.js";
+
+/**
+ * @typedef {{
+ *   preference: "system" | "light" | "dark",
+ *   resolvedTheme: "light" | "dark",
+ *   setPreference: (preference: "system" | "light" | "dark") => void
+ * }} ThemeContextValue
+ */
+
+const ThemeContext = createContext(/** @type {ThemeContextValue | null} */ (null));
+
+function systemPrefersDark() {
+  return (
+    typeof window.matchMedia === "function" &&
+    window.matchMedia("(prefers-color-scheme: dark)").matches
+  );
+}
+
+/**
+ * @param {{
+ *   storage?: import("../../application/ports/storage-port.js").StoragePort,
+ *   children: React.ReactNode
+ * }} props
+ */
+export function ThemeProvider({ storage, children }) {
+  const [preference, updatePreference] = useState(() => {
+    const result = storage?.read("COLOR_SCHEME");
+    return normalizeColorSchemePreference(
+      result?.ok ? result.value : undefined,
+    );
+  });
+  const [darkSystemTheme, setDarkSystemTheme] = useState(systemPrefersDark);
+  const resolvedTheme = resolveColorScheme(preference, darkSystemTheme);
+
+  useEffect(() => {
+    if (typeof window.matchMedia !== "function") return undefined;
+    const query = window.matchMedia("(prefers-color-scheme: dark)");
+    /** @param {MediaQueryListEvent} event */
+    const update = (event) => setDarkSystemTheme(event.matches);
+    setDarkSystemTheme(query.matches);
+    query.addEventListener("change", update);
+    return () => query.removeEventListener("change", update);
+  }, []);
+
+  useLayoutEffect(() => {
+    document.documentElement.dataset.theme = resolvedTheme;
+    document.documentElement.dataset.themePreference = preference;
+    document.documentElement.style.colorScheme = resolvedTheme;
+  }, [preference, resolvedTheme]);
+
+  const value = useMemo(
+    () =>
+      Object.freeze({
+        preference,
+        resolvedTheme,
+        /** @param {"system" | "light" | "dark"} next */
+        setPreference(next) {
+          const normalized = normalizeColorSchemePreference(next);
+          updatePreference(normalized);
+          storage?.write("COLOR_SCHEME", normalized);
+        },
+      }),
+    [preference, resolvedTheme, storage],
+  );
+
+  return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>;
+}
+
+export function useTheme() {
+  const theme = useContext(ThemeContext);
+  if (!theme) throw new Error("ThemeProvider is required");
+  return theme;
+}

src/presentation/routes/app-router.jsx

@@ -11,6 +11,7 @@ import { RouteBoundary } from "../boundaries/render-error-boundary.jsx";
 import { AppShell } from "../layouts/app-shell.jsx";
 import { PageHeader } from "../components/page-header.jsx";
 import { SessionProvider, useSession } from "../providers/session-provider.jsx";
+import { ThemeProvider } from "../providers/theme-provider.jsx";
 import { decideRouteAccess } from "./navigation-policy.js";
 
 const HomePage = lazy(() => import("../pages/home-page.jsx"));
@@ -171,6 +172,7 @@ function PublicRoute({ routeId, buildId, telemetry, children }) {
  *   authSession: import("../../application/ports/auth-session-port.js").AuthSessionPort,
  *   basename?: string,
  *   buildId?: string,
+ *   storage?: import("../../application/ports/storage-port.js").StoragePort,
  *   telemetry?: import("../../application/ports/telemetry-port.js").TelemetryPort
  * }} props
  */
@@ -178,13 +180,15 @@ export function AppRouter({
   authSession,
   basename = "/",
   buildId = "local-build",
+  storage,
   telemetry,
 }) {
   return (
     <BrowserRouter basename={basename}>
-      <SessionProvider authSession={authSession}>
-        <Routes>
-          <Route element={<AppShell />}>
+      <ThemeProvider storage={storage}>
+        <SessionProvider authSession={authSession}>
+          <Routes>
+            <Route element={<AppShell />}>
             <Route
               index
               element={
@@ -259,9 +263,10 @@ export function AppRouter({
                 </PublicRoute>
               }
             />
-          </Route>
-        </Routes>
-      </SessionProvider>
+            </Route>
+          </Routes>
+        </SessionProvider>
+      </ThemeProvider>
     </BrowserRouter>
   );
 }

src/presentation/styles/theme.css

@@ -3,12 +3,28 @@
 @theme {
   --color-surface: oklch(0.985 0.003 247);
   --color-surface-muted: oklch(0.94 0.01 247);
+  --color-panel: oklch(1 0 0);
+  --color-border: oklch(0.87 0.015 247);
   --color-content: oklch(0.25 0.025 247);
   --color-content-muted: oklch(0.48 0.025 247);
   --color-action: oklch(0.55 0.18 255);
   --color-action-hover: oklch(0.48 0.2 255);
   --color-danger: oklch(0.55 0.2 25);
+  --color-danger-hover: oklch(0.47 0.2 25);
+  --color-on-action: oklch(1 0 0);
   --color-focus: oklch(0.72 0.16 225);
+  --color-info-content: oklch(0.38 0.16 255);
+  --color-info-surface: oklch(0.95 0.03 255);
+  --color-info-border: oklch(0.75 0.08 250);
+  --color-success-content: oklch(0.35 0.12 155);
+  --color-success-surface: oklch(0.95 0.04 155);
+  --color-success-border: oklch(0.72 0.1 155);
+  --color-warning-content: oklch(0.38 0.12 70);
+  --color-warning-surface: oklch(0.96 0.05 80);
+  --color-warning-border: oklch(0.75 0.12 80);
+  --color-danger-content: oklch(0.42 0.18 25);
+  --color-danger-surface: oklch(0.96 0.035 25);
+  --color-danger-border: oklch(0.72 0.12 25);
   --radius-control: 0.5rem;
   --radius-surface: 0.75rem;
   --spacing-page: 1.5rem;
@@ -22,6 +38,33 @@
     font-family: var(--font-sans);
   }
 
+  :root[data-theme="dark"] {
+    --color-surface: oklch(0.16 0.02 255);
+    --color-surface-muted: oklch(0.25 0.025 255);
+    --color-panel: oklch(0.205 0.022 255);
+    --color-border: oklch(0.36 0.025 255);
+    --color-content: oklch(0.94 0.012 255);
+    --color-content-muted: oklch(0.74 0.025 255);
+    --color-action: oklch(0.7 0.14 250);
+    --color-action-hover: oklch(0.79 0.12 245);
+    --color-danger: oklch(0.68 0.19 25);
+    --color-danger-hover: oklch(0.76 0.16 25);
+    --color-on-action: oklch(0.16 0.02 255);
+    --color-focus: oklch(0.82 0.15 220);
+    --color-info-content: oklch(0.83 0.09 250);
+    --color-info-surface: oklch(0.27 0.045 255);
+    --color-info-border: oklch(0.55 0.09 250);
+    --color-success-content: oklch(0.83 0.1 155);
+    --color-success-surface: oklch(0.27 0.045 155);
+    --color-success-border: oklch(0.53 0.1 155);
+    --color-warning-content: oklch(0.88 0.1 80);
+    --color-warning-surface: oklch(0.29 0.045 80);
+    --color-warning-border: oklch(0.58 0.11 80);
+    --color-danger-content: oklch(0.84 0.11 25);
+    --color-danger-surface: oklch(0.28 0.055 25);
+    --color-danger-border: oklch(0.56 0.13 25);
+  }
+
   body {
     margin: 0;
     min-width: 20rem;
@@ -81,7 +124,7 @@
     left: 0.75rem;
     padding: 0.75rem 1rem;
     border-radius: var(--radius-control);
-    color: white;
+    color: var(--color-panel);
     background: var(--color-content);
     transform: translateY(-200%);
   }
@@ -111,7 +154,7 @@
     min-width: 0;
     padding: 0.75rem 1.25rem;
     border-bottom: 1px solid var(--color-surface-muted);
-    background: color-mix(in oklch, white 92%, var(--color-surface));
+    background: color-mix(in oklch, var(--color-panel) 92%, var(--color-surface));
     box-shadow: 0 1px 8px color-mix(in oklch, var(--color-content) 8%, transparent);
   }
 
@@ -132,7 +175,7 @@
     border-radius: var(--radius-control);
     padding: 0.55rem 0.75rem;
     color: var(--color-content);
-    background: white;
+    background: var(--color-panel);
     cursor: pointer;
   }
 
@@ -143,13 +186,24 @@
     margin-inline-start: auto;
   }
 
+  .theme-selector {
+    min-height: 2.25rem;
+    max-width: 8.5rem;
+    border: 1px solid var(--color-border);
+    border-radius: var(--radius-control);
+    padding: 0.35rem 2rem 0.35rem 0.65rem;
+    color: var(--color-content);
+    background: var(--color-panel);
+    cursor: pointer;
+  }
+
   .app-shell__session-error {
     position: absolute;
     top: calc(100% + 0.25rem);
     right: 1rem;
     padding: 0.5rem;
     color: var(--color-danger);
-    background: white;
+    background: var(--color-panel);
   }
 
   .session-status {
@@ -165,8 +219,8 @@
   }
 
   .session-status[data-state="authenticated"] {
-    color: oklch(0.35 0.12 155);
-    background: oklch(0.93 0.05 155);
+    color: var(--color-success-content);
+    background: var(--color-success-surface);
   }
 
   .session-status[data-state="integration-failed"] {
@@ -179,8 +233,8 @@
     grid-area: sidebar;
     height: calc(100vh - 4.5rem);
     padding: 1.25rem 0.75rem;
-    border-right: 1px solid var(--color-surface-muted);
-    background: white;
+    border-right: 1px solid var(--color-border);
+    background: var(--color-panel);
   }
 
   .app-navigation {
@@ -208,7 +262,11 @@
 
   .app-navigation__link.is-active {
     color: var(--color-action-hover);
-    background: color-mix(in oklch, var(--color-action) 10%, white);
+    background: color-mix(
+      in oklch,
+      var(--color-action) 14%,
+      var(--color-panel)
+    );
     font-weight: 800;
   }
 
@@ -224,16 +282,19 @@
   }
 
   .ui-panel {
-    @apply rounded-surface border border-surface-muted bg-white p-6 shadow-sm;
+    @apply rounded-surface p-6 shadow-sm;
+    border: 1px solid var(--color-border);
+    background: var(--color-panel);
   }
 
   .ui-button {
-    @apply rounded-control bg-action px-4 py-2 font-semibold text-white;
+    @apply rounded-control bg-action px-4 py-2 font-semibold;
     display: inline-flex;
     min-height: 2.75rem;
     align-items: center;
     justify-content: center;
     border: 0;
+    color: var(--color-on-action);
     text-decoration: none;
     cursor: pointer;
   }
@@ -250,7 +311,7 @@
   .ui-button--secondary {
     border: 1px solid var(--color-surface-muted);
     color: var(--color-content);
-    background: white;
+    background: var(--color-panel);
   }
 
   .ui-button--secondary:hover {
@@ -259,12 +320,12 @@
   }
 
   .ui-button--danger {
-    color: white;
+    color: var(--color-on-action);
     background: var(--color-danger);
   }
 
   .ui-button--danger:hover {
-    background: oklch(0.47 0.2 25);
+    background: var(--color-danger-hover);
   }
 
   .ui-button--ghost {
@@ -321,11 +382,12 @@
     width: 100%;
     min-height: 2.75rem;
     box-sizing: border-box;
-    border: 1px solid color-mix(in oklch, var(--color-content-muted) 55%, white);
+    border: 1px solid
+      color-mix(in oklch, var(--color-content-muted) 55%, var(--color-panel));
     border-radius: var(--radius-control);
     padding: 0.65rem 0.8rem;
     color: var(--color-content);
-    background: white;
+    background: var(--color-panel);
   }
 
   .ui-field__input[aria-invalid="true"] {
@@ -337,10 +399,10 @@
     min-width: 0;
     flex-direction: column;
     gap: 1.25rem;
-    border: 1px solid var(--color-surface-muted);
+    border: 1px solid var(--color-border);
     border-radius: var(--radius-surface);
     padding: 1.25rem;
-    background: white;
+    background: var(--color-panel);
     box-shadow: 0 8px 28px color-mix(in oklch, var(--color-content) 6%, transparent);
   }
 
@@ -376,23 +438,23 @@
   }
 
   .ui-alert--info {
-    border-color: oklch(0.75 0.08 250);
-    background: oklch(0.96 0.025 250);
+    border-color: var(--color-info-border);
+    background: var(--color-info-surface);
   }
 
   .ui-alert--success {
-    border-color: oklch(0.72 0.1 155);
-    background: oklch(0.96 0.03 155);
+    border-color: var(--color-success-border);
+    background: var(--color-success-surface);
   }
 
   .ui-alert--warning {
-    border-color: oklch(0.75 0.12 80);
-    background: oklch(0.97 0.035 80);
+    border-color: var(--color-warning-border);
+    background: var(--color-warning-surface);
   }
 
   .ui-alert--danger {
-    border-color: oklch(0.72 0.12 25);
-    background: oklch(0.96 0.03 25);
+    border-color: var(--color-danger-border);
+    background: var(--color-danger-surface);
   }
 
   .ui-alert__content,
@@ -432,23 +494,23 @@
   }
 
   .ui-badge--info {
-    color: oklch(0.38 0.16 255);
-    background: oklch(0.93 0.04 255);
+    color: var(--color-info-content);
+    background: var(--color-info-surface);
   }
 
   .ui-badge--success {
-    color: oklch(0.35 0.12 155);
-    background: oklch(0.93 0.05 155);
+    color: var(--color-success-content);
+    background: var(--color-success-surface);
   }
 
   .ui-badge--warning {
-    color: oklch(0.38 0.12 70);
-    background: oklch(0.94 0.06 80);
+    color: var(--color-warning-content);
+    background: var(--color-warning-surface);
   }
 
   .ui-badge--danger {
-    color: oklch(0.42 0.18 25);
-    background: oklch(0.94 0.045 25);
+    color: var(--color-danger-content);
+    background: var(--color-danger-surface);
   }
 
   .ui-dialog {
@@ -460,7 +522,7 @@
     border-radius: var(--radius-surface);
     padding: 0;
     color: var(--color-content);
-    background: white;
+    background: var(--color-panel);
     box-shadow: 0 24px 70px color-mix(in oklch, var(--color-content) 25%, transparent);
   }
 
@@ -508,6 +570,10 @@
     padding-block: clamp(1rem, 5vw, 3.5rem) 0.5rem;
   }
 
+  [data-route-heading]:focus {
+    outline: none;
+  }
+
   .page-header__eyebrow {
     margin-block-end: 0.75rem;
     color: var(--color-action);
@@ -612,10 +678,10 @@
     display: grid;
     gap: 0.45rem;
     min-width: 0;
-    border: 1px solid var(--color-surface-muted);
+    border: 1px solid var(--color-border);
     border-radius: var(--radius-control);
     padding: 0.75rem;
-    background: white;
+    background: var(--color-panel);
   }
 
   .token-swatch__color {
@@ -633,9 +699,6 @@
   }
 
   .gallery-notice {
-    position: sticky;
-    z-index: 10;
-    bottom: 1rem;
     display: block;
     width: fit-content;
     max-width: 100%;
@@ -644,7 +707,7 @@
     border-radius: 999px;
     padding: 0.65rem 1rem;
     color: var(--color-content);
-    background: white;
+    background: var(--color-panel);
     box-shadow: 0 8px 28px color-mix(in oklch, var(--color-content) 10%, transparent);
     font-size: 0.875rem;
     font-weight: 650;
@@ -681,14 +744,14 @@
   }
 
   .state-surface--warning {
-    border-color: oklch(0.75 0.12 80);
-    background: oklch(0.97 0.035 80);
+    border-color: var(--color-warning-border);
+    background: var(--color-warning-surface);
   }
 
   .state-surface--danger,
   .ui-terminal-error {
-    border-color: oklch(0.72 0.12 25);
-    background: oklch(0.98 0.02 25);
+    border-color: var(--color-danger-border);
+    background: var(--color-danger-surface);
   }
 
   .state-surface--loading {
@@ -757,6 +820,10 @@
     display: none;
   }
 
+  .app-shell__brand {
+    display: none;
+  }
+
   .readiness-grid {
     grid-template-columns: minmax(0, 1fr);
   }

tests/e2e/responsive.spec.js

@@ -0,0 +1,36 @@
+import { expect, test } from "@playwright/test";
+
+test("reflows the UI gallery at the 320px minimum without horizontal overflow", async ({
+  page,
+}) => {
+  await page.setViewportSize({ width: 320, height: 720 });
+  await page.goto("/examples/ui");
+  await expect(
+    page.getByRole("heading", { level: 1, name: "UI 구성요소" }),
+  ).toBeVisible();
+  await expect(
+    page.getByRole("button", { name: "메뉴", exact: true }),
+  ).toBeVisible();
+
+  const viewport = await page.evaluate(() => ({
+    clientWidth: document.documentElement.clientWidth,
+    scrollWidth: document.documentElement.scrollWidth,
+  }));
+  expect(viewport.scrollWidth).toBeLessThanOrEqual(viewport.clientWidth);
+});
+
+test("keeps desktop navigation and two-column examples at wide viewports", async ({
+  page,
+}) => {
+  await page.setViewportSize({ width: 1440, height: 900 });
+  await page.goto("/examples/ui");
+
+  await expect(page.getByRole("navigation", { name: "주요 탐색" })).toBeVisible();
+  await expect(
+    page.getByRole("button", { name: "메뉴", exact: true }),
+  ).toBeHidden();
+  await expect(page.locator(".component-grid--two").first()).toHaveCSS(
+    "grid-template-columns",
+    /.+px .+px/,
+  );
+});

tests/e2e/theme.spec.js

@@ -0,0 +1,38 @@
+import AxeBuilder from "@axe-core/playwright";
+import { expect, test } from "@playwright/test";
+
+test("persists an explicit color scheme through the storage contract", async ({
+  page,
+}) => {
+  await page.goto("/");
+  const selector = page.getByRole("combobox", { name: "색상 테마" });
+
+  await selector.selectOption("dark");
+  await expect(page.locator("html")).toHaveAttribute("data-theme", "dark");
+  await expect(page.locator("html")).toHaveCSS("color-scheme", "dark");
+  const results = await new AxeBuilder({ page })
+    .withTags(["wcag2a", "wcag2aa", "wcag21a", "wcag21aa"])
+    .analyze();
+  expect(
+    results.violations.filter((violation) =>
+      ["critical", "serious"].includes(violation.impact ?? ""),
+    ),
+  ).toEqual([]);
+
+  await page.reload();
+  await expect(selector).toHaveValue("dark");
+  await expect(page.locator("html")).toHaveAttribute("data-theme", "dark");
+});
+
+test("tracks operating-system changes while system preference is selected", async ({
+  page,
+}) => {
+  await page.emulateMedia({ colorScheme: "dark" });
+  await page.goto("/");
+  const selector = page.getByRole("combobox", { name: "색상 테마" });
+  await selector.selectOption("system");
+  await expect(page.locator("html")).toHaveAttribute("data-theme", "dark");
+
+  await page.emulateMedia({ colorScheme: "light" });
+  await expect(page.locator("html")).toHaveAttribute("data-theme", "light");
+});

tests/unit/color-scheme.test.js

@@ -0,0 +1,44 @@
+// @vitest-environment jsdom
+
+import { describe, expect, it } from "vitest";
+
+import {
+  normalizeColorSchemePreference,
+  resolveColorScheme,
+} from "../../src/application/policies/color-scheme.js";
+import { initializeColorScheme } from "../../src/bootstrap/initialize-color-scheme.js";
+
+describe("color scheme policy", () => {
+  it("normalizes unknown persisted values to the safe system default", () => {
+    expect(normalizeColorSchemePreference("sepia")).toBe("system");
+    expect(normalizeColorSchemePreference("dark")).toBe("dark");
+  });
+
+  it("resolves system and explicit preferences deterministically", () => {
+    expect(resolveColorScheme("system", true)).toBe("dark");
+    expect(resolveColorScheme("system", false)).toBe("light");
+    expect(resolveColorScheme("light", true)).toBe("light");
+  });
+
+  it("applies a persisted preference before application paint", () => {
+    const storage = {
+      read: () => ({ ok: true, value: "system" }),
+      write: () => ({ ok: true }),
+      remove: () => ({ ok: true }),
+    };
+
+    const result = initializeColorScheme(storage, {
+      documentElement: document.documentElement,
+      matchMedia: () =>
+        /** @type {MediaQueryList} */ ({ matches: true }),
+    });
+
+    expect(result).toEqual({ preference: "system", resolved: "dark" });
+    expect(document.documentElement).toHaveAttribute("data-theme", "dark");
+    expect(document.documentElement).toHaveAttribute(
+      "data-theme-preference",
+      "system",
+    );
+    expect(document.documentElement.style.colorScheme).toBe("dark");
+  });
+});

tests/unit/manual-a11y-evidence.test.js

@@ -1,6 +1,10 @@
 import { describe, expect, it } from "vitest";
 
-import { validateManualA11yEvidence } from "../../scripts/lib/manual-a11y-evidence.mjs";
+import {
+  MANUAL_A11Y_ROUTE_IDS,
+  validateManualA11yEvidence,
+} from "../../scripts/lib/manual-a11y-evidence.mjs";
+import { ROUTE_REGISTRY } from "../../src/contracts/routes.js";
 
 const reviewed = `Status: reviewed
 Route ID: APP_HOME
@@ -20,6 +24,12 @@ Screen reader: pass
 Notes: no defects`;
 
 describe("manual accessibility evidence", () => {
+  it("requires evidence for every registered user-visible route", () => {
+    expect([...MANUAL_A11Y_ROUTE_IDS].sort()).toEqual(
+      Object.keys(ROUTE_REGISTRY).sort(),
+    );
+  });
+
   it("accepts a complete signed human review record", () => {
     expect(validateManualA11yEvidence(reviewed)).toMatchObject({
       failures: [],