diff --git a/docs/changelog.mdx b/docs/changelog.mdx
index cfd139e036..647f59b659 100644
--- a/docs/changelog.mdx
+++ b/docs/changelog.mdx
@@ -8,6 +8,54 @@ Recent HyperFrames releases, including user-facing features, fixes, and migratio
 
 {/* New release entries are prepended by `bun run changelog:draft <version> --write`. */}
 
+<Update
+  label="Unreleased"
+  description="Migration note"
+  tags={["Migration", "Core"]}
+>
+## Composition variables no longer take over theme token names
+
+A declared composition variable is now written to the CSS custom property
+`--hf-var-<slug>` instead of the bare `--<slug>`.
+
+**Reserved theme-token ids change immediately, with no deprecation period.**
+Fifteen names belong to the page hosting a composition: `accent`, `accent-2`,
+`accent-3`, `accent2`, `bg`, `border`, `brand`, `fg`, `ink`, `muted`,
+`primary`, `secondary`, `surface`, `tertiary`, `text`. A variable using one of
+those ids is now written only to `--hf-var-<slug>`, never to the bare name. The
+old behaviour was already broken rather than useful: a variable declared
+`accent` overwrote the very `--accent` token the composition was trying to
+read, so a composition mapping the value `blue` onto `var(--accent, #18181b)`
+rendered the CSS keyword `blue`, and no host theme could win it back.
+
+**Every other id keeps the bare alias for one deprecation cycle.** A variable
+called `speed` still writes both `--hf-var-speed` and `--speed`. The bare
+alias is deprecated and will be removed in a future release.
+
+### Are you affected
+
+You are affected if a composition binds `var(--<id>)` for an id it declares in
+`data-composition-variables`. List the custom properties your compositions
+read, then compare that list against your declared ids:
+
+```bash
+grep -rho 'var(--[A-Za-z0-9_-]*' . --include='*.html' | sort -u
+```
+
+Any match on a reserved name in the list above stops resolving to the declared
+value once you upgrade. Any other match still resolves, through the deprecated
+alias.
+
+### What to change
+
+Rewrite the binding to the namespaced name: `var(--accent)` becomes
+`var(--hf-var-accent)`. If the value should follow a host theme when one is
+present and fall back to the declared variable otherwise, write
+`var(--accent, var(--hf-var-accent))` instead. Declarations, `--variables`
+overrides, `data-variable-values`, `data-var-text`, `data-var-src`, and
+`getVariables()` are unchanged; only the CSS custom property name moves.
+</Update>
+
 <Update
   label="HyperFrames v0.7.103"
   description="Released - 2026-08-09"
diff --git a/docs/concepts/variables.mdx b/docs/concepts/variables.mdx
index 72f5fa8b98..73ccdfd21e 100644
--- a/docs/concepts/variables.mdx
+++ b/docs/concepts/variables.mdx
@@ -86,15 +86,35 @@ Use direct bindings for the normal cases:
 
 <style>
   .card-title {
-    color: var(--accent);
+    color: var(--hf-var-accent);
   }
 </style>
 ```
 
 - `data-var-text` replaces the element’s own text.
 - `data-var-src` replaces an image, video, audio, or source URL.
-- Scalar variables are available as CSS custom properties such as
-  `var(--accent)`.
+- Scalar variables are available as CSS custom properties named
+  `--hf-var-<slug>`, so the `accent` variable above is read as
+  `var(--hf-var-accent)`.
+
+The slug is the id lowercased, with anything that is not a letter, digit or
+hyphen replaced by a hyphen. So `accentColor` is readable as
+`var(--hf-var-accentcolor)`, and `swap_at` as `var(--hf-var-swap-at)`.
+
+<Note>
+**How a variable is named in CSS.** Every scalar variable is written to
+`--hf-var-<slug>`. It is also written to the bare `--<slug>`, but only when the id
+is not one of the fifteen reserved theme-token names: `accent`, `accent-2`,
+`accent-3`, `accent2`, `bg`, `border`, `brand`, `fg`, `ink`, `muted`,
+`primary`, `secondary`, `surface`, `tertiary`, `text`. Those names belong to
+the page hosting the composition, so a variable never writes them. A variable
+called `accent` cannot shadow the host theme's `--accent`.
+
+The bare `--<slug>` alias is deprecated and will be removed in a future release.
+Bind `var(--hf-var-<slug>)` in new work. When a value should follow the host
+theme if there is one and fall back to the declared variable otherwise, write
+`var(--accent, var(--hf-var-accent))`.
+</Note>
 
 Use `window.__hyperframes.getVariables()` only when the result needs conditions,
 loops, or derived values:
diff --git a/docs/deploy/templates-on-lambda.mdx b/docs/deploy/templates-on-lambda.mdx
index e9e6d9dcd4..49a045db2a 100644
--- a/docs/deploy/templates-on-lambda.mdx
+++ b/docs/deploy/templates-on-lambda.mdx
@@ -30,7 +30,7 @@ example exposes a headline and accent color:
       data-height="1080"
       data-duration="5"
       data-no-timeline
-      style="color:var(--accent)"
+      style="color:var(--hf-var-accent)"
     >
       <h1 data-var-text="title">Welcome</h1>
     </div>
@@ -38,7 +38,10 @@ example exposes a headline and accent color:
 </html>
 ```
 
-See [Variables](/concepts/variables) for every type and binding method.
+A scalar variable is exposed as the CSS custom property `--hf-var-<slug>`, which
+is why the stage binds `var(--hf-var-accent)` rather than `var(--accent)`. See
+[Variables](/concepts/variables) for every type and binding method, and for the
+reserved theme-token names a variable never writes.
 
 ## Test locally
 
diff --git a/docs/prompting/capstone.mdx b/docs/prompting/capstone.mdx
index 4c38cacf1f..d996ca0c16 100644
--- a/docs/prompting/capstone.mdx
+++ b/docs/prompting/capstone.mdx
@@ -97,7 +97,7 @@ That is the same catch-and-tighten loop [Iterating](/prompting/iterating) teache
 >
 > **Technique, pinned:** continuous world-camera via GSAP transforms (the dolly is the film); parallax layers in every region; `data-chart`, `world-map`, `sdf-iris`, and a caption component adapted from the registry; per-character typing at the open; matched-motion handoffs at every region boundary (the wire IS the match); full footage pipeline (generated clip → HEVC → auto-proxy → background removal → lower-third → word-synced captions); real beat grid from `hyperframes beats`; real Three.js via the frame adapter; seeded two-frame-hold confetti; SFX on hits; VO-paced reveals throughout.
 >
-> **Variables:** expose `ground` (default `#0a0a0a`) and `ink` (default `#3CE6AC`) as composition variables on the single root file, bound via CSS custom properties everywhere (including the duotoned mural), so one `--variables` call re-skins the entire journey. It will be rendered twice: the default brand palette, and a second full render with `{"ground":"#0d1420","ink":"#c8ff3d"}`.
+> **Variables:** expose `ground` (default `#0a0a0a`) and `ink` (default `#3CE6AC`) as composition variables on the single root file, bound everywhere via their namespaced CSS custom properties `var(--hf-var-ground)` and `var(--hf-var-ink)` (including the duotoned mural), so one `--variables` call re-skins the entire journey. It will be rendered twice: the default brand palette, and a second full render with `{"ground":"#0d1420","ink":"#c8ff3d"}`.
 >
 > **Architecture constraint (technical):** single composition file — one `index.html`, one variable scope. The world is one wide scene space traversed by a camera transform; regions may still be timed `class="clip"` sections synchronized to the camera's arrival (so capture stays efficient), but their positions form one continuous world and the wire + ruler + protagonist chip layers persist across 100% of the film. No `data-composition-src` sub-files.
 >
@@ -142,6 +142,13 @@ hyperframes render --variables '{"ground":"#0d1420","ink":"#c8ff3d"}' --strict-v
 <video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/capstone-timeline-reskin-v2.mp4#t=0.1" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
 *The same composition, navy and acid green — the wire, ruler, chart, map, glass, and even the generated mural all follow the override.*
 
+Both colors are bound as `var(--hf-var-ground)` and `var(--hf-var-ink)`, not as
+`var(--ground)` and `var(--ink)`. Every declared variable is written to
+`--hf-var-<slug>`, and `ink` is one of the reserved theme-token names (see
+[Variables](/concepts/variables)), so it is written to the namespaced property
+only. A `var(--ink)` binding would have re-skinned the ground and quietly
+ignored the ink.
+
 The mural trick from the previous capstone carries over. The artwork is generated in grayscale, then duotoned live by CSS layers driven by the `ground` and `ink` variables. Even the raster re-skins. Keep color in CSS and shapes in the raster whenever a template frame needs to survive a re-skin.
 
 ## What the prompt actually adds
diff --git a/docs/prompting/design-systems.mdx b/docs/prompting/design-systems.mdx
index 2f1c345540..c786b5a07b 100644
--- a/docs/prompting/design-systems.mdx
+++ b/docs/prompting/design-systems.mdx
@@ -78,7 +78,9 @@ The constant parts come from that one authoring spec, or from one set of importe
 
 When `frame.md` changes, rerun the workflow steps that generate or assemble the affected compositions. That's how the authored HTML picks up the new brand value.
 
-Some compositions already exist and have to re-skin at render time. Declare the shared brand tokens as composition variables instead. Every scalar variable is applied as a `--{id}` CSS custom property on the composition root, so `var(--id)` in your CSS follows the override.
+Some compositions already exist and have to re-skin at render time. Declare the shared brand tokens as composition variables instead. Every scalar variable is applied to the composition root as the CSS custom property `--hf-var-{slug}`, so `var(--hf-var-{slug})` in your CSS follows the override.
+
+Brand work is where the exact name matters. Fifteen role names belong to the page hosting the composition (`accent`, `bg`, `ink`, `primary`, `surface` and the rest of the reserved list in [Variables](/concepts/variables)), and a variable never writes them. So a variable called `accent` is readable as `var(--hf-var-accent)` only, and a stylesheet still saying `var(--accent)` will not follow the override. Bind the namespaced name, or write `var(--accent, var(--hf-var-accent))` when a host theme should win wherever one is defined.
 
 This is where design systems and templating meet. The brand is shared. The content is parameterized.
 
diff --git a/docs/prompting/variables-and-templating.mdx b/docs/prompting/variables-and-templating.mdx
index cf69717c22..be7e818e44 100644
--- a/docs/prompting/variables-and-templating.mdx
+++ b/docs/prompting/variables-and-templating.mdx
@@ -179,10 +179,19 @@ full list and the compile-time-vs-live-DOM rule behind it.
 <Note>
   An authored CSS custom property always wins over a same-named variable. Say
   your composition already defines its own `:root { --accent: ... }` as a
-  hand-written theme token. A variable called `accent` never overwrites it — the
-  authored value stands. A render-time `--variables` override still wins over
-  both. So when you need to override an authored value per render, use
-  `--variables`, not a same-named declared variable.
+  hand-written theme token. A variable called `accent` never overwrites it, and
+  it cannot: `accent` is one of the reserved theme-token names, so the variable
+  is only ever written to `--hf-var-accent`. A render-time `--variables`
+  override lands on `--hf-var-accent` too, so a `var(--accent)` binding keeps
+  showing the authored value. To drive that property per render, bind
+  `var(--hf-var-accent)`, or `var(--accent, var(--hf-var-accent))` if the
+  authored theme should still win whenever it is present.
+
+  For an id that is *not* a reserved theme-token name, the bare `--{slug}` alias
+  is still written: an authored `--{slug}` wins over the declared default, and a
+  render-time `--variables` override wins over both. That alias is deprecated
+  and will be removed in a future release, so prefer `var(--hf-var-{slug})`. The
+  reserved names are listed in [Variables](/concepts/variables).
 </Note>
 
 ## Related
@@ -213,7 +222,7 @@ capstone page.
 This is the clause in the [full capstone prompt](/prompting/capstone#the-prompt-word-for-word)
 that buys the piece — prompt language you can lift for your own video:
 
-> **Variables:** expose `ground` (default `#0a0a0a`) and `ink` (default `#3CE6AC`) as composition variables on the single root file, bound via CSS custom properties everywhere (including the duotoned mural), so one `--variables` call re-skins the entire journey. It will be rendered twice: the default brand palette, and a second full render with `{"ground":"#0d1420","ink":"#c8ff3d"}`.
+> **Variables:** expose `ground` (default `#0a0a0a`) and `ink` (default `#3CE6AC`) as composition variables on the single root file, bound everywhere via their namespaced CSS custom properties `var(--hf-var-ground)` and `var(--hf-var-ink)` (including the duotoned mural), so one `--variables` call re-skins the entire journey. It will be rendered twice: the default brand palette, and a second full render with `{"ground":"#0d1420","ink":"#c8ff3d"}`.
 >
 > **Architecture constraint (technical):** single composition file — one `index.html`, one variable scope. […] No `data-composition-src` sub-files.
 
diff --git a/docs/reference/html-schema.mdx b/docs/reference/html-schema.mdx
index c71613c98c..0596abf7d0 100644
--- a/docs/reference/html-schema.mdx
+++ b/docs/reference/html-schema.mdx
@@ -281,9 +281,13 @@ render or a nested host:
 ></div>
 ```
 
-Use `data-var-text`, `data-var-src`, or CSS `var(--variableId)` for direct
+Use `data-var-text`, `data-var-src`, or CSS `var(--hf-var-<slug>)` for direct
 bindings. Use `getVariables()` when the value affects logic.
 
+A scalar variable is written to `--hf-var-<slug>`. The bare `--<slug>` is a
+deprecated alias, and it is not written at all when `<id>` is one of the fifteen
+reserved theme-token names listed in [Variables](/concepts/variables).
+
 ## Animation contract
 
 A composition using GSAP must:
diff --git a/packages/core/package-subpaths.json b/packages/core/package-subpaths.json
index 2a61955dc0..77481e17d9 100644
--- a/packages/core/package-subpaths.json
+++ b/packages/core/package-subpaths.json
@@ -158,6 +158,12 @@
       "types": "./dist/compiler/htmlDocument.d.ts",
       "environments": ["browser", "bun", "node"]
     },
+    "./runtime/theme-tokens": {
+      "source": "./src/runtime/themeTokens.ts",
+      "runtime": "./dist/runtime/themeTokens.js",
+      "types": "./dist/runtime/themeTokens.d.ts",
+      "environments": ["browser", "bun", "node"]
+    },
     "./runtime/position-edits": {
       "source": "./src/runtime/positionEdits.ts",
       "runtime": "./dist/runtime/positionEdits.js",
diff --git a/packages/core/package.json b/packages/core/package.json
index af846f4539..ad09109402 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -167,6 +167,12 @@
       "import": "./src/compiler/htmlDocument.ts",
       "types": "./src/compiler/htmlDocument.ts"
     },
+    "./runtime/theme-tokens": {
+      "bun": "./src/runtime/themeTokens.ts",
+      "node": "./dist/runtime/themeTokens.js",
+      "import": "./src/runtime/themeTokens.ts",
+      "types": "./src/runtime/themeTokens.ts"
+    },
     "./runtime/position-edits": {
       "bun": "./src/runtime/positionEdits.ts",
       "node": "./dist/runtime/positionEdits.js",
@@ -403,6 +409,10 @@
         "import": "./dist/compiler/htmlDocument.js",
         "types": "./dist/compiler/htmlDocument.d.ts"
       },
+      "./runtime/theme-tokens": {
+        "import": "./dist/runtime/themeTokens.js",
+        "types": "./dist/runtime/themeTokens.d.ts"
+      },
       "./runtime/position-edits": {
         "import": "./dist/runtime/positionEdits.js",
         "types": "./dist/runtime/positionEdits.d.ts"
diff --git a/packages/core/src/compiler/htmlBundler.test.ts b/packages/core/src/compiler/htmlBundler.test.ts
index b820d536fa..e2eea63726 100644
--- a/packages/core/src/compiler/htmlBundler.test.ts
+++ b/packages/core/src/compiler/htmlBundler.test.ts
@@ -1388,3 +1388,91 @@ describe("bundleToSingleHtml", () => {
     }
   });
 });
+
+/** The `<style data-hf-composition-variables>` block the compiler emits, if any. */
+function emittedVariableSheet(bundled: string): string {
+  const { document } = parseHTML(bundled);
+  return document.querySelector("style[data-hf-composition-variables]")?.textContent ?? "";
+}
+
+describe("compiled composition variable properties", () => {
+  /**
+   * The case the authored-<style> guard cannot see: the host theme arrives as
+   * an inline `style` attribute, so nothing in any <style> block mentions
+   * `--accent`. The composition declares `accent: "blue"` — an enum-ish
+   * selector, not a colour — and CSS-binds `color: var(--accent)`.
+   */
+  const HOST_INLINE_THEME = `<!doctype html>
+<html><body>
+  <div
+    id="stage"
+    style="--accent: #7c3aed"
+    data-composition-id="main"
+    data-width="320"
+    data-height="180"
+    data-start="0"
+    data-duration="5">
+    <div
+      id="card"
+      data-composition-variables='[{"id":"accent","type":"string","label":"Accent","default":"blue"},{"id":"cardTitle","type":"string","label":"Title","default":"Hi"}]'>
+      <h1 id="headline" style="color: var(--accent)">Hi</h1>
+    </div>
+  </div>
+  <script>window.__timelines={};</script>
+</body></html>`;
+
+  it("never writes a theme token's bare name, whatever defines the theme", async () => {
+    const bundled = await bundleToSingleHtml(makeTempProject({ "index.html": HOST_INLINE_THEME }));
+    const sheet = emittedVariableSheet(bundled);
+
+    expect(sheet).toContain("--hf-var-accent: blue");
+    // The whole point: `var(--accent)` must keep resolving to the host's
+    // #7c3aed, so the compiled sheet may not define --accent anywhere.
+    expect(sheet).not.toContain("--accent:");
+    expect(bundled).not.toContain("--accent: blue");
+  });
+
+  it("keeps the deprecated bare alias for a non-reserved id", async () => {
+    const bundled = await bundleToSingleHtml(makeTempProject({ "index.html": HOST_INLINE_THEME }));
+    const sheet = emittedVariableSheet(bundled);
+    expect(sheet).toContain("--hf-var-cardtitle: Hi");
+    expect(sheet).toContain("--cardtitle: Hi");
+  });
+
+  /**
+   * Compiler leg of the cross-site agreement gate: the runtime legs are in
+   * runtime/themeTokens.test.ts and the SDK's in
+   * packages/sdk/src/session.variabledecls.test.ts, against these same ids.
+   * A mixed-case id is what exposes drift — the name is slugged once, in
+   * variableCssPropertiesForId, so an author's var(--hf-var-accentcolor)
+   * binding resolves no matter which site defined the property.
+   */
+  const MIXED_CASE_IDS = `<!doctype html>
+<html><body>
+  <div
+    id="stage"
+    data-composition-id="main"
+    data-width="320"
+    data-height="180"
+    data-start="0"
+    data-duration="5"
+    data-composition-variables='[{"id":"accentColor","type":"color","label":"Accent color","default":"#00c3ff"},{"id":"Accent","type":"string","label":"Accent","default":"blue"}]'>
+    <h1 id="headline" style="color: var(--hf-var-accentcolor)">Hi</h1>
+  </div>
+  <script>window.__timelines={};</script>
+</body></html>`;
+
+  it("derives one slugified property per id, whatever the id's casing", async () => {
+    const bundled = await bundleToSingleHtml(makeTempProject({ "index.html": MIXED_CASE_IDS }));
+    const sheet = emittedVariableSheet(bundled);
+
+    expect(sheet).toContain("--hf-var-accentcolor: #00c3ff");
+    expect(sheet).toContain("--accentcolor: #00c3ff");
+    expect(sheet).not.toContain("accentColor");
+    // `Accent` slugs onto the reserved `accent`, so it is reserved here too —
+    // the same id cannot be aliasable on one path and reserved on another.
+    expect(sheet).toContain("--hf-var-accent: blue");
+    expect(sheet).not.toContain("--accent:");
+    expect(sheet).not.toContain("--Accent");
+  });
+});
diff --git a/packages/core/src/compiler/htmlBundler.ts b/packages/core/src/compiler/htmlBundler.ts
index d7f32b77e8..95632dbd1a 100644
--- a/packages/core/src/compiler/htmlBundler.ts
+++ b/packages/core/src/compiler/htmlBundler.ts
@@ -1,7 +1,7 @@
 import { markFlattenedInnerRoot } from "../runtime/flattenedRoot";
 export { FLATTENED_INNER_ROOT_STRIP_ATTRS } from "../runtime/flattenedRoot";
 import { parseHostVariableValues } from "../runtime/getVariables";
-import { cssVariableName } from "../tokenSlug";
+import { collidingCssName, variableCssPropertiesForId } from "../runtime/themeTokens";
 import { readFileSync, existsSync } from "fs";
 import { resolve, relative, dirname, isAbsolute, sep } from "path";
 import { CSS_URL_RE, isNonRelativeUrl } from "./assetPaths.js";
@@ -1128,7 +1128,12 @@ export async function bundleToSingleHtml(
   return document.toString();
 }
 
-/** One stylesheet rule defining primitive composition variables under `selector`. */
+/**
+ * One stylesheet rule defining primitive composition variables under
+ * `selector`. Same namespacing the runtime applies (`variableCssPropertiesForId`)
+ * — the namespaced `--hf-var-{slug}` always, plus the deprecated bare alias
+ * unless the id names a theme token, where writing it would shadow the host's.
+ */
 function compositionVariablesCssBlock(
   variables: Record<string, unknown>,
   selector: string,
@@ -1136,7 +1141,10 @@ function compositionVariablesCssBlock(
   const lines: string[] = [];
   for (const [id, value] of Object.entries(variables)) {
     if ((typeof value === "string" && value !== "") || typeof value === "number") {
-      lines.push(`  ${cssVariableName(id)}: ${String(value)};`);
+      const { namespaced, legacy } = variableCssPropertiesForId(id);
+      for (const name of legacy === null ? [namespaced] : [namespaced, legacy]) {
+        lines.push(`  ${name}: ${String(value)};`);
+      }
     }
   }
   if (lines.length === 0) return null;
@@ -1185,7 +1193,7 @@ function authoredDefinesPredicate(document: Document): (id: string) => boolean {
   const authoredCss = [...document.querySelectorAll("style:not([data-hf-composition-variables])")]
     .map((s) => s.textContent || "")
     .join("\n");
-  return (id) => new RegExp(`${cssVariableName(id)}\\s*:`).test(authoredCss);
+  return (id) => new RegExp(`${collidingCssName(id)}\\s*:`).test(authoredCss);
 }
 
 /**
diff --git a/packages/core/src/runtime/applyVariableBindings.test.ts b/packages/core/src/runtime/applyVariableBindings.test.ts
index faca78f312..c153fa99c4 100644
--- a/packages/core/src/runtime/applyVariableBindings.test.ts
+++ b/packages/core/src/runtime/applyVariableBindings.test.ts
@@ -63,7 +63,7 @@ describe("applyVariableBindings", () => {
     expect(document.querySelector("h1")?.textContent).toBe("Overridden");
   });
 
-  it("applies scalar variables as --{id} custom props on the root", () => {
+  it("applies scalar variables as --hf-var-{id} custom props on the root", () => {
     setDeclared([
       { id: "accent", type: "color", label: "Accent", default: "#00C3FF" },
       { id: "count", type: "number", label: "Count", default: 3 },
@@ -72,7 +72,11 @@ describe("applyVariableBindings", () => {
     document.body.innerHTML = `<div id="root" data-hf-root></div>`;
     applyVariableBindings(document);
     const root = document.getElementById("root");
-    expect(root?.style.getPropertyValue("--accent")).toBe("#ff0000");
+    // `accent` is a theme token, so it gets the namespaced name ONLY — the
+    // bare --accent belongs to the host theme.
+    expect(root?.style.getPropertyValue("--hf-var-accent")).toBe("#ff0000");
+    expect(root?.style.getPropertyValue("--accent")).toBe("");
+    expect(root?.style.getPropertyValue("--hf-var-count")).toBe("3");
     expect(root?.style.getPropertyValue("--count")).toBe("3");
   });
 
@@ -84,8 +88,11 @@ describe("applyVariableBindings", () => {
     document.body.innerHTML = `<div id="root" data-hf-root></div>`;
     applyVariableBindings(document);
     const root = document.getElementById("root");
-    expect(root?.style.getPropertyValue("--brandFont")).toBe("Inter");
-    expect(root?.style.getPropertyValue("--img")).toBe("");
+    // The id is slugified (case-folded) exactly once, in
+    // variableCssPropertiesForId, so every injection site agrees on the name.
+    expect(root?.style.getPropertyValue("--hf-var-brandfont")).toBe("Inter");
+    expect(root?.style.getPropertyValue("--brandfont")).toBe("Inter");
+    expect(root?.style.getPropertyValue("--hf-var-img")).toBe("");
   });
 
   it("preserves element children when binding text on a container", () => {
@@ -169,10 +176,67 @@ describe("applyVariableBindings", () => {
       win.__hfVariables = { accent: "red; background: url(//evil?data=secret)" };
       document.body.innerHTML = `<div id="root" data-hf-root></div>`;
       applyVariableBindings(document);
-      const css = document.getElementById("root")?.style.getPropertyValue("--accent") ?? "";
+      const css = document.getElementById("root")?.style.getPropertyValue("--hf-var-accent") ?? "";
       expect(css).not.toContain(";");
       expect(css).not.toContain("{");
       expect(css).not.toContain("<");
     });
   });
 });
+
+/** Every custom property currently set inline on `el`, sorted. */
+function customProps(el: HTMLElement): string[] {
+  const names: string[] = [];
+  for (let i = 0; i < el.style.length; i++) {
+    const name = el.style.item(i);
+    if (name.startsWith("--")) names.push(name);
+  }
+  return names.sort();
+}
+
+describe("injected CSS custom properties", () => {
+  /** A composition root under a host that defines the `--accent` theme token. */
+  function representativeRoot(): HTMLElement {
+    setDeclared([
+      { id: "accent", type: "enum", label: "Accent", default: "blue" },
+      { id: "accentColor", type: "color", label: "Accent color", default: "#00c3ff" },
+      { id: "count", type: "number", label: "Count", default: 3 },
+    ]);
+    document.body.innerHTML = `<div id="host" style="--accent: #7c3aed"><div id="root" data-hf-root></div></div>`;
+    applyVariableBindings(document);
+    return document.getElementById("root") as HTMLElement;
+  }
+
+  it("writes exactly this property set for a representative composition", () => {
+    // Names are slugged (case-folded) once, in variableCssPropertiesForId,
+    // so `accentColor` cannot land here as `--hf-var-accentColor` while the
+    // compiler bakes `--hf-var-accentcolor` into the shipped stylesheet.
+    expect(customProps(representativeRoot())).toEqual([
+      "--accentcolor",
+      "--count",
+      "--hf-var-accent",
+      "--hf-var-accentcolor",
+      "--hf-var-count",
+    ]);
+  });
+
+  it("does not shadow the host theme's --accent", () => {
+    const root = representativeRoot();
+    expect(root.style.getPropertyValue("--accent")).toBe("");
+    expect(root.style.getPropertyValue("--hf-var-accent")).toBe("blue");
+    // The cascade, not the property map: var(--accent) still finds the host's
+    // value rather than the enum keyword the composition maps onto it.
+    expect(window.getComputedStyle(root).getPropertyValue("--accent")).toBe("#7c3aed");
+  });
+
+  it("removes both names when a value resolves to the empty string", () => {
+    setDeclared([{ id: "tint", type: "color", label: "Tint", default: "#123456" }]);
+    document.body.innerHTML = `<div id="root" data-hf-root></div>`;
+    applyVariableBindings(document);
+    const root = document.getElementById("root") as HTMLElement;
+    expect(customProps(root)).toEqual(["--hf-var-tint", "--tint"]);
+    win.__hfVariables = { tint: "" };
+    applyVariableBindings(document);
+    expect(customProps(root)).toEqual([]);
+  });
+});
diff --git a/packages/core/src/runtime/applyVariableBindings.ts b/packages/core/src/runtime/applyVariableBindings.ts
index 7b704f9338..2ddee8d07c 100644
--- a/packages/core/src/runtime/applyVariableBindings.ts
+++ b/packages/core/src/runtime/applyVariableBindings.ts
@@ -13,9 +13,13 @@
  *   node is replaced, mirroring the SDK's setOwnText semantics — a text
  *   binding must never delete nested clips or animation targets.
  * - Every scalar variable (and a font value's family name) is applied as a
- *   `--{id}` CSS custom property on its composition root, so CSS bindings
- *   like `color: var(--accent)` respond to render/preview overrides instead
- *   of only the persisted default.
+ *   `--hf-var-{slug}` CSS custom property on its composition root, so CSS
+ *   bindings like `color: var(--hf-var-accent)` respond to render/preview
+ *   overrides instead of only the persisted default. The bare `--{slug}` is
+ *   written too as a deprecated alias, but never for a theme-token name —
+ *   a variable called `accent` must not shadow the host theme's `--accent`.
+ *   The slug is variableCssPropertiesForId's, shared with the declared-default
+ *   injector, the compiler and the SDK, so one id has one property name.
  *
  * Values resolve against the element's owning composition — the same scope
  * chain the color-grading runtime uses: `__hfVariablesByComp[compId]` for
@@ -28,6 +32,7 @@
  */
 
 import { readVariablesForElement } from "./variableScope";
+import { variableCssPropertiesForId } from "./themeTokens";
 import { isScalarVariableValue as isScalar } from "@hyperframes/parsers/composition";
 
 // data-var-src only rebinds media `src` on media elements. A user-controlled
@@ -158,7 +163,12 @@ function applyCssCustomProperties(doc: Document, cache: ScopeValuesCache): void
     for (const [id, value] of Object.entries(values)) {
       const css = cssValueFor(value);
       if (css !== null && root instanceof HTMLElement) {
-        root.style.setProperty(`--${id}`, sanitizeCssValue(css));
+        const clean = sanitizeCssValue(css);
+        // An empty value REMOVES the property (CSSOM setProperty semantics).
+        // Both names go through the same call so an alias can't go stale.
+        const { namespaced, legacy } = variableCssPropertiesForId(id);
+        root.style.setProperty(namespaced, clean);
+        if (legacy) root.style.setProperty(legacy, clean);
       }
     }
   }
diff --git a/packages/core/src/runtime/getVariables.test.ts b/packages/core/src/runtime/getVariables.test.ts
index a9bfd730e2..bd1c197c88 100644
--- a/packages/core/src/runtime/getVariables.test.ts
+++ b/packages/core/src/runtime/getVariables.test.ts
@@ -276,7 +276,7 @@ describe("css variable injection (figma brand-token chain)", () => {
     applyCssVariables(el, { blank: "", real: "#123456" });
     expect(el.style.getPropertyValue("--blank")).toBe("");
     expect(el.style.getPropertyValue("--real")).toBe("#123456");
-    expect(el.getAttribute("data-hf-css-vars")).toBe("--real");
+    expect(el.getAttribute("data-hf-css-vars")).toBe("--hf-var-real --real");
   });
 
   it("clearAppliedCssVariables removes exactly what was applied", async () => {
@@ -296,3 +296,59 @@ describe("css variable injection (figma brand-token chain)", () => {
     expect(getVariables()["figma:brand"]).toBe("#445566");
   });
 });
+
+/** Every custom property currently set inline on `el`, sorted. */
+function customProps(el: HTMLElement): string[] {
+  const names: string[] = [];
+  for (let i = 0; i < el.style.length; i++) {
+    const name = el.style.item(i);
+    if (name.startsWith("--")) names.push(name);
+  }
+  return names.sort();
+}
+
+describe("injected CSS custom property names", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+    setOverrides(undefined);
+  });
+
+  it("applyCssVariables writes and records exactly these names", async () => {
+    const { applyCssVariables } = await import("./getVariables");
+    const el = document.createElement("div");
+    applyCssVariables(el, { accent: "blue", accentColor: "#00c3ff", count: 3, blank: "" });
+    expect(customProps(el)).toEqual([
+      "--accentcolor",
+      "--count",
+      "--hf-var-accent",
+      "--hf-var-accentcolor",
+      "--hf-var-count",
+    ]);
+    expect(el.getAttribute("data-hf-css-vars")).toBe(
+      "--hf-var-accent --hf-var-accentcolor --accentcolor --hf-var-count --count",
+    );
+  });
+
+  it("clearAppliedCssVariables clears the whole pair, leaving no stale alias", async () => {
+    const { applyCssVariables, clearAppliedCssVariables } = await import("./getVariables");
+    const el = document.createElement("div");
+    applyCssVariables(el, { accent: "blue", tint: "#111111" });
+    expect(customProps(el)).toEqual(["--hf-var-accent", "--hf-var-tint", "--tint"]);
+    clearAppliedCssVariables(el);
+    expect(customProps(el)).toEqual([]);
+    expect(el.hasAttribute("data-hf-css-vars")).toBe(false);
+  });
+
+  it("a declared `accent` leaves the host's --accent alone", async () => {
+    const { injectCompositionCssVariables } = await import("./getVariables");
+    document.body.innerHTML =
+      `<div id="host" style="--accent: #7c3aed">` +
+      `<div id="root" ${VARIABLES_ATTR}='[{"id":"accent","type":"enum","label":"a","default":"blue"}]'></div>` +
+      `</div>`;
+    injectCompositionCssVariables(document);
+    const root = document.getElementById("root") as HTMLElement;
+    expect(root.style.getPropertyValue("--accent")).toBe("");
+    expect(root.style.getPropertyValue("--hf-var-accent")).toBe("blue");
+    expect(window.getComputedStyle(root).getPropertyValue("--accent")).toBe("#7c3aed");
+  });
+});
diff --git a/packages/core/src/runtime/getVariables.ts b/packages/core/src/runtime/getVariables.ts
index 189356760d..5920b9552e 100644
--- a/packages/core/src/runtime/getVariables.ts
+++ b/packages/core/src/runtime/getVariables.ts
@@ -20,6 +20,7 @@
  *     const { title = "Untitled", theme = "light" } = getVariables<MyVars>();
  */
 import { cssVariableName, detectSlugCollisions } from "../tokenSlug";
+import { collidingCssName, variableCssPropertiesForId } from "./themeTokens";
 
 export function getVariables<
   T extends Record<string, unknown> = Record<string, unknown>,
@@ -82,18 +83,21 @@ function hasInlineStyle(target: Element): target is Element & ElementCSSInlineSt
 
 /**
  * Define primitive-valued variables as CSS custom properties on `target`,
- * recording the applied names so re-init/unmount can clear them. Empty
- * strings are skipped — CSSOM setProperty("", …) REMOVES the property, and a
- * blank default has no CSS meaning anyway.
+ * recording every applied name (the namespaced one and, for a non-reserved
+ * id, its deprecated bare alias) so re-init/unmount can clear the pair.
+ * Empty strings are skipped — CSSOM setProperty("", …) REMOVES the property,
+ * and a blank default has no CSS meaning anyway.
  */
 export function applyCssVariables(target: Element, variables: Record<string, unknown>): void {
   if (!hasInlineStyle(target)) return;
   const applied: string[] = [];
   for (const [id, value] of Object.entries(variables)) {
     if ((typeof value === "string" && value !== "") || typeof value === "number") {
-      const name = cssVariableName(id);
-      target.style.setProperty(name, String(value));
-      applied.push(name);
+      const { namespaced, legacy } = variableCssPropertiesForId(id);
+      for (const name of legacy === null ? [namespaced] : [namespaced, legacy]) {
+        target.style.setProperty(name, String(value));
+        applied.push(name);
+      }
     }
   }
   if (applied.length > 0) target.setAttribute(APPLIED_VARS_ATTR, applied.join(" "));
@@ -107,7 +111,7 @@ export function filterVariablesIfAbsent(
 ): Record<string, unknown> {
   const filtered: Record<string, unknown> = {};
   for (const [id, value] of Object.entries(variables)) {
-    const name = cssVariableName(id);
+    const name = collidingCssName(id);
     const existing =
       (hasInlineStyle(target) ? target.style.getPropertyValue(name) : "") ||
       (view ? view.getComputedStyle(target).getPropertyValue(name) : "");
@@ -173,7 +177,7 @@ function applyDeclaredForElement(
   const toApply: Record<string, unknown> = {};
   for (const [id, value] of Object.entries(declared)) {
     if (id in overrides) continue; // overrides applied below, always win
-    const name = cssVariableName(id);
+    const name = collidingCssName(id);
     // define-if-absent: respect authored/compiled definitions
     const existing =
       el.style.getPropertyValue(name) ||
diff --git a/packages/core/src/runtime/themeTokens.test.ts b/packages/core/src/runtime/themeTokens.test.ts
new file mode 100644
index 0000000000..b70ef493b7
--- /dev/null
+++ b/packages/core/src/runtime/themeTokens.test.ts
@@ -0,0 +1,126 @@
+/**
+ * @vitest-environment jsdom
+ */
+import { describe, it, expect, afterEach } from "vitest";
+import { THEME_TOKENS, variableCssPropertiesForId, collidingCssName } from "./themeTokens";
+import { applyVariableBindings } from "./applyVariableBindings";
+import { getVariables, injectCompositionCssVariables } from "./getVariables";
+
+describe("THEME_TOKENS", () => {
+  it("is non-empty", () => {
+    expect(THEME_TOKENS.size).toBeGreaterThan(0);
+  });
+
+  it("reserves the tokens compositions read from their host", () => {
+    for (const token of ["accent", "brand", "accent-2", "bg", "fg", "surface", "muted"]) {
+      expect(THEME_TOKENS.has(token)).toBe(true);
+    }
+  });
+
+  it("does not reserve ordinary variable ids", () => {
+    for (const id of ["swap_at", "title", "count", "flowSpeed"]) {
+      expect(THEME_TOKENS.has(id)).toBe(false);
+    }
+  });
+
+  it("stores bare names, so callers can name the token they would shadow", () => {
+    for (const token of THEME_TOKENS) expect(token.startsWith("--")).toBe(false);
+  });
+});
+
+describe("variableCssPropertiesForId", () => {
+  it("gives a non-reserved id both the namespaced name and the legacy alias", () => {
+    expect(variableCssPropertiesForId("swap_at")).toEqual({
+      namespaced: "--hf-var-swap-at",
+      legacy: "--swap-at",
+    });
+  });
+
+  it("gives a reserved id the namespaced name only", () => {
+    expect(variableCssPropertiesForId("accent")).toEqual({
+      namespaced: "--hf-var-accent",
+      legacy: null,
+    });
+  });
+
+  it("slugifies the id, so a mixed-case id has ONE name", () => {
+    // Case-folded, not camel-split: `accentColor` is `accentcolor`, never
+    // `accent-color`. The slug shape is tokenSlug's contract, not this one.
+    expect(variableCssPropertiesForId("accentColor")).toEqual({
+      namespaced: "--hf-var-accentcolor",
+      legacy: "--accentcolor",
+    });
+  });
+
+  it("reserves a mixed-case theme-token id exactly as it reserves the bare one", () => {
+    // The consequence of deriving the bare name verbatim: `Accent` would test
+    // as un-reserved and be aliased to `--Accent` on the paths that skipped
+    // the slug, while the compiler reserved it. Same id, two answers.
+    expect(variableCssPropertiesForId("Accent")).toEqual(variableCssPropertiesForId("accent"));
+    expect(variableCssPropertiesForId("Accent").legacy).toBeNull();
+  });
+
+  it("collidingCssName names the property define-if-absent must test", () => {
+    expect(collidingCssName("accentColor")).toBe("--accentcolor");
+    expect(collidingCssName("Accent")).toBe("--hf-var-accent");
+  });
+});
+
+/**
+ * The agreement gate. A composition author binds `var(--hf-var-<slug>)`; that
+ * only works if every site that injects the variable derives the SAME
+ * property name from the id. These drove different derivations once (the
+ * runtime bindings path used the id verbatim, everything else slugified), so
+ * a mixed-case id silently produced two properties and the binding could only
+ * match one.
+ *
+ * The compiler leg is pinned in packages/core/src/compiler/htmlBundler.test.ts
+ * and the SDK's two writers in packages/sdk/src/session.variabledecls.test.ts,
+ * against these same ids. (They cannot run here: this file is jsdom, and
+ * importing the bundler drags in esbuild, which refuses to load under it.)
+ */
+describe("every injection path derives one property name per id", () => {
+  const MIXED = "accentColor"; // non-reserved, mixed case
+  const RESERVED = "Accent"; // slugs onto a theme token, mixed case
+  const EXPECTED = "--hf-var-accentcolor";
+  const EXPECTED_RESERVED = "--hf-var-accent";
+
+  const DECLS = JSON.stringify([
+    { id: MIXED, type: "color", label: "Accent colour", default: "#00c3ff" },
+    { id: RESERVED, type: "color", label: "Accent", default: "#7c3aed" },
+  ]);
+
+  afterEach(() => {
+    delete (window as Window & { __hfVariables?: unknown; __hyperframes?: unknown }).__hfVariables;
+    delete (window as Window & { __hyperframes?: unknown }).__hyperframes;
+    document.documentElement.removeAttribute("data-composition-variables");
+    document.head.innerHTML = "";
+    document.body.innerHTML = "";
+  });
+
+  it("applyVariableBindings (runtime, resolved values)", () => {
+    (window as Window & { __hyperframes?: unknown }).__hyperframes = { getVariables };
+    document.documentElement.setAttribute("data-composition-variables", DECLS);
+    document.body.innerHTML = `<div id="root" data-hf-root></div>`;
+    applyVariableBindings(document);
+
+    const style = document.getElementById("root")?.style;
+    expect(style?.getPropertyValue(EXPECTED)).toBe("#00c3ff");
+    expect(style?.getPropertyValue("--hf-var-accentColor")).toBe("");
+    expect(style?.getPropertyValue(EXPECTED_RESERVED)).toBe("#7c3aed");
+    // Reserved on this path too: the host's --accent stays the host's.
+    expect(style?.getPropertyValue("--accent")).toBe("");
+    expect(style?.getPropertyValue("--Accent")).toBe("");
+  });
+
+  it("injectCompositionCssVariables (runtime, declared defaults)", () => {
+    document.body.innerHTML = `<div id="decl" data-composition-variables='${DECLS}'></div>`;
+    injectCompositionCssVariables(document);
+
+    const style = (document.getElementById("decl") as HTMLElement).style;
+    expect(style.getPropertyValue(EXPECTED)).toBe("#00c3ff");
+    expect(style.getPropertyValue("--hf-var-accentColor")).toBe("");
+    expect(style.getPropertyValue(EXPECTED_RESERVED)).toBe("#7c3aed");
+    expect(style.getPropertyValue("--accent")).toBe("");
+  });
+});
diff --git a/packages/core/src/runtime/themeTokens.ts b/packages/core/src/runtime/themeTokens.ts
new file mode 100644
index 0000000000..7f02529262
--- /dev/null
+++ b/packages/core/src/runtime/themeTokens.ts
@@ -0,0 +1,87 @@
+/**
+ * The CSS custom properties a composition expects its HOST to define — the
+ * theme namespace. Declared composition variables are injected as custom
+ * properties too, so an id that happens to match one of these names would
+ * overwrite the theme token by inline-style specificity and no host theme
+ * could win it back. A variable declared `accent: "blue"` is not a colour, it
+ * is a selector the composition maps onto `var(--accent)`; writing `--accent:
+ * blue` makes that lookup resolve to the CSS keyword instead of the theme.
+ *
+ * Reserved ids therefore get the namespaced property ONLY (see
+ * `variableCssPropertiesForId`), which is what stops the collision.
+ *
+ * Derivation, not memory — the names shipped theme blocks in this repo define
+ * alongside `--accent`:
+ *
+ *     rg -U --pcre2 '\{[^{}]*--accent\s*:[^{}]*\}' -o skills registry docs
+ *
+ * ...filtered to theme ROLES (a slot a host fills: ground, ink, accent,
+ * surface) and away from literal values (`--green`, `--cream`), typography
+ * (`--font-*`, `--sans`) and component-local names (`--tab-bg`), which are not
+ * a host contract and are better left aliasable.
+ */
+
+import { cssVariableName } from "../tokenSlug";
+
+/** Reserved theme-token names, without the leading `--`. */
+export const THEME_TOKENS: ReadonlySet<string> = new Set([
+  "accent",
+  "accent-2",
+  "accent-3",
+  "accent2",
+  "bg",
+  "border",
+  "brand",
+  "fg",
+  "ink",
+  "muted",
+  "primary",
+  "secondary",
+  "surface",
+  "tertiary",
+  "text",
+]);
+
+/** The custom properties one injected variable writes. */
+export interface VariableCssNames {
+  /** Always written. Namespaced, so nothing else can be shadowed by it. */
+  namespaced: string;
+  /**
+   * The bare name, kept as a deprecated alias for compositions that read
+   * `var(--<id>)` today. `null` for a reserved id — writing it is the bug.
+   */
+  legacy: string | null;
+}
+
+/**
+ * THE property names one injected variable writes. Every injection site takes
+ * the raw variable id here — runtime bindings, runtime declared defaults, the
+ * compiler and the SDK writer — so one id yields exactly one namespaced
+ * property everywhere, and an authored `var(--hf-var-<slug>)` binding matches
+ * whichever site happened to define it.
+ *
+ * Taking the id (not a pre-derived name) is the point: the slug is applied
+ * here, once. `cssVariableName` is already the form the figma importer emits
+ * `var(--<slug>)` against and the form the compiler bakes into shipped
+ * output, and it is the only form guaranteed to be a legal custom-property
+ * name — a raw id may carry spaces or dots. Slugging folds case, which the
+ * reserved test below depends on: derived verbatim, the same declared id
+ * `Accent` would be aliasable on one path and reserved on another.
+ */
+export function variableCssPropertiesForId(id: string): VariableCssNames {
+  const bare = cssVariableName(id).slice(2);
+  return {
+    namespaced: `--hf-var-${bare}`,
+    legacy: THEME_TOKENS.has(bare) ? null : `--${bare}`,
+  };
+}
+
+/**
+ * The one name define-if-absent tests. An authored definition can only be
+ * clobbered by a name we would actually write, and a reserved id never writes
+ * the bare one — so an authored `--accent` must not suppress `--hf-var-accent`.
+ */
+export function collidingCssName(id: string): string {
+  const { namespaced, legacy } = variableCssPropertiesForId(id);
+  return legacy ?? namespaced;
+}
diff --git a/packages/sdk/src/adapters/iframe.sync.test.ts b/packages/sdk/src/adapters/iframe.sync.test.ts
index aa9f17dc92..026ae343dc 100644
--- a/packages/sdk/src/adapters/iframe.sync.test.ts
+++ b/packages/sdk/src/adapters/iframe.sync.test.ts
@@ -197,7 +197,7 @@ window.__timelines = { t: tl };</script>
     expect(liveTitle.style.getPropertyValue("color")).not.toBe("#f00");
   });
 
-  it("mirrors setVariableValue onto the live root's CSS custom property", async () => {
+  it("mirrors setVariableValue onto the live root's namespaced custom property", async () => {
     const html = `<!DOCTYPE html>
 <html data-composition-variables='[{"id":"accent","default":"#fff"}]'>
 <body>
@@ -216,7 +216,10 @@ window.__timelines = { t: tl };</script>
     const liveRoot = iframe.contentDocument!.querySelector(
       '[data-hf-id="hf-stage"]',
     ) as HTMLElement;
-    expect(liveRoot.style.getPropertyValue("--accent")).toBe("#0f0");
+    // `accent` is a theme token: the edit lands on --hf-var-accent, and the
+    // authored --accent stays whatever the document (or its host) set.
+    expect(liveRoot.style.getPropertyValue("--hf-var-accent")).toBe("#0f0");
+    expect(liveRoot.style.getPropertyValue("--accent")).toBe("#fff");
   });
 
   it("mirrors declareVariable/removeVariable onto the live document's schema attribute", async () => {
diff --git a/packages/sdk/src/engine/apply-patches.ts b/packages/sdk/src/engine/apply-patches.ts
index a37158e761..d64665b58d 100644
--- a/packages/sdk/src/engine/apply-patches.ts
+++ b/packages/sdk/src/engine/apply-patches.ts
@@ -20,6 +20,7 @@ import {
   setStyleSheet,
 } from "./model.js";
 import { keyToPath, stylePath } from "./patches.js";
+import { variableCssPropertiesForId } from "@hyperframes/core/runtime/theme-tokens";
 import {
   writeVariableDefault,
   clearVariableDefault,
@@ -116,6 +117,32 @@ function applyVariableDefault(declEl: Element | null, id: string, newDefault: un
 
 // ─── Patch application ───────────────────────────────────────────────────────
 
+/**
+ * The CSS custom-property patches a scalar `var.{id}` override implies.
+ *
+ * Current sessions persist a paired style override, but sets written before
+ * the model/CSS split carry only `var.{id}`, so the CSS is derived here and
+ * `var()` bindings rehydrate. Names come from core so this stays in step with
+ * the SDK writer: a theme-token id gets `--hf-var-{slug}` only.
+ *
+ * Object values (font, image) are never CSS and yield nothing. `typeof null`
+ * is `"object"`, so null is admitted explicitly rather than by omission.
+ */
+function cssPatchesForVariableOverride(rootId: string, key: string, value: unknown): JsonPatchOp[] {
+  if (!key.startsWith("var.")) return [];
+  if (value !== null && typeof value === "object") return [];
+
+  const { namespaced, legacy } = variableCssPropertiesForId(key.slice("var.".length));
+  const names = legacy === null ? [namespaced] : [namespaced, legacy];
+
+  return names.map((cssVar) => {
+    const path = stylePath(rootId, cssVar);
+    return value === null
+      ? ({ op: "remove", path } as JsonPatchOp)
+      : ({ op: "replace", path, value: String(value) } as JsonPatchOp);
+  });
+}
+
 /**
  * Replay a stored override-set onto a freshly-parsed base document (T3 init).
  * A null value means the property was explicitly deleted — emit a remove patch
@@ -146,17 +173,7 @@ export function applyOverrideSet(parsed: ParsedDocument, overrides: OverrideSet)
     } else {
       patches.push({ op: "replace", path, value });
     }
-    // A scalar `var.{id}` override must also restore the `--{id}` CSS custom
-    // prop on the root. Current sessions persist a paired style override, but
-    // sets written before the model/CSS split only carry `var.{id}`; derive the
-    // CSS here so `var(--{id})` bindings rehydrate. Object (font/image) values
-    // are never CSS, so they are skipped.
-    if (rootId && key.startsWith("var.") && value !== null && typeof value !== "object") {
-      const cssPath = stylePath(rootId, `--${key.slice("var.".length)}`);
-      patches.push({ op: "replace", path: cssPath, value: String(value) });
-    } else if (rootId && key.startsWith("var.") && value === null) {
-      patches.push({ op: "remove", path: stylePath(rootId, `--${key.slice("var.".length)}`) });
-    }
+    if (rootId) patches.push(...cssPatchesForVariableOverride(rootId, key, value));
   }
   applyPatchesToDocument(parsed, patches);
 }
diff --git a/packages/sdk/src/engine/mutate.ts b/packages/sdk/src/engine/mutate.ts
index adfa85f3c5..cf62a6abec 100644
--- a/packages/sdk/src/engine/mutate.ts
+++ b/packages/sdk/src/engine/mutate.ts
@@ -54,6 +54,7 @@ import {
 import { upsertCssRule } from "./cssWriter.js";
 import { mintHfId, EXCLUDED_TAGS } from "@hyperframes/core/hf-ids";
 import { EDIT_BASE_X_ATTR, EDIT_BASE_Y_ATTR } from "@hyperframes/core/runtime/position-edits";
+import { variableCssPropertiesForId } from "@hyperframes/core/runtime/theme-tokens";
 import { readClipTiming, writeClipTiming } from "@hyperframes/core/composition-contract";
 import { parseGsapScriptAcornForWrite } from "@hyperframes/core/gsap-parser-acorn";
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
@@ -873,9 +874,9 @@ function handleSetVariableValue(
   const oldVarDefault = readVariableDefault(declEl, id);
 
   // Update the JSON model (B1 — drives the runtime) and keep the CSS custom
-  // prop as secondary / compat for compositions that CSS-bind directly to
-  // --{id}. Object values (font / image) are not valid CSS custom property
-  // values (LOCKED §7) — cssCompatChange clears any stale scalar prop instead.
+  // props as secondary / compat for compositions that CSS-bind directly to
+  // the variable. Object values (font / image) are not valid CSS custom
+  // property values (LOCKED §7) — cssCompatChanges clears stale scalar props.
   // Emitting separate model + style patches keeps apply-patches.ts pure per
   // path type, so inverse patches restore the exact pre-call state.
   writeVariableDefault(declEl, id, value);
@@ -883,8 +884,11 @@ function handleSetVariableValue(
   const forward: JsonPatchOp[] = [modelP.forward];
   const inverse: JsonPatchOp[] = [modelP.inverse];
 
-  const css = cssCompatChange(parsed, id, isObjectVariableValue(value) ? null : String(value));
-  if (css) {
+  for (const css of cssCompatChanges(
+    parsed,
+    id,
+    isObjectVariableValue(value) ? null : String(value),
+  )) {
     forward.push(css.forward);
     inverse.push(css.inverse);
   }
@@ -893,29 +897,38 @@ function handleSetVariableValue(
 }
 
 /**
- * Keep the `--{id}` CSS compat custom property on the root in sync with a
- * scalar default (same secondary channel handleSetVariableValue maintains).
- * Pass null to clear. Returns the patch pair, or null when there is no root
- * or nothing to change.
+ * Keep the CSS compat custom properties on the root in sync with a scalar
+ * default (same secondary channel handleSetVariableValue maintains). Pass
+ * null to clear. Returns one patch pair per property, empty when there is no
+ * root or nothing to change.
+ *
+ * Core's `variableCssPropertiesForId` owns which names those are, so the SDK
+ * writer and the runtime/compiler injectors cannot drift: the namespaced
+ * `--hf-var-{slug}` always, plus the deprecated bare `--{slug}` unless the id
+ * names a theme token — writing `--accent` there would shadow the host's.
  */
-function cssCompatChange(
+function cssCompatChanges(
   parsed: ParsedDocument,
   id: string,
   newVal: string | null,
-): { forward: JsonPatchOp; inverse: JsonPatchOp } | null {
+): { forward: JsonPatchOp; inverse: JsonPatchOp }[] {
   const root = findRoot(parsed.document);
   const rootId = root?.getAttribute("data-hf-id");
-  if (!root || !rootId) return null;
-  const cssVar = `--${id}`;
-  const oldCssValue = getElementStyles(root)[cssVar] ?? null;
-  if (newVal !== null) {
-    if (oldCssValue === newVal) return null;
-    setElementStyles(root, { [cssVar]: newVal });
-    return scalarChange(stylePath(rootId, cssVar), oldCssValue, newVal);
+  if (!root || !rootId) return [];
+  const { namespaced, legacy } = variableCssPropertiesForId(id);
+  const changes: { forward: JsonPatchOp; inverse: JsonPatchOp }[] = [];
+  for (const cssVar of legacy === null ? [namespaced] : [namespaced, legacy]) {
+    const oldCssValue = getElementStyles(root)[cssVar] ?? null;
+    if (newVal !== null) {
+      if (oldCssValue === newVal) continue;
+      setElementStyles(root, { [cssVar]: newVal });
+      changes.push(scalarChange(stylePath(rootId, cssVar), oldCssValue, newVal));
+    } else if (oldCssValue !== null) {
+      setElementStyles(root, { [cssVar]: null });
+      changes.push(scalarDelete(stylePath(rootId, cssVar), oldCssValue));
+    }
   }
-  if (oldCssValue === null) return null;
-  setElementStyles(root, { [cssVar]: null });
-  return scalarDelete(stylePath(rootId, cssVar), oldCssValue);
+  return changes;
 }
 
 /**
@@ -1000,8 +1013,7 @@ function handleDeclareVariable(
   // Same CSS compat channel every other variable op maintains — a composition
   // CSS-bound to var(--id) must resolve regardless of which op set the value.
   if (isScalar(declaration.default)) {
-    const css = cssCompatChange(parsed, declaration.id, String(declaration.default));
-    if (css) {
+    for (const css of cssCompatChanges(parsed, declaration.id, String(declaration.default))) {
       result.forward.push(css.forward);
       result.inverse.push(css.inverse);
     }
@@ -1033,8 +1045,11 @@ function handleUpdateVariableDeclaration(
     const valueP = valueChange(variablePath(id), oldDefault ?? null, newDefault);
     result.forward.push(valueP.forward);
     result.inverse.push(valueP.inverse);
-    const css = cssCompatChange(parsed, id, isScalar(newDefault) ? String(newDefault) : null);
-    if (css) {
+    for (const css of cssCompatChanges(
+      parsed,
+      id,
+      isScalar(newDefault) ? String(newDefault) : null,
+    )) {
       result.forward.push(css.forward);
       result.inverse.push(css.inverse);
     }
@@ -1053,8 +1068,7 @@ function handleRemoveVariableDeclaration(parsed: ParsedDocument, id: string): Mu
     forward: [patchRemove(path)],
     inverse: [patchAdd(path, old)],
   };
-  const css = cssCompatChange(parsed, id, null);
-  if (css) {
+  for (const css of cssCompatChanges(parsed, id, null)) {
     result.forward.push(css.forward);
     result.inverse.push(css.inverse);
   }
diff --git a/packages/sdk/src/session.variabledecls.test.ts b/packages/sdk/src/session.variabledecls.test.ts
index 1edb8f0a2b..3770523bb3 100644
--- a/packages/sdk/src/session.variabledecls.test.ts
+++ b/packages/sdk/src/session.variabledecls.test.ts
@@ -41,6 +41,10 @@ const UNDECLARED_HTML = `<!DOCTYPE html>
 <body>${BARE_HTML}</body>
 </html>`;
 
+function rootStyles(comp: Awaited<ReturnType<typeof openComposition>>) {
+  return comp.getElements().find((e) => e.id === "hf-stage")?.inlineStyles ?? {};
+}
+
 describe("declareVariable", () => {
   it("creates the attribute on a composition with no declarations", async () => {
     const comp = await openComposition(UNDECLARED_HTML);
@@ -234,12 +238,118 @@ describe("patch grammar", () => {
     });
     comp.declareVariable(TITLE_DECL);
     comp.removeVariableDeclaration("title");
-    // Declaration ops also maintain the --{id} CSS compat prop (scalar defaults).
+    // Declaration ops also maintain the CSS compat props (scalar defaults):
+    // the namespaced name plus, for a non-reserved id like `title`, the
+    // deprecated bare alias.
     expect(events).toEqual([
       "add /variableDeclarations/title",
+      "add /elements/hf-stage/inlineStyles/--hf-var-title",
       "add /elements/hf-stage/inlineStyles/--title",
       "remove /variableDeclarations/title",
+      "remove /elements/hf-stage/inlineStyles/--hf-var-title",
       "remove /elements/hf-stage/inlineStyles/--title",
     ]);
   });
 });
+
+describe("theme-token variable ids", () => {
+  const ACCENT_DECL: CompositionVariable = {
+    id: "accent",
+    type: "string",
+    label: "Accent",
+    default: "blue",
+  };
+
+  /** A composition whose root sits under a host that themes `--accent`. */
+  const THEMED_HTML = `<!DOCTYPE html>
+<html data-composition-variables='${JSON.stringify([ACCENT_DECL, TITLE_DECL])}'>
+<body><div id="host" style="--accent: #7c3aed">${BARE_HTML}</div></body>
+</html>`;
+
+  it("setVariableValue namespaces a reserved id, leaving the theme's --accent free", async () => {
+    const comp = await openComposition(THEMED_HTML);
+    comp.setVariableValue("accent", "red");
+    expect(rootStyles(comp)["--hf-var-accent"]).toBe("red");
+    expect(rootStyles(comp)["--accent"]).toBeUndefined();
+    expect(comp.serialize()).not.toContain("--accent: red");
+  });
+
+  it("still writes the deprecated bare alias for a non-reserved id", async () => {
+    const comp = await openComposition(THEMED_HTML);
+    comp.setVariableValue("title", "Hi");
+    expect(rootStyles(comp)["--hf-var-title"]).toBe("Hi");
+    expect(rootStyles(comp)["--title"]).toBe("Hi");
+  });
+
+  it("declare/remove of a reserved id never touches the bare property", async () => {
+    const comp = await openComposition(UNDECLARED_HTML);
+    comp.declareVariable(ACCENT_DECL);
+    expect(rootStyles(comp)["--hf-var-accent"]).toBe("blue");
+    expect(rootStyles(comp)["--accent"]).toBeUndefined();
+    comp.removeVariableDeclaration("accent");
+    expect(rootStyles(comp)["--hf-var-accent"]).toBeUndefined();
+  });
+
+  it("rehydrating a legacy var.{id} override set does not resurrect --accent", async () => {
+    // Pre-model/CSS-split shape: only the model key, CSS derived on replay.
+    const comp = await openComposition(THEMED_HTML, {
+      overrides: { "var.accent": "red", "var.title": "Hi" },
+    });
+    expect(rootStyles(comp)["--hf-var-accent"]).toBe("red");
+    expect(rootStyles(comp)["--accent"]).toBeUndefined();
+    expect(rootStyles(comp)["--title"]).toBe("Hi");
+  });
+});
+
+/**
+ * The SDK half of the cross-site agreement gate (core's half lives in
+ * packages/core/src/runtime/themeTokens.test.ts). The property name is
+ * derived from the id by core's `variableCssPropertiesForId` in exactly one
+ * place, so a mixed-case id cannot land on `--hf-var-accentColor` here and
+ * `--hf-var-accentcolor` in the runtime/compiler injectors.
+ */
+describe("mixed-case variable ids", () => {
+  const MIXED_DECL: CompositionVariable = {
+    id: "accentColor",
+    type: "string",
+    label: "Accent colour",
+    default: "#00c3ff",
+  };
+  /** Slugs onto the reserved `accent`, so the reserved test must agree too. */
+  const CASED_TOKEN_DECL: CompositionVariable = {
+    id: "Accent",
+    type: "string",
+    label: "Accent",
+    default: "blue",
+  };
+  const MIXED_HTML = `<!DOCTYPE html>
+<html data-composition-variables='${JSON.stringify([MIXED_DECL, CASED_TOKEN_DECL])}'>
+<body>${BARE_HTML}</body>
+</html>`;
+
+  it("setVariableValue writes the slugified property, not the id verbatim", async () => {
+    const comp = await openComposition(MIXED_HTML);
+    comp.setVariableValue("accentColor", "red");
+    expect(rootStyles(comp)["--hf-var-accentcolor"]).toBe("red");
+    expect(rootStyles(comp)["--hf-var-accentColor"]).toBeUndefined();
+    expect(rootStyles(comp)["--accentcolor"]).toBe("red");
+  });
+
+  it("reserves a mixed-case theme-token id, as core's injectors do", async () => {
+    const comp = await openComposition(MIXED_HTML);
+    comp.setVariableValue("Accent", "red");
+    expect(rootStyles(comp)["--hf-var-accent"]).toBe("red");
+    expect(rootStyles(comp)["--Accent"]).toBeUndefined();
+    expect(rootStyles(comp)["--accent"]).toBeUndefined();
+  });
+
+  it("rehydrating a legacy var.{id} override set derives the same slug", async () => {
+    const comp = await openComposition(MIXED_HTML, {
+      overrides: { "var.accentColor": "red", "var.Accent": "green" },
+    });
+    expect(rootStyles(comp)["--hf-var-accentcolor"]).toBe("red");
+    expect(rootStyles(comp)["--hf-var-accentColor"]).toBeUndefined();
+    expect(rootStyles(comp)["--hf-var-accent"]).toBe("green");
+    expect(rootStyles(comp)["--Accent"]).toBeUndefined();
+  });
+});
diff --git a/skills-manifest.json b/skills-manifest.json
index cb7dbe3e27..901a782594 100644
--- a/skills-manifest.json
+++ b/skills-manifest.json
@@ -30,7 +30,7 @@
       "files": 11
     },
     "hyperframes-core": {
-      "hash": "e9daaccaed05b8b4",
+      "hash": "45686c48c3c7f39b",
       "files": 19
     },
     "hyperframes-creative": {
diff --git a/skills/hyperframes-core/SKILL.md b/skills/hyperframes-core/SKILL.md
index 3e44a4e54a..59e4d35815 100644
--- a/skills/hyperframes-core/SKILL.md
+++ b/skills/hyperframes-core/SKILL.md
@@ -69,6 +69,7 @@ Surfaced here; full rationale in the linked reference. Do not violate:
 - No `<br>` in body text; transformed elements must be block-level + sized; pulsing absolute decoratives need peak clearance. → `determinism-rules.md`
 - `<video>`/`<audio>` work at **any nesting depth** (including inside a sub-comp `<template>` or wrapper); the framework owns playback and seeks/decodes media wherever it lives. The one caveat is timelines, not placement: a sub-comp timeline can't animate host-root elements. → `variables-and-media.md`
 - Every `id` must be unique across the **assembled** page; inside a sub-comp, prefix ids with the composition id (`#<id>-hero`). Duplicate `<video>`/`<img>` ids render **blank** — the producer injects frames by `getElementById`, and cross-file dupes slip past `lint`. → `composition-patterns.md`
+- A declared variable is read from CSS as `var(--hf-var-<slug>)`. The bare `var(--<id>)` is a deprecated alias that is **not** written at all when `<id>` is a reserved theme-token name (`accent`, `accent-2`, `accent-3`, `accent2`, `bg`, `border`, `brand`, `fg`, `ink`, `muted`, `primary`, `secondary`, `surface`, `tertiary`, `text`); those belong to the host page's theme. The alias for every other id will be removed in a future release. → `variables-and-media.md`
 - A full-screen scene fill goes on a full-bleed **child** (`position:absolute; inset:0`), never on the composition root itself — the producer's frame compositing can drop the root element's own `background` (the frame renders **black**) even though preview/`snapshot` show it correctly. → `composition-patterns.md`
 
 ## Editing existing compositions
diff --git a/skills/hyperframes-core/references/variables-and-media.md b/skills/hyperframes-core/references/variables-and-media.md
index 0d50268f61..e7784bb6ac 100644
--- a/skills/hyperframes-core/references/variables-and-media.md
+++ b/skills/hyperframes-core/references/variables-and-media.md
@@ -22,14 +22,15 @@ Declare variables on the `<html>` element with `data-composition-variables`. Eac
 <h1 class="clip" data-start="0" data-duration="5" data-var-text="title">Fallback</h1>
 <style>
   .card {
-    color: var(--accent);
+    color: var(--hf-var-accent);
   }
 </style>
 ```
 
 - `data-var-src="id"` substitutes the element's `src` (URL string or image `{url}`); the authored `src` is the fallback.
 - `data-var-text="id"` substitutes the element's own text; element children (nested clips, animated spans) are preserved.
-- Every scalar variable is applied automatically as a `--{id}` CSS custom property on the composition root, so `var(--id)` CSS responds to overrides — no `setProperty` boilerplate.
+- Every scalar variable is applied automatically as the `--hf-var-{slug}` CSS custom property on the composition root, so `var(--hf-var-{slug})` CSS responds to overrides (no `setProperty` boilerplate).
+- The bare `--{slug}` is written too, but **only when the id is not a reserved theme-token name**: `accent`, `accent-2`, `accent-3`, `accent2`, `bg`, `border`, `brand`, `fg`, `ink`, `muted`, `primary`, `secondary`, `surface`, `tertiary`, `text`. Those belong to the host page's theme, so a variable called `accent` never shadows the theme's `--accent`. The bare alias is deprecated and will be removed in a future release, so bind `var(--hf-var-{slug})`; use `var(--accent, var(--hf-var-accent))` when the host theme should win and the declared value is only the fallback.
 - Bindings resolve identically in preview and render, and per-instance for sub-compositions.
 - Caveat: media with audio should keep a real fallback `src` — render audio extraction reads the authored attribute (lint: `media_variable_src_no_fallback`).