Themes

Themes provide a consistent token palette for rendered Elucim documents. Use semantic color tokens in JSON/YAML and pass an ElucimTheme or colorScheme to DslRenderer.

Usage

import { DslRenderer } from '@elucim/dsl';

<DslRenderer dsl={doc} colorScheme="dark" theme={{ accent: '#4fc3f7' }} />

Documents reference semantic colors with $token values such as $accent, $foreground, and $surface. The renderer resolves those tokens at render time.

Theme Properties

Property	Type	Description
background	string	Scene background color
foreground	string	Default text color
primary	string	Primary brand color
accent	string	Primary visual accent
secondary	string	Secondary accent
tertiary	string	Third accent
muted	string	Muted / annotation color
surface	string	Card/panel fill color
border	string	Card/panel stroke color
success	string	Positive / success color
warning	string	Warning / highlight color
error	string	Error / negative color

Color Values

Property	Dark Theme	Light Theme
background	#0a0a1e	#f8fafc
primary	#4fc3f7	#2563eb
secondary	#a78bfa	#7c3aed
tertiary	#f472b6	#db2777
muted	#64748b	#94a3b8
foreground	#c8d6e5	#334155
surface	#1e293b	#ffffff
border	#334155	#cbd5e1
success	#34d399	#16a34a
warning	#fbbf24	#d97706
error	#f87171	#dc2626

Custom Themes

Create a custom theme by implementing the Theme interface:

import type { ElucimTheme } from '@elucim/dsl';

const solarized: ElucimTheme = {
  background: '#002b36',
  foreground: '#fdf6e3',
  primary: '#268bd2',
  accent: '#2aa198',
  surface: 'rgba(38,139,210,0.15)',
};

Tip

When creating a custom theme, start with the tokens your document actually uses. Any missing token falls back to the selected light/dark color scheme.

Semantic Color Tokens

Any color field in a DSL document (fill, stroke, color, background, axisColor, labelColor, barColor, nodeColor, edgeColor, etc.) accepts $token syntax that resolves to CSS custom properties at render time.

{
  "type": "circle",
  "cx": 200, "cy": 200, "r": 80,
  "stroke": "$accent",
  "fill": "$surface"
}

At render time:

• "$accent" → var(--elucim-accent, #4fc3f7)
• "$surface" → var(--elucim-surface, #1e293b)
• "#ff0000" → "#ff0000" (literal colors are unchanged)

This lets a single DSL document adapt to any host theme without modification.

Standard Tokens

Token	CSS Variable	Default Fallback
$foreground	--elucim-foreground	#e0e0e0
$background	--elucim-background	#0f172a
$accent	--elucim-accent	#4fc3f7
$muted	--elucim-muted	#64748b
$surface	--elucim-surface	#1e293b
$border	--elucim-border	#334155
$primary	--elucim-primary	#4fc3f7
$secondary	--elucim-secondary	#a78bfa
$tertiary	--elucim-tertiary	#f472b6
$success	--elucim-success	#34d399
$warning	--elucim-warning	#fbbf24
$error	--elucim-error	#f87171

Custom tokens also work: "$brand" → var(--elucim-brand) (no default fallback).

Providing Token Values

Use the theme prop on DslRenderer to set token values from the host:

<DslRenderer
  dsl={doc}
  theme={{
    foreground: '#1e293b',
    background: '#f8fafc',
    accent: '#2563eb',
  }}
/>

Or set them with plain CSS on any ancestor element:

.my-container {
  --elucim-foreground: #1e293b;
  --elucim-background: #f8fafc;
  --elucim-accent: #2563eb;
}

Example: Theme-Adaptive Scene

{
  "version": "2.0",
  "scene": {
    "type": "player",
    "preset": "card",
    "background": "$background",
    "children": ["orb", "label"]
  },
  "elements": {
    "orb": {
      "id": "orb",
      "type": "circle",
      "props": { "type": "circle", "cx": 320, "cy": 180, "r": 80, "stroke": "$accent", "strokeWidth": 3 }
    },
    "label": {
      "id": "label",
      "type": "text",
      "props": { "type": "text", "content": "Adaptive!", "x": 320, "y": 180, "fill": "$foreground", "fontSize": 24, "textAnchor": "middle" }
    }
  }
}

This scene renders with blue accents on a dark background by default, but automatically adapts if the host provides different --elucim-* values.

Note

Semantic tokens ($accent) are resolved at render time via CSS, so the JSON/YAML document stays portable across host applications and themes.

Core Theme Utilities

The @elucim/core package exports theme utilities used by both DslRenderer and ElucimEditor:

import {
  type ElucimTheme,
  DARK_THEME,
  LIGHT_THEME,
  SEMANTIC_TOKENS,
  resolveColor,
  themeToVars,
} from '@elucim/core';

ElucimTheme

The unified theme type accepted by both DslRenderer and ElucimEditor. All fields are optional — only set the tokens you want to override:

interface ElucimTheme {
  foreground?: string;
  background?: string;
  title?: string;
  subtitle?: string;
  muted?: string;
  primary?: string;
  secondary?: string;
  tertiary?: string;
  accent?: string;
  surface?: string;
  border?: string;
  success?: string;
  warning?: string;
  error?: string;
}

Values can be hex colors, named colors, or CSS var() references (e.g. "var(--my-brand-color)").

DARK_THEME / LIGHT_THEME

Pre-built theme presets with sensible defaults:

<DslRenderer dsl={doc} theme={DARK_THEME} colorScheme="dark" />
<DslRenderer dsl={doc} theme={LIGHT_THEME} colorScheme="light" />

themeToVars()

Converts an ElucimTheme into CSS custom property declarations (--elucim-{key}: value):

const vars = themeToVars(myTheme);
// { '--elucim-foreground': '#e0e0e0', '--elucim-background': '#1a1a2e', ... }

resolveColor()

Resolves $token syntax to CSS var() references with fallbacks:

resolveColor('$accent');    // → 'var(--elucim-accent, #4fc3f7)'
resolveColor('#ff0000');    // → '#ff0000' (unchanged)
resolveColor('\\$literal'); // → '$literal' (escaped)

SEMANTIC_TOKENS

Registry of all standard token names and their default fallback values:

SEMANTIC_TOKENS.foreground  // '#e0e0e0'
SEMANTIC_TOKENS.accent      // '#4fc3f7'
SEMANTIC_TOKENS.surface     // '#1e293b'

Editor Design Tokens

The visual editor uses its own set of CSS custom properties for chrome styling. These are defined in EDITOR_TOKENS (dark) and EDITOR_TOKENS_LIGHT and can be overridden via the editorTheme prop.

Sizing & Spacing

Token	Default	Description
--elucim-editor-input-height	20px	Standard input field height
--elucim-editor-font-xs	9px	Extra-small font (labels, buttons)
--elucim-editor-font-sm	10px	Small font (field values)
--elucim-editor-radius-sm	3px	Small border radius
--elucim-editor-space-xs	2px	Extra-small spacing
--elucim-editor-space-sm	4px	Small spacing (gaps)

Shadows

Token	Dark	Light
--elucim-editor-shadow-panel	0 4px 24px rgba(0,0,0,0.4)	0 4px 24px rgba(0,0,0,0.15)
--elucim-editor-shadow-dropdown	0 4px 12px rgba(0,0,0,0.3)	0 4px 12px rgba(0,0,0,0.1)

Motion

Token	Default	Description
--elucim-editor-duration-fast	150ms	Quick transitions (hover, focus)
--elucim-editor-duration-normal	250ms	Standard transitions (panel open/close)
--elucim-editor-easing-default	cubic-bezier(0.4, 0, 0.2, 1)	Default easing curve

Tip

Override any of these via the editorTheme prop on ElucimEditor to customize the editor chrome without changing content theming.