@diginestai/theme — Theme System
@diginestai/theme defines the DigiNest Maps design token system: the SpatialTheme TypeScript interface, lightTheme and darkTheme presets, and the applyTheme function that injects all tokens as CSS custom properties.
Installation
bash
pnpm add @diginestai/themeQuick Start
tsx
import { SpatialProvider, SpatialMap } from '@diginestai/core';
import { darkTheme } from '@diginestai/theme';
<SpatialProvider>
<SpatialMap theme={darkTheme} />
</SpatialProvider>Or apply a custom theme at runtime:
tsx
import { applyTheme, lightTheme } from '@diginestai/theme';
const myTheme = {
...lightTheme,
colors: { ...lightTheme.colors, primary: '#ff5500' },
};
applyTheme(myTheme); // writes CSS vars to document.documentElementSpatialTheme Interface
SpatialTheme is a public alias for the internal Theme type.
typescript
interface SpatialTheme {
mode: 'light' | 'dark';
colors: ThemeColors;
map: ThemeMap;
controls: ThemeControls;
font: ThemeFont;
radius: ThemeRadius;
motion: ThemeMotion;
heatmap: ThemeHeatmap;
sensorDefaults: Record<SensorKind, string>;
}ThemeColors
| Field | Type | Description |
|---|---|---|
primary | string | Brand primary colour (hex). |
primaryReshape | string | Darker primary for hover/active states. |
secondary | string | Secondary accent colour. |
accent | string | Highlight / call-to-action colour. |
surface | string | Card and panel background. |
background | string | Page background. |
text | string | Body text colour. |
border | string | Divider and outline colour. |
alarm | string | Error / critical alert colour. |
warning | string | Warning alert colour. |
ok | string | Success / healthy state colour. |
nodata | string | Placeholder colour for missing data. |
ThemeMap
| Field | Type | Description |
|---|---|---|
wallFill | string | IMDF wall polygon fill colour. |
floorFill | string | IMDF floor/unit polygon fill colour. |
doorLine | string | IMDF door line stroke colour. |
amenityIcon | string | Amenity symbol fill colour. |
Other Sub-Interfaces
| Interface | Fields | Description |
|---|---|---|
ThemeControls | floorSwitcherBg, toolbarBg, infoCardBg | UI control backgrounds. |
ThemeFont | family, sizeBase | Font family string and base size in px. |
ThemeRadius | sm, md, lg | Border radius values in px. |
ThemeMotion | duration, easing, durationMs | Animation duration (ms) and CSS easing string. |
ThemeHeatmap | palette, opacity | Heatmap colour ramp (string[]) and global opacity (0–1). |
SensorKind values: temperature · humidity · co2 · voc · pressure · peopleCounter.
applyTheme(theme, root?)
Writes all theme tokens as CSS custom properties on the given element (defaults to document.documentElement). Throws descriptively if required fields (heatmap.opacity, motion.durationMs, sensorDefaults) are missing.
typescript
applyTheme(myTheme); // apply to <html>
applyTheme(myTheme, containerRef.current); // apply to a specific elementCSS Custom Properties Reference
All properties are written by applyTheme. Consume them in custom CSS or component styles.
Colours
| Custom Property | Theme Source |
|---|---|
--spatial-primary | colors.primary |
--spatial-primary-reshape | colors.primaryReshape |
--spatial-secondary | colors.secondary |
--spatial-accent | colors.accent |
--spatial-surface | colors.surface |
--spatial-bg | colors.background |
--spatial-background | colors.background (legacy alias) |
--spatial-text | colors.text |
--spatial-border | colors.border |
--spatial-alarm | colors.alarm |
--spatial-warning | colors.warning |
--spatial-ok | colors.ok |
--spatial-nodata | colors.nodata |
Map Layer Colours
| Custom Property | Theme Source |
|---|---|
--spatial-wall-fill | map.wallFill |
--spatial-floor-fill | map.floorFill |
--spatial-door-line | map.doorLine |
--spatial-amenity-icon | map.amenityIcon |
UI Controls
| Custom Property | Theme Source |
|---|---|
--spatial-floor-switcher-bg | controls.floorSwitcherBg |
--spatial-toolbar-bg | controls.toolbarBg |
--spatial-info-card-bg | controls.infoCardBg |
Typography
| Custom Property | Theme Source |
|---|---|
--spatial-font-family | font.family |
--spatial-font-size-base | font.sizeBase (px) |
Spacing & Shape
| Custom Property | Theme Source |
|---|---|
--spatial-radius-sm | radius.sm (px) |
--spatial-radius-md | radius.md (px) |
--spatial-radius-lg | radius.lg (px) |
Motion
| Custom Property | Theme Source |
|---|---|
--spatial-motion-duration | motion.duration (ms) |
--spatial-motion-easing | motion.easing |
--spatial-motion-duration-ms | motion.durationMs (ms) |
Heatmap
| Custom Property | Theme Source |
|---|---|
--spatial-heatmap-opacity | heatmap.opacity |
Sensor Defaults
Sensor colours follow the pattern --spatial-sensor-{kind} where {kind} is the camelCase sensor name converted to kebab-case:
| Custom Property | Sensor |
|---|---|
--spatial-sensor-temperature | sensorDefaults.temperature |
--spatial-sensor-humidity | sensorDefaults.humidity |
--spatial-sensor-co2 | sensorDefaults.co2 |
--spatial-sensor-voc | sensorDefaults.voc |
--spatial-sensor-pressure | sensorDefaults.pressure |
--spatial-sensor-people-counter | sensorDefaults.peopleCounter |
Bundled Presets
Both presets satisfy the full SpatialTheme interface and pass applyTheme validation.
typescript
import { lightTheme, darkTheme } from '@diginestai/theme';| Preset | mode | Primary | Background | Text |
|---|---|---|---|---|
lightTheme | 'light' | #2393d4 | #ffffff | #1a1a2e |
darkTheme | 'dark' | #38b2f5 | #0f172a | #f1f5f9 |