feat(web): dark mode - system default + persisted toggle, warm dark tokens, dark basemap and band ramp

alidade_smooth_dark basemap; graded dark band alphas (deep amber glow over
dark ground, validated monotonic legend swatches); dark category-chip
variants; sun/moon toggle beside the logo chip; e2e covers system-follows +
toggle-override.

Author: TomerBenda

apps/web/e2e/smoke.spec.ts

@@ -58,6 +58,15 @@ test('walking isochrone smoke', async ({ page }) => {
   expect(draggedBody.type).toBe('FeatureCollection');
 });
 
+test('theme: follows system dark and toggles back to light', async ({ page }) => {
+  test.setTimeout(90_000);
+  await page.emulateMedia({ colorScheme: 'dark' });
+  await page.goto('/');
+  await expect(page.locator('html')).toHaveAttribute('data-theme', 'dark');
+  await page.getByRole('button', { name: 'Switch to light theme' }).click();
+  await expect(page.locator('html')).toHaveAttribute('data-theme', 'light');
+});
+
 test('mobile: bottom sheet hosts the controls', async ({ page }) => {
   test.setTimeout(90_000);
   await page.setViewportSize({ width: 375, height: 667 });

apps/web/src/app/globals.css

@@ -22,13 +22,16 @@
 
   [data-theme='dark'],
   .dark {
-    --background: 222 47% 11%;
-    --foreground: 210 40% 98%;
-    --muted: 217 33% 17%;
-    --muted-foreground: 215 20% 65%;
-    --border: 217 33% 17%;
-    --accent: 217 33% 17%;
-    --accent-foreground: 210 40% 98%;
+    --background: 24 15% 10%;
+    --foreground: 33 30% 92%;
+    --muted: 24 12% 17%;
+    --muted-foreground: 30 8% 66%;
+    --border: 24 12% 24%;
+    --accent: 21 45% 19%;
+    --accent-foreground: 33 100% 88%;
+    --primary: 21 88% 48%; /* brighter orange pops on dark */
+    --primary-hover: 24 94% 56%;
+    --primary-foreground: 0 0% 100%;
   }
 
   html,

apps/web/src/app/home-inner.tsx

@@ -25,11 +25,13 @@ import { TimeSelector } from '@/components/controls/TimeSelector';
 import { ModeSelector } from '@/components/controls/ModeSelector';
 import { CategoryToggles } from '@/components/controls/CategoryToggles';
 import { SurpriseMe } from '@/components/controls/SurpriseMe';
+import { ThemeToggle } from '@/components/controls/ThemeToggle';
 import { DestinationCard } from '@/components/destination/DestinationCard';
 import { BandLegend } from '@/components/legend/BandLegend';
 import { CoachMark } from '@/components/onboarding/CoachMark';
 import { tryGeolocate } from '@/lib/geolocation';
 import { useIsochroneBands } from '@/lib/hooks/useIsochroneBands';
+import { useTheme } from '@/lib/hooks/useTheme';
 import { useIsMobile } from '@/lib/hooks/useIsMobile';
 import { usePois } from '@/lib/hooks/usePois';
 import { bboxOf, isInsidePolygon } from '@/lib/polygon';
@@ -56,7 +58,8 @@ export function HomeInner() {
     () => new StadiaTileProvider({ apiKey: PUBLIC_CONFIG.stadiaApiKey || undefined }),
     [],
   );
-  const tileStyle = useMemo(() => tileProvider.getStyle('light'), [tileProvider]);
+  const { theme, toggle: toggleTheme } = useTheme();
+  const tileStyle = useMemo(() => tileProvider.getStyle(theme), [tileProvider, theme]);
 
   // Initial state: parse from URL on first render, fall back to public defaults.
   const initialState = useMemo<AppUrlState>(() => {
@@ -262,6 +265,7 @@ export function HomeInner() {
           onOriginDragEnd={onOriginDragEnd}
           bands={data}
           selectedMinutes={state.minutes}
+          theme={theme}
           originLoading={isLoading}
           onPickDestination={onPickDestination}
           onMapBackgroundClick={onMapBackgroundClick}
@@ -300,8 +304,9 @@ export function HomeInner() {
       </div>
 
       <header className="pointer-events-none absolute left-0 right-0 top-0 flex items-start gap-3 p-4">
-        <div className="pointer-events-auto">
+        <div className="pointer-events-auto flex items-start gap-2">
           <LogoChip />
+          <ThemeToggle theme={theme} onToggle={toggleTheme} />
         </div>
         <ControlBar className="mx-auto hidden md:flex">
           <ModeSelector value={state.mode} onChange={onModeChange} />
@@ -322,7 +327,7 @@ export function HomeInner() {
       </header>
 
       <div className="absolute bottom-4 left-4 hidden md:block">
-        <BandLegend selectedMinutes={state.minutes} />
+        <BandLegend selectedMinutes={state.minutes} theme={theme} />
       </div>
 
       {isMobile && (
@@ -345,7 +350,7 @@ export function HomeInner() {
                     : `Pick one of ${visiblePois.length} reachable places`
                 }
               />
-              <BandLegend selectedMinutes={state.minutes} />
+              <BandLegend selectedMinutes={state.minutes} theme={theme} />
             </>
           }
         />

apps/web/src/components/controls/CategoryToggles.tsx

@@ -27,14 +27,32 @@ const CATEGORIES: { id: PoiCategory; label: string; Icon: LucideIcon }[] = [
   { id: 'beach', label: 'Beaches', Icon: Waves },
 ];
 
-/** Pastel chip fill + saturated icon per category (warm & playful, harmonized). */
+/** Pastel chip fill + saturated icon per category (warm & playful, harmonized; deep fills in dark). */
 const CATEGORY_STYLES: Record<PoiCategory, { chip: string; icon: string }> = {
-  park: { chip: 'bg-emerald-100 text-emerald-900', icon: 'text-emerald-600' },
-  cafe: { chip: 'bg-amber-100 text-amber-900', icon: 'text-amber-600' },
-  restaurant: { chip: 'bg-rose-100 text-rose-900', icon: 'text-rose-600' },
-  museum: { chip: 'bg-violet-100 text-violet-900', icon: 'text-violet-600' },
-  viewpoint: { chip: 'bg-sky-100 text-sky-900', icon: 'text-sky-600' },
-  beach: { chip: 'bg-cyan-100 text-cyan-900', icon: 'text-cyan-600' },
+  park: {
+    chip: 'bg-emerald-100 text-emerald-900 dark:bg-emerald-950 dark:text-emerald-200',
+    icon: 'text-emerald-600 dark:text-emerald-400',
+  },
+  cafe: {
+    chip: 'bg-amber-100 text-amber-900 dark:bg-amber-950 dark:text-amber-200',
+    icon: 'text-amber-600 dark:text-amber-400',
+  },
+  restaurant: {
+    chip: 'bg-rose-100 text-rose-900 dark:bg-rose-950 dark:text-rose-200',
+    icon: 'text-rose-600 dark:text-rose-400',
+  },
+  museum: {
+    chip: 'bg-violet-100 text-violet-900 dark:bg-violet-950 dark:text-violet-200',
+    icon: 'text-violet-600 dark:text-violet-400',
+  },
+  viewpoint: {
+    chip: 'bg-sky-100 text-sky-900 dark:bg-sky-950 dark:text-sky-200',
+    icon: 'text-sky-600 dark:text-sky-400',
+  },
+  beach: {
+    chip: 'bg-cyan-100 text-cyan-900 dark:bg-cyan-950 dark:text-cyan-200',
+    icon: 'text-cyan-600 dark:text-cyan-400',
+  },
 };
 
 export function CategoryToggles({ value, onChange, className }: Props) {

apps/web/src/components/controls/ThemeToggle.tsx

@@ -0,0 +1,19 @@
+'use client';
+
+import { Moon, Sun } from 'lucide-react';
+import type { Theme } from '@/lib/hooks/useTheme';
+
+export function ThemeToggle({ theme, onToggle }: { theme: Theme; onToggle: () => void }) {
+  const next = theme === 'dark' ? 'light' : 'dark';
+  return (
+    <button
+      type="button"
+      onClick={onToggle}
+      aria-label={`Switch to ${next} theme`}
+      title={`Switch to ${next} theme`}
+      className="pointer-events-auto flex h-9 w-9 items-center justify-center rounded-xl bg-background/95 text-foreground shadow-md ring-1 ring-border backdrop-blur transition-colors hover:bg-accent"
+    >
+      {theme === 'dark' ? <Sun className="h-4 w-4" aria-hidden /> : <Moon className="h-4 w-4" aria-hidden />}
+    </button>
+  );
+}

apps/web/src/components/legend/BandLegend.tsx

@@ -3,9 +3,9 @@
 import { TIME_BANDS_MIN } from '@ilsochrone/providers';
 
 /**
- * Composite swatches of the graded #F97316 band stack over the basemap
- * (validated monotonic ramp; keep in sync with BAND_FILL_OPACITY in
- * IlsochroneMap).
+ * Composite swatches of the graded #F97316 band stack over each basemap
+ * (validated monotonic ramps; keep in sync with BAND_FILL_OPACITY /
+ * DARK_BAND_FILL_OPACITY in IlsochroneMap).
  */
 const SWATCHES: Record<number, string> = {
   5: '#F5BE98',
@@ -15,7 +15,22 @@ const SWATCHES: Record<number, string> = {
   30: '#F2EAE5',
 };
 
-export function BandLegend({ selectedMinutes }: { selectedMinutes: number }) {
+const DARK_SWATCHES: Record<number, string> = {
+  5: '#874619',
+  10: '#663919',
+  15: '#4D2F1A',
+  20: '#39271A',
+  30: '#2B221B',
+};
+
+export function BandLegend({
+  selectedMinutes,
+  theme = 'light',
+}: {
+  selectedMinutes: number;
+  theme?: 'light' | 'dark';
+}) {
+  const swatches = theme === 'dark' ? DARK_SWATCHES : SWATCHES;
   const active = TIME_BANDS_MIN.filter((m) => m <= selectedMinutes);
   return (
     <div className="pointer-events-none flex items-center gap-2 rounded-xl bg-background/95 px-3 py-2 text-xs shadow-md ring-1 ring-border backdrop-blur">
@@ -26,7 +41,7 @@ export function BandLegend({ selectedMinutes }: { selectedMinutes: number }) {
         aria-label={`Bands from 5 to ${selectedMinutes} minutes`}
       >
         {active.map((m) => (
-          <span key={m} className="h-3 w-6" style={{ backgroundColor: SWATCHES[m] }} title={`${m} min`} />
+          <span key={m} className="h-3 w-6" style={{ backgroundColor: swatches[m] }} title={`${m} min`} />
         ))}
       </div>
       <span className="tabular-nums text-muted-foreground">5–{selectedMinutes} min</span>

apps/web/src/components/map/IlsochroneMap.tsx

@@ -29,9 +29,9 @@ import {
 
 /**
  * Graded per-band fill opacity (bands nest, so zones stack every band >= m):
- * inner zones composite to a deep amber core (~0.34) fading to a pale peach
- * edge (0.04). Legend swatches in BandLegend are the computed composites —
- * keep the two in sync.
+ * inner zones composite to a deep amber core fading to a pale edge. Dark mode
+ * needs higher alphas for the same perceived warmth over the dark basemap.
+ * Legend swatches in BandLegend are the computed composites — keep in sync.
  */
 const BAND_FILL_OPACITY: Record<number, number> = {
   5: 0.18,
@@ -41,6 +41,14 @@ const BAND_FILL_OPACITY: Record<number, number> = {
   30: 0.045,
 };
 
+const DARK_BAND_FILL_OPACITY: Record<number, number> = {
+  5: 0.22,
+  10: 0.15,
+  15: 0.1,
+  20: 0.07,
+  30: 0.055,
+};
+
 interface Props {
   tileStyle: TileStyle;
   viewState: { longitude: number; latitude: number; zoom: number };
@@ -52,6 +60,8 @@ interface Props {
   selectedMinutes: number;
   /** Shows a soft pulsing halo on the origin pin while bands are loading. */
   originLoading?: boolean;
+  /** Adjusts band paint (seams/ring/fill alphas) for the dark basemap. */
+  theme?: 'light' | 'dark';
   /** Optional destination pin + popup content (e.g. NavigateTo card). */
   destination?: { lng: number; lat: number; popup: React.ReactNode };
   /**
@@ -84,6 +94,7 @@ export function IlsochroneMap({
   bands,
   selectedMinutes,
   originLoading,
+  theme = 'light',
   destination,
   onPickDestination,
   onMapBackgroundClick,
@@ -156,7 +167,11 @@ export function IlsochroneMap({
               type="fill"
               filter={['==', ['get', 'minutes'], m]}
               layout={{ visibility: m <= selectedMinutes ? 'visible' : 'none' }}
-              paint={{ 'fill-color': '#f97316', 'fill-opacity': BAND_FILL_OPACITY[m] ?? 0.05 }}
+              paint={{
+                'fill-color': '#f97316',
+                'fill-opacity':
+                  (theme === 'dark' ? DARK_BAND_FILL_OPACITY[m] : BAND_FILL_OPACITY[m]) ?? 0.05,
+              }}
             />
           ))}
           {TIME_BANDS_MIN.map((m) => (
@@ -168,8 +183,14 @@ export function IlsochroneMap({
               layout={{ visibility: m <= selectedMinutes ? 'visible' : 'none' }}
               paint={
                 m === selectedMinutes
-                  ? { 'line-color': '#c2410c', 'line-width': 3, 'line-opacity': 0.9 }
-                  : { 'line-color': '#ffffff', 'line-width': 1.2, 'line-opacity': 0.95 }
+                  ? {
+                      'line-color': theme === 'dark' ? '#fb923c' : '#c2410c',
+                      'line-width': 3,
+                      'line-opacity': 0.9,
+                    }
+                  : theme === 'dark'
+                    ? { 'line-color': '#1c1917', 'line-width': 1.2, 'line-opacity': 0.55 }
+                    : { 'line-color': '#ffffff', 'line-width': 1.2, 'line-opacity': 0.95 }
               }
             />
           ))}

apps/web/src/lib/hooks/useTheme.ts

@@ -0,0 +1,43 @@
+'use client';
+
+import { useCallback, useEffect, useState } from 'react';
+
+const STORAGE_KEY = 'ilso.theme';
+
+export type Theme = 'light' | 'dark';
+
+function systemTheme(): Theme {
+  return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+}
+
+/**
+ * System preference by default; an explicit toggle overrides it and persists.
+ * Applies `data-theme` on <html> (Tailwind darkMode selector + globals.css).
+ */
+export function useTheme(): { theme: Theme; toggle: () => void } {
+  const [theme, setTheme] = useState<Theme>('light');
+
+  useEffect(() => {
+    const stored = localStorage.getItem(STORAGE_KEY) as Theme | null;
+    setTheme(stored ?? systemTheme());
+    if (stored) return; // explicit choice: stop following the OS
+    const mql = window.matchMedia('(prefers-color-scheme: dark)');
+    const onChange = () => setTheme(systemTheme());
+    mql.addEventListener('change', onChange);
+    return () => mql.removeEventListener('change', onChange);
+  }, []);
+
+  useEffect(() => {
+    document.documentElement.setAttribute('data-theme', theme);
+  }, [theme]);
+
+  const toggle = useCallback(() => {
+    setTheme((t) => {
+      const next: Theme = t === 'dark' ? 'light' : 'dark';
+      localStorage.setItem(STORAGE_KEY, next);
+      return next;
+    });
+  }, []);
+
+  return { theme, toggle };
+}

docs/superpowers/specs/2026-07-19-ui-elevation-design.md

@@ -136,6 +136,9 @@ Testing:
 
 ## 8. Non-goals (this round)
 
-Dark mode (tokens ready, not shipped) · POI clustering · suggested-places
+~~Dark mode~~ (shipped 2026-07-19-c: system-preference default + persisted
+sun/moon toggle; warm near-black tokens; alidade_smooth_dark basemap; graded
+dark band alphas 0.22/0.15/0.10/0.07/0.055 with validated monotonic legend
+swatches; dark category-chip variants) · POI clustering · suggested-places
 panel (T-17) · browser-side engine computation · custom basemap style ·
 cycling/transit UI enablement.