115 lines
3.8 KiB
Markdown
115 lines
3.8 KiB
Markdown
|
# 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()
|