From 049b4b5202fefebd32f00dc55e50afe0eb4796ef Mon Sep 17 00:00:00 2001
From: Kiyeon Jeon <kiyeon.jeon.21@gmail.com>
Date: Mon, 22 Jun 2026 22:55:48 +0900
Subject: [PATCH 1/3] feat(cli): --theme brand kit + theme-aware batch (design
 re-skin surface)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Phase 2c. `render/frame/player --theme brand.json` applies a brand kit (a nested
partial theme, flattened to a design.* overlay and composed first so --overlay
still wins). `batch` gains a `design.<token.path>` column, so one data file
renders one on-brand mp4 per row — on-brand video at scale. Reuses the 2b
overlay machinery (composeScene); no core change.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 packages/render-cli/src/batch.ts           |  5 ++-
 packages/render-cli/src/cli.ts             | 10 +++---
 packages/render-cli/src/frame.ts           |  6 ++--
 packages/render-cli/src/overlay.ts         | 42 +++++++++++++++++-----
 packages/render-cli/src/player.ts          | 14 +++++---
 packages/render-cli/src/reframe.ts         | 12 ++++---
 packages/render-cli/test/theme-cli.test.ts | 42 ++++++++++++++++++++++
 7 files changed, 106 insertions(+), 25 deletions(-)
 create mode 100644 packages/render-cli/test/theme-cli.test.ts

diff --git a/packages/render-cli/src/batch.ts b/packages/render-cli/src/batch.ts
index 016cab0..c1ffd6d 100644
--- a/packages/render-cli/src/batch.ts
+++ b/packages/render-cli/src/batch.ts
@@ -56,9 +56,12 @@ export function overlayFromFlat(row: FlatRow, name: string): OverlayDoc {
         );
       }
       (doc.scene ??= {})[sceneKey as "background" | "duration" | "fps"] = value as never;
+    } else if (head === "design" && parts.length >= 2) {
+      // a design-token re-skin column, e.g. "design.color.accent" -> one mp4 per brand
+      (doc.design ??= {})[parts.slice(1).join(".")] = value;
     } else {
       throw new Error(
-        `row key "${key}" is not a valid overlay address — expected nodes.<id>.<prop>, states.<state>.<id>.<prop>, timeline.<label>.<duration|ease|stagger>, or scene.<background|duration|fps>`,
+        `row key "${key}" is not a valid overlay address — expected nodes.<id>.<prop>, states.<state>.<id>.<prop>, timeline.<label>.<duration|ease|stagger>, scene.<background|duration|fps>, or design.<token.path>`,
       );
     }
   }
diff --git a/packages/render-cli/src/cli.ts b/packages/render-cli/src/cli.ts
index 5caa815..194a60a 100755
--- a/packages/render-cli/src/cli.ts
+++ b/packages/render-cli/src/cli.ts
@@ -24,6 +24,7 @@ interface Args {
   keepFrames: boolean;
   framesDir?: string;
   overlays: string[];
+  theme?: string;
   noAudio: boolean;
   /** Composition: render only this scene id, standalone. */
   scene?: string;
@@ -54,6 +55,7 @@ function parseArgs(argv: string[]): Args {
     else if (a === "--keep-frames") args.keepFrames = true;
     else if (a === "--frames-dir") args.framesDir = resolve(rest[++i]!);
     else if (a === "--overlay") args.overlays.push(resolve(rest[++i]!));
+    else if (a === "--theme") args.theme = resolve(rest[++i]!);
     else if (a === "--no-audio") args.noAudio = true;
     else if (a === "--scene") args.scene = rest[++i]!;
     else {
@@ -71,8 +73,8 @@ async function main() {
   // concatenates (its own frame/temp handling), so branch before the per-scene path.
   const loaded = args.mode === "ir" ? await loadModule(args.input) : null;
   if (loaded?.kind === "composition") {
-    if (args.overlays.length > 0) {
-      console.error("note: overlays apply per-scene, not to a composition — ignored here");
+    if (args.overlays.length > 0 || args.theme) {
+      console.error("note: overlays / --theme apply per-scene, not to a composition — ignored here");
     }
     const { duration, sceneCount } = await renderComposition(loaded.ir, {
       compositionPath: args.input,
@@ -95,8 +97,8 @@ async function main() {
   let audioJob: { plan: import("@reframe/core").AudioPlan; videoOut: string } | null = null;
   if (args.mode === "ir") {
     let ir = loaded!.ir;
-    if (args.overlays.length > 0) {
-      const composed = await applyOverlays(ir, args.overlays);
+    if (args.overlays.length > 0 || args.theme) {
+      const composed = await applyOverlays(ir, args.overlays, args.theme);
       console.error(formatComposeReport(composed.report));
       ir = composed.ir;
     }
diff --git a/packages/render-cli/src/frame.ts b/packages/render-cli/src/frame.ts
index 898c86b..61772dd 100644
--- a/packages/render-cli/src/frame.ts
+++ b/packages/render-cli/src/frame.ts
@@ -24,11 +24,13 @@ async function main(): Promise<void> {
   let t = 0;
   let out = "";
   const overlays: string[] = [];
+  let theme: string | undefined;
   for (let i = 1; i < argv.length; i++) {
     const a = argv[i]!;
     if (a === "--t") t = Number(argv[++i]);
     else if (a === "-o") out = argv[++i]!;
     else if (a === "--overlay") overlays.push(resolve(argv[++i]!));
+    else if (a === "--theme") theme = resolve(argv[++i]!);
     else {
       console.error(`unknown argument: ${a}`);
       process.exit(2);
@@ -46,8 +48,8 @@ async function main(): Promise<void> {
     process.exit(2);
   }
   let ir = loaded.ir;
-  if (overlays.length > 0) {
-    const composed = await applyOverlays(ir, overlays);
+  if (overlays.length > 0 || theme) {
+    const composed = await applyOverlays(ir, overlays, theme);
     console.error(formatComposeReport(composed.report));
     ir = composed.ir;
   }
diff --git a/packages/render-cli/src/overlay.ts b/packages/render-cli/src/overlay.ts
index 7f8c896..f7ee6c6 100644
--- a/packages/render-cli/src/overlay.ts
+++ b/packages/render-cli/src/overlay.ts
@@ -5,20 +5,46 @@
  * overlays and report applied/orphans identically.
  */
 import { readFile } from "node:fs/promises";
-import { composeScene, type ComposeReport, type OverlayDoc, type SceneIR } from "@reframe/core";
+import { basename } from "node:path";
+import { composeScene, type ComposeReport, type OverlayDoc, type PropValue, type SceneIR } from "@reframe/core";
+
+/** Flatten a nested theme object to dotted scalar leaves (skipping arrays): `{color:{accent}}` -> `{"color.accent":…}`. */
+export function flattenTokens(obj: unknown, prefix = ""): Record<string, PropValue> {
+  const out: Record<string, PropValue> = {};
+  if (!obj || typeof obj !== "object" || Array.isArray(obj)) return out;
+  for (const [k, v] of Object.entries(obj as Record<string, unknown>)) {
+    const path = prefix ? `${prefix}.${k}` : k;
+    if (typeof v === "string" || typeof v === "number") out[path] = v;
+    else if (v && typeof v === "object" && !Array.isArray(v)) Object.assign(out, flattenTokens(v, path));
+  }
+  return out;
+}
+
+/**
+ * Load a brand-kit JSON (a NESTED partial theme, e.g. `{ "color": { "accent": "#1E90FF" } }`)
+ * as a `design` OverlayDoc — the `--theme` path. Flattens its scalar leaves to the dotted
+ * `design.<path>` address form `composeScene` applies.
+ */
+export async function loadThemeDoc(themePath: string): Promise<OverlayDoc> {
+  const parsed = JSON.parse(await readFile(themePath, "utf8")) as unknown;
+  return { reframeOverlay: 1, name: basename(themePath), design: flattenTokens(parsed) };
+}
 
 /**
- * Compose `overlayPaths` (JSON OverlayDocs) onto `ir`. Returns the composed IR and
- * the report (applied/orphans/warnings). With no overlays, returns `ir` unchanged
- * and an empty report. The composed IR is validated by `composeScene`.
+ * Compose `overlayPaths` (JSON OverlayDocs) onto `ir`, optionally prefixed by a `--theme`
+ * brand kit (`themePath`). The theme is composed FIRST so a `--overlay` can still override it.
+ * Returns the composed IR and the report. With nothing to apply, returns `ir` unchanged.
  */
 export async function applyOverlays(
   ir: SceneIR,
   overlayPaths: string[],
+  themePath?: string,
 ): Promise<{ ir: SceneIR; report: ComposeReport }> {
-  if (overlayPaths.length === 0) return { ir, report: { applied: [], orphans: [], warnings: [] } };
-  const docs = await Promise.all(
-    overlayPaths.map(async (p) => JSON.parse(await readFile(p, "utf8")) as OverlayDoc),
-  );
+  if (overlayPaths.length === 0 && !themePath) {
+    return { ir, report: { applied: [], orphans: [], warnings: [] } };
+  }
+  const docs: OverlayDoc[] = [];
+  if (themePath) docs.push(await loadThemeDoc(themePath));
+  for (const p of overlayPaths) docs.push(JSON.parse(await readFile(p, "utf8")) as OverlayDoc);
   return composeScene(ir, ...docs);
 }
diff --git a/packages/render-cli/src/player.ts b/packages/render-cli/src/player.ts
index 5b5abc6..94aa562 100644
--- a/packages/render-cli/src/player.ts
+++ b/packages/render-cli/src/player.ts
@@ -23,7 +23,7 @@ import { fileURLToPath } from "node:url";
 import type { OverlayDoc } from "@reframe/core";
 import { formatComposeReport } from "@reframe/core";
 import { loadModule } from "./loadScene.js";
-import { applyOverlays } from "./overlay.js";
+import { applyOverlays, loadThemeDoc } from "./overlay.js";
 
 const PACKAGED = process.env.REFRAME_PACKAGED === "1";
 const HERE = dirname(fileURLToPath(import.meta.url));
@@ -123,9 +123,11 @@ async function main(): Promise<void> {
   let edit = false;
   let editOrigin = "*";
   let initialT = 0;
+  let theme: string | undefined;
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i]!;
     if (a === "--overlay") overlays.push(resolve(argv[++i]!));
+    else if (a === "--theme") theme = resolve(argv[++i]!);
     else if (a === "--edit") edit = true;
     else if (a === "--edit-origin") editOrigin = argv[++i]!;
     else if (a === "--t") initialT = Number(argv[++i]);
@@ -133,7 +135,7 @@ async function main(): Promise<void> {
   }
   const [scenePath, outPath] = positional;
   if (!scenePath || !outPath) {
-    console.error("usage: player <scene.ts|.json> [--overlay <doc.json>]... [--edit [--t <sec>]] <out.html>");
+    console.error("usage: player <scene.ts|.json> [--overlay <doc.json>]... [--theme <brand.json>] [--edit [--t <sec>]] <out.html>");
     process.exit(2);
   }
 
@@ -145,18 +147,20 @@ async function main(): Promise<void> {
       console.error("player --edit needs a single scene (not a composition)");
       process.exit(2);
     }
-    const docs = await Promise.all(overlays.map(async (p) => JSON.parse(await readFile(p, "utf8")) as OverlayDoc));
+    const docs: OverlayDoc[] = [];
+    if (theme) docs.push(await loadThemeDoc(theme));
+    for (const p of overlays) docs.push(JSON.parse(await readFile(p, "utf8")) as OverlayDoc);
     entry = editEntry(JSON.stringify(loaded.ir), JSON.stringify(docs), initialT, JSON.stringify(editOrigin));
   } else {
     // default build: import the scene file, or inline the composed IR when --overlay is given
     let sceneSource = `import sceneIR from ${JSON.stringify(scenePath)};`;
-    if (overlays.length > 0) {
+    if (overlays.length > 0 || theme) {
       const loaded = await loadModule(scenePath);
       if (loaded.kind !== "scene") {
         console.error("player needs a single scene (not a composition)");
         process.exit(2);
       }
-      const composed = await applyOverlays(loaded.ir, overlays);
+      const composed = await applyOverlays(loaded.ir, overlays, theme);
       console.error(formatComposeReport(composed.report));
       sceneSource = `const sceneIR = ${JSON.stringify(composed.ir)};`;
     }
diff --git a/packages/render-cli/src/reframe.ts b/packages/render-cli/src/reframe.ts
index 9c9455c..6835e5b 100644
--- a/packages/render-cli/src/reframe.ts
+++ b/packages/render-cli/src/reframe.ts
@@ -97,12 +97,12 @@ const PLUGIN_DIR = PACKAGED ? ROOT : join(ROOT, "plugin");
 const USAGE = `reframe — declarative motion graphics
 
 usage:
-  ${CMD} render <scene.ts|.json|.html> [--overlay edits.json]... [-o out.mp4] [--fps N] [--duration S] [--no-audio]
+  ${CMD} render <scene.ts|.json|.html> [--overlay edits.json]... [--theme brand.json] [-o out.mp4] [--fps N] [--duration S] [--no-audio]
   ${CMD} batch <scene.ts> <data.json|csv> [-o outDir] [--overlay base.json]... [--concurrency N] [--fps N]
   ${CMD} logo <logo.svg|brand-slug> ["Name"] [--motion <preset>] [--energy 0..1] [--seed N] [-o out.mp4]
                                  animate a logo into a sting (presets: draw-bloom, punch-in,
                                  rise-settle, slide-bank, reveal-orbit, spin-forge)
-  ${CMD} player <scene.ts|.json> [--overlay <doc.json>]... [--edit [--t <sec>]] [-o out.html]  bundle a scene into one
+  ${CMD} player <scene.ts|.json> [--overlay <doc.json>]... [--theme brand.json] [--edit [--t <sec>]] [-o out.html]  bundle a scene into one
                                  self-contained HTML player (visual only; --overlay previews edits; --edit = embedded-editor
                                  build with window.__reframe { seek, hitTest, bounds, waypoints, setOverlay } + postMessage)
   ${CMD} preview                 open the scrub/edit UI (lists scenes in your directory)
@@ -120,7 +120,7 @@ usage:
                                  compose overlay(s) onto a scene → composed SceneIR (no render; feed to player/frame for live preview)
   ${CMD} compile <scene.ts|.json> [-o out.json] [--stdin] [--code "<src>"] [--json]
                                  bundle + validate a scene to SceneIR JSON, no render (fast; no ffmpeg/chromium)
-  ${CMD} frame <scene.ts|.json> [--t <sec>] [--overlay <doc.json>]... [-o out.png]  render ONE frame at time t to a PNG (no mp4; --overlay previews edits)
+  ${CMD} frame <scene.ts|.json> [--t <sec>] [--overlay <doc.json>]... [--theme brand.json] [-o out.png]  render ONE frame at time t to a PNG (no mp4; --overlay/--theme preview edits)
   ${CMD} skill [--path]          print the authoring skill (SKILL.md) for an agent; --path prints the plugin dir to load
   ${CMD} motion <mp4|framesDir>  motion-profile a rendered clip
   ${CMD} trace <ref.mp4> [--apply scene.ts]  extract a video's motion structure → MotionSketch / timeline
@@ -277,9 +277,11 @@ async function main() {
         await mkdir(dir, { recursive: true });
         outArgs = args.map((a, i) => (i === oIdx + 1 ? join(dir, stem) : a));
       }
-      // user-relative paths for overlays and -o (idempotent on the absolute -o we just built)
+      // user-relative paths for overlays, --theme and -o (idempotent on the absolute -o we just built)
       outArgs = outArgs.map((a, i) =>
-        outArgs[i - 1] === "--overlay" || outArgs[i - 1] === "-o" ? userPath(a) : a,
+        outArgs[i - 1] === "--overlay" || outArgs[i - 1] === "--theme" || outArgs[i - 1] === "-o"
+          ? userPath(a)
+          : a,
       );
       process.exit(
         await (PACKAGED
diff --git a/packages/render-cli/test/theme-cli.test.ts b/packages/render-cli/test/theme-cli.test.ts
new file mode 100644
index 0000000..4fcab6e
--- /dev/null
+++ b/packages/render-cli/test/theme-cli.test.ts
@@ -0,0 +1,42 @@
+import { mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { flattenTokens, loadThemeDoc } from "../src/overlay.js";
+import { overlayFromFlat } from "../src/batch.js";
+
+describe("flattenTokens", () => {
+  it("flattens a nested theme to dotted scalar leaves, skipping arrays", () => {
+    expect(
+      flattenTokens({ color: { accent: "#1E90FF", dataViz: ["#a", "#b"] }, motion: { energy: 0.7 } }),
+    ).toEqual({ "color.accent": "#1E90FF", "motion.energy": 0.7 });
+  });
+
+  it("is empty for a non-object", () => {
+    expect(flattenTokens("nope")).toEqual({});
+  });
+});
+
+describe("loadThemeDoc (--theme path)", () => {
+  it("loads a nested brand-kit JSON as a flattened design overlay", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "reframe-theme-"));
+    const p = join(dir, "ocean.json");
+    await writeFile(p, JSON.stringify({ color: { accent: "#1E90FF", bg: "#0B1020" } }));
+    const doc = await loadThemeDoc(p);
+    expect(doc.reframeOverlay).toBe(1);
+    expect(doc.name).toBe("ocean.json");
+    expect(doc.design).toEqual({ "color.accent": "#1E90FF", "color.bg": "#0B1020" });
+  });
+});
+
+describe("batch overlayFromFlat — design.* column", () => {
+  it("maps a design-token column into doc.design (one re-skin per row)", () => {
+    const doc = overlayFromFlat(
+      { _name: "vivid", "design.color.accent": "#FF3D6E", "nodes.title.content": "Vivid" },
+      "vivid",
+    );
+    expect(doc.design).toEqual({ "color.accent": "#FF3D6E" });
+    expect(doc.nodes?.title?.content).toBe("Vivid");
+    expect(doc.name).toBe("vivid");
+  });
+});

From 34b92948259f30ba0cad7abe64d349f14cec0a20 Mon Sep 17 00:00:00 2001
From: Kiyeon Jeon <kiyeon.jeon.21@gmail.com>
Date: Mon, 22 Jun 2026 22:55:48 +0900
Subject: [PATCH 2/3] docs(examples): 3-brand batch + a sample --theme brand
 kit

themed-card-brands.json renders themed-card into vivid/mono/ocean mp4s in one
batch; ocean.json is a nested brand kit for the --theme path.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 examples/data/themed-card-brands.json | 5 +++++
 examples/themes/ocean.json            | 7 +++++++
 2 files changed, 12 insertions(+)
 create mode 100644 examples/data/themed-card-brands.json
 create mode 100644 examples/themes/ocean.json

diff --git a/examples/data/themed-card-brands.json b/examples/data/themed-card-brands.json
new file mode 100644
index 0000000..ef5d509
--- /dev/null
+++ b/examples/data/themed-card-brands.json
@@ -0,0 +1,5 @@
+[
+  { "_name": "vivid", "nodes.title.content": "Vivid", "design.color.accent": "#FF3D6E", "design.color.bg": "#140A1E", "design.color.surface": "#241433" },
+  { "_name": "mono", "nodes.title.content": "Mono", "design.color.accent": "#E6E6EA", "design.color.bg": "#0C0C0E", "design.color.surface": "#1A1A1E" },
+  { "_name": "ocean", "nodes.title.content": "Ocean", "design.color.accent": "#1E90FF", "design.color.bg": "#0B1020", "design.color.surface": "#141B2E" }
+]
diff --git a/examples/themes/ocean.json b/examples/themes/ocean.json
new file mode 100644
index 0000000..3fa49ca
--- /dev/null
+++ b/examples/themes/ocean.json
@@ -0,0 +1,7 @@
+{
+  "color": {
+    "accent": "#1E90FF",
+    "bg": "#0B1020",
+    "surface": "#141B2E"
+  }
+}

From 04d2362dc76fe72bd395dada62ec2df0076a25c7 Mon Sep 17 00:00:00 2001
From: Kiyeon Jeon <kiyeon.jeon.21@gmail.com>
Date: Mon, 22 Jun 2026 22:55:48 +0900
Subject: [PATCH 3/3] docs(brand): teach token() re-skin, --theme, and batch
 design columns

Guide/DESIGN.md/SKILL/READMEs/AGENTS document the now-complete design-token
surface: token() for re-skinnable scenes, --theme brand kits, and per-brand
batch. Bumps the plugin to 0.1.13 (SKILL.md change).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 AGENTS.md                         | 16 ++++++++++++++--
 DESIGN.md                         | 18 ++++++++++++++++--
 README.md                         |  4 ++--
 docs/guides/edsl-guide.md         | 24 ++++++++++++++++++++++++
 packages/reframe-video/README.md  |  4 ++--
 plugin/.claude-plugin/plugin.json |  2 +-
 plugin/skills/reframe/SKILL.md    |  5 ++++-
 7 files changed, 63 insertions(+), 10 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index f13f2ed..9e890e8 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -11,8 +11,8 @@ deterministic mp4 render. Human edits survive AI regeneration of the base.
 
 ## Commands
 
-- `pnpm reframe render <scene.ts|.html> [--overlay f] [-o out]` — mp4 into `out/`
-- `pnpm reframe batch <scene.ts> <data.json|csv>` — one mp4 per row (row keys are overlay addresses like `nodes.<id>.<prop>`)
+- `pnpm reframe render <scene.ts|.html> [--overlay f] [--theme brand.json] [-o out]` — mp4 into `out/`; `--theme` re-skins `token()` colors (a brand kit is a nested partial theme; also on `frame`/`player`)
+- `pnpm reframe batch <scene.ts> <data.json|csv>` — one mp4 per row (row keys are overlay addresses like `nodes.<id>.<prop>` or `design.<token.path>` for a per-brand re-skin)
 - `pnpm reframe logo <logo.svg | brand-slug> [--motion <preset>] [--energy n] [--seed n]` — animate a logo into a sting (published CLI command; `packages/render-cli/src/logoSting.ts`)
 - `pnpm reframe labels <scene.ts>` — print the compiled event clock (every timeline label → exact seconds; the timing source for `audio.cues` and beat debugging)
 - `pnpm reframe compile <scene.ts|.json> [-o out.json] [--stdin] [--code "<src>"] [--json]` — bundle + validate eDSL source into SceneIR JSON, NO render (no ffmpeg/chromium; fast). On failure: a concise classified error (`bundle`/`eval`/`validation`), never the base64 bundle; `--json` makes it `{ok:false,error,kind,issues?}` where `issues` is the structured validation problems (each `{code,path,message}` — e.g. `code:"unknown-blend", path:"nodes.box"`). The in-process equivalent is exported as `reframe-video/compile` (`loadScene`/`loadSceneFromCode`/`checkDeterminism`, server-only); a thrown `SceneValidationError` carries `.issues` (and `.problems` for back-compat), and `SceneLoadError.issues` propagates them across the scene bundle. Entry `packages/render-cli/src/compile.ts`; loader `loadScene.ts`.
@@ -158,6 +158,18 @@ no `Math.random()`/`Date` (use `wiggle` with a seed, or pass a `seed` knob).
   spread into node `x`/`y` (a row of cards, a grid of tiles) — pure math, no nodes. Both
   added after a fresh-user reproducibility test flagged hand-positioned affixes + absolute-only
   layout as the main friction.
+- Design tokens / brand (`packages/core/src/theme.ts`, `DESIGN.md`) — the house brand as code:
+  `brand` (the DESIGN.md values) + `theme(overrides)` (deep-merge a reusable brand kit). `brand.color.accent`
+  bakes the literal at author time; `token("color.accent")` is a DEFERRED ref the compiler resolves
+  against the scene's `design?: DeepPartial<Theme>` field (falling back to `brand`), scoped to color
+  props (`fill`/`stroke`/`shadowColor`). Golden-safe via `CompiledScene.hasDesign` (no `design`/`$ref`
+  → byte-identical; resolution only touches `$`-strings on color props, so a text `content:"$5M"` is
+  untouched). Overlay-addressable as `design.<token.path>` (`compose.ts`, validated against the brand
+  shape, regen-stable by name, orphan-clean); `sceneManifest().design` surfaces them. Re-skin via
+  `render/frame/player --theme brand.json` (a nested partial theme, flattened in `render-cli/overlay.ts`
+  `loadThemeDoc`) or a `batch` `design.<token.path>` column (one mp4 per brand). Demo
+  `examples/scenes/themed-card.ts` + `examples/data/themed-card-brands.json`. Numeric/type/gradient-stop
+  tokens + scene-`background` tokens are a later phase.
 - Photo/video montage (`packages/core/src/montage.ts`) — `photoMontage(shots, opts)` /
   `videoMontage` (same generator) turn a list of shots — images AND video clips, mixed
   (video detected by src extension, plays as a clip for its `hold`, audio muted by default
diff --git a/DESIGN.md b/DESIGN.md
index 01227c0..54555ac 100644
--- a/DESIGN.md
+++ b/DESIGN.md
@@ -75,8 +75,22 @@ const myBrand = theme({ color: { accent: "#1E90FF" } });
 
 `packages/core/src/theme.ts` is the source of truth for the values; this document mirrors and
 explains them. (`brand` is pure data, so referencing a token renders byte-identical to writing
-the literal. An engine-level `theme` field that the compiler resolves and an overlay can re-skin
-is a later phase.)
+the literal.)
+
+For a scene you want to RE-SKIN later, use `token("color.accent")` on a color prop instead of a
+literal. It is a deferred reference the compiler resolves against the scene's `design` (or the
+house brand), so the same scene renders in any brand:
+
+```ts
+import { rect, token } from "reframe-video";
+rect({ id: "bar", fill: token("color.accent") });
+```
+
+Then re-skin with no edit to the scene: `reframe frame scene.ts --theme brand.json` (a brand kit
+is a nested partial theme), or a `batch` data file with a `design.<token.path>` column (one mp4
+per brand). An overlay can patch `design.color.accent` directly, and the re-skin survives an AI
+regen of the base (the address is the token name). Color props resolve tokens today; numeric and
+type tokens are a later phase.
 
 ## Brand
 
diff --git a/README.md b/README.md
index f944aec..cf4e538 100644
--- a/README.md
+++ b/README.md
@@ -287,8 +287,8 @@ and `liquid-glass-nav.ts` (nav bar over a photo).
 
 | command | what it does |
 |---|---|
-| `pnpm reframe render <scene.ts\|.json\|.html> [--overlay f]... [-o out]` | deterministic mp4 (mode inferred from extension; output defaults to `out/`) |
-| `pnpm reframe batch <scene.ts> <data.json\|csv> [-o dir] [--overlay f]...` | one mp4 per data row (rows = overlays), parallel, with a per-row report |
+| `pnpm reframe render <scene.ts\|.json\|.html> [--overlay f]... [--theme brand.json] [-o out]` | deterministic mp4 (mode inferred from extension; output defaults to `out/`); `--theme` re-skins `token()` colors |
+| `pnpm reframe batch <scene.ts> <data.json\|csv> [-o dir] [--overlay f]...` | one mp4 per data row (rows = overlays; a `design.<token.path>` column = one mp4 per brand), parallel, with a per-row report |
 | `pnpm reframe compile <scene.ts\|.json> [-o out.json] [--json]` | bundle + validate a scene to SceneIR JSON, no render (fast; no ffmpeg/chromium); `--json` returns `{ok, kind, issues}` |
 | `pnpm reframe frame <scene.ts\|.json> [--t <sec>] [--overlay f]... [-o out.png]` | render one frame at time `t` to a PNG (chromium only, no mux); `--overlay` previews edits |
 | `pnpm reframe compose <scene.ts\|.json> --overlay f... [-o out.json] [--json]` | compose overlay(s) onto a scene and emit composed SceneIR, no render (feed to `player`/`frame` for live preview) |
diff --git a/docs/guides/edsl-guide.md b/docs/guides/edsl-guide.md
index 5f1eda4..fa563ce 100644
--- a/docs/guides/edsl-guide.md
+++ b/docs/guides/edsl-guide.md
@@ -61,6 +61,30 @@ const myBrand = theme({ color: { accent: "#1E90FF" } });
 `brand.motion.*`, and `brand.layout.*` cover the tokens above. Referencing a token is
 byte-identical to writing the literal.
 
+### Re-skinnable scenes (`token()`)
+
+`brand.color.accent` bakes the literal at author time. For a scene you want to RE-SKIN later,
+use `token("color.accent")` on a color prop (`fill` / `stroke` / `shadowColor`) instead. It is a
+deferred reference the compiler resolves against the scene's `design` (or the house brand), so
+the same scene renders in any brand:
+
+```ts
+import { rect, token } from "@reframe/core";
+rect({ id: "bar", fill: token("color.accent") }); // resolves to the active theme
+```
+
+Re-skin without touching the scene:
+
+- one frame/render: `reframe frame scene.ts --theme brand.json` (a brand kit is a nested partial
+  theme, e.g. `{ "color": { "accent": "#1E90FF" } }`).
+- many brands at once: a `batch` data file with a `design.<token.path>` column (plus `_name`)
+  renders one mp4 per brand:
+  `[{ "_name": "ocean", "design.color.accent": "#1E90FF" }, …]` →
+  `reframe batch scene.ts brands.json`.
+
+An overlay can also patch `design.color.accent` directly, and that re-skin survives an AI regen
+of the base (the address is the token name). Only color props resolve tokens today.
+
 ## Nodes
 
 Factories return plain data. Every node needs a unique `id`.
diff --git a/packages/reframe-video/README.md b/packages/reframe-video/README.md
index 189a7e4..b2edd65 100644
--- a/packages/reframe-video/README.md
+++ b/packages/reframe-video/README.md
@@ -20,8 +20,8 @@ npx reframe-video render hello.ts    # → out/hello.mp4
 
 | command | what it does |
 |---|---|
-| `reframe render <scene.ts> [--overlay edits.json] [-o out.mp4]` | deterministic mp4 |
-| `reframe batch <scene.ts> <data.json\|csv>` | one mp4 per data row (row keys are overlay addresses) |
+| `reframe render <scene.ts> [--overlay edits.json] [--theme brand.json] [-o out.mp4]` | deterministic mp4; `--theme` re-skins `token()` colors |
+| `reframe batch <scene.ts> <data.json\|csv>` | one mp4 per data row (row keys are overlay addresses; a `design.<token.path>` column = one mp4 per brand) |
 | `reframe compile <scene.ts> [-o out.json] [--json]` | bundle + validate a scene to SceneIR JSON, no render (fast; no ffmpeg/chromium) |
 | `reframe frame <scene.ts> [--t <sec>] [-o out.png]` | render one frame at time `t` to a PNG (chromium only, no mux) |
 | `reframe compose <scene.ts> --overlay f... [-o out.json]` | compose overlay(s) onto a scene and emit composed SceneIR, no render |
diff --git a/plugin/.claude-plugin/plugin.json b/plugin/.claude-plugin/plugin.json
index 688f7d0..019cabe 100644
--- a/plugin/.claude-plugin/plugin.json
+++ b/plugin/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "reframe",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "description": "Create and iterate motion-graphics videos as addressable data: deterministic mp4 renders, human edits that survive AI regeneration, label-anchored audio, data-driven batch rendering.",
   "author": {
     "name": "Kiyeon Jeon",
diff --git a/plugin/skills/reframe/SKILL.md b/plugin/skills/reframe/SKILL.md
index 333e27d..2b37287 100644
--- a/plugin/skills/reframe/SKILL.md
+++ b/plugin/skills/reframe/SKILL.md
@@ -26,7 +26,10 @@ runtime needs ffmpeg on PATH and a one-time `npx playwright install chromium`
    house style in the guide's **Brand / house style** section: background
    `#0A0C14`, foreground `#FFFFFF`, accent `#FF4D00` (with `#00C2A8` secondary),
    Inter, and a Balanced motion tone (`easeOutCubic`, entrances `easeOutBack`,
-   `energy: 0.5`). A user-supplied brief always overrides it.
+   `energy: 0.5`). A user-supplied brief always overrides it. If the scene needs
+   to be RE-SKINNABLE (multiple brands, or a brand kit applied later), color it
+   with `token("color.accent")` etc. on `fill`/`stroke` instead of literals, then
+   re-skin with `--theme brand.json` or a `batch` `design.<token.path>` column.
 3. Iterate on the cheap commands; full-render once at the end:
    - `npx -y reframe-video compile <name>.ts` — validate eDSL → IR in ~1s, no
      browser, no ffmpeg. Fix the classified error it prints, repeat. Catch every