@depths/waves 0.2.0 → 0.5.0

package/README.md

@@ -1,4 +1,4 @@
-# @depths/waves (v0.2.0)
+# @depths/waves (v0.5.0)
 
 `@depths/waves` is a TypeScript-first library + CLI for rendering videos from a JSON "intermediate representation" (IR) using Remotion.
 
@@ -8,11 +8,25 @@ The intended workflow is:
 2. The IR is validated (schema + semantics + registry contracts).
 3. The IR is rendered to an output video file (MP4 by default) using Remotion.
 
-v0.2.0 adds a shadcn-like catalog of higher-level "composite" components and a hybrid IR that supports:
+v0.2.0 introduced a shadcn-like catalog of higher-level "composite" components and a hybrid IR that supports:
 
 - **Segments (recommended for agents):** sequential scenes with optional overlaps ("transitions")
 - **Timeline (escape hatch):** explicit timed nodes with overlaps allowed
 
+v0.4.0 focuses on **unified aesthetics control**:
+
+- **Theme tokens:** shadcn-ish design tokens (colors, typography, spacing, radii, shadows, motion) declared once at the video level
+- **Presets:** built-in theme presets for fast, consistent styling
+- **Token-only styling:** components reference token keys (no hardcoded styling constants in primitives or composites)
+- **Visual debugging workflow:** `waves stills` and `--debugBounds/--debugLabels` to inspect alignment issues without pixel tests
+
+v0.5.0 focuses on **robustness and performance**:
+
+- **Faster agent loops:** deterministic bundle caching (`.waves-cache/`) so repeated renders don't re-bundle
+- **Fail-fast assets:** local `/assets/...` references are checked before expensive renders
+- **Deterministic font loading:** theme fonts must load successfully or the render is cancelled
+- **Stricter transitions:** invalid transition types/props are rejected (no silent overlaps)
+
 ## Table of contents
 
 - [Concept (end-to-end)](#concept-end-to-end)
@@ -24,7 +38,7 @@ v0.2.0 adds a shadcn-like catalog of higher-level "composite" components and a h
   - [Rendering model](#rendering-model)
 - [Installation](#installation)
 - [CLI (agent workflow)](#cli-agent-workflow)
-- [IR v2.0 (authoring contract)](#ir-v20-authoring-contract)
+- [IR v3.0 (authoring contract)](#ir-v30-authoring-contract)
 - [Components (primitives + composites)](#components-primitives--composites)
 - [Examples (composition recipes)](#examples-composition-recipes)
 - [Library API (quickstart)](#library-api-quickstart)
@@ -62,7 +76,7 @@ At render time, Waves is "just React + Remotion". The strictness lives earlier (
 The codebase has a small number of core concepts:
 
 - **Video IR (`VideoIRSchema`)**: the JSON document format you author.
-  - v0.2.0 targets `version: "2.0"` only.
+- v0.4.0+ targets `version: "3.0"` only.
   - You author exactly one of `segments[]` (recommended) or `timeline[]` (escape hatch).
 - **Component Registry (`ComponentRegistry`)**: a map from string `type` -> React component + Zod props schema + metadata.
   - Only registered components can render.
@@ -99,7 +113,7 @@ Why the internal `Segment` wrapper exists:
 Overlap math:
 
 - Let segment `i` have duration `Di`.
-- Let overlap `Oi` be `segments[i].transitionToNext.durationInFrames` (only for segments that have a next segment).
+- Let overlap `Oi` (in frames) be `theme.motion.durationsInFrames[segments[i].transitionToNext.duration]` (only for segments that have a next segment).
 - Then the compiled start time is:
   - `start(0) = 0`
   - `start(i+1) = start(i) + Di - Oi`
@@ -178,9 +192,9 @@ For an agent that can execute terminal commands, the recommended flow is:
 1. `waves prompt --format json --out waves-prompt.json`
 2. Use `waves-prompt.json.systemPrompt` + `waves-prompt.json.schemas` + `waves-prompt.json.catalog` as the authoring contract for the model
 3. Have the model output a single JSON object (Video IR)
-4. Write that JSON to `video.v2.json`
-5. `waves validate --in video.v2.json` until it passes
-6. `waves render --in video.v2.json --out output.mp4 ...`
+4. Write that JSON to `video.v3.json`
+5. `waves validate --in video.v3.json` until it passes
+6. `waves render --in video.v3.json --out output.mp4 ...`
 
 ### 1) Get the prompt payload (system prompt + schemas + catalog)
 
@@ -214,7 +228,7 @@ If you register custom components at module import time, include them with repea
 ```bash
 npx waves prompt --format json --register ./src/register-waves-components.ts
 npx waves schema --kind components --register ./src/register-waves-components.ts
-npx waves validate --in ./video.v2.json --register ./src/register-waves-components.ts
+npx waves validate --in ./video.v3.json --register ./src/register-waves-components.ts
 ```
 
 Important notes on `--register`:
@@ -227,31 +241,31 @@ Important notes on `--register`:
 ### 2) Write IR JSON
 
 ```bash
-npx waves write-ir --template basic --pretty --out ./video.v2.json
+npx waves write-ir --template basic --pretty --out ./video.v3.json
 ```
 
 ### 3) Validate IR JSON
 
 ```bash
-npx waves validate --in ./video.v2.json
+npx waves validate --in ./video.v3.json
 ```
 
 Structured validation result:
 
 ```bash
-npx waves validate --in ./video.v2.json --format json
+npx waves validate --in ./video.v3.json --format json
 ```
 
 ### 4) Render MP4
 
 ```bash
-npx waves render --in ./video.v2.json --out ./output.mp4 --codec h264 --crf 28 --concurrency 1
+npx waves render --in ./video.v3.json --out ./output.mp4 --codec h264 --crf 28 --concurrency 1
 ```
 
 If your IR references `"/assets/..."` paths, pass `--publicDir` and ensure the files exist at `${publicDir}/assets/...`:
 
 ```bash
-npx waves render --in ./video.v2.json --out ./output.mp4 --publicDir ./public
+npx waves render --in ./video.v3.json --out ./output.mp4 --publicDir ./public
 ```
 
 ### Exit codes
@@ -273,7 +287,7 @@ Prints a short help text.
 
 #### `waves --version`
 
-Prints the package version (e.g. `0.2.0`).
+Prints the package version (e.g. `0.5.0`).
 
 #### `waves prompt`
 
@@ -336,21 +350,42 @@ npx waves catalog
 npx waves catalog --format json --pretty --out ./waves-catalog.json
 ```
 
+#### `waves themes`
+
+Lists built-in theme presets (or prints the full token object for a preset).
+
+Flags:
+
+- `--format text|json` (default `text`)
+- `--id <preset>` (optional; when set, prints the preset tokens instead of listing preset ids)
+- `--pretty` (json format only)
+- `--out <path>` (optional)
+
+Examples:
+
+```bash
+npx waves themes
+npx waves themes --format json --pretty --out ./waves-themes.json
+npx waves themes --id studio-dark --format json --pretty --out ./studio-dark.tokens.json
+```
+
 #### `waves write-ir`
 
-Writes a starter IR JSON file (always `version: "2.0"` segments mode).
+Writes a starter IR JSON file (always `version: "3.0"` segments mode).
 
 Flags:
 
 - `--template minimal|basic` (default `minimal`)
+- `--preset <id>` (optional; default `studio-dark`)
+- `--themeOverrides <path>` (optional; JSON theme override object merged over the preset)
 - `--pretty`
 - `--out <path>` (required)
 
 Examples:
 
 ```bash
-npx waves write-ir --template minimal --pretty --out ./video.v2.json
-npx waves write-ir --template basic --pretty --out ./examples/basic.v2.json
+npx waves write-ir --template minimal --pretty --out ./video.v3.json
+npx waves write-ir --template basic --pretty --out ./examples/basic.v3.json
 ```
 
 #### `waves validate`
@@ -362,6 +397,8 @@ Flags:
 - `--in <path>` (required)
 - `--format text|json` (default `text`)
 - `--pretty` (json format only)
+- `--preset <id>` (optional; overrides the IR theme preset id)
+- `--themeOverrides <path>` (optional; JSON theme override object merged over IR theme overrides)
 - `--register <module>` (repeatable)
 
 Behavior:
@@ -372,8 +409,8 @@ Behavior:
 Examples:
 
 ```bash
-npx waves validate --in ./video.v2.json
-npx waves validate --in ./video.v2.json --format json --pretty
+npx waves validate --in ./video.v3.json
+npx waves validate --in ./video.v3.json --format json --pretty
 ```
 
 #### `waves render`
@@ -388,19 +425,49 @@ Flags:
 - `--codec h264|h265|vp8|vp9` (optional; default `h264`)
 - `--crf <n>` (optional; forwarded to Remotion renderer)
 - `--concurrency <n|string>` (optional; forwarded to Remotion renderer)
+- `--preset <id>` (optional; overrides the IR theme preset id)
+- `--themeOverrides <path>` (optional; JSON theme override object merged over IR theme overrides)
+- `--debugBounds` (optional; draws debug outlines for every rendered node)
+- `--debugLabels` (optional; labels debug outlines with `type#id`)
 - `--register <module>` (repeatable)
 - `--pretty` (only affects the formatting of error JSON when render fails)
 
 Examples:
 
 ```bash
-npx waves render --in ./video.v2.json --out ./output.mp4 --codec h264 --crf 28 --concurrency 1
-npx waves render --in ./video.v2.json --out ./output.mp4 --publicDir ./public
+npx waves render --in ./video.v3.json --out ./output.mp4 --codec h264 --crf 28 --concurrency 1
+npx waves render --in ./video.v3.json --out ./output.mp4 --publicDir ./public
+npx waves render --in ./video.v3.json --out ./output.mp4 --publicDir ./public --debugBounds --debugLabels
+```
+
+#### `waves stills`
+
+Renders a set of still images (single frames) from an IR JSON file. This is the recommended way to iterate on alignment and overlays without re-rendering full MP4s.
+
+Flags:
+
+- `--in <path>` (required)
+- `--outDir <path>` (required)
+- `--frames <csv>` (required; e.g. `"0,30,60"`)
+- `--publicDir <path>` (optional; required if your IR uses `/assets/...` paths)
+- `--imageFormat png|jpeg|webp` (optional; default `png`)
+- `--scale <n>` (optional; default `1`)
+- `--jpegQuality <n>` (optional; default `90`; only used when `--imageFormat jpeg`)
+- `--preset <id>` (optional; overrides the IR theme preset id)
+- `--themeOverrides <path>` (optional; JSON theme override object merged over IR theme overrides)
+- `--debugBounds` / `--debugLabels` (same as `waves render`)
+- `--register <module>` (repeatable)
+
+Examples:
+
+```bash
+npx waves stills --in ./video.v3.json --outDir ./examples/_stills --frames "0,45,90" --publicDir ./public
+npx waves stills --in ./video.v3.json --outDir ./examples/_stills --frames "0,45,90" --publicDir ./public --debugBounds --debugLabels
 ```
 
-## IR v2.0 (authoring contract)
+## IR v3.0 (authoring contract)
 
-v0.2.0 targets `version: "2.0"` only.
+v0.4.0+ targets `version: "3.0"` only.
 
 ### Recommended: `segments[]` (high-level)
 
@@ -408,18 +475,19 @@ In segments mode, you provide sequential segments and Waves compiles them into a
 
 Key rules:
 
-- Segment overlap is controlled by `transitionToNext.durationInFrames`.
+- Segment overlap is controlled by `transitionToNext.duration` (a theme motion token key like `"fast"`, `"base"`, `"slow"`).
 - `transitionToNext` is only valid when there is a "next" segment (i.e. it is not allowed on the last segment).
 - The total video duration must match the compiled timeline end:
   - `video.durationInFrames = sum(segment.durationInFrames) - sum(overlap)`
-  - where `overlap = transitionToNext.durationInFrames` for each segment that has a next segment.
+  - where `overlap = theme.motion.durationsInFrames[transitionToNext.duration]` for each segment that has a next segment (after resolving the theme preset + overrides).
 
 Minimal example:
 
 ```json
 {
-  "version": "2.0",
+  "version": "3.0",
   "video": { "id": "main", "width": 1920, "height": 1080, "fps": 30, "durationInFrames": 60 },
+  "theme": { "preset": "studio-dark" },
   "segments": [
     {
       "id": "scene-1",
@@ -427,7 +495,7 @@ Minimal example:
       "root": {
         "id": "root",
         "type": "Scene",
-        "props": { "background": { "type": "color", "value": "#000000" } },
+        "props": { "background": { "type": "color", "token": "background" } },
         "children": [{ "id": "t1", "type": "Text", "props": { "content": "Hello" } }]
       }
     }
@@ -438,7 +506,7 @@ Minimal example:
 Supported `transitionToNext.type` values (segment overlap transitions):
 
 - `FadeTransition`
-- `SlideTransition` (`props`: `{ direction: "left"|"right"|"up"|"down", distance?: number }`)
+- `SlideTransition` (`props`: `{ direction: "left"|"right"|"up"|"down", distance?: "enter"|"nudge"|"travel" }`)
 - `ZoomTransition` (`props`: `{ type: "zoomIn"|"zoomOut" }`)
 - `WipeTransition` (`props`: `{ direction: "left"|"right"|"up"|"down"|"diagonal", softEdge?: boolean }`)
 - `CircularReveal` (`props`: `{ direction: "open"|"close", center?: { x: 0..1, y: 0..1 } }`)
@@ -454,14 +522,15 @@ Notes:
 
 ```json
 {
-  "version": "2.0",
+  "version": "3.0",
   "video": { "id": "main", "width": 1920, "height": 1080, "fps": 30, "durationInFrames": 60 },
+  "theme": { "preset": "studio-dark" },
   "timeline": [
     {
       "id": "scene",
       "type": "Scene",
       "timing": { "from": 0, "durationInFrames": 60 },
-      "props": { "background": { "type": "color", "value": "#000000" } }
+      "props": { "background": { "type": "color", "token": "background" } }
     }
   ]
 }
@@ -559,10 +628,13 @@ node scripts/generate-readme-components.mjs
 | `ImageSequence` | composite | image | no | no | Plays a numbered image sequence (frame-by-frame) |
 | `ImageWithCaption` | composite | image | no | no | Image with a caption strip (top/bottom) or overlay caption |
 | `KenBurnsImage` | composite | image | no | no | Slow zoom and pan (Ken Burns effect) for a still image |
-| `Box` | primitive | layout | yes | no | Positioned container box for layout and backgrounds |
+| `Box` | primitive | layout | yes | no | Flow container for layout and backgrounds (layout-safe) |
 | `CardStack` | composite | layout | no | no | Sequential stacked cards (2-5) with flip/slide/fade transitions |
+| `Frame` | primitive | layout | yes | no | Absolute-positioned container (x/y placement) |
 | `Grid` | primitive | layout | yes | no | Grid layout container with configurable rows/columns |
 | `GridLayout` | composite | layout | yes (1..∞) | no | Simple responsive grid layout for child components |
+| `Layer` | primitive | layout | yes (1..∞) | no | One overlay layer with explicit zIndex inside Layers |
+| `Layers` | primitive | layout | yes (1..∞) | no | Overlay container for stacking children (use Layer for zIndex) |
 | `Scene` | primitive | layout | yes | no | Scene container with a background and nested children |
 | `Segment` | primitive | layout | yes (1..1) | yes | Internal segment wrapper (used by v2 segments compiler) |
 | `Shape` | primitive | layout | no | no | Simple rect/circle shape for UI accents |
@@ -586,7 +658,7 @@ node scripts/generate-readme-components.mjs
 | `TypewriterText` | composite | text | no | no | Character-by-character text reveal with optional blinking cursor |
 | `CircularReveal` | composite | transition | yes (1..∞) | no | Circular iris reveal/hide transition wrapper |
 | `FadeTransition` | composite | transition | yes (1..∞) | no | Fade in/out wrapper (used for segment transitions and overlays) |
-| `SlideTransition` | composite | transition | yes (1..∞) | no | Slide in/out wrapper (used for segment transitions and overlays) |
+| `SlideTransition` | composite | transition | yes (1..∞) | no | Slide in/out wrapper transition |
 | `WipeTransition` | composite | transition | yes (1..∞) | no | Directional wipe reveal/hide wrapper transition |
 | `ZoomTransition` | composite | transition | yes (1..∞) | no | Zoom in/out wrapper transition |
 
@@ -601,18 +673,25 @@ node scripts/generate-readme-components.mjs
 - internal: `false`
 - children: `no`
 - description: Branded intro scene (logo + company name + optional tagline)
-- llmGuidance: Use as the first segment. Works best at 3-5 seconds. musicTrack can add ambience.
+- llmGuidance: Use as the first segment. Works best at 3-5 seconds. Uses theme tokens (no raw styling). musicTrack can add ambience.
 
 Props:
 
 | Prop | Type | Required | Default | Notes |
 | - | - | - | - | - |
-| `backgroundColor` | string | yes | "#000000" |  |
+| `background` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "background" |  |
 | `companyName` | string | yes |  | minLength=1 |
+| `font` | enum("display" \| "body" \| "mono") | yes | "display" |  |
+| `logoSize` | enum("xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl") | yes | "xl" |  |
 | `logoSrc` | string | yes |  | minLength=1 |
 | `musicTrack` | string | no |  |  |
-| `primaryColor` | string | yes | "#FFFFFF" |  |
+| `nameColor` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "foreground" |  |
+| `nameSize` | enum("xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl" \| "3xl" \| "4xl" \| "5xl" \| "6xl") | yes | "4xl" |  |
+| `nameWeight` | enum("regular" \| "medium" \| "semibold" \| "bold" \| "black") | yes | "black" |  |
 | `tagline` | string | no |  |  |
+| `taglineColor` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "mutedForeground" |  |
+| `taglineSize` | enum("xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl" \| "3xl" \| "4xl" \| "5xl" \| "6xl") | yes | "xl" |  |
+| `taglineWeight` | enum("regular" \| "medium" \| "semibold" \| "bold" \| "black") | yes | "semibold" |  |
 
 ##### `LogoReveal`
 
@@ -621,15 +700,17 @@ Props:
 - internal: `false`
 - children: `no`
 - description: Logo intro animation (fade/scale/rotate/slide), optionally with a sound effect
-- llmGuidance: Use for intros/outros. Keep the logo high-contrast and centered. soundEffect can be a short sting.
+- llmGuidance: Use for intros/outros. Keep the logo high-contrast and centered. Uses theme tokens (no raw styling). soundEffect can be a short sting.
 
 Props:
 
 | Prop | Type | Required | Default | Notes |
 | - | - | - | - | - |
-| `backgroundColor` | string | yes | "#000000" |  |
+| `background` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "background" |  |
 | `effect` | enum("fade" \| "scale" \| "rotate" \| "slide") | yes | "scale" |  |
+| `logoSize` | enum("xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl") | yes | "xl" |  |
 | `logoSrc` | string | yes |  | minLength=1 |
+| `slideDistance` | enum("enter" \| "nudge" \| "travel") | yes | "travel" |  |
 | `soundEffect` | string | no |  |  |
 
 ##### `OutroScene`
@@ -639,17 +720,30 @@ Props:
 - internal: `false`
 - children: `no`
 - description: End screen with logo, message, optional CTA buttons and social handles
-- llmGuidance: Use as the last segment. Keep CTAs <=3 for clarity.
+- llmGuidance: Use as the last segment. Keep CTAs <=3 for clarity. Uses theme tokens (no raw styling).
 
 Props:
 
 | Prop | Type | Required | Default | Notes |
 | - | - | - | - | - |
-| `backgroundColor` | string | yes | "#000000" |  |
+| `background` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "background" |  |
+| `ctaBackground` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "muted" |  |
 | `ctaButtons` | array<object> | no |  | maxItems=3 |
+| `ctaColor` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "foreground" |  |
+| `ctaRadius` | enum("none" \| "sm" \| "md" \| "lg" \| "full") | yes | "md" |  |
+| `ctaTextSize` | enum("xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl" \| "3xl" \| "4xl" \| "5xl" \| "6xl") | yes | "lg" |  |
+| `ctaTextWeight` | enum("regular" \| "medium" \| "semibold" \| "bold" \| "black") | yes | "bold" |  |
+| `logoSize` | enum("xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl") | yes | "lg" |  |
 | `logoSrc` | string | yes |  | minLength=1 |
 | `message` | string | yes | "Thank You" |  |
+| `messageColor` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "foreground" |  |
+| `messageFont` | enum("display" \| "body" \| "mono") | yes | "display" |  |
+| `messageSize` | enum("xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl" \| "3xl" \| "4xl" \| "5xl" \| "6xl") | yes | "4xl" |  |
+| `messageWeight` | enum("regular" \| "medium" \| "semibold" \| "bold" \| "black") | yes | "black" |  |
+| `socialColor` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "mutedForeground" |  |
 | `socialHandles` | array<object> | no |  | maxItems=4 |
+| `socialTextSize` | enum("xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl" \| "3xl" \| "4xl" \| "5xl" \| "6xl") | yes | "md" |  |
+| `socialTextWeight` | enum("regular" \| "medium" \| "semibold" \| "bold" \| "black") | yes | "semibold" |  |
 
 ##### `Watermark`
 
@@ -658,18 +752,21 @@ Props:
 - internal: `false`
 - children: `no`
 - description: Persistent logo/text watermark in a corner
-- llmGuidance: Use subtle opacity (0.3-0.6). bottomRight is standard.
+- llmGuidance: Use subtle opacity. bottomRight is standard. Uses theme tokens (no raw styling).
 
 Props:
 
 | Prop | Type | Required | Default | Notes |
 | - | - | - | - | - |
-| `color` | string | yes | "#FFFFFF" |  |
-| `opacity` | number | yes | 0.5 | min=0.1, max=1 |
+| `color` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "mutedForeground" |  |
+| `font` | enum("display" \| "body" \| "mono") | yes | "body" |  |
+| `opacity` | enum("faint" \| "subtle" \| "medium" \| "strong") | yes | "subtle" |  |
 | `position` | enum("topLeft" \| "topRight" \| "bottomLeft" \| "bottomRight") | yes | "bottomRight" |  |
-| `size` | number | yes | 60 | min=30, max=150 |
+| `size` | enum("0" \| "1" \| "2" \| "3" \| "4" \| "5" \| "6" \| "8" \| "10" \| "12" \| "16" \| "20" \| "24" \| "32") | yes | "16" |  |
 | `src` | string | no |  |  |
 | `text` | string | no |  |  |
+| `textSize` | enum("xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl" \| "3xl" \| "4xl" \| "5xl" \| "6xl") | yes | "lg" |  |
+| `textWeight` | enum("regular" \| "medium" \| "semibold" \| "bold" \| "black") | yes | "bold" |  |
 | `type` | enum("logo" \| "text") | yes | "logo" |  |
 
 #### Category: `data`
@@ -681,21 +778,22 @@ Props:
 - internal: `false`
 - children: `no`
 - description: Animated numeric counter (spring or linear), optionally with an icon and suffix
-- llmGuidance: Use for big stats. animationType="spring" feels natural. suffix for units (%, K, M).
+- llmGuidance: Use for big stats. animationType="spring" feels natural. suffix for units (%, K, M). Uses theme tokens (no raw styling).
 
 Props:
 
 | Prop | Type | Required | Default | Notes |
 | - | - | - | - | - |
 | `animationType` | enum("spring" \| "linear") | yes | "spring" |  |
-| `color` | string | yes | "#FFFFFF" |  |
-| `fontFamily` | string | yes | "Inter" |  |
-| `fontSize` | number | yes | 96 | min=8, max=300 |
-| `fontWeight` | integer | yes | 700 | min=100, max=900 |
+| `color` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "foreground" |  |
+| `font` | enum("display" \| "body" \| "mono") | yes | "display" |  |
 | `from` | number | yes | 0 |  |
 | `icon` | string | no |  |  |
+| `iconSize` | enum("xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl" \| "3xl" \| "4xl" \| "5xl" \| "6xl") | yes | "2xl" |  |
+| `size` | enum("xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl" \| "3xl" \| "4xl" \| "5xl" \| "6xl") | yes | "5xl" |  |
 | `suffix` | string | no |  |  |
 | `to` | number | yes | 100 |  |
+| `weight` | enum("regular" \| "medium" \| "semibold" \| "bold" \| "black") | yes | "black" |  |
 
 ##### `BarChart`
 
@@ -704,17 +802,32 @@ Props:
 - internal: `false`
 - children: `no`
 - description: Animated bar chart (vertical or horizontal)
-- llmGuidance: Use 2-6 bars. Provide maxValue to lock scale across multiple charts.
+- llmGuidance: Use 2-6 bars. Provide maxValue to lock scale across multiple charts. Uses theme tokens (no raw styling).
 
 Props:
 
 | Prop | Type | Required | Default | Notes |
 | - | - | - | - | - |
 | `data` | array<object> | yes |  | minItems=2, maxItems=8 |
+| `gap` | enum("0" \| "1" \| "2" \| "3" \| "4" \| "5" \| "6" \| "8" \| "10" \| "12" \| "16" \| "20" \| "24" \| "32") | yes | "6" |  |
+| `gridColor` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "border" |  |
+| `gridOpacity` | enum("faint" \| "subtle" \| "medium" \| "strong") | yes | "faint" |  |
+| `gridRowSize` | enum("0" \| "1" \| "2" \| "3" \| "4" \| "5" \| "6" \| "8" \| "10" \| "12" \| "16" \| "20" \| "24" \| "32") | yes | "16" |  |
+| `labelColor` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "foreground" |  |
+| `labelSize` | enum("xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl" \| "3xl" \| "4xl" \| "5xl" \| "6xl") | yes | "md" |  |
+| `labelWeight` | enum("regular" \| "medium" \| "semibold" \| "bold" \| "black") | yes | "semibold" |  |
 | `maxValue` | number | no |  |  |
 | `orientation` | enum("horizontal" \| "vertical") | yes | "vertical" |  |
+| `padding` | enum("0" \| "1" \| "2" \| "3" \| "4" \| "5" \| "6" \| "8" \| "10" \| "12" \| "16" \| "20" \| "24" \| "32") | yes | "24" |  |
+| `radius` | enum("none" \| "sm" \| "md" \| "lg" \| "full") | yes | "sm" |  |
 | `showGrid` | boolean | yes | false |  |
 | `showValues` | boolean | yes | true |  |
+| `stagger` | enum("fast" \| "base" \| "slow") | yes | "fast" |  |
+| `trackColor` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "muted" |  |
+| `trackRadius` | enum("none" \| "sm" \| "md" \| "lg" \| "full") | yes | "full" |  |
+| `valueColor` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "foreground" |  |
+| `valueSize` | enum("xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl" \| "3xl" \| "4xl" \| "5xl" \| "6xl") | yes | "lg" |  |
+| `valueWeight` | enum("regular" \| "medium" \| "semibold" \| "bold" \| "black") | yes | "bold" |  |
 
 ##### `LineGraph`
 
@@ -723,18 +836,21 @@ Props:
 - internal: `false`
 - children: `no`
 - description: Animated line graph (SVG) with draw/reveal modes
-- llmGuidance: Use 5-20 points. animate="draw" traces the line; animate="reveal" wipes it left-to-right.
+- llmGuidance: Use 5-20 points. animate="draw" traces the line; animate="reveal" wipes it left-to-right. Uses theme tokens (no raw styling).
 
 Props:
 
 | Prop | Type | Required | Default | Notes |
 | - | - | - | - | - |
 | `animate` | enum("draw" \| "reveal") | yes | "draw" |  |
-| `color` | string | yes | "#00FF00" |  |
+| `color` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "primary" |  |
 | `data` | array<object> | yes |  | minItems=2, maxItems=50 |
+| `dotRadius` | enum("0" \| "1" \| "2" \| "3" \| "4" \| "5" \| "6" \| "8" \| "10" \| "12" \| "16" \| "20" \| "24" \| "32") | yes | "2" |  |
 | `fillArea` | boolean | yes | false |  |
+| `fillOpacity` | enum("faint" \| "subtle" \| "medium" \| "strong") | yes | "faint" |  |
+| `padding` | enum("0" \| "1" \| "2" \| "3" \| "4" \| "5" \| "6" \| "8" \| "10" \| "12" \| "16" \| "20" \| "24" \| "32") | yes | "8" |  |
 | `showDots` | boolean | yes | true |  |
-| `strokeWidth` | number | yes | 3 | min=1, max=10 |
+| `strokeWidth` | enum("0" \| "1" \| "2" \| "3" \| "4" \| "5" \| "6" \| "8" \| "10" \| "12" \| "16" \| "20" \| "24" \| "32") | yes | "1" |  |
 
 ##### `ProgressBar`
 
@@ -743,18 +859,25 @@ Props:
 - internal: `false`
 - children: `no`
 - description: Animated progress bar that fills over the component duration
-- llmGuidance: Use for loading/countdowns. showPercentage=true is helpful for clarity.
+- llmGuidance: Use for loading/countdowns. showPercentage=true is helpful for clarity. Uses theme tokens (no raw styling).
 
 Props:
 
 | Prop | Type | Required | Default | Notes |
 | - | - | - | - | - |
-| `backgroundColor` | string | yes | "rgba(255,255,255,0.2)" |  |
-| `color` | string | yes | "#00FF00" |  |
-| `height` | number | yes | 10 | min=5, max=50 |
+| `barColor` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "primary" |  |
+| `edgeOffset` | enum("0" \| "1" \| "2" \| "3" \| "4" \| "5" \| "6" \| "8" \| "10" \| "12" \| "16" \| "20" \| "24" \| "32") | yes | "12" |  |
+| `height` | enum("0" \| "1" \| "2" \| "3" \| "4" \| "5" \| "6" \| "8" \| "10" \| "12" \| "16" \| "20" \| "24" \| "32") | yes | "3" |  |
+| `insetX` | enum("0" \| "1" \| "2" \| "3" \| "4" \| "5" \| "6" \| "8" \| "10" \| "12" \| "16" \| "20" \| "24" \| "32") | yes | "20" |  |
 | `label` | string | no |  |  |
+| `labelColor` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "foreground" |  |
+| `labelFont` | enum("display" \| "body" \| "mono") | yes | "body" |  |
+| `labelSize` | enum("xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl" \| "3xl" \| "4xl" \| "5xl" \| "6xl") | yes | "md" |  |
+| `labelWeight` | enum("regular" \| "medium" \| "semibold" \| "bold" \| "black") | yes | "bold" |  |
 | `position` | enum("top" \| "bottom") | yes | "bottom" |  |
+| `radius` | enum("none" \| "sm" \| "md" \| "lg" \| "full") | yes | "full" |  |
 | `showPercentage` | boolean | yes | true |  |
+| `trackColor` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "muted" |  |
 
 ##### `ProgressRing`
 
@@ -763,18 +886,22 @@ Props:
 - internal: `false`
 - children: `no`
 - description: Circular progress indicator (SVG) that animates from 0 to percentage over duration
-- llmGuidance: Use for completion and goals. size 160-260 is typical. showLabel displays the percentage.
+- llmGuidance: Use for completion and goals. showLabel displays the percentage. Uses theme tokens (no raw styling).
 
 Props:
 
 | Prop | Type | Required | Default | Notes |
 | - | - | - | - | - |
-| `backgroundColor` | string | yes | "rgba(255,255,255,0.2)" |  |
-| `color` | string | yes | "#00FF00" |  |
+| `color` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "primary" |  |
+| `labelColor` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "foreground" |  |
+| `labelFont` | enum("display" \| "body" \| "mono") | yes | "display" |  |
+| `labelSize` | enum("xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl" \| "3xl" \| "4xl" \| "5xl" \| "6xl") | yes | "xl" |  |
+| `labelWeight` | enum("regular" \| "medium" \| "semibold" \| "bold" \| "black") | yes | "black" |  |
 | `percentage` | number | yes |  | min=0, max=100 |
 | `showLabel` | boolean | yes | true |  |
-| `size` | number | yes | 200 | min=100, max=500 |
-| `strokeWidth` | number | yes | 20 | min=5, max=50 |
+| `size` | enum("xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl") | yes | "lg" |  |
+| `strokeWidth` | enum("0" \| "1" \| "2" \| "3" \| "4" \| "5" \| "6" \| "8" \| "10" \| "12" \| "16" \| "20" \| "24" \| "32") | yes | "5" |  |
+| `trackColor` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "muted" |  |
 
 #### Category: `image`
 
@@ -791,7 +918,7 @@ Props:
 
 | Prop | Type | Required | Default | Notes |
 | - | - | - | - | - |
-| `borderRadius` | number | yes | 0 | min=0 |
+| `borderRadius` | enum("none" \| "sm" \| "md" \| "lg" \| "full") | yes | "none" |  |
 | `fit` | enum("cover" \| "contain") | yes | "cover" |  |
 | `opacity` | number | yes | 1 | min=0, max=1 |
 | `src` | string | yes |  | minLength=1 |
@@ -803,15 +930,28 @@ Props:
 - internal: `false`
 - children: `no`
 - description: Collage of multiple images in a grid/stack/scatter layout with staggered entrances
-- llmGuidance: Use 2-6 images for best results. layout="grid" is clean; "scatter" is energetic.
+- llmGuidance: Use 2-6 images for best results. layout="grid" is clean; "scatter" is energetic. Uses theme tokens (no raw styling).
 
 Props:
 
 | Prop | Type | Required | Default | Notes |
 | - | - | - | - | - |
+| `captionBackground` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "background" |  |
+| `captionColor` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "foreground" |  |
+| `captionFont` | enum("display" \| "body" \| "mono") | yes | "body" |  |
+| `captionOpacity` | enum("faint" \| "subtle" \| "medium" \| "strong") | yes | "medium" |  |
+| `captionPadding` | enum("0" \| "1" \| "2" \| "3" \| "4" \| "5" \| "6" \| "8" \| "10" \| "12" \| "16" \| "20" \| "24" \| "32") | yes | "3" |  |
+| `captionSize` | enum("xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl" \| "3xl" \| "4xl" \| "5xl" \| "6xl") | yes | "md" |  |
+| `captionWeight` | enum("regular" \| "medium" \| "semibold" \| "bold" \| "black") | yes | "bold" |  |
+| `cardHeight` | enum("xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl") | yes | "xl" |  |
+| `cardWidth` | enum("xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl") | yes | "2xl" |  |
+| `gap` | enum("0" \| "1" \| "2" \| "3" \| "4" \| "5" \| "6" \| "8" \| "10" \| "12" \| "16" \| "20" \| "24" \| "32") | yes | "6" |  |
 | `images` | array<object> | yes |  | minItems=2, maxItems=9 |
 | `layout` | enum("grid" \| "stack" \| "scatter") | yes | "grid" |  |
-| `stagger` | integer | yes | 5 | min=2, max=10 |
+| `padding` | enum("0" \| "1" \| "2" \| "3" \| "4" \| "5" \| "6" \| "8" \| "10" \| "12" \| "16" \| "20" \| "24" \| "32") | yes | "20" |  |
+| `radius` | enum("none" \| "sm" \| "md" \| "lg" \| "full") | yes | "md" |  |
+| `shadow` | enum("sm" \| "md" \| "lg") | yes | "lg" |  |
+| `stagger` | enum("fast" \| "base" \| "slow") | yes | "fast" |  |
 
 ##### `ImageReveal`
 
@@ -855,15 +995,21 @@ Props:
 - internal: `false`
 - children: `no`
 - description: Image with a caption strip (top/bottom) or overlay caption
-- llmGuidance: Use overlay for quotes/testimonials over photos. Use bottom for standard captions.
+- llmGuidance: Use overlay for quotes/testimonials over photos. Use bottom for standard captions. Uses theme tokens (no raw styling).
 
 Props:
 
 | Prop | Type | Required | Default | Notes |
 | - | - | - | - | - |
 | `caption` | string | yes |  | maxLength=200 |
+| `captionBackground` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "muted" |  |
+| `captionColor` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "foreground" |  |
+| `captionFont` | enum("display" \| "body" \| "mono") | yes | "body" |  |
+| `captionPadding` | enum("0" \| "1" \| "2" \| "3" \| "4" \| "5" \| "6" \| "8" \| "10" \| "12" \| "16" \| "20" \| "24" \| "32") | yes | "5" |  |
 | `captionPosition` | enum("top" \| "bottom" \| "overlay") | yes | "bottom" |  |
-| `captionStyle` | object | no |  | additionalProperties=false |
+| `captionRadius` | enum("none" \| "sm" \| "md" \| "lg" \| "full") | yes | "md" |  |
+| `captionSize` | enum("xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl" \| "3xl" \| "4xl" \| "5xl" \| "6xl") | yes | "xl" |  |
+| `captionWeight` | enum("regular" \| "medium" \| "semibold" \| "bold" \| "black") | yes | "bold" |  |
 | `src` | string | yes |  | minLength=1 |
 
 ##### `KenBurnsImage`
@@ -873,17 +1019,16 @@ Props:
 - internal: `false`
 - children: `no`
 - description: Slow zoom and pan (Ken Burns effect) for a still image
-- llmGuidance: Classic documentary-style motion. startScale 1 -> endScale 1.2 is subtle; add panDirection for extra movement.
+- llmGuidance: Classic documentary-style motion. mode controls zoom; panDirection adds drift. Uses theme tokens (no raw styling).
 
 Props:
 
 | Prop | Type | Required | Default | Notes |
 | - | - | - | - | - |
-| `endScale` | number | yes | 1.2 | min=1, max=2 |
-| `panAmount` | number | yes | 50 | min=0, max=100 |
+| `mode` | enum("zoomIn" \| "zoomOut" \| "none") | yes | "zoomIn" |  |
 | `panDirection` | enum("none" \| "left" \| "right" \| "up" \| "down") | yes | "none" |  |
+| `panDistance` | enum("enter" \| "nudge" \| "travel") | yes | "nudge" |  |
 | `src` | string | yes |  | minLength=1 |
-| `startScale` | number | yes | 1 | min=1, max=2 |
 
 #### Category: `layout`
 
@@ -893,21 +1038,19 @@ Props:
 - category: `layout`
 - internal: `false`
 - children: `yes`
-- description: Positioned container box for layout and backgrounds
-- llmGuidance: Use Box to position content by x/y and optionally constrain width/height. Prefer Box+Stack/Grid for layouts.
+- description: Flow container for layout and backgrounds (layout-safe)
+- llmGuidance: Use Box as a container inside Grid/Stack. Box participates in layout flow. For x/y positioning, use Frame.
 
 Props:
 
 | Prop | Type | Required | Default | Notes |
 | - | - | - | - | - |
-| `backgroundColor` | string | no |  |  |
-| `borderRadius` | number | yes | 0 | min=0 |
+| `backgroundColor` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | no |  |  |
+| `borderRadius` | enum("none" \| "sm" \| "md" \| "lg" \| "full") | yes | "none" |  |
 | `height` | number | no |  |  |
 | `opacity` | number | yes | 1 | min=0, max=1 |
-| `padding` | number | yes | 0 | min=0 |
+| `padding` | enum("0" \| "1" \| "2" \| "3" \| "4" \| "5" \| "6" \| "8" \| "10" \| "12" \| "16" \| "20" \| "24" \| "32") | yes | "0" |  |
 | `width` | number | no |  |  |
-| `x` | number | yes | 0 |  |
-| `y` | number | yes | 0 |  |
 
 ##### `CardStack`
 
@@ -916,16 +1059,50 @@ Props:
 - internal: `false`
 - children: `no`
 - description: Sequential stacked cards (2-5) with flip/slide/fade transitions
-- llmGuidance: Use for steps/features. displayDuration is frames per card.
+- llmGuidance: Use for steps/features. displayDuration is frames per card. Uses theme tokens (no raw styling).
 
 Props:
 
 | Prop | Type | Required | Default | Notes |
 | - | - | - | - | - |
+| `background` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "surface" |  |
 | `cards` | array<object> | yes |  | minItems=2, maxItems=5 |
+| `contentFont` | enum("display" \| "body" \| "mono") | yes | "body" |  |
+| `contentOpacity` | enum("faint" \| "subtle" \| "medium" \| "strong") | yes | "strong" |  |
+| `contentSize` | enum("xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl" \| "3xl" \| "4xl" \| "5xl" \| "6xl") | yes | "xl" |  |
+| `contentWeight` | enum("regular" \| "medium" \| "semibold" \| "bold" \| "black") | yes | "bold" |  |
 | `displayDuration` | integer | yes | 90 | min=30, max=150 |
+| `padding` | enum("0" \| "1" \| "2" \| "3" \| "4" \| "5" \| "6" \| "8" \| "10" \| "12" \| "16" \| "20" \| "24" \| "32") | yes | "16" |  |
+| `radius` | enum("none" \| "sm" \| "md" \| "lg" \| "full") | yes | "lg" |  |
+| `shadow` | enum("sm" \| "md" \| "lg") | yes | "lg" |  |
+| `textColor` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "surfaceForeground" |  |
+| `titleFont` | enum("display" \| "body" \| "mono") | yes | "display" |  |
+| `titleSize` | enum("xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl" \| "3xl" \| "4xl" \| "5xl" \| "6xl") | yes | "4xl" |  |
+| `titleWeight` | enum("regular" \| "medium" \| "semibold" \| "bold" \| "black") | yes | "black" |  |
 | `transition` | enum("flip" \| "slide" \| "fade") | yes | "flip" |  |
 
+##### `Frame`
+
+- kind: `primitive`
+- category: `layout`
+- internal: `false`
+- children: `yes`
+- description: Absolute-positioned container (x/y placement)
+- llmGuidance: Use Frame for precise pixel placement (x/y). Use Box for normal layout flow inside Grid/Stack.
+
+Props:
+
+| Prop | Type | Required | Default | Notes |
+| - | - | - | - | - |
+| `backgroundColor` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | no |  |  |
+| `borderRadius` | enum("none" \| "sm" \| "md" \| "lg" \| "full") | yes | "none" |  |
+| `height` | number | no |  |  |
+| `opacity` | number | yes | 1 | min=0, max=1 |
+| `padding` | enum("0" \| "1" \| "2" \| "3" \| "4" \| "5" \| "6" \| "8" \| "10" \| "12" \| "16" \| "20" \| "24" \| "32") | yes | "0" |  |
+| `width` | number | no |  |  |
+| `x` | number | yes | 0 |  |
+| `y` | number | yes | 0 |  |
+
 ##### `Grid`
 
 - kind: `primitive`
@@ -941,9 +1118,9 @@ Props:
 | - | - | - | - | - |
 | `align` | enum("start" \| "center" \| "end" \| "stretch") | yes | "stretch" |  |
 | `columns` | integer | yes | 2 | min=1, max=12 |
-| `gap` | number | yes | 24 | min=0 |
+| `gap` | enum("0" \| "1" \| "2" \| "3" \| "4" \| "5" \| "6" \| "8" \| "10" \| "12" \| "16" \| "20" \| "24" \| "32") | yes | "6" |  |
 | `justify` | enum("start" \| "center" \| "end" \| "stretch") | yes | "stretch" |  |
-| `padding` | number | yes | 0 | min=0 |
+| `padding` | enum("0" \| "1" \| "2" \| "3" \| "4" \| "5" \| "6" \| "8" \| "10" \| "12" \| "16" \| "20" \| "24" \| "32") | yes | "0" |  |
 | `rows` | integer | yes | 1 | min=1, max=12 |
 
 ##### `GridLayout`
@@ -960,10 +1137,43 @@ Props:
 | Prop | Type | Required | Default | Notes |
 | - | - | - | - | - |
 | `columns` | integer | yes | 2 | min=1, max=4 |
-| `gap` | number | yes | 20 | min=0, max=50 |
-| `padding` | number | yes | 40 | min=0, max=100 |
+| `gap` | enum("0" \| "1" \| "2" \| "3" \| "4" \| "5" \| "6" \| "8" \| "10" \| "12" \| "16" \| "20" \| "24" \| "32") | yes | "5" |  |
+| `padding` | enum("0" \| "1" \| "2" \| "3" \| "4" \| "5" \| "6" \| "8" \| "10" \| "12" \| "16" \| "20" \| "24" \| "32") | yes | "10" |  |
 | `rows` | integer | yes | 2 | min=1, max=4 |
 
+##### `Layer`
+
+- kind: `primitive`
+- category: `layout`
+- internal: `false`
+- children: `yes (1..∞)`
+- description: One overlay layer with explicit zIndex inside Layers
+- llmGuidance: Use Layer inside Layers to control stacking. Put exactly one child in a Layer (recommended).
+
+Props:
+
+| Prop | Type | Required | Default | Notes |
+| - | - | - | - | - |
+| `inset` | enum("0" \| "1" \| "2" \| "3" \| "4" \| "5" \| "6" \| "8" \| "10" \| "12" \| "16" \| "20" \| "24" \| "32") | yes | "0" |  |
+| `opacity` | number | yes | 1 | min=0, max=1 |
+| `pointerEvents` | enum("none" \| "auto") | yes | "none" |  |
+| `zIndex` | integer | yes | 0 | min=-9007199254740991, max=9007199254740991 |
+
+##### `Layers`
+
+- kind: `primitive`
+- category: `layout`
+- internal: `false`
+- children: `yes (1..∞)`
+- description: Overlay container for stacking children (use Layer for zIndex)
+- llmGuidance: Use Layers to stack background/content/overlays. Prefer Layer children with explicit zIndex.
+
+Props:
+
+| Prop | Type | Required | Default | Notes |
+| - | - | - | - | - |
+| `overflow` | enum("visible" \| "hidden") | yes | "visible" |  |
+
 ##### `Scene`
 
 - kind: `primitive`
@@ -1007,12 +1217,13 @@ Props:
 
 | Prop | Type | Required | Default | Notes |
 | - | - | - | - | - |
-| `fill` | string | yes | "#FFFFFF" |  |
+| `fill` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "foreground" |  |
 | `height` | number | yes | 100 |  |
 | `opacity` | number | yes | 1 | min=0, max=1 |
+| `radius` | enum("none" \| "sm" \| "md" \| "lg" \| "full") | yes | "none" |  |
 | `shape` | enum("rect" \| "circle") | yes | "rect" |  |
-| `strokeColor` | string | no |  |  |
-| `strokeWidth` | number | yes | 0 | min=0 |
+| `strokeColor` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | no |  |  |
+| `strokeWidth` | enum("0" \| "1" \| "2" \| "3" \| "4" \| "5" \| "6" \| "8" \| "10" \| "12" \| "16" \| "20" \| "24" \| "32") | yes | "0" |  |
 | `width` | number | yes | 100 |  |
 | `x` | number | yes | 0 |  |
 | `y` | number | yes | 0 |  |
@@ -1030,10 +1241,12 @@ Props:
 
 | Prop | Type | Required | Default | Notes |
 | - | - | - | - | - |
-| `dividerColor` | string | no |  |  |
-| `gap` | number | yes | 48 | min=0 |
+| `dividerColor` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | no |  |  |
+| `dividerOpacity` | enum("faint" \| "subtle" \| "medium" \| "strong") | yes | "subtle" |  |
+| `dividerThickness` | enum("0" \| "1" \| "2" \| "3" \| "4" \| "5" \| "6" \| "8" \| "10" \| "12" \| "16" \| "20" \| "24" \| "32") | yes | "1" |  |
+| `gap` | enum("0" \| "1" \| "2" \| "3" \| "4" \| "5" \| "6" \| "8" \| "10" \| "12" \| "16" \| "20" \| "24" \| "32") | yes | "12" |  |
 | `orientation` | enum("vertical" \| "horizontal") | yes | "vertical" |  |
-| `padding` | number | yes | 80 | min=0 |
+| `padding` | enum("0" \| "1" \| "2" \| "3" \| "4" \| "5" \| "6" \| "8" \| "10" \| "12" \| "16" \| "20" \| "24" \| "32") | yes | "20" |  |
 | `split` | number | yes | 0.5 | min=0.1, max=0.9 |
 
 ##### `Stack`
@@ -1051,9 +1264,9 @@ Props:
 | - | - | - | - | - |
 | `align` | enum("start" \| "center" \| "end" \| "stretch") | yes | "center" |  |
 | `direction` | enum("row" \| "column") | yes | "column" |  |
-| `gap` | number | yes | 24 | min=0 |
+| `gap` | enum("0" \| "1" \| "2" \| "3" \| "4" \| "5" \| "6" \| "8" \| "10" \| "12" \| "16" \| "20" \| "24" \| "32") | yes | "6" |  |
 | `justify` | enum("start" \| "center" \| "end" \| "between") | yes | "center" |  |
-| `padding` | number | yes | 0 | min=0 |
+| `padding` | enum("0" \| "1" \| "2" \| "3" \| "4" \| "5" \| "6" \| "8" \| "10" \| "12" \| "16" \| "20" \| "24" \| "32") | yes | "0" |  |
 
 ##### `ThirdLowerBanner`
 
@@ -1068,14 +1281,28 @@ Props:
 
 | Prop | Type | Required | Default | Notes |
 | - | - | - | - | - |
-| `accentColor` | string | yes | "#FF0000" |  |
+| `accent` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "primary" |  |
+| `avatarBox` | enum("xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl") | yes | "md" |  |
+| `avatarSize` | enum("xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl") | yes | "sm" |  |
 | `avatarSrc` | string | no |  |  |
-| `backgroundColor` | string | yes | "rgba(0,0,0,0.8)" |  |
+| `background` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "muted" |  |
+| `barWidth` | enum("0" \| "1" \| "2" \| "3" \| "4" \| "5" \| "6" \| "8" \| "10" \| "12" \| "16" \| "20" \| "24" \| "32") | yes | "2" |  |
+| `inset` | enum("0" \| "1" \| "2" \| "3" \| "4" \| "5" \| "6" \| "8" \| "10" \| "12" \| "16" \| "20" \| "24" \| "32") | yes | "20" |  |
+| `minHeight` | enum("xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl") | yes | "md" |  |
 | `name` | string | yes |  | maxLength=50 |
-| `primaryColor` | string | yes | "#FFFFFF" |  |
-| `secondaryColor` | string | yes | "#CCCCCC" |  |
+| `nameColor` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "foreground" |  |
+| `nameFont` | enum("display" \| "body" \| "mono") | yes | "display" |  |
+| `nameSize` | enum("xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl" \| "3xl" \| "4xl" \| "5xl" \| "6xl") | yes | "3xl" |  |
+| `nameWeight` | enum("regular" \| "medium" \| "semibold" \| "bold" \| "black") | yes | "black" |  |
+| `paddingX` | enum("0" \| "1" \| "2" \| "3" \| "4" \| "5" \| "6" \| "8" \| "10" \| "12" \| "16" \| "20" \| "24" \| "32") | yes | "8" |  |
+| `paddingY` | enum("0" \| "1" \| "2" \| "3" \| "4" \| "5" \| "6" \| "8" \| "10" \| "12" \| "16" \| "20" \| "24" \| "32") | yes | "6" |  |
+| `radius` | enum("none" \| "sm" \| "md" \| "lg" \| "full") | yes | "md" |  |
 | `showAvatar` | boolean | yes | false |  |
 | `title` | string | yes |  | maxLength=100 |
+| `titleColor` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "mutedForeground" |  |
+| `titleFont` | enum("display" \| "body" \| "mono") | yes | "body" |  |
+| `titleSize` | enum("xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl" \| "3xl" \| "4xl" \| "5xl" \| "6xl") | yes | "lg" |  |
+| `titleWeight` | enum("regular" \| "medium" \| "semibold" \| "bold" \| "black") | yes | "semibold" |  |
 
 #### Category: `media`
 
@@ -1111,7 +1338,7 @@ Props:
 
 | Prop | Type | Required | Default | Notes |
 | - | - | - | - | - |
-| `borderRadius` | number | yes | 0 | min=0 |
+| `borderRadius` | enum("none" \| "sm" \| "md" \| "lg" \| "full") | yes | "none" |  |
 | `fit` | enum("cover" \| "contain") | yes | "cover" |  |
 | `muted` | boolean | yes | true |  |
 | `opacity` | number | yes | 1 | min=0, max=1 |
@@ -1124,7 +1351,7 @@ Props:
 - internal: `false`
 - children: `no`
 - description: Video background with an optional overlay (text/logo/gradient)
-- llmGuidance: Use gradient overlay to improve text readability. Set volume=0 to mute.
+- llmGuidance: Use gradient overlay to improve text readability. Set volume=0 to mute. Uses theme tokens (no raw styling).
 
 Props:
 
@@ -1144,19 +1371,38 @@ Props:
 - internal: `false`
 - children: `no`
 - description: Instagram story-style layout with profile header, text overlay, and optional sticker
-- llmGuidance: Best with 1080x1920 (9:16). Use backgroundImage + short text + optional sticker for mobile-style content.
+- llmGuidance: Best with 1080x1920 (9:16). Use backgroundImage + short text + optional sticker for mobile-style content. Uses theme tokens (no raw styling).
 
 Props:
 
 | Prop | Type | Required | Default | Notes |
 | - | - | - | - | - |
-| `backgroundColor` | string | yes | "#000000" |  |
+| `avatarSize` | enum("xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl") | yes | "sm" |  |
+| `background` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "background" |  |
 | `backgroundImage` | string | no |  |  |
+| `headerGap` | enum("0" \| "1" \| "2" \| "3" \| "4" \| "5" \| "6" \| "8" \| "10" \| "12" \| "16" \| "20" \| "24" \| "32") | yes | "4" |  |
 | `musicTrack` | string | no |  |  |
+| `padding` | enum("0" \| "1" \| "2" \| "3" \| "4" \| "5" \| "6" \| "8" \| "10" \| "12" \| "16" \| "20" \| "24" \| "32") | yes | "16" |  |
 | `profilePic` | string | no |  |  |
 | `sticker` | enum("none" \| "poll" \| "question" \| "countdown") | yes | "none" |  |
+| `stickerBackground` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "surface" |  |
+| `stickerBottom` | enum("xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl") | yes | "lg" |  |
+| `stickerLeft` | enum("0" \| "1" \| "2" \| "3" \| "4" \| "5" \| "6" \| "8" \| "10" \| "12" \| "16" \| "20" \| "24" \| "32") | yes | "16" |  |
+| `stickerPadding` | enum("0" \| "1" \| "2" \| "3" \| "4" \| "5" \| "6" \| "8" \| "10" \| "12" \| "16" \| "20" \| "24" \| "32") | yes | "6" |  |
+| `stickerRadius` | enum("none" \| "sm" \| "md" \| "lg" \| "full") | yes | "md" |  |
+| `stickerTextColor` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "surfaceForeground" |  |
+| `stickerTextSize` | enum("xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl" \| "3xl" \| "4xl" \| "5xl" \| "6xl") | yes | "lg" |  |
+| `stickerTextWeight` | enum("regular" \| "medium" \| "semibold" \| "bold" \| "black") | yes | "black" |  |
+| `stickerWidth` | enum("xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl") | yes | "2xl" |  |
 | `text` | string | no |  | maxLength=100 |
+| `textColor` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "foreground" |  |
+| `textMarginTop` | enum("0" \| "1" \| "2" \| "3" \| "4" \| "5" \| "6" \| "8" \| "10" \| "12" \| "16" \| "20" \| "24" \| "32") | yes | "32" |  |
+| `textSize` | enum("xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl" \| "3xl" \| "4xl" \| "5xl" \| "6xl") | yes | "3xl" |  |
+| `textWeight` | enum("regular" \| "medium" \| "semibold" \| "bold" \| "black") | yes | "black" |  |
 | `username` | string | no |  |  |
+| `usernameColor` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "foreground" |  |
+| `usernameSize` | enum("xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl" \| "3xl" \| "4xl" \| "5xl" \| "6xl") | yes | "xl" |  |
+| `usernameWeight` | enum("regular" \| "medium" \| "semibold" \| "bold" \| "black") | yes | "black" |  |
 
 ##### `TikTokCaption`
 
@@ -1165,19 +1411,22 @@ Props:
 - internal: `false`
 - children: `no`
 - description: TikTok-style captions with stroke and optional word highlighting
-- llmGuidance: Always keep strokeWidth>=2 for readability. highlightStyle="word" or "bounce" makes captions feel dynamic.
+- llmGuidance: highlightStyle="word" or "bounce" makes captions feel dynamic. Uses theme tokens (no raw styling).
 
 Props:
 
 | Prop | Type | Required | Default | Notes |
 | - | - | - | - | - |
-| `color` | string | yes | "#FFFFFF" |  |
-| `fontSize` | number | yes | 48 | min=12, max=120 |
+| `color` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "foreground" |  |
+| `font` | enum("display" \| "body" \| "mono") | yes | "display" |  |
+| `highlightColor` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "accent" |  |
 | `highlightStyle` | enum("word" \| "bounce" \| "none") | yes | "word" |  |
 | `position` | enum("center" \| "bottom") | yes | "center" |  |
-| `strokeColor` | string | yes | "#000000" |  |
-| `strokeWidth` | number | yes | 3 | min=0, max=10 |
+| `size` | enum("xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl" \| "3xl" \| "4xl" \| "5xl" \| "6xl") | yes | "2xl" |  |
+| `strokeColor` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "background" |  |
+| `strokeWidth` | enum("0" \| "1" \| "2" \| "3" \| "4" \| "5" \| "6" \| "8" \| "10" \| "12" \| "16" \| "20" \| "24" \| "32") | yes | "1" |  |
 | `text` | string | yes |  | maxLength=150 |
+| `weight` | enum("regular" \| "medium" \| "semibold" \| "bold" \| "black") | yes | "black" |  |
 
 ##### `TwitterCard`
 
@@ -1186,19 +1435,39 @@ Props:
 - internal: `false`
 - children: `no`
 - description: Twitter/X post card layout with author header and optional image
-- llmGuidance: Use for announcements/testimonials. Keep tweet short for readability.
+- llmGuidance: Use for announcements/testimonials. Keep tweet short for readability. Uses theme tokens (no raw styling).
 
 Props:
 
 | Prop | Type | Required | Default | Notes |
 | - | - | - | - | - |
 | `author` | string | yes |  | minLength=1 |
+| `authorSize` | enum("xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl" \| "3xl" \| "4xl" \| "5xl" \| "6xl") | yes | "xl" |  |
+| `authorWeight` | enum("regular" \| "medium" \| "semibold" \| "bold" \| "black") | yes | "black" |  |
+| `avatarSize` | enum("xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl") | yes | "sm" |  |
 | `avatarSrc` | string | no |  |  |
+| `background` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "background" |  |
+| `cardBackground` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "surface" |  |
+| `cardText` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "surfaceForeground" |  |
+| `font` | enum("display" \| "body" \| "mono") | yes | "body" |  |
+| `gap` | enum("0" \| "1" \| "2" \| "3" \| "4" \| "5" \| "6" \| "8" \| "10" \| "12" \| "16" \| "20" \| "24" \| "32") | yes | "4" |  |
 | `handle` | string | yes |  | minLength=1 |
+| `handleSize` | enum("xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl" \| "3xl" \| "4xl" \| "5xl" \| "6xl") | yes | "lg" |  |
+| `handleWeight` | enum("regular" \| "medium" \| "semibold" \| "bold" \| "black") | yes | "bold" |  |
 | `image` | string | no |  |  |
+| `mutedText` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "mutedForeground" |  |
+| `padding` | enum("0" \| "1" \| "2" \| "3" \| "4" \| "5" \| "6" \| "8" \| "10" \| "12" \| "16" \| "20" \| "24" \| "32") | yes | "12" |  |
+| `placeholderAvatarBackground` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "muted" |  |
+| `radius` | enum("none" \| "sm" \| "md" \| "lg" \| "full") | yes | "lg" |  |
+| `shadow` | enum("sm" \| "md" \| "lg") | yes | "lg" |  |
 | `timestamp` | string | no |  |  |
+| `timestampSize` | enum("xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl" \| "3xl" \| "4xl" \| "5xl" \| "6xl") | yes | "md" |  |
+| `timestampWeight` | enum("regular" \| "medium" \| "semibold" \| "bold" \| "black") | yes | "semibold" |  |
 | `tweet` | string | yes |  | maxLength=280 |
+| `tweetSize` | enum("xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl" \| "3xl" \| "4xl" \| "5xl" \| "6xl") | yes | "xl" |  |
+| `tweetWeight` | enum("regular" \| "medium" \| "semibold" \| "bold" \| "black") | yes | "semibold" |  |
 | `verified` | boolean | yes | false |  |
+| `verifiedColor` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "primary" |  |
 
 ##### `YouTubeThumbnail`
 
@@ -1207,18 +1476,26 @@ Props:
 - internal: `false`
 - children: `no`
 - description: YouTube-style thumbnail layout (16:9) with bold title and optional face cutout
-- llmGuidance: Use 1280x720 video size. Keep title short and high-contrast. style="bold" is classic thumbnail.
+- llmGuidance: Use 1280x720 video size. Keep title short and high-contrast. Uses theme tokens (no raw styling).
 
 Props:
 
 | Prop | Type | Required | Default | Notes |
 | - | - | - | - | - |
-| `accentColor` | string | yes | "#FF0000" |  |
 | `backgroundImage` | string | yes |  | minLength=1 |
+| `barHeight` | enum("0" \| "1" \| "2" \| "3" \| "4" \| "5" \| "6" \| "8" \| "10" \| "12" \| "16" \| "20" \| "24" \| "32") | yes | "4" |  |
+| `barWidth` | enum("xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl") | yes | "xl" |  |
+| `faceWidth` | enum("xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl") | yes | "2xl" |  |
+| `overlayColor` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "background" |  |
+| `overlayOpacity` | enum("faint" \| "subtle" \| "medium" \| "strong") | yes | "medium" |  |
+| `strokeColor` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "background" |  |
+| `strokeWidth` | enum("0" \| "1" \| "2" \| "3" \| "4" \| "5" \| "6" \| "8" \| "10" \| "12" \| "16" \| "20" \| "24" \| "32") | yes | "3" |  |
 | `style` | enum("bold" \| "minimal" \| "dramatic") | yes | "bold" |  |
 | `subtitle` | string | no |  | maxLength=40 |
+| `subtitleColor` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "primary" |  |
 | `thumbnailFace` | string | no |  |  |
 | `title` | string | yes |  | maxLength=60 |
+| `titleColor` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "foreground" |  |
 
 #### Category: `text`
 
@@ -1229,23 +1506,23 @@ Props:
 - internal: `false`
 - children: `no`
 - description: Counts from a start value to an end value with formatting options
-- llmGuidance: Use for metrics. format="currency" adds $, format="percentage" multiplies by 100 and adds %.
+- llmGuidance: Use for metrics. format="currency" adds $, format="percentage" multiplies by 100 and adds %. Uses theme tokens (no raw styling).
 
 Props:
 
 | Prop | Type | Required | Default | Notes |
 | - | - | - | - | - |
-| `color` | string | yes | "#FFFFFF" |  |
+| `color` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "foreground" |  |
 | `decimals` | integer | yes | 0 | min=0, max=4 |
-| `fontFamily` | string | yes | "Inter" |  |
-| `fontSize` | number | yes | 72 | min=8, max=240 |
-| `fontWeight` | integer | yes | 700 | min=100, max=900 |
+| `font` | enum("display" \| "body" \| "mono") | yes | "display" |  |
 | `format` | enum("integer" \| "decimal" \| "currency" \| "percentage") | yes | "integer" |  |
 | `from` | number | yes | 0 |  |
 | `position` | enum("top" \| "center" \| "bottom") | yes | "center" |  |
 | `prefix` | string | no |  |  |
+| `size` | enum("xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl" \| "3xl" \| "4xl" \| "5xl" \| "6xl") | yes | "4xl" |  |
 | `suffix` | string | no |  |  |
 | `to` | number | yes | 100 |  |
+| `weight` | enum("regular" \| "medium" \| "semibold" \| "bold" \| "black") | yes | "bold" |  |
 
 ##### `GlitchText`
 
@@ -1254,19 +1531,26 @@ Props:
 - internal: `false`
 - children: `no`
 - description: Cyberpunk-style glitch text with RGB split jitter
-- llmGuidance: Use for tech/error moments. intensity 1-3 subtle, 7-10 extreme. glitchDuration is frames at start.
+- llmGuidance: Use for tech/error moments. intensity 1-3 subtle, 7-10 extreme. glitchDuration uses theme motion tokens.
 
 Props:
 
 | Prop | Type | Required | Default | Notes |
 | - | - | - | - | - |
-| `color` | string | yes | "#FFFFFF" |  |
+| `channelAColor` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "secondary" |  |
+| `channelBColor` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "primary" |  |
+| `channelOffset` | enum("0" \| "1" \| "2" \| "3" \| "4" \| "5" \| "6" \| "8" \| "10" \| "12" \| "16" \| "20" \| "24" \| "32") | yes | "1" |  |
+| `channelOpacity` | enum("faint" \| "subtle" \| "medium" \| "strong") | yes | "strong" |  |
+| `color` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "foreground" |  |
 | `content` | string | yes |  | maxLength=100 |
-| `fontFamily` | string | yes | "monospace" |  |
-| `fontSize` | number | yes | 72 | min=8, max=240 |
-| `glitchDuration` | integer | yes | 10 | min=5, max=30 |
+| `font` | enum("display" \| "body" \| "mono") | yes | "mono" |  |
+| `glitchDuration` | enum("fast" \| "base" \| "slow") | yes | "fast" |  |
 | `intensity` | integer | yes | 5 | min=1, max=10 |
+| `jitterX` | enum("0" \| "1" \| "2" \| "3" \| "4" \| "5" \| "6" \| "8" \| "10" \| "12" \| "16" \| "20" \| "24" \| "32") | yes | "3" |  |
+| `jitterY` | enum("0" \| "1" \| "2" \| "3" \| "4" \| "5" \| "6" \| "8" \| "10" \| "12" \| "16" \| "20" \| "24" \| "32") | yes | "2" |  |
 | `position` | enum("top" \| "center" \| "bottom") | yes | "center" |  |
+| `size` | enum("xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl" \| "3xl" \| "4xl" \| "5xl" \| "6xl") | yes | "4xl" |  |
+| `weight` | enum("regular" \| "medium" \| "semibold" \| "bold" \| "black") | yes | "black" |  |
 
 ##### `KineticTypography`
 
@@ -1275,15 +1559,15 @@ Props:
 - internal: `false`
 - children: `no`
 - description: Rhythmic single-word kinetic typography driven by a timing array
-- llmGuidance: Provide timing frames for when each word appears. Use emphasis="giant" sparingly for impact.
+- llmGuidance: Provide timing frames for when each word appears. Use emphasis="giant" sparingly for impact. Uses theme tokens (no raw styling).
 
 Props:
 
 | Prop | Type | Required | Default | Notes |
 | - | - | - | - | - |
-| `color` | string | yes | "#FFFFFF" |  |
-| `fontFamily` | string | yes | "Inter" |  |
-| `fontSize` | number | yes | 48 | min=12, max=140 |
+| `baseSize` | enum("xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl" \| "3xl" \| "4xl" \| "5xl" \| "6xl") | yes | "2xl" |  |
+| `color` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "foreground" |  |
+| `font` | enum("display" \| "body" \| "mono") | yes | "display" |  |
 | `timing` | array<integer> | yes |  | minItems=1 |
 | `transition` | enum("fade" \| "scale" \| "slideLeft" \| "slideRight") | yes | "scale" |  |
 | `words` | array<object> | yes |  | minItems=1, maxItems=50 |
@@ -1295,7 +1579,7 @@ Props:
 - internal: `false`
 - children: `no`
 - description: Outlined title text with simple draw/fill animation
-- llmGuidance: Use for bold titles. animation="draw" emphasizes the outline; animation="fill" reveals the fill color.
+- llmGuidance: Use for bold titles. animation="draw" emphasizes the outline; animation="fill" reveals the fill color. Uses theme tokens (no raw styling).
 
 Props:
 
@@ -1303,13 +1587,13 @@ Props:
 | - | - | - | - | - |
 | `animation` | enum("draw" \| "fill") | yes | "draw" |  |
 | `content` | string | yes |  | maxLength=50 |
-| `fillColor` | string | yes | "#000000" |  |
-| `fontFamily` | string | yes | "Inter" |  |
-| `fontSize` | number | yes | 96 | min=8, max=240 |
-| `fontWeight` | integer | yes | 800 | min=100, max=900 |
-| `outlineColor` | string | yes | "#FFFFFF" |  |
+| `fillColor` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "background" |  |
+| `font` | enum("display" \| "body" \| "mono") | yes | "display" |  |
+| `outlineColor` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "foreground" |  |
 | `position` | enum("top" \| "center" \| "bottom") | yes | "center" |  |
-| `strokeWidth` | number | yes | 3 | min=1, max=10 |
+| `size` | enum("xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl" \| "3xl" \| "4xl" \| "5xl" \| "6xl") | yes | "5xl" |  |
+| `strokeWidth` | enum("0" \| "1" \| "2" \| "3" \| "4" \| "5" \| "6" \| "8" \| "10" \| "12" \| "16" \| "20" \| "24" \| "32") | yes | "1" |  |
+| `weight` | enum("regular" \| "medium" \| "semibold" \| "bold" \| "black") | yes | "black" |  |
 
 ##### `SplitText`
 
@@ -1325,13 +1609,14 @@ Props:
 | Prop | Type | Required | Default | Notes |
 | - | - | - | - | - |
 | `animation` | enum("fade" \| "slideUp" \| "slideDown" \| "scale" \| "rotate") | yes | "slideUp" |  |
-| `color` | string | yes | "#FFFFFF" |  |
+| `color` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "foreground" |  |
 | `content` | string | yes |  | maxLength=200 |
-| `fontFamily` | string | yes | "Inter" |  |
-| `fontSize` | number | yes | 48 | min=8, max=200 |
+| `font` | enum("display" \| "body" \| "mono") | yes | "display" |  |
 | `position` | enum("top" \| "center" \| "bottom") | yes | "center" |  |
+| `size` | enum("xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl" \| "3xl" \| "4xl" \| "5xl" \| "6xl") | yes | "2xl" |  |
 | `splitBy` | enum("word" \| "letter") | yes | "word" |  |
-| `stagger` | integer | yes | 3 | min=1, max=10 |
+| `stagger` | enum("fast" \| "base" \| "slow") | yes | "fast" |  |
+| `weight` | enum("regular" \| "medium" \| "semibold" \| "bold" \| "black") | yes | "bold" |  |
 
 ##### `SubtitleText`
 
@@ -1340,21 +1625,24 @@ Props:
 - internal: `false`
 - children: `no`
 - description: Caption/subtitle box with fade in/out and optional highlighted words
-- llmGuidance: Use for narration/captions. highlightWords helps emphasize key terms.
+- llmGuidance: Use for narration/captions. highlightWords helps emphasize key terms. Uses theme tokens (no raw styling).
 
 Props:
 
 | Prop | Type | Required | Default | Notes |
 | - | - | - | - | - |
-| `backgroundColor` | string | yes | "rgba(0,0,0,0.7)" |  |
-| `color` | string | yes | "#FFFFFF" |  |
-| `fontFamily` | string | yes | "Inter" |  |
-| `fontSize` | number | yes | 36 | min=12, max=80 |
+| `background` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "muted" |  |
+| `color` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "foreground" |  |
+| `edgeOffset` | enum("0" \| "1" \| "2" \| "3" \| "4" \| "5" \| "6" \| "8" \| "10" \| "12" \| "16" \| "20" \| "24" \| "32") | yes | "20" |  |
+| `font` | enum("display" \| "body" \| "mono") | yes | "body" |  |
+| `highlightColor` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "accent" |  |
 | `highlightWords` | array<string> | no |  |  |
-| `maxWidth` | number | yes | 800 | min=200, max=1200 |
-| `padding` | number | yes | 20 | min=0, max=80 |
+| `padding` | enum("0" \| "1" \| "2" \| "3" \| "4" \| "5" \| "6" \| "8" \| "10" \| "12" \| "16" \| "20" \| "24" \| "32") | yes | "5" |  |
 | `position` | enum("top" \| "bottom") | yes | "bottom" |  |
+| `radius` | enum("none" \| "sm" \| "md" \| "lg" \| "full") | yes | "md" |  |
+| `size` | enum("xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl" \| "3xl" \| "4xl" \| "5xl" \| "6xl") | yes | "xl" |  |
 | `text` | string | yes |  | maxLength=200 |
+| `weight` | enum("regular" \| "medium" \| "semibold" \| "bold" \| "black") | yes | "bold" |  |
 
 ##### `Text`
 
@@ -1370,10 +1658,15 @@ Props:
 | Prop | Type | Required | Default | Notes |
 | - | - | - | - | - |
 | `animation` | enum("none" \| "fade" \| "slide" \| "zoom") | yes | "fade" |  |
-| `color` | string | yes | "#FFFFFF" |  |
+| `color` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "foreground" |  |
 | `content` | string | yes |  |  |
-| `fontSize` | number | yes | 48 |  |
+| `font` | enum("display" \| "body" \| "mono") | yes | "display" |  |
+| `lineHeight` | enum("tight" \| "normal" \| "relaxed") | yes | "normal" |  |
 | `position` | enum("top" \| "center" \| "bottom" \| "left" \| "right") | yes | "center" |  |
+| `size` | enum("xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl" \| "3xl" \| "4xl" \| "5xl" \| "6xl") | yes | "2xl" |  |
+| `textAlign` | enum("left" \| "center" \| "right") | yes | "center" |  |
+| `tracking` | enum("tight" \| "normal" \| "wide") | yes | "normal" |  |
+| `weight` | enum("regular" \| "medium" \| "semibold" \| "bold" \| "black") | yes | "semibold" |  |
 
 ##### `TypewriterText`
 
@@ -1388,14 +1681,15 @@ Props:
 
 | Prop | Type | Required | Default | Notes |
 | - | - | - | - | - |
-| `color` | string | yes | "#FFFFFF" |  |
+| `color` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "foreground" |  |
 | `content` | string | yes |  | maxLength=500 |
-| `cursorColor` | string | yes | "#FFFFFF" |  |
-| `fontFamily` | string | yes | "Inter" |  |
-| `fontSize` | number | yes | 48 | min=8, max=200 |
+| `cursorColor` | enum("background" \| "foreground" \| "surface" \| "surfaceForeground" \| "muted" \| "mutedForeground" \| "primary" \| "primaryForeground" \| "secondary" \| "secondaryForeground" \| "accent" \| "accentForeground" \| "border" \| "ring") | yes | "foreground" |  |
+| `font` | enum("display" \| "body" \| "mono") | yes | "body" |  |
 | `position` | enum("top" \| "center" \| "bottom") | yes | "center" |  |
 | `showCursor` | boolean | yes | true |  |
+| `size` | enum("xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl" \| "3xl" \| "4xl" \| "5xl" \| "6xl") | yes | "2xl" |  |
 | `speed` | number | yes | 2 | min=0.5, max=5 |
+| `weight` | enum("regular" \| "medium" \| "semibold" \| "bold" \| "black") | yes | "semibold" |  |
 
 #### Category: `transition`
 
@@ -1406,7 +1700,7 @@ Props:
 - internal: `false`
 - children: `yes (1..∞)`
 - description: Circular iris reveal/hide transition wrapper
-- llmGuidance: direction="open" reveals from center, direction="close" hides to a point. center controls origin.
+- llmGuidance: direction controls reveal vs hide; center controls origin. duration uses theme motion tokens.
 
 Props:
 
@@ -1414,7 +1708,7 @@ Props:
 | - | - | - | - | - |
 | `center` | object | no |  | additionalProperties=false |
 | `direction` | enum("open" \| "close") | yes | "open" |  |
-| `durationInFrames` | integer | yes | 30 | min=10, max=60 |
+| `duration` | enum("fast" \| "base" \| "slow") | yes | "fast" |  |
 | `phase` | enum("in" \| "out" \| "inOut") | yes | "inOut" |  |
 
 ##### `FadeTransition`
@@ -1424,13 +1718,13 @@ Props:
 - internal: `false`
 - children: `yes (1..∞)`
 - description: Fade in/out wrapper (used for segment transitions and overlays)
-- llmGuidance: Use for gentle transitions. durationInFrames ~30 is standard.
+- llmGuidance: Use for gentle transitions. duration uses theme motion tokens.
 
 Props:
 
 | Prop | Type | Required | Default | Notes |
 | - | - | - | - | - |
-| `durationInFrames` | integer | yes | 30 | min=10, max=60 |
+| `duration` | enum("fast" \| "base" \| "slow") | yes | "fast" |  |
 | `easing` | enum("linear" \| "easeIn" \| "easeOut" \| "easeInOut") | yes | "easeInOut" |  |
 | `phase` | enum("in" \| "out" \| "inOut") | yes | "inOut" |  |
 
@@ -1440,16 +1734,16 @@ Props:
 - category: `transition`
 - internal: `false`
 - children: `yes (1..∞)`
-- description: Slide in/out wrapper (used for segment transitions and overlays)
-- llmGuidance: Use for more dynamic transitions. direction controls where content enters from.
+- description: Slide in/out wrapper transition
+- llmGuidance: Use for directional movement. duration and distance use theme motion tokens.
 
 Props:
 
 | Prop | Type | Required | Default | Notes |
 | - | - | - | - | - |
 | `direction` | enum("left" \| "right" \| "up" \| "down") | yes | "left" |  |
-| `distance` | integer | yes | 160 | min=1, max=2000 |
-| `durationInFrames` | integer | yes | 30 | min=10, max=60 |
+| `distance` | enum("enter" \| "nudge" \| "travel") | yes | "travel" |  |
+| `duration` | enum("fast" \| "base" \| "slow") | yes | "fast" |  |
 | `phase` | enum("in" \| "out" \| "inOut") | yes | "inOut" |  |
 
 ##### `WipeTransition`
@@ -1459,14 +1753,14 @@ Props:
 - internal: `false`
 - children: `yes (1..∞)`
 - description: Directional wipe reveal/hide wrapper transition
-- llmGuidance: Use as a more stylized reveal. softEdge can make it feel less harsh.
+- llmGuidance: Use as a more stylized reveal. softEdge can make it feel less harsh. duration uses theme motion tokens.
 
 Props:
 
 | Prop | Type | Required | Default | Notes |
 | - | - | - | - | - |
 | `direction` | enum("left" \| "right" \| "up" \| "down" \| "diagonal") | yes | "right" |  |
-| `durationInFrames` | integer | yes | 30 | min=10, max=60 |
+| `duration` | enum("fast" \| "base" \| "slow") | yes | "fast" |  |
 | `phase` | enum("in" \| "out" \| "inOut") | yes | "inOut" |  |
 | `softEdge` | boolean | yes | false |  |
 
@@ -1477,13 +1771,13 @@ Props:
 - internal: `false`
 - children: `yes (1..∞)`
 - description: Zoom in/out wrapper transition
-- llmGuidance: Use for energetic cuts. type="zoomIn" feels punchy; type="zoomOut" feels calmer.
+- llmGuidance: Use for energetic cuts. type controls zoom direction. duration uses theme motion tokens.
 
 Props:
 
 | Prop | Type | Required | Default | Notes |
 | - | - | - | - | - |
-| `durationInFrames` | integer | yes | 30 | min=10, max=60 |
+| `duration` | enum("fast" \| "base" \| "slow") | yes | "fast" |  |
 | `phase` | enum("in" \| "out" \| "inOut") | yes | "inOut" |  |
 | `type` | enum("zoomIn" \| "zoomOut") | yes | "zoomIn" |  |
 
@@ -1496,30 +1790,30 @@ The `examples/` directory contains validated IR JSON files you can use as starti
 Quick validate:
 
 ```bash
-npx waves validate --in examples/basic.v2.json
+npx waves validate --in examples/basic.v3.json
 ```
 
 Validate all examples:
 
 ```powershell
-Get-ChildItem examples -Filter *.v2.json | ForEach-Object { npx waves validate --in $_.FullName }
+Get-ChildItem examples -Filter *.v3.json | ForEach-Object { npx waves validate --in $_.FullName }
 ```
 
 Render (writes an MP4; `examples/*.mp4` are gitignored):
 
 ```bash
-npx waves render --in examples/basic.v2.json --out examples/basic.v2.mp4 --codec h264 --crf 28 --concurrency 1
+npx waves render --in examples/basic.v3.json --out examples/basic.v3.mp4 --codec h264 --crf 28 --concurrency 1
 ```
 
 If an example references `/assets/...`, you must provide those files and pass `--publicDir`:
 
 ```bash
-npx waves render --in examples/intro-stats-outro.v2.json --out examples/intro-stats-outro.v2.mp4 --publicDir ./public
+npx waves render --in examples/intro-stats-outro.v3.json --out examples/intro-stats-outro.v3.mp4 --publicDir ./public
 ```
 
 ### Example 0: basic starter (segments + composites)
 
-File: `examples/basic.v2.json`
+File: `examples/basic.v3.json`
 
 This is the default starter IR used by `waves write-ir --template basic`. It demonstrates:
 
@@ -1530,60 +1824,33 @@ This is the default starter IR used by `waves write-ir --template basic`. It dem
 
 ```json
 {
-  "version": "2.0",
-  "video": {
-    "id": "main",
-    "width": 1920,
-    "height": 1080,
-    "fps": 30,
-    "durationInFrames": 165
-  },
+  "version": "3.0",
+  "video": { "id": "main", "width": 1920, "height": 1080, "fps": 30, "durationInFrames": 168 },
+  "theme": { "preset": "studio-dark" },
   "segments": [
     {
       "id": "scene-1",
       "durationInFrames": 90,
-      "transitionToNext": {
-        "type": "FadeTransition",
-        "durationInFrames": 15
-      },
+      "transitionToNext": { "type": "FadeTransition", "duration": "fast" },
       "root": {
         "id": "root",
         "type": "Scene",
-        "props": {
-          "background": { "type": "color", "value": "#000000" }
-        },
+        "props": { "background": { "type": "color", "token": "background" } },
         "children": [
           {
             "id": "title",
             "type": "SplitText",
-            "props": {
-              "content": "Waves v0.2.0",
-              "fontSize": 96,
-              "splitBy": "word",
-              "stagger": 3,
-              "animation": "slideUp"
-            }
+            "props": { "content": "Waves v0.5.0", "size": "5xl", "color": "foreground", "font": "display", "weight": "black", "splitBy": "word", "stagger": "fast", "animation": "slideUp" }
           },
           {
             "id": "subtitle",
             "type": "TypewriterText",
-            "props": {
-              "content": "Composite components + hybrid IR",
-              "fontSize": 48,
-              "position": "bottom",
-              "speed": 1.5
-            }
+            "props": { "content": "Unified tokens + presets", "size": "2xl", "color": "mutedForeground", "font": "body", "weight": "semibold", "position": "bottom", "speed": 1.5 }
           },
           {
             "id": "wm",
             "type": "Watermark",
-            "props": {
-              "type": "text",
-              "text": "@depths.ai",
-              "position": "bottomRight",
-              "opacity": 0.4,
-              "size": 60
-            }
+            "props": { "type": "text", "text": "@depths.ai", "position": "bottomRight", "opacity": "subtle", "size": "16", "color": "mutedForeground", "textSize": "lg" }
           }
         ]
       }
@@ -1594,25 +1861,11 @@ This is the default starter IR used by `waves write-ir --template basic`. It dem
       "root": {
         "id": "root-2",
         "type": "Scene",
-        "props": {
-          "background": { "type": "color", "value": "#0B1220" }
-        },
+        "props": { "background": { "type": "color", "token": "surface" } },
         "children": [
-          {
-            "id": "lower-third",
-            "type": "ThirdLowerBanner",
-            "props": { "name": "Waves", "title": "v0.2.0 - Composites + transitions", "accentColor": "#3B82F6" }
-          },
-          {
-            "id": "count",
-            "type": "AnimatedCounter",
-            "props": { "from": 0, "to": 35, "suffix": " components", "fontSize": 96, "color": "#FFFFFF" }
-          },
-          {
-            "id": "wm-2",
-            "type": "Watermark",
-            "props": { "type": "text", "text": "waves", "position": "topLeft", "opacity": 0.25, "size": 52 }
-          }
+          { "id": "lower-third", "type": "ThirdLowerBanner", "props": { "name": "Waves", "title": "v0.5.0 - Robustness & polish", "accent": "primary", "background": "surface" } },
+          { "id": "count", "type": "AnimatedCounter", "props": { "from": 0, "to": 35, "suffix": " components", "size": "5xl", "color": "foreground" } },
+          { "id": "wm-2", "type": "Watermark", "props": { "type": "text", "text": "waves", "position": "topLeft", "opacity": "faint", "size": "12", "color": "mutedForeground", "textSize": "md" } }
         ]
       }
     }
@@ -1622,14 +1875,15 @@ This is the default starter IR used by `waves write-ir --template basic`. It dem
 
 ### Example 1: primitives-only layout
 
-File: `examples/primitives-card.v2.json`
+File: `examples/primitives-card.v3.json`
 
 This example uses only primitives: `Scene`, `Box`, `Grid`, `Shape`, `Text`.
 
 ```json
 {
-  "version": "2.0",
+  "version": "3.0",
   "video": { "id": "main", "width": 1920, "height": 1080, "fps": 30, "durationInFrames": 150 },
+  "theme": { "preset": "studio-dark" },
   "segments": [
     {
       "id": "card",
@@ -1637,49 +1891,49 @@ This example uses only primitives: `Scene`, `Box`, `Grid`, `Shape`, `Text`.
       "root": {
         "id": "scene",
         "type": "Scene",
-        "props": { "background": { "type": "color", "value": "#0B1220" } },
+        "props": { "background": { "type": "color", "token": "surface" } },
         "children": [
-          { "id": "accent", "type": "Shape", "props": { "shape": "rect", "x": 180, "y": 200, "width": 12, "height": 680, "fill": "#3B82F6", "opacity": 1 } },
+          { "id": "accent", "type": "Shape", "props": { "shape": "rect", "x": 180, "y": 200, "width": 12, "height": 680, "fill": "primary", "opacity": 1 } },
           {
             "id": "panel",
-            "type": "Box",
-            "props": { "x": 192, "y": 200, "width": 1548, "height": 680, "padding": 0, "backgroundColor": "rgba(255,255,255,0.06)", "borderRadius": 36, "opacity": 1 },
+            "type": "Frame",
+            "props": { "x": 192, "y": 200, "width": 1548, "height": 680, "padding": "0", "backgroundColor": "surface", "borderRadius": "lg", "opacity": 0.7 },
             "children": [
               {
                 "id": "panel-grid",
                 "type": "Grid",
-                "props": { "columns": 2, "rows": 2, "gap": 28, "padding": 64, "align": "stretch", "justify": "stretch" },
+                "props": { "columns": 2, "rows": 2, "gap": "8", "padding": "16", "align": "stretch", "justify": "stretch" },
                 "children": [
                   {
                     "id": "tile-1",
                     "type": "Box",
-                    "props": { "x": 0, "y": 0, "padding": 40, "backgroundColor": "rgba(255,255,255,0.07)", "borderRadius": 24 },
+                    "props": { "padding": "10", "backgroundColor": "muted", "borderRadius": "lg", "opacity": 0.8 },
                     "children": [
-                      { "id": "t1", "type": "Text", "props": { "content": "Primitives", "fontSize": 64, "position": "center", "animation": "fade" } }
+                      { "id": "t1", "type": "Text", "props": { "content": "Primitives", "size": "3xl", "position": "center", "animation": "fade" } }
                     ]
                   },
                   {
                     "id": "tile-2",
                     "type": "Box",
-                    "props": { "x": 0, "y": 0, "padding": 40, "backgroundColor": "rgba(255,255,255,0.07)", "borderRadius": 24 },
+                    "props": { "padding": "10", "backgroundColor": "muted", "borderRadius": "lg", "opacity": 0.8 },
                     "children": [
-                      { "id": "t2", "type": "Text", "props": { "content": "Box + Grid", "fontSize": 54, "position": "center", "animation": "slide" } }
+                      { "id": "t2", "type": "Text", "props": { "content": "Box + Grid", "size": "2xl", "position": "center", "animation": "slide" } }
                     ]
                   },
                   {
                     "id": "tile-3",
                     "type": "Box",
-                    "props": { "x": 0, "y": 0, "padding": 40, "backgroundColor": "rgba(255,255,255,0.07)", "borderRadius": 24 },
+                    "props": { "padding": "10", "backgroundColor": "muted", "borderRadius": "lg", "opacity": 0.8 },
                     "children": [
-                      { "id": "t3", "type": "Text", "props": { "content": "Shape", "fontSize": 54, "position": "center", "animation": "zoom" } }
+                      { "id": "t3", "type": "Text", "props": { "content": "Shape", "size": "2xl", "position": "center", "animation": "zoom" } }
                     ]
                   },
                   {
                     "id": "tile-4",
                     "type": "Box",
-                    "props": { "x": 0, "y": 0, "padding": 40, "backgroundColor": "rgba(255,255,255,0.07)", "borderRadius": 24 },
+                    "props": { "padding": "10", "backgroundColor": "muted", "borderRadius": "lg", "opacity": 0.8 },
                     "children": [
-                      { "id": "t4", "type": "Text", "props": { "content": "Text", "fontSize": 54, "position": "center", "animation": "fade" } }
+                      { "id": "t4", "type": "Text", "props": { "content": "Text", "size": "2xl", "position": "center", "animation": "fade" } }
                     ]
                   }
                 ]
@@ -1691,10 +1945,12 @@ This example uses only primitives: `Scene`, `Box`, `Grid`, `Shape`, `Text`.
             "type": "Text",
             "props": {
               "content": "This entire layout is built from primitives only.",
-              "fontSize": 34,
               "position": "bottom",
               "animation": "fade",
-              "color": "#C7D2FE"
+              "size": "xl",
+              "color": "mutedForeground",
+              "font": "body",
+              "weight": "medium"
             }
           }
         ]
@@ -1708,64 +1964,65 @@ This example uses only primitives: `Scene`, `Box`, `Grid`, `Shape`, `Text`.
 
 When authoring segments with overlaps, the total end time is:
 
-`sum(segments[i].durationInFrames) - sum(segments[i].transitionToNext.durationInFrames)`
+`sum(segments[i].durationInFrames) - sum(theme.motion.durationsInFrames[segments[i].transitionToNext.duration])`
 
 Example 2 has 4 segments:
 
 - segment durations: 90 + 90 + 90 + 90 = 360
-- overlap durations: 15 + 15 + 15 = 45
-- video duration: 360 - 45 = 315 (must match `video.durationInFrames`)
+- overlap durations: 24 + 24 + 24 = 72 (for the `studio-dark` preset where `"base"` = 24 frames)
+- video duration: 360 - 72 = 288 (must match `video.durationInFrames`)
 
 ### Example 2: segment transitions showcase
 
-File: `examples/transitions-showcase.v2.json`
+File: `examples/transitions-showcase.v3.json`
 
 This example shows how to chain segments with overlaps using `transitionToNext`.
 
 ```json
 {
-  "version": "2.0",
-  "video": { "id": "main", "width": 1920, "height": 1080, "fps": 30, "durationInFrames": 315 },
+  "version": "3.0",
+  "video": { "id": "main", "width": 1920, "height": 1080, "fps": 30, "durationInFrames": 288 },
+  "theme": { "preset": "studio-dark" },
   "segments": [
     {
       "id": "s1",
       "durationInFrames": 90,
-      "transitionToNext": { "type": "FadeTransition", "durationInFrames": 15 },
+      "transitionToNext": { "type": "FadeTransition", "duration": "base" },
       "root": {
         "id": "scene-1",
         "type": "Scene",
-        "props": { "background": { "type": "color", "value": "#000000" } },
+        "props": { "background": { "type": "color", "token": "background" } },
         "children": [
-          { "id": "title-1", "type": "SplitText", "props": { "content": "FadeTransition", "fontSize": 100, "splitBy": "word", "stagger": 3, "animation": "slideUp", "position": "center" } },
-          { "id": "wm-1", "type": "Watermark", "props": { "type": "text", "text": "waves", "position": "bottomRight", "opacity": 0.35, "size": 60 } }
+          { "id": "title-1", "type": "SplitText", "props": { "content": "FadeTransition", "size": "6xl", "splitBy": "word", "stagger": "fast", "animation": "slideUp", "position": "center" } },
+          { "id": "wm-1", "type": "Watermark", "props": { "type": "text", "text": "waves", "position": "bottomRight", "opacity": "subtle", "color": "mutedForeground", "textSize": "lg" } }
         ]
       }
     },
     {
       "id": "s2",
       "durationInFrames": 90,
-      "transitionToNext": { "type": "SlideTransition", "durationInFrames": 15, "props": { "direction": "left", "distance": 120 } },
+      "transitionToNext": { "type": "SlideTransition", "duration": "base", "props": { "direction": "left", "distance": "travel" } },
       "root": {
         "id": "scene-2",
         "type": "Scene",
-        "props": { "background": { "type": "color", "value": "#0B1220" } },
+        "props": { "background": { "type": "color", "token": "surface" } },
         "children": [
-          { "id": "title-2", "type": "SplitText", "props": { "content": "SlideTransition", "fontSize": 96, "splitBy": "word", "stagger": 3, "animation": "slideUp", "position": "center" } },
-          { "id": "subtitle-2", "type": "TypewriterText", "props": { "content": "direction=left, distance=120", "fontSize": 44, "position": "bottom", "speed": 1.6, "showCursor": true } }
+          { "id": "title-2", "type": "SplitText", "props": { "content": "SlideTransition", "size": "6xl", "splitBy": "word", "stagger": "fast", "animation": "slideUp", "position": "center" } },
+          { "id": "subtitle-2", "type": "TypewriterText", "props": { "content": "direction=left, distance=travel", "size": "xl", "position": "bottom", "speed": 1.6, "showCursor": true } }
         ]
       }
     },
     {
       "id": "s3",
       "durationInFrames": 90,
-      "transitionToNext": { "type": "WipeTransition", "durationInFrames": 15, "props": { "direction": "diagonal", "softEdge": true } },
+      "transitionToNext": { "type": "WipeTransition", "duration": "base", "props": { "direction": "diagonal", "softEdge": true } },
       "root": {
         "id": "scene-3",
         "type": "Scene",
-        "props": { "background": { "type": "color", "value": "#111827" } },
+        "props": { "background": { "type": "color", "token": "muted" } },
         "children": [
-          { "id": "title-3", "type": "SplitText", "props": { "content": "WipeTransition", "fontSize": 96, "splitBy": "word", "stagger": 3, "animation": "scale", "position": "center" } },
-          { "id": "subtitle-3", "type": "TypewriterText", "props": { "content": "direction=diagonal, softEdge=true", "fontSize": 44, "position": "bottom", "speed": 1.6, "showCursor": false } }
+          { "id": "title-3", "type": "SplitText", "props": { "content": "WipeTransition", "size": "6xl", "splitBy": "word", "stagger": "fast", "animation": "scale", "position": "center" } },
+          { "id": "subtitle-3", "type": "TypewriterText", "props": { "content": "direction=diagonal, softEdge=true", "size": "xl", "position": "bottom", "speed": 1.6, "showCursor": false } }
         ]
       }
     },
@@ -1775,10 +2032,10 @@ This example shows how to chain segments with overlaps using `transitionToNext`.
       "root": {
         "id": "scene-4",
         "type": "Scene",
-        "props": { "background": { "type": "color", "value": "#000000" } },
+        "props": { "background": { "type": "color", "token": "background" } },
         "children": [
-          { "id": "title-4", "type": "SplitText", "props": { "content": "Done", "fontSize": 120, "splitBy": "letter", "stagger": 2, "animation": "rotate", "position": "center" } },
-          { "id": "wm-4", "type": "Watermark", "props": { "type": "text", "text": "@depths.ai", "position": "bottomRight", "opacity": 0.4, "size": 60 } }
+          { "id": "title-4", "type": "SplitText", "props": { "content": "Done", "size": "6xl", "splitBy": "letter", "stagger": "fast", "animation": "rotate", "position": "center" } },
+          { "id": "wm-4", "type": "Watermark", "props": { "type": "text", "text": "@depths.ai", "position": "bottomRight", "opacity": "subtle", "color": "mutedForeground", "textSize": "lg" } }
         ]
       }
     }
@@ -1788,7 +2045,7 @@ This example shows how to chain segments with overlaps using `transitionToNext`.
 
 ### Example 3: data dashboard
 
-File: `examples/data-dashboard.v2.json`
+File: `examples/data-dashboard.v3.json`
 
 This example uses data composites inside a `Grid`:
 
@@ -1799,8 +2056,9 @@ This example uses data composites inside a `Grid`:
 
 ```json
 {
-  "version": "2.0",
+  "version": "3.0",
   "video": { "id": "main", "width": 1920, "height": 1080, "fps": 30, "durationInFrames": 180 },
+  "theme": { "preset": "studio-dark" },
   "segments": [
     {
       "id": "dashboard",
@@ -1808,14 +2066,14 @@ This example uses data composites inside a `Grid`:
       "root": {
         "id": "scene",
         "type": "Scene",
-        "props": { "background": { "type": "color", "value": "#0B1220" } },
+        "props": { "background": { "type": "color", "token": "surface" } },
         "children": [
           {
             "id": "grid",
             "type": "Grid",
-            "props": { "columns": 2, "rows": 2, "gap": 36, "padding": 90, "align": "stretch", "justify": "stretch" },
+            "props": { "columns": 2, "rows": 2, "gap": "8", "padding": "24", "align": "stretch", "justify": "stretch" },
             "children": [
-              { "id": "ring", "type": "ProgressRing", "props": { "percentage": 72, "size": 260, "color": "#22C55E", "showLabel": true } },
+              { "id": "ring", "type": "ProgressRing", "props": { "percentage": 72, "size": "xl", "color": "secondary", "showLabel": true } },
               {
                 "id": "bars",
                 "type": "BarChart",
@@ -1824,10 +2082,10 @@ This example uses data composites inside a `Grid`:
                   "showValues": true,
                   "showGrid": true,
                   "data": [
-                    { "label": "A", "value": 32, "color": "#3B82F6" },
-                    { "label": "B", "value": 56, "color": "#22C55E" },
-                    { "label": "C", "value": 18, "color": "#F59E0B" },
-                    { "label": "D", "value": 44, "color": "#EF4444" }
+                    { "label": "A", "value": 32, "color": "primary" },
+                    { "label": "B", "value": 56, "color": "secondary" },
+                    { "label": "C", "value": 18, "color": "accent" },
+                    { "label": "D", "value": 44, "color": "ring" }
                   ]
                 }
               },
@@ -1835,8 +2093,8 @@ This example uses data composites inside a `Grid`:
                 "id": "line",
                 "type": "LineGraph",
                 "props": {
-                  "color": "#60A5FA",
-                  "strokeWidth": 4,
+                  "color": "primary",
+                  "strokeWidth": "2",
                   "showDots": true,
                   "fillArea": true,
                   "animate": "draw",
@@ -1850,10 +2108,10 @@ This example uses data composites inside a `Grid`:
                   ]
                 }
               },
-              { "id": "progress", "type": "ProgressBar", "props": { "label": "Rendering", "position": "bottom", "height": 16, "color": "#A855F7", "showPercentage": true } }
+              { "id": "progress", "type": "ProgressBar", "props": { "label": "Rendering", "position": "bottom", "height": "4", "barColor": "accent", "showPercentage": true } }
             ]
           },
-          { "id": "title", "type": "SplitText", "props": { "content": "Data composites", "fontSize": 86, "splitBy": "word", "stagger": 3, "animation": "slideUp", "position": "top" } }
+          { "id": "title", "type": "SplitText", "props": { "content": "Data composites", "size": "5xl", "splitBy": "word", "stagger": "fast", "animation": "slideUp", "position": "top" } }
         ]
       }
     }
@@ -1863,7 +2121,7 @@ This example uses data composites inside a `Grid`:
 
 ### Example 4: vertical social-style video (9:16)
 
-File: `examples/social-vertical.v2.json`
+File: `examples/social-vertical.v3.json`
 
 This example uses:
 
@@ -1873,19 +2131,20 @@ This example uses:
 
 ```json
 {
-  "version": "2.0",
-  "video": { "id": "main", "width": 1080, "height": 1920, "fps": 30, "durationInFrames": 225 },
+  "version": "3.0",
+  "video": { "id": "main", "width": 1080, "height": 1920, "fps": 30, "durationInFrames": 216 },
+  "theme": { "preset": "studio-dark" },
   "segments": [
     {
       "id": "ig",
       "durationInFrames": 120,
-      "transitionToNext": { "type": "CircularReveal", "durationInFrames": 15, "props": { "direction": "open", "center": { "x": 0.5, "y": 0.45 } } },
+      "transitionToNext": { "type": "CircularReveal", "duration": "base", "props": { "direction": "open", "center": { "x": 0.5, "y": 0.45 } } },
       "root": {
         "id": "ig-root",
         "type": "Scene",
-        "props": { "background": { "type": "color", "value": "#000000" } },
+        "props": { "background": { "type": "color", "token": "background" } },
         "children": [
-          { "id": "ig", "type": "InstagramStory", "props": { "backgroundColor": "#0B1220", "username": "depths.ai", "text": "Waves v0.2.0 ships composites + hybrid IR", "sticker": "poll" } }
+          { "id": "ig", "type": "InstagramStory", "props": { "background": "background", "username": "depths.ai", "text": "Waves v0.5.0 improves robustness + performance", "sticker": "poll" } }
         ]
       }
     },
@@ -1895,10 +2154,10 @@ This example uses:
       "root": {
         "id": "tt-root",
         "type": "Scene",
-        "props": { "background": { "type": "color", "value": "#0B1220" } },
+        "props": { "background": { "type": "color", "token": "surface" } },
         "children": [
-          { "id": "caption", "type": "TikTokCaption", "props": { "text": "Composites make LLM video authoring dramatically easier", "position": "bottom", "highlightStyle": "bounce", "fontSize": 58, "strokeWidth": 4 } },
-          { "id": "wm", "type": "Watermark", "props": { "type": "text", "text": "@depths.ai", "position": "topRight", "opacity": 0.35, "size": 72 } }
+          { "id": "caption", "type": "TikTokCaption", "props": { "text": "Token-only styling makes LLM video authoring dramatically easier", "position": "bottom", "highlightStyle": "bounce", "size": "4xl", "strokeWidth": "2" } },
+          { "id": "wm", "type": "Watermark", "props": { "type": "text", "text": "@depths.ai", "position": "topRight", "opacity": "subtle", "color": "mutedForeground", "textSize": "lg" } }
         ]
       }
     }
@@ -1908,7 +2167,7 @@ This example uses:
 
 ### Example 5: intro -> stats -> outro (assets)
 
-File: `examples/intro-stats-outro.v2.json`
+File: `examples/intro-stats-outro.v3.json`
 
 This example uses branding + layout + data composites:
 
@@ -1920,34 +2179,35 @@ It references `/assets/logo.svg` style paths; supply those files and pass `--pub
 
 ```json
 {
-  "version": "2.0",
-  "video": { "id": "main", "width": 1920, "height": 1080, "fps": 30, "durationInFrames": 360 },
+  "version": "3.0",
+  "video": { "id": "main", "width": 1920, "height": 1080, "fps": 30, "durationInFrames": 342 },
+  "theme": { "preset": "studio-dark" },
   "segments": [
     {
       "id": "intro",
       "durationInFrames": 120,
-      "transitionToNext": { "type": "FadeTransition", "durationInFrames": 15 },
+      "transitionToNext": { "type": "FadeTransition", "duration": "base" },
       "root": {
         "id": "intro-scene",
         "type": "Scene",
-        "props": { "background": { "type": "color", "value": "#000000" } },
+        "props": { "background": { "type": "color", "token": "background" } },
         "children": [
-          { "id": "intro", "type": "IntroScene", "props": { "logoSrc": "/assets/logo.svg", "companyName": "Depths AI", "tagline": "Waves v0.2.0", "backgroundColor": "#000000", "primaryColor": "#FFFFFF" } }
+          { "id": "intro", "type": "IntroScene", "props": { "logoSrc": "/assets/logo.svg", "companyName": "Depths AI", "tagline": "Waves v0.5.0" } }
         ]
       }
     },
     {
       "id": "stats",
       "durationInFrames": 150,
-      "transitionToNext": { "type": "SlideTransition", "durationInFrames": 15, "props": { "direction": "up", "distance": 140 } },
+      "transitionToNext": { "type": "SlideTransition", "duration": "base", "props": { "direction": "up", "distance": "travel" } },
       "root": {
         "id": "stats-scene",
         "type": "Scene",
-        "props": { "background": { "type": "color", "value": "#0B1220" } },
+        "props": { "background": { "type": "color", "token": "surface" } },
         "children": [
-          { "id": "lower-third", "type": "ThirdLowerBanner", "props": { "name": "Waves", "title": "Composite components", "accentColor": "#22C55E" } },
-          { "id": "counter", "type": "AnimatedCounter", "props": { "from": 0, "to": 44, "suffix": " types", "fontSize": 110, "color": "#FFFFFF", "animationType": "spring" } },
-          { "id": "bars", "type": "BarChart", "props": { "orientation": "horizontal", "showValues": true, "showGrid": false, "data": [ { "label": "Primitives", "value": 10, "color": "#3B82F6" }, { "label": "Composites", "value": 34, "color": "#22C55E" } ] } }
+          { "id": "lower-third", "type": "ThirdLowerBanner", "props": { "name": "Waves", "title": "Composite components", "accent": "secondary" } },
+          { "id": "counter", "type": "AnimatedCounter", "props": { "from": 0, "to": 48, "suffix": " types", "size": "6xl", "color": "foreground", "animationType": "spring" } },
+          { "id": "bars", "type": "BarChart", "props": { "orientation": "horizontal", "showValues": true, "showGrid": false, "data": [ { "label": "Primitives", "value": 12, "color": "primary" }, { "label": "Composites", "value": 36, "color": "secondary" } ] } }
         ]
       }
     },
@@ -1957,7 +2217,7 @@ It references `/assets/logo.svg` style paths; supply those files and pass `--pub
       "root": {
         "id": "outro-scene",
         "type": "Scene",
-        "props": { "background": { "type": "color", "value": "#000000" } },
+        "props": { "background": { "type": "color", "token": "background" } },
         "children": [
           {
             "id": "outro",
@@ -1965,18 +2225,11 @@ It references `/assets/logo.svg` style paths; supply those files and pass `--pub
             "props": {
               "logoSrc": "/assets/logo.svg",
               "message": "Thanks for watching",
-              "backgroundColor": "#000000",
-              "ctaButtons": [
-                { "text": "Star", "icon": "*" },
-                { "text": "Follow", "icon": "->" }
-              ],
-              "socialHandles": [
-                { "platform": "twitter", "handle": "@depths_ai" },
-                { "platform": "youtube", "handle": "@depths-ai" }
-              ]
+              "ctaButtons": [ { "text": "Star", "icon": "*" }, { "text": "Follow", "icon": "->" } ],
+              "socialHandles": [ { "platform": "twitter", "handle": "@depths_ai" }, { "platform": "youtube", "handle": "@depths-ai" } ]
             }
           },
-          { "id": "wm", "type": "Watermark", "props": { "type": "text", "text": "@depths.ai", "position": "bottomRight", "opacity": 0.25, "size": 64 } }
+          { "id": "wm", "type": "Watermark", "props": { "type": "text", "text": "@depths.ai", "position": "bottomRight", "opacity": "faint", "color": "mutedForeground", "textSize": "lg" } }
         ]
       }
     }
@@ -1986,7 +2239,7 @@ It references `/assets/logo.svg` style paths; supply those files and pass `--pub
 
 ### Example 6: timeline mode (global audio)
 
-File: `examples/timeline-global-audio.v2.json`
+File: `examples/timeline-global-audio.v3.json`
 
 This example uses `timeline[]` to place a global `Audio` track as a root node spanning the entire video.
 
@@ -1994,17 +2247,18 @@ This is a common reason to choose timeline mode over segments mode: you want "gl
 
 ```json
 {
-  "version": "2.0",
+  "version": "3.0",
   "video": { "id": "main", "width": 1920, "height": 1080, "fps": 30, "durationInFrames": 150 },
+  "theme": { "preset": "studio-dark" },
   "timeline": [
     {
       "id": "scene",
       "type": "Scene",
       "timing": { "from": 0, "durationInFrames": 150 },
-      "props": { "background": { "type": "color", "value": "#0B1220" } },
+      "props": { "background": { "type": "color", "token": "surface" } },
       "children": [
-        { "id": "title", "type": "SplitText", "props": { "content": "Timeline mode", "fontSize": 96, "splitBy": "word", "stagger": 3, "animation": "slideUp", "position": "top" } },
-        { "id": "subtitle", "type": "TypewriterText", "props": { "content": "Audio spans the whole video", "fontSize": 44, "position": "bottom", "speed": 1.4, "showCursor": false } }
+        { "id": "title", "type": "SplitText", "props": { "content": "Timeline mode", "size": "6xl", "splitBy": "word", "stagger": "fast", "animation": "slideUp", "position": "top" } },
+        { "id": "subtitle", "type": "TypewriterText", "props": { "content": "Audio spans the whole video", "size": "xl", "position": "bottom", "speed": 1.4, "showCursor": false } }
       ]
     },
     {
@@ -2024,8 +2278,9 @@ import { renderVideo } from '@depths/waves';
 
 await renderVideo(
   {
-    version: '2.0',
+    version: '3.0',
     video: { id: 'main', width: 1920, height: 1080, fps: 30, durationInFrames: 60 },
+    theme: { preset: 'studio-dark' },
     segments: [
       {
         id: 'scene-1',
@@ -2033,7 +2288,7 @@ await renderVideo(
         root: {
           id: 'root',
           type: 'Scene',
-          props: { background: { type: 'color', value: '#000000' } },
+          props: { background: { type: 'color', token: 'background' } },
           children: [{ id: 't1', type: 'Text', props: { content: 'Hello' } }]
         }
       }
@@ -2043,7 +2298,7 @@ await renderVideo(
 );
 ```
 
-## Assets and paths (Windows/Linux)
+## Assets and paths (Windows/Linux)
 
 In IR JSON, asset paths must be either:
 
@@ -2052,12 +2307,33 @@ In IR JSON, asset paths must be either:
 
 On Windows:
 
-- Prefer forward slashes in IR (`/assets/foo.png`), not `C:\\...` paths.
-- If you pass Windows paths to the CLI (e.g. `--out`), quote them if they contain spaces.
-
-## Rendering prerequisites
-
-Waves uses `@remotion/renderer` (Remotion 4.x). Remotion runs headless Chromium; if a compatible browser isn't available, it may download one automatically (or you can configure browser paths via Remotion). Remotion 4 also ships its own ffmpeg binary, so you typically do not need `ffmpeg` installed on your PATH.
+- Prefer forward slashes in IR (`/assets/foo.png`), not `C:\\...` paths.
+- If you pass Windows paths to the CLI (e.g. `--out`), quote them if they contain spaces.
+
+## Robustness / Troubleshooting
+
+### Missing local assets
+
+If your IR contains local `/assets/...` references, you **must** pass `--publicDir` (CLI) / `publicDir` (library). Waves checks that referenced files exist under `<publicDir>/assets/...` before bundling/rendering and fails fast with a structured error listing missing assets.
+
+### Theme font loading failures
+
+Theme fonts are loaded via `FontFace` at render time. If any font fails to load, Waves cancels the render with a clear error. Use either:
+
+- a local `/assets/...` font with `--publicDir`, or
+- a full `http(s)://...` URL.
+
+### Segment duration mismatches
+
+In segments mode, the expected total duration is:
+
+`sum(segment.durationInFrames) - sum(overlapFrames)`
+
+Where each overlap is derived from the `segment.transitionToNext.duration` token resolved from the theme (`theme.motion.durationsInFrames`). If you see `DURATION_MISMATCH`, set `video.durationInFrames` to the expected duration (the validator error message includes a breakdown).
+
+## Rendering prerequisites
+
+Waves uses `@remotion/renderer` (Remotion 4.x). Remotion runs headless Chromium; if a compatible browser isn't available, it may download one automatically (or you can configure browser paths via Remotion). Remotion 4 also ships its own ffmpeg binary, so you typically do not need `ffmpeg` installed on your PATH.
 
 ## Local CLI testing (before publishing)
 
@@ -2067,9 +2343,9 @@ From the `waves/` package directory:
 npm install
 npm run build
 node dist/cli.js --help
-node dist/cli.js write-ir --template basic --pretty --out examples/basic.v2.json
-node dist/cli.js validate --in examples/basic.v2.json
-node dist/cli.js render --in examples/basic.v2.json --out examples/basic.v2.mp4 --codec h264 --crf 28 --concurrency 1
+node dist/cli.js write-ir --template basic --pretty --out examples/basic.v3.json
+node dist/cli.js validate --in examples/basic.v3.json
+node dist/cli.js render --in examples/basic.v3.json --out examples/basic.v3.mp4 --codec h264 --crf 28 --concurrency 1
 ```
 
 To test the installed experience:
@@ -2101,7 +2377,7 @@ The build emits ESM into `dist/`. Most CLI tests execute the built CLI via `node
 
 - `src/cli.ts`: the CLI (`waves <command> ...`)
 - `src/llm/prompt.ts`: system prompt + prompt payload (schemas + catalog)
-- `src/ir/schema.ts`: IR v2.0 Zod schemas (authoring + full IR)
+- `src/ir/schema.ts`: IR v3.0 Zod schemas (authoring + full IR)
 - `src/ir/migrations.ts`: compiler (`compileToRenderGraph`) from authored IR -> render timeline
 - `src/core/registry.ts`: component registry + JSON Schema export for LLM use
 - `src/core/validator.ts`: schema + semantics + registry validation