@elucim/dsl 0.5.0 → 0.7.0

package/README.md

@@ -59,9 +59,10 @@ Validates the DSL document and renders it as React components. If validation fai
 - `dsl: ElucimDocument` — The DSL document to render
 - `className?: string` — CSS class for the wrapper div
 - `style?: CSSProperties` — Inline styles for the wrapper div
-- `theme?: 'light' | 'dark'` — Override the color theme
-- `poster?: number` — Frame number to display as a static poster before playback
-- `onError?: (errors: ValidationError[]) => void` — Callback for validation errors
+- `theme?: ElucimTheme` — Custom color tokens as CSS custom properties (e.g. `{ foreground: '#fff', background: '#000' }`)
+- `colorScheme?: 'light' | 'dark' | 'auto'` — Inject light/dark theme variables automatically. `'auto'` detects from `prefers-color-scheme`. DSL docs using `$token` syntax adapt automatically.
+- `poster?: 'first' | 'last' | number` — Render a static frame instead of interactive player
+- `onError?: (errors: Array<{ path: string; message: string }>) => void` — Callback for validation errors
 - `ref?: React.Ref<DslRendererRef>` — Imperative handle for programmatic control
 
 ### `validate(doc: unknown): ValidationResult`
@@ -230,6 +231,59 @@ Used in `functionPlot.fn` and `vectorField.fn`. Safe evaluation — no `eval()`.
 - `"[-y, x]"` — Rotation vector field
 - `"[sin(y), cos(x)]"` — Wave vector field
 
+## Semantic Color Tokens
+
+Use `$token` syntax in your DSL JSON to create theme-adaptive visualizations:
+
+```json
+{
+  "type": "player",
+  "background": "$background",
+  "children": [
+    { "type": "text", "x": 400, "y": 300, "content": "Hello", "fill": "$foreground" },
+    { "type": "circle", "cx": 200, "cy": 200, "r": 50, "stroke": "$accent" }
+  ]
+}
+```
+
+**Available tokens:**
+
+| Token | Dark default | Light default | Usage |
+|-------|-------------|---------------|-------|
+| `$foreground` | `#c8d6e5` | `#334155` | Body text |
+| `$background` | `#0a0a1e` | `#f8fafc` | Slide/scene background |
+| `$title` | `#e0e7ff` | `#1e293b` | Heading text (brighter than foreground) |
+| `$subtitle` | `#94a3b8` | `#64748b` | Secondary/subtitle text |
+| `$muted` | `#64748b` | `#94a3b8` | Annotations, faint text |
+| `$primary` | `#4fc3f7` | `#2563eb` | Primary accent |
+| `$secondary` | `#a78bfa` | `#7c3aed` | Secondary accent |
+| `$tertiary` | `#f472b6` | `#db2777` | Tertiary accent |
+| `$success` | `#34d399` | `#16a34a` | Positive / success |
+| `$warning` | `#fbbf24` | `#d97706` | Warning / highlight |
+| `$error` | `#f87171` | `#dc2626` | Error / negative |
+| `$surface` | `#1e293b` | `#f8fafc` | Panel backgrounds |
+| `$border` | `#334155` | `#334155` | Borders, grid lines |
+| `$accent` | `#4fc3f7` | `#2563eb` | Alias for primary |
+
+Tokens resolve to CSS custom properties (`$background` → `var(--elucim-background, #0a0a1e)`). Pair with `colorScheme` to auto-adapt:
+
+```tsx
+<DslRenderer dsl={doc} colorScheme="auto" />
+```
+
+| colorScheme | Behavior |
+|-------------|----------|
+| `'dark'` | Injects dark palette variables |
+| `'light'` | Injects light palette variables |
+| `'auto'` | Detects `prefers-color-scheme` media query |
+| _(omitted)_ | Tokens fall back to built-in defaults (dark) |
+
+You can also override individual tokens with the `theme` prop:
+
+```tsx
+<DslRenderer dsl={doc} colorScheme="auto" theme={{ accent: '#ff6600' }} />
+```
+
 ## Examples
 
 See the [`examples/`](./examples/) directory:
@@ -281,6 +335,7 @@ const doc = presentation(darkTheme)
 ## Related
 
 - **[@elucim/core](https://www.npmjs.com/package/@elucim/core)** — The React rendering engine (peer dependency)
+- **[@elucim/editor](https://www.npmjs.com/package/@elucim/editor)** — Visual canvas editor for Elucim animations
 - **[Elucim Docs](https://elucim.com)** — Full docs with live interactive examples
 
 ## License

package/dist/index.d.ts

@@ -173,6 +173,17 @@ export declare interface DslRendererProps {
     style?: default_2.CSSProperties;
     /** Inject theme colors as CSS custom properties (e.g. --elucim-foreground) */
     theme?: ElucimTheme;
+    /**
+     * Color scheme for semantic token resolution.
+     * - `'dark'` — inject dark theme CSS variables
+     * - `'light'` — inject light theme CSS variables
+     * - `'auto'` — detect from `prefers-color-scheme` media query
+     *
+     * DSL documents using `$token` syntax (e.g. `$background`, `$foreground`)
+     * will automatically adapt. Explicit `theme` values take priority over
+     * colorScheme defaults.
+     */
+    colorScheme?: 'light' | 'dark' | 'auto';
     /** Render a static frame instead of interactive player. 'first' | 'last' | frame number */
     poster?: 'first' | 'last' | number;
     /** Callback fired when DSL validation fails */