auto: docs sync 2026-05-02T00:00:04+00:00

Files changed: docs/navi/cc-rules.md docs/navi/deployment.md docs/navi/themes.md

docs/navi/themes.md

@@ -0,0 +1,115 @@
+# Navi Theme System
+
+## Architecture
+
+**Registry:** `src/themes/registry.js`  
+Central source for theme metadata, overlay config, UI CSS vars, and satellite adjustments.
+
+## Critical: namedTheme Import
+
+> **NEVER re-export namedTheme through registry.js or any other module.**
+
+namedTheme must be imported **directly** from protomaps-themes-base in MapView.jsx:
+
+```javascript
+// CORRECT
+import { layers, namedTheme } from 'protomaps-themes-base'
+import { getTheme, getThemeSprite, getOverlayConfig } from '../themes/registry'
+
+function buildStyle(themeName) {
+  const theme = getTheme(themeName)
+  const colors = theme.colors || namedTheme(themeName)  // direct import for built-ins
+  return {
+    // ...
+    layers: layers('protomaps', colors, { lang: 'en' }),
+  }
+}
+```
+
+**Why:** Vite's bundling of namedTheme through a re-export breaks MapLibre's Web Worker, causing silent GeoJSON rendering failure (routes, boundaries, measure tool all invisible, "f is not defined" error in worker).
+
+## Theme Config Shape
+
+```javascript
+{
+  id: 'dark',              // unique identifier
+  name: 'Dark',            // display name
+  dark: true,              // affects overlay styling, sprite fallback
+  swatch: ['#1c1917', '#7a9a6b', '#b8a88a'],  // theme picker preview
+  fontImports: [],         // Google Font URLs (empty = system fonts)
+  colors: null,            // null = built-in, object = custom theme colors
+  satellite: null,         // raster adjustments when satellite active
+  overlay: { ... },        // per-layer styling for overlays
+  ui: { ... },             // 32 CSS custom properties
+}
+```
+
+## UI CSS Variables
+
+Applied by applyThemeUI() via document.documentElement.style.setProperty():
+
+- Backgrounds: --bg-base, --bg-raised, --bg-overlay, --bg-input, --bg-inset, --bg-muted
+- Text: --text-primary, --text-secondary, --text-tertiary, --text-inverse
+- Borders: --border, --border-subtle
+- Accent: --accent, --accent-hover, --accent-muted
+- Pins: --pin-origin, --pin-destination, --pin-intermediate, --pin-stroke
+- Status: --status-success, --status-warning, --status-danger, --success, --warning, --warning-muted
+- Fonts: --font-sans, --font-mono, --font-heading
+- Shadows: --shadow, --shadow-lg
+
+## Overlay Config
+
+Read via getOverlayConfig(themeId, layerKey) with spread-defaults fallback:
+
+- hillshade: exaggeration, illuminationDirection, shadowColor, highlightColor
+- contours: colors, opacities, widths for minor/intermediate/index lines + labels
+- publicLands: fill/outline colors per agency (NPS, USFS, BLM, etc.)
+- usfsTrails: road/trail colors by use type (motorized, bicycle, hiker)
+- blmTrails: route colors by vehicle class (4WD, ATV, non-mechanized)
+
+## Satellite Raster Adjustments
+
+Neutral defaults (no adjustment):
+
+```javascript
+satellite: {
+  opacity: 1.0,
+  brightnessMin: 0.0,
+  brightnessMax: 1.0,
+  contrast: 0.0,      // MapLibre uses -1 to 1 range
+  saturation: 0.0,    // MapLibre uses -1 to 1 range
+  hueRotate: 0,
+}
+```
+
+## Font Support
+
+fontImports array of Google Font URLs, managed on theme switch:
+
+```javascript
+fontImports: [
+  'https://fonts.googleapis.com/css2?family=Orbitron&display=swap',
+  'https://fonts.googleapis.com/css2?family=Share+Tech+Mono&display=swap',
+]
+```
+
+Injected as <link data-theme-font> tags, removed on theme switch.
+
+## Theme Picker
+
+ThemePicker.jsx — swatch popover in header, reads themeList() for [{id, name, dark, swatch}].
+
+## Current Themes
+
+| ID | Name | Type | Description |
+|----|------|------|-------------|
+| light | Light | built-in | Default light theme |
+| dark | Dark | built-in | Default dark theme |
+| clean | Clean | custom | Google Maps-inspired, utilitarian |
+| cyberpunk | Cyberpunk | custom | Neon palette, Orbitron + Share Tech Mono fonts |
+
+## Adding a New Theme
+
+1. Create src/themes/{name}.js with full theme config
+2. Import and register in registry.js themes object
+3. Theme auto-appears in picker via themeList()