Themes

Themes provide a consistent color palette for presentations built with the Builder API. Two themes ship with @elucim/dsl — darkTheme and lightTheme.

Usage

import { presentation, darkTheme, lightTheme } from '@elucim/dsl';

const doc = presentation('My Talk', darkTheme).slide('Intro', s => {
  s.title('Hello');
}).build();

The theme is passed to the SlideBuilder, which uses it for default colors on titles, subtitles, boxes, arrows, and other elements.

Theme Properties

Property	Type	Description
`background`	`string`	Slide background color
`title`	`string`	Title text color
`subtitle`	`string`	Subtitle / secondary text color
`primary`	`string`	Primary accent (arrows, highlights)
`secondary`	`string`	Secondary accent
`tertiary`	`string`	Third accent
`muted`	`string`	Muted / annotation color
`foreground`	`string`	Default body text color
`boxFill`	`string`	Fill color for diagram boxes
`boxStroke`	`string`	Stroke color for diagram boxes
`success`	`string`	Positive / success color
`warning`	`string`	Warning / highlight color
`error`	`string`	Error / negative color
`palette`	`string[]`	8-color sequential palette for data vis and accents

Color Values

Property	Dark Theme	Light Theme
`background`	`#0a0a1e`	`#f8fafc`
`title`	`#e0e7ff`	`#1e293b`
`subtitle`	`#94a3b8`	`#64748b`
`primary`	`#4fc3f7`	`#2563eb`
`secondary`	`#a78bfa`	`#7c3aed`
`tertiary`	`#f472b6`	`#db2777`
`muted`	`#64748b`	`#94a3b8`
`foreground`	`#c8d6e5`	`#334155`
`boxFill`	`rgba(79,195,247,0.12)`	`rgba(37,99,235,0.08)`
`boxStroke`	`#4fc3f7`	`#2563eb`
`success`	`#34d399`	`#16a34a`
`warning`	`#fbbf24`	`#d97706`
`error`	`#f87171`	`#dc2626`

Palette Colors

Index	Dark Theme	Light Theme
0	`#4fc3f7`	`#2563eb`
1	`#a78bfa`	`#7c3aed`
2	`#f472b6`	`#db2777`
3	`#34d399`	`#16a34a`
4	`#fbbf24`	`#d97706`
5	`#fb923c`	`#ea580c`
6	`#6366f1`	`#4f46e5`
7	`#22d3ee`	`#0891b2`

Custom Themes

Create a custom theme by implementing the Theme interface:

import { presentation } from '@elucim/dsl';
import type { Theme } from '@elucim/dsl';

const solarized: Theme = {
  background: '#002b36',
  title: '#fdf6e3',
  subtitle: '#93a1a1',
  primary: '#268bd2',
  secondary: '#2aa198',
  tertiary: '#d33682',
  muted: '#586e75',
  foreground: '#eee8d5',
  boxFill: 'rgba(38,139,210,0.15)',
  boxStroke: '#268bd2',
  success: '#859900',
  warning: '#b58900',
  error: '#dc322f',
  palette: [
    '#268bd2', '#2aa198', '#d33682', '#859900',
    '#b58900', '#cb4b16', '#6c71c4', '#93a1a1',
  ],
};

const doc = presentation('Solarized Talk', solarized)
  .slide('Hello', s => s.title('Custom colors!'))
  .build();

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": "1.0",
  "root": {
    "type": "player",
    "preset": "card",
    "durationInFrames": 60,
    "background": "$background",
    "children": [
      { "type": "circle", "cx": 320, "cy": 180, "r": 80, "stroke": "$accent", "strokeWidth": 3 },
      { "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.

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