diff --git a/CLAUDE.md b/CLAUDE.md
index 9090721..7e84ec6 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -30,7 +30,11 @@ cli.ts                CLI entry (commander). Detects jj/git, builds DiffArgs
                       starts the API server, spawns Vite in --dev mode.
 server/
   main.ts             Hono server. GET /api/diff; POST/DELETE /api/viewed;
-                      POST/DELETE /api/comment; serves dist/web statics.
+                      POST/DELETE /api/comment; GET/POST /api/theme;
+                      GET /api/theme.js (pre-first-paint theme boot script
+                      loaded by index.html); serves dist/web statics.
+  settings.ts         Global (not per-repo) UI settings — currently just the
+                      theme — in ~/.local/share/skepsis/settings.json.
   diff.ts             Runs `jj diff --git`/`git diff`, extracts per-file blob
                       hashes from index lines.
   viewed.ts           Viewed state, content-addressed by git blob ID — files
diff --git a/index.html b/index.html
index 38379e7..57ea737 100644
--- a/index.html
+++ b/index.html
@@ -12,6 +12,11 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>skepsis</title>
+    <!-- Sets data-theme from the stored preference. Deliberately a classic
+         (render-blocking) script so a forced theme applies before first
+         paint. Served by the API server; reaches it via the Vite proxy in
+         dev. -->
+    <script src="/api/theme.js"></script>
   </head>
   <body>
     <div id="root"></div>
diff --git a/server/main.ts b/server/main.ts
index dbe1295..36613ac 100644
--- a/server/main.ts
+++ b/server/main.ts
@@ -19,6 +19,7 @@ import { getFileContents } from './fileContents.ts'
 import { loadViewed, markViewed, unmarkViewed, unmarkViewedAll } from './viewed.ts'
 import { insertComment, removeComment } from './comment.ts'
 import { getCommentSyntaxes } from './commentSyntax.ts'
+import { loadTheme, saveTheme, themeBootScript } from './settings.ts'
 import {
   viewedRequestSchema,
   viewedDeleteSchema,
@@ -26,12 +27,14 @@ import {
   commentRequestSchema,
   commentDeleteSchema,
   fileContentsQuerySchema,
+  themeRequestSchema,
 } from '../shared/types.ts'
 import type {
   DiffResponse,
   FileContentsResponse,
   OkResponse,
   ErrorResponse,
+  ThemeResponse,
 } from '../shared/types.ts'
 
 export async function startServer(opts: {
@@ -99,6 +102,24 @@ export async function startServer(opts: {
     return c.json({ ok: true } satisfies OkResponse)
   })
 
+  app.get('/api/theme', async (c) => {
+    return c.json({ theme: await loadTheme() } satisfies ThemeResponse)
+  })
+
+  // Loaded by a render-blocking <script> in index.html (see themeBootScript).
+  // no-store: a cached copy would re-apply an old preference before React
+  // corrects it, flashing the wrong theme — the exact problem this solves.
+  app.get('/api/theme.js', async (c) => {
+    c.header('Cache-Control', 'no-store')
+    c.header('Content-Type', 'text/javascript')
+    return c.body(themeBootScript(await loadTheme()))
+  })
+
+  app.post('/api/theme', zValidator('json', themeRequestSchema), async (c) => {
+    await saveTheme(c.req.valid('json').theme)
+    return c.json({ ok: true } satisfies OkResponse)
+  })
+
   // Keep this path valid from source (`server/`) and from the published bundle
   // (`dist/cli.js`): both are one directory below the package root.
   const distDir = join(import.meta.dirname, '..', 'dist', 'web')
diff --git a/server/settings.test.ts b/server/settings.test.ts
new file mode 100644
index 0000000..6a4f64c
--- /dev/null
+++ b/server/settings.test.ts
@@ -0,0 +1,67 @@
+/*
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, you can obtain one at https://mozilla.org/MPL/2.0/.
+ *
+ * Copyright Oxide Computer Company
+ */
+
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest'
+// Type-only, so it doesn't evaluate the module before HOME is stubbed.
+import type * as SettingsModule from './settings.ts'
+
+// The module derives its storage path from HOME at import time, so stub HOME
+// and import dynamically instead of statically.
+let home: string
+let settings: typeof SettingsModule
+
+beforeAll(async () => {
+  home = await mkdtemp(join(tmpdir(), 'skepsis-settings-'))
+  vi.stubEnv('HOME', home)
+  settings = await import('./settings.ts')
+})
+
+afterAll(async () => {
+  vi.unstubAllEnvs()
+  await rm(home, { recursive: true, force: true })
+})
+
+describe('loadTheme/saveTheme', () => {
+  it('defaults to system when the file is missing', async () => {
+    expect(await settings.loadTheme()).toBe('system')
+  })
+
+  it('round-trips a saved theme', async () => {
+    await settings.saveTheme('light')
+    expect(await settings.loadTheme()).toBe('light')
+    await settings.saveTheme('system')
+    expect(await settings.loadTheme()).toBe('system')
+  })
+
+  it('falls back to system on garbage', async () => {
+    const path = join(home, '.local', 'share', 'skepsis', 'settings.json')
+    await mkdir(join(home, '.local', 'share', 'skepsis'), { recursive: true })
+    await writeFile(path, 'not json')
+    expect(await settings.loadTheme()).toBe('system')
+    await writeFile(path, JSON.stringify({ theme: 'mauve' }))
+    expect(await settings.loadTheme()).toBe('system')
+  })
+})
+
+describe('themeBootScript', () => {
+  it('stamps a forced theme onto the html element', () => {
+    expect(settings.themeBootScript('light')).toBe(
+      "document.documentElement.dataset.theme = 'light'\n",
+    )
+    expect(settings.themeBootScript('dark')).toBe(
+      "document.documentElement.dataset.theme = 'dark'\n",
+    )
+  })
+
+  it('is empty for system', () => {
+    expect(settings.themeBootScript('system')).toBe('')
+  })
+})
diff --git a/server/settings.ts b/server/settings.ts
new file mode 100644
index 0000000..ee0c7f6
--- /dev/null
+++ b/server/settings.ts
@@ -0,0 +1,49 @@
+/*
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, you can obtain one at https://mozilla.org/MPL/2.0/.
+ *
+ * Copyright Oxide Computer Company
+ */
+
+/**
+ * Global UI settings at ~/.local/share/skepsis/settings.json. Unlike viewed
+ * state, settings are not per-repo (no cwd hashing): a theme preference is
+ * about the user, not the diff under review. Server-side storage is what
+ * makes the preference survive restarts at all — the ephemeral port means a
+ * fresh browser origin every run, so web storage can't.
+ */
+
+import { join } from 'path'
+import { mkdir, readFile, writeFile } from 'fs/promises'
+import { THEME_MODES } from '../shared/types.ts'
+import type { ThemeMode } from '../shared/types.ts'
+
+const BASE_DIR = join(process.env['HOME'] ?? '~', '.local', 'share', 'skepsis')
+const SETTINGS_PATH = join(BASE_DIR, 'settings.json')
+
+/** Missing file, unparseable JSON, or an unknown value → 'system'. */
+export async function loadTheme(): Promise<ThemeMode> {
+  try {
+    const raw: unknown = JSON.parse(await readFile(SETTINGS_PATH, 'utf-8'))
+    const theme = (raw as { theme?: unknown }).theme
+    if ((THEME_MODES as readonly unknown[]).includes(theme)) return theme as ThemeMode
+  } catch {
+    // fall through to the default
+  }
+  return 'system'
+}
+
+export async function saveTheme(theme: ThemeMode): Promise<void> {
+  await mkdir(BASE_DIR, { recursive: true })
+  await writeFile(SETTINGS_PATH, JSON.stringify({ theme }, null, 2) + '\n')
+}
+
+/** Body of /api/theme.js, loaded by a render-blocking <script> in index.html
+ *  so a forced theme's data-theme lands on <html> before first paint (CSS
+ *  keys color-scheme off the attribute). 'system' means no attribute: an
+ *  empty script leaves the page following the OS. */
+export function themeBootScript(theme: ThemeMode): string {
+  if (theme === 'system') return ''
+  return `document.documentElement.dataset.theme = '${theme}'\n`
+}
diff --git a/shared/types.ts b/shared/types.ts
index 8fdf925..30d8a93 100644
--- a/shared/types.ts
+++ b/shared/types.ts
@@ -48,6 +48,20 @@ export type ViewedRequest = z.infer<typeof viewedRequestSchema>
 export type CommentRequest = z.infer<typeof commentRequestSchema>
 export type CommentDeleteRequest = z.infer<typeof commentDeleteSchema>
 
+// --- UI types ---
+
+/** Color scheme. 'system' follows the OS preference; 'light' and 'dark' force
+ *  it (e.g. light diffs on a dark desktop). One list drives the API schema,
+ *  the toggle cycle, and the client's data-theme validation. */
+export const THEME_MODES = ['light', 'dark', 'system'] as const
+export type ThemeMode = (typeof THEME_MODES)[number]
+
+export const themeRequestSchema = z.object({ theme: z.enum(THEME_MODES) })
+
+export interface ThemeResponse {
+  theme: ThemeMode
+}
+
 // --- VCS types ---
 
 /**
diff --git a/src/App.tsx b/src/App.tsx
index 632758e..0b99b82 100644
--- a/src/App.tsx
+++ b/src/App.tsx
@@ -37,10 +37,13 @@ import type {
   LineAnnotation,
   SelectedLineRange,
 } from '@pierre/diffs'
+import { THEME_MODES } from '../shared/types.ts'
 import type {
   DiffResponse,
   ErrorResponse,
   FileContentsResponse,
+  ThemeMode,
+  ThemeResponse,
   ViewedMap,
   FileHashes,
 } from '../shared/types.ts'
@@ -54,6 +57,27 @@ import {
 
 const queryClient = new QueryClient()
 
+// The /api/theme.js boot script in index.html stamps the stored theme
+// preference onto <html> as data-theme before this bundle loads, so CSS pins
+// color-scheme (and our light-dark() tokens resolve to the forced side)
+// before first paint. Read it back as the initial client state; /api/theme
+// is the source of truth from then on. The diff shadow roots don't inherit
+// the page's color-scheme and are pinned separately via the CodeView
+// themeType option.
+const themeAttr = document.documentElement.dataset['theme']
+const initialTheme: ThemeMode = (THEME_MODES as readonly (string | undefined)[]).includes(
+  themeAttr,
+)
+  ? (themeAttr as ThemeMode)
+  : 'system'
+
+function applyTheme(theme: ThemeMode) {
+  if (theme === 'system') delete document.documentElement.dataset['theme']
+  else document.documentElement.dataset['theme'] = theme
+}
+
+const THEME_CYCLE = { system: 'light', light: 'dark', dark: 'system' } as const
+
 async function apiFetch<T = unknown>(
   url: string,
   opts: { method: string; body?: unknown } = { method: 'GET' },
@@ -381,7 +405,7 @@ function Tip({
   closeOnClick,
   children,
 }: {
-  text: string
+  text: React.ReactNode
   closeOnClick?: boolean
   children: ReactElement
 }) {
@@ -439,6 +463,40 @@ function ExpandAllIcon() {
   )
 }
 
+// Sun/moon/device-desktop octicons for the theme toggle, one per mode.
+function SunIcon() {
+  return (
+    <svg viewBox="0 0 16 16" width="18" height="18" aria-hidden="true">
+      <path
+        fill="currentColor"
+        d="M8 12a4 4 0 1 1 0-8 4 4 0 0 1 0 8Zm0-1.5a2.5 2.5 0 1 0 0-5 2.5 2.5 0 0 0 0 5Zm5.657-8.157a.75.75 0 0 1 0 1.061l-1.061 1.06a.749.749 0 0 1-1.275-.326.749.749 0 0 1 .215-.734l1.06-1.06a.75.75 0 0 1 1.06 0Zm-9.193 9.193a.75.75 0 0 1 0 1.06l-1.06 1.061a.75.75 0 1 1-1.061-1.06l1.06-1.061a.75.75 0 0 1 1.061 0ZM8 0a.75.75 0 0 1 .75.75v1.5a.75.75 0 0 1-1.5 0V.75A.75.75 0 0 1 8 0ZM3 8a.75.75 0 0 1-.75.75H.75a.75.75 0 0 1 0-1.5h1.5A.75.75 0 0 1 3 8Zm13 0a.75.75 0 0 1-.75.75h-1.5a.75.75 0 0 1 0-1.5h1.5A.75.75 0 0 1 16 8Zm-8 5a.75.75 0 0 1 .75.75v1.5a.75.75 0 0 1-1.5 0v-1.5A.75.75 0 0 1 8 13Zm3.536-1.464a.75.75 0 0 1 1.06 0l1.061 1.06a.75.75 0 0 1-1.06 1.061l-1.061-1.06a.75.75 0 0 1 0-1.061ZM2.343 2.343a.75.75 0 0 1 1.061 0l1.06 1.061a.751.751 0 0 1-.018 1.042.751.751 0 0 1-1.042.018l-1.06-1.06a.75.75 0 0 1 0-1.06Z"
+      />
+    </svg>
+  )
+}
+
+function MoonIcon() {
+  return (
+    <svg viewBox="0 0 16 16" width="18" height="18" aria-hidden="true">
+      <path
+        fill="currentColor"
+        d="M9.598 1.591a.749.749 0 0 1 .785-.175 7.001 7.001 0 1 1-8.967 8.967.75.75 0 0 1 .961-.96 5.5 5.5 0 0 0 7.046-7.046.75.75 0 0 1 .175-.786Zm1.616 1.945a7 7 0 0 1-7.678 7.678 5.499 5.499 0 1 0 7.678-7.678Z"
+      />
+    </svg>
+  )
+}
+
+function SystemThemeIcon() {
+  return (
+    <svg viewBox="0 0 16 16" width="18" height="18" aria-hidden="true">
+      <path
+        fill="currentColor"
+        d="M14.25 1c.966 0 1.75.784 1.75 1.75v7.5A1.75 1.75 0 0 1 14.25 12h-3.727c.099 1.041.52 1.872 1.292 2.757A.752.752 0 0 1 11.25 16h-6.5a.75.75 0 0 1-.565-1.243c.772-.885 1.192-1.716 1.292-2.757H1.75A1.75 1.75 0 0 1 0 10.25v-7.5C0 1.784.784 1 1.75 1ZM1.75 2.5a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h12.5a.25.25 0 0 0 .25-.25v-7.5a.25.25 0 0 0-.25-.25ZM9.018 12H6.982a5.72 5.72 0 0 1-.765 2.5h3.566a5.72 5.72 0 0 1-.765-2.5Z"
+      />
+    </svg>
+  )
+}
+
 function FileHeader({
   fileDiff,
   isViewed,
@@ -555,11 +613,15 @@ function ProgressBar({
   fileHashes,
   viewed,
   onUnviewAll,
+  theme,
+  onCycleTheme,
 }: {
   command: string
   fileHashes: FileHashes
   viewed: ViewedMap
   onUnviewAll: () => void
+  theme: ThemeMode
+  onCycleTheme: () => void
 }) {
   const total = Object.keys(fileHashes).length
   const viewedCount = Object.entries(fileHashes).filter(
@@ -595,6 +657,31 @@ function ProgressBar({
           Clear
         </button>
       </Tip>
+      {/* The icon and tooltip show the current mode including "system": a
+          toggle that hides the system state leaves a user who forced a theme
+          long ago unable to see why the app ignores their OS setting. */}
+      <Tip
+        text={
+          <>
+            Theme: {theme} <kbd>t</kbd>
+          </>
+        }
+      >
+        <button
+          type="button"
+          className="theme-toggle-button"
+          aria-label={`Theme: ${theme}`}
+          onClick={onCycleTheme}
+        >
+          {theme === 'system' ? (
+            <SystemThemeIcon />
+          ) : theme === 'light' ? (
+            <SunIcon />
+          ) : (
+            <MoonIcon />
+          )}
+        </button>
+      </Tip>
     </div>
   )
 }
@@ -623,6 +710,7 @@ const SHORTCUTS: [string, string][] = [
   ['v', 'Toggle viewed'],
   ['e / E', 'Toggle collapse file / all files'],
   ['s', 'Toggle split mode (responsive / unified)'],
+  ['t', 'Cycle theme (system / light / dark)'],
   ['c', 'Comment on line'],
   ['Esc', 'Close / cancel'],
   ['?', 'Toggle this help'],
@@ -774,6 +862,41 @@ function DiffView() {
 
   const qc = useQueryClient()
 
+  // Server-persisted so the preference survives the per-run ephemeral port (a
+  // fresh browser origin every run, which defeats web storage) and reaches
+  // other running instances. initialData comes from the data-theme attribute
+  // the server stamped into the HTML; the default refetchOnWindowFocus
+  // re-applies the stored value when a stale tab regains focus — the only
+  // moment cross-instance staleness is observable.
+  const { data: themeData } = useQuery({
+    queryKey: ['theme'],
+    queryFn: () => apiFetch<ThemeResponse>('/api/theme'),
+    initialData: { theme: initialTheme },
+  })
+  const theme = themeData.theme
+
+  const themeMutation = useMutation({
+    mutationFn: (next: ThemeMode) =>
+      apiFetch('/api/theme', { method: 'POST', body: { theme: next } }),
+    // Write the cache up front so the toggle doesn't fight a stale entry.
+    onMutate: (next) => qc.setQueryData(['theme'], { theme: next } satisfies ThemeResponse),
+  })
+  const mutateTheme = themeMutation.mutate
+
+  // Shared by the header button and the t shortcut. Returns the new mode so
+  // the shortcut can toast it. Reads the current mode from the query cache
+  // rather than closing over `theme`: the theme switch re-renders every
+  // CodeView item, so a second press during that render would otherwise see
+  // a stale mode and cycle to the same place.
+  const cycleTheme = useCallback(() => {
+    const cur = qc.getQueryData<ThemeResponse>(['theme'])?.theme ?? 'system'
+    const next = THEME_CYCLE[cur]
+    mutateTheme(next)
+    return next
+  }, [qc, mutateTheme])
+
+  useEffect(() => applyTheme(theme), [theme])
+
   const markMutation = useMutation({
     mutationFn: ({ file, hash, mark }: { file: string; hash: string; mark: boolean }) =>
       apiFetch('/api/viewed', {
@@ -1247,7 +1370,13 @@ function DiffView() {
 
   const options = useMemo<CodeViewOptions<AnnotationMeta>>(
     () => ({
-      theme: 'github-dark-default',
+      // Always the dual theme: Shiki tokenizes both up front and switching
+      // themes is purely a CSS flip (a single theme would retokenize on every
+      // toggle). themeType pins the shadow roots' color-scheme — they don't
+      // inherit the page's value ('system' leaves their :host default of
+      // `light dark`, following the OS).
+      theme: { light: 'github-light-default', dark: 'github-dark-default' },
+      themeType: theme,
       diffStyle,
       // The library lays out collapsed files (and unmeasured estimates) from
       // these metrics rather than the DOM. Its diffHeaderHeight default (44)
@@ -1297,7 +1426,7 @@ function DiffView() {
         }
       },
     }),
-    [diffStyle, commentsEnabled, markSeen],
+    [theme, diffStyle, commentsEnabled, markSeen],
   )
 
   // Keyboard shortcuts. File navigation (n/p) and the focused-file actions
@@ -1502,6 +1631,17 @@ function DiffView() {
           setCollapsed(Object.fromEntries(files.map((f) => [f.name, anyExpanded])))
           break
         }
+        case 't': {
+          if (showHelp || composing) break
+          e.preventDefault()
+          const next = cycleTheme()
+          showToast(
+            <>
+              Theme: <code>{next}</code>
+            </>,
+          )
+          break
+        }
       }
     }
 
@@ -1523,10 +1663,13 @@ function DiffView() {
     commentMutation,
     setFocused,
     markProgrammaticScroll,
+    cycleTheme,
   ])
 
-  if (isLoading || !data) return <div className="empty-diff">Loading...</div>
+  // Error before loading: on a failed fetch react-query settles with `data`
+  // undefined, so a loading-first guard would show "Loading..." forever.
   if (error) return <pre style={{ color: 'red', padding: 20 }}>{String(error)}</pre>
+  if (isLoading || !data) return <div className="empty-diff">Loading...</div>
   if (data.error) return <pre style={{ color: 'red', padding: 20 }}>{data.error}</pre>
   if (!patch)
     return (
@@ -1550,6 +1693,8 @@ function DiffView() {
           command={data.revset}
           fileHashes={fileHashes}
           viewed={viewed}
+          theme={theme}
+          onCycleTheme={cycleTheme}
           onUnviewAll={() => {
             const entries = Object.entries(viewed).map(([file, hash]) => ({ file, hash }))
             if (entries.length === 0) return
diff --git a/src/styles.css b/src/styles.css
index 90a0516..3730890 100644
--- a/src/styles.css
+++ b/src/styles.css
@@ -7,48 +7,91 @@
  */
 
 /*
- * Color tokens. Neutrals share a fixed hue (256) and chroma (.015) and vary
- * only in OKLCH lightness, so surfaces form one perceptually-even elevation
- * ramp: darker = recessed, lighter = raised. Controls (--bg-control) sit ABOVE
- * the header bar (--bg-header) so a button reads as resting on the bar rather
- * than punched into it. Borders are a separate low→high contrast ramp; accents
- * are four fixed hues with bright/text variants.
+ * Color tokens, a light-dark(light, dark) pair per token, resolved by
+ * color-scheme on :root: 'light dark' follows the OS, and a forced theme pins
+ * it via the data-theme attribute (rules below) — the diff library's shadow
+ * roots resolve their theme CSS from the same property. Neutrals share one
+ * hue and vary only in OKLCH lightness, so surfaces form an elevation ramp:
+ * raised chrome steps away from the page background. The two schemes express
+ * elevation differently (matching GitHub's grammar): in dark, a control
+ * (--bg-control) sits a wide step ABOVE the header bar (--bg-header) so it
+ * reads as raised; in light, fills that dark against white read as pressed-in,
+ * so controls share the bar's lightness and the border carries the affordance.
+ * Borders are a separate low→high contrast ramp; accents are four fixed hues
+ * with bright/text variants.
  */
 :root {
+  /* Drives light-dark() resolution here and native widget rendering, and is
+     inherited into the diff library's shadow roots. Forced themes override
+     this via data-theme, set pre-first-paint by the /api/theme.js boot
+     script in index.html and toggled at runtime by the theme button / t. */
+  color-scheme: light dark;
+
   /* Surfaces, ascending elevation. The page (--bg-canvas) matches the diff/code
-     base (--bg-code) so the code area doesn't read as an odd dark inset — the
-     whole app sits on one dark base and only chrome (header, controls) lifts off
-     it. Steps are small so raised elements stay dark rather than pasty-gray. */
-  --bg-code: oklch(17.5% 0.015 256); /* diff/code content, textarea — the base */
-  --bg-canvas: oklch(17.5% 0.015 256); /* page — same as the code base */
-  --bg-panel: oklch(22% 0.015 256); /* modal, comment form, separator band */
-  --bg-muted: oklch(24% 0.015 256); /* progress track, kbd, inline code chip */
-  --bg-header: oklch(26% 0.015 256); /* file header bar */
-  --bg-control: oklch(28.5% 0.015 256); /* buttons — just above the header */
-  --bg-control-hover: oklch(33% 0.015 256);
+     base (--bg-code) so the code area doesn't read as an odd inset — the whole
+     app sits on one base and only chrome (header, controls) steps off it.
+     Steps are small so raised elements stay close to the base rather than
+     pasty-gray. Light --bg-code is pure white to match the
+     github-light-default syntax theme background the diff bodies render with. */
+  --bg-code: light-dark(
+    oklch(100% 0 0),
+    oklch(17.5% 0.015 256)
+  ); /* diff/code, textarea — the base */
+  --bg-canvas: light-dark(
+    oklch(100% 0 0),
+    oklch(17.5% 0.015 256)
+  ); /* page — same as the code base */
+  --bg-panel: light-dark(
+    oklch(97.5% 0.004 256),
+    oklch(22% 0.015 256)
+  ); /* modal, comment form, separator band */
+  --bg-muted: light-dark(
+    oklch(94.5% 0.007 256),
+    oklch(24% 0.015 256)
+  ); /* progress track, kbd, inline code chip */
+  --bg-header: light-dark(oklch(97% 0.005 256), oklch(26% 0.015 256)); /* file header bar */
+  --bg-control: light-dark(
+    oklch(97% 0.005 256),
+    oklch(31% 0.016 256)
+  ); /* buttons — dark: a wide step above the header; light: level with it */
+  --bg-control-hover: light-dark(oklch(94% 0.008 256), oklch(35.5% 0.016 256));
 
   /* Borders, low→high contrast against the surface they sit on. */
-  --border: oklch(33% 0.013 256); /* default, on dark surfaces */
-  --border-soft: oklch(32% 0.015 256); /* header strip — low contrast on the bar */
-  --border-strong: oklch(42% 0.016 256); /* control outlines */
-  --border-muted: oklch(56% 0.018 256); /* hover / emphasis */
+  --border: light-dark(oklch(88% 0.012 256), oklch(36% 0.015 256)); /* default */
+  --border-soft: light-dark(
+    oklch(90.5% 0.01 256),
+    oklch(32% 0.015 256)
+  ); /* header strip — low contrast on the bar */
+  --border-strong: light-dark(
+    oklch(84% 0.013 256),
+    oklch(45% 0.016 256)
+  ); /* control outlines */
+  --border-muted: light-dark(
+    oklch(65% 0.016 256),
+    oklch(58% 0.018 256)
+  ); /* hover / emphasis */
 
   /* Text, hue 250. */
-  --fg: oklch(86% 0.014 250);
-  --fg-bright: oklch(94% 0.012 250);
-  --fg-dim: oklch(77% 0.016 250); /* between muted and fg: de-emphasized but interactive */
-  --fg-muted: oklch(66% 0.018 250);
-
-  /* Accents: base / brighter (hover) / lighter (text-on-dark). */
+  --fg: light-dark(oklch(27% 0.018 250), oklch(88% 0.013 250));
+  --fg-bright: light-dark(oklch(18% 0.018 250), oklch(96% 0.01 250));
+  --fg-dim: light-dark(
+    oklch(42% 0.02 250),
+    oklch(78% 0.016 250)
+  ); /* between muted and fg: de-emphasized but interactive */
+  --fg-muted: light-dark(oklch(49% 0.021 250), oklch(68% 0.017 250));
+
+  /* Accents: base / bright (hover) / text (on the scheme's surfaces). Bases
+     used as fills under white text (--blue, --green) hold in both schemes;
+     hover and text variants swing toward the scheme's contrast direction. */
   --blue: oklch(57% 0.2 260);
-  --blue-bright: oklch(65% 0.19 257);
-  --blue-text: oklch(72% 0.15 253);
+  --blue-bright: light-dark(oklch(52% 0.2 258), oklch(65% 0.19 257));
+  --blue-text: light-dark(oklch(47% 0.18 258), oklch(72% 0.15 253));
   --green: oklch(55% 0.15 146);
-  --green-bright: oklch(62% 0.17 146);
-  --green-text: oklch(69% 0.18 146);
-  --red: oklch(66% 0.2 27);
-  --amber: oklch(72% 0.14 80);
-  --amber-deep: oklch(56% 0.12 78);
+  --green-bright: light-dark(oklch(50% 0.15 146), oklch(62% 0.17 146));
+  --green-text: light-dark(oklch(44% 0.14 146), oklch(69% 0.18 146));
+  --red: light-dark(oklch(53% 0.19 27), oklch(66% 0.2 27));
+  --amber: light-dark(oklch(50% 0.12 80), oklch(72% 0.14 80));
+  --amber-deep: light-dark(oklch(52% 0.11 78), oklch(56% 0.12 78));
 
   /* Monospace stack. Berkeley Mono first for those who have it, then each OS's
      best system mono (ui-monospace → SF Mono on macOS, Consolas/Cascadia on
@@ -59,6 +102,17 @@
     Consolas, 'Liberation Mono', monospace;
 }
 
+/* Forced themes. The attribute arrives two ways: set by the /api/theme.js
+   boot script before first paint, and set/removed by the theme toggle at
+   runtime. */
+:root[data-theme='light'] {
+  color-scheme: light;
+}
+
+:root[data-theme='dark'] {
+  color-scheme: dark;
+}
+
 body {
   margin: 0;
   background: var(--bg-canvas);
@@ -67,7 +121,6 @@ body {
     -apple-system,
     sans-serif;
   color: var(--fg);
-  color-scheme: dark;
 }
 
 /* Full-height layout so CodeView's single scroll container fills the viewport
@@ -114,6 +167,17 @@ body,
   --diffs-font-family: var(--font-mono);
   --diffs-bg-separator-override: var(--bg-panel);
   --diffs-modified-color-override: var(--blue);
+  /* Selected-line highlight. The library builds it by color-mix()ing this
+     into the line background in CIELAB, whose blue region drifts purple as it
+     lightens — feeding --blue (hue 260) directly yields a periwinkle wash
+     (hue ~282 in light mode) clashing with the solid-blue comment button
+     sitting on it. These hues are rotated so the post-mix tint lands back at
+     --blue's hue 260 in each scheme (the two mixes drift by different
+     amounts). Chroma is up a notch to keep the tint from washing out at the
+     rotated hue. */
+  --diffs-bg-selection-override: light-dark(oklch(57% 0.22 227), oklch(57% 0.22 238));
+  /* The gutter-number cells mix from this separate slot; same target. */
+  --diffs-bg-selection-number-override: var(--diffs-bg-selection-override);
 }
 
 /* The library focuses the scroll container (tabindex="-1") after programmatic
@@ -127,9 +191,30 @@ body,
    scrolls, so any top chrome would scroll off and leave the pinned sticky header
    flush and square against the scroll edge ("cut off") — fighting the library,
    whose native model has no card. Files are delineated by the header strip
-   (.file-header background + border) and inter-file spacing instead. */
+   (.file-header background + border) and inter-file spacing instead. Side
+   borders (matching the header's top border) close off the file's edges —
+   without them the header/body strips just stop mid-air. No border-radius:
+   rounding fights the sticky header. */
 .codeview-root diffs-container {
   display: block;
+  border-left: 1px solid var(--border-soft);
+  border-right: 1px solid var(--border-soft);
+  border-bottom: 1px solid var(--border-soft);
+}
+
+/* Track the focused header (which swaps to --border-strong): otherwise its
+   darkened top border visibly mismatches the file's soft side borders where
+   they meet at the corners. This also outlines the focused file's full
+   extent. */
+.codeview-root diffs-container:has(.file-header.focused) {
+  border-color: var(--border-strong);
+}
+
+/* Collapsed file: the header is the only content, so its border-bottom would
+   sit directly on the container's and read as a double line. Let the header's
+   (which tracks focus) be the file's bottom edge. */
+.codeview-root diffs-container:has(.collapse-chevron.collapsed) {
+  border-bottom: none;
 }
 
 /* Custom file header. Sticky positioning is handled by CodeView (stickyHeaders),
@@ -215,6 +300,25 @@ body,
   animation: tooltip-in 0.09s ease;
 }
 
+/* Key-cap chip inside a tooltip (e.g. the theme toggle's shortcut), like
+   .help-modal kbd but sized down to sit inline in tooltip text. Translucent
+   background rather than a ramp token: the tooltip surface is already near
+   the top of the elevation ramp, so a fixed token would sit below it in dark
+   mode and read as a hole instead of a key. */
+.tooltip-popup kbd {
+  display: inline-block;
+  padding: 1px 4px;
+  margin-left: 2px;
+  background: light-dark(rgb(0 0 0 / 5%), rgb(255 255 255 / 10%));
+  /* One ramp step stronger in dark: the translucent fill lightens the chip
+     interior to about --border-strong's level, swallowing that border. */
+  border: 1px solid light-dark(var(--border-strong), var(--border-muted));
+  border-radius: 4px;
+  font-family: var(--font-mono);
+  font-size: 11px;
+  color: var(--fg-bright);
+}
+
 @keyframes tooltip-in {
   from {
     opacity: 0;
@@ -322,10 +426,12 @@ body,
   transform: scale(0.85);
 }
 
-/* Keep the control lit while the file is expanded so it reads as active. */
+/* Keep the control lit while the file is expanded so it reads as active.
+   The hover step, not --bg-control: in light mode the control fill is level
+   with the header bar, so it would vanish here. */
 .expand-all-button.expanded {
   color: var(--fg-bright);
-  background: var(--bg-control);
+  background: var(--bg-control-hover);
 }
 
 /* Disabled: dimmed and inert, but still hoverable so its tooltip (the reason it
@@ -494,7 +600,7 @@ body,
 /* Clear-viewed-progress button next to the counter. Chrome matches
    .viewed-button so the two read as the same family of control. */
 .unview-all-button {
-  padding: 3px 6px;
+  padding: 4px 7px;
   border: 1px solid var(--border-strong);
   border-radius: 6px;
   background: var(--bg-control);
@@ -508,6 +614,32 @@ body,
   user-select: none;
 }
 
+/* Theme toggle: a plain icon rather than a bordered button — quieter than
+   the text controls, but with a hover background so it still reads as
+   clickable. */
+.theme-toggle-button {
+  display: flex;
+  align-items: center;
+  padding: 4px;
+  border: none;
+  border-radius: 4px;
+  background: none;
+  color: var(--fg-dim);
+  cursor: pointer;
+  flex-shrink: 0;
+}
+
+/* The hover step, not --bg-control: in light mode the control fill is level
+   with the white canvas this button sits on, so it wouldn't show. */
+.theme-toggle-button:hover {
+  background: var(--bg-control-hover);
+  color: var(--fg);
+}
+
+.theme-toggle-button svg {
+  display: block;
+}
+
 .unview-all-button:hover {
   border-color: var(--border-muted);
   background: var(--bg-control-hover);
