echo6-docs/docs/navi/themes.md

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:

// 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

{
  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):

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:

fontImports: [
  'https://fonts.googleapis.com/css2?family=Orbitron&display=swap',
  'https://fonts.googleapis.com/css2?family=Share+Tech+Mono&display=swap',
]

Injected as 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()