echo6-docs/vault/docs/navi/themes.md

---
title: Navi Theme System
type: reference
tags:
  - auth
aliases: []
related:
  - [[cc-rules]]
  - [[deployment]]
  - [[searxng]]
  - [[echo6-landing-page-data-export]]
  - [[pipeline-patterns]]
updated: 2026-06-18
---
# 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()