heygen-com · miguel-heygen · Apr 22, 2026 · Apr 22, 2026
diff --git a/docs/concepts/compositions.mdx b/docs/concepts/compositions.mdx
@@ -127,13 +127,54 @@ Every composition has two layers:
 
 ## Variables
 
-Compositions can expose variables for dynamic content:
+HyperFrames does not automatically bind `data-var-*` attributes into your composition DOM or CSS.
+
+Today, the supported pattern is:
+
+1. Pass per-instance values on the composition host with `data-variable-values`
+2. Read those values inside the composition and apply them in your own script
+
+```html index.html
+<div
+  data-composition-id="card"
+  data-composition-src="compositions/card.html"
+  data-start="0"
+  data-track-index="1"
+  data-variable-values='{"title":"Hello","color":"#ff4d4f"}'
+></div>
+```
 
 ```html compositions/card.html
-<div data-composition-id="card" data-var-title="string" data-var-color="color">
+<template id="card-template">
+  <div data-composition-id="card" data-width="1920" data-height="1080">
+    <h1 class="title">Fallback</h1>
+
+    <style>
+      [data-composition-id="card"] {
+        --card-color: #111827;
+      }
+
+      [data-composition-id="card"] .title {
+        color: var(--card-color);
+      }
+    </style>
+
+    <script>
+      const root = document.querySelector('[data-composition-id="card"]');
+      const vars = JSON.parse(root?.getAttribute("data-variable-values") ?? "{}");
+      const titleEl = root?.querySelector(".title");
+
+      if (titleEl) {
+        titleEl.textContent = vars.title ?? "Fallback";
+      }
+
+      root?.style.setProperty("--card-color", String(vars.color ?? "#111827"));
+    </script>
+  </div>
+</template>
 ```
 
-Variables make compositions reusable as [examples](/examples) -- the same composition can render different content by injecting variable values at render time.
+If you are building tooling on top of `@hyperframes/core`, you can also declare variable metadata separately with `data-composition-variables` and read it via `extractCompositionMetadata()`. That metadata is descriptive only; you still apply the actual values manually inside the composition.
 
 ## Listing Compositions
 

diff --git a/docs/concepts/data-attributes.mdx b/docs/concepts/data-attributes.mdx
@@ -29,6 +29,7 @@ Hyperframes uses HTML data attributes to control timing, media playback, and [co
 | `data-width` | `"1920"` | Composition width in pixels |
 | `data-height` | `"1080"` | Composition height in pixels |
 | `data-composition-src` | `"./intro.html"` | Path to external [composition](/concepts/compositions) HTML file |
+| `data-variable-values` | `'{"title":"Hello"}'` | JSON object of values passed to a nested composition. HyperFrames carries these values through, but your composition script must read and apply them manually. |
 
 ## Element Visibility
 

diff --git a/docs/packages/core.mdx b/docs/packages/core.mdx
@@ -122,6 +122,13 @@ const parsed: ParsedHtml = parseHtml(htmlString);
 import { extractCompositionMetadata } from '@hyperframes/core';
 const meta: CompositionMetadata = extractCompositionMetadata(htmlString);
 // meta.id, meta.duration, meta.width, meta.height, meta.variables
+//
+// Variable metadata is declared on the document root, for example:
+// <html
+//   data-composition-id="card"
+//   data-composition-duration="3"
+//   data-composition-variables='[{"id":"title","label":"Title","type":"string","default":"Hello"}]'
+// >
 
 // Generate HTML from structured data
 const html = generateHyperframesHtml(elements, {

diff --git a/docs/reference/html-schema.mdx b/docs/reference/html-schema.mdx
@@ -58,6 +58,7 @@ Common sizes:
 | `data-volume` | audio, video | No | Volume level from `0` to `1`. Default: `1`. |
 | `data-composition-id` | div | On compositions | Unique composition ID. Must match the key used in `window.__timelines`. |
 | `data-composition-src` | div | No | Path to external composition HTML file (for [nested compositions](#composition-clips)). |
+| `data-variable-values` | div | No | JSON object of values passed to a nested composition. The framework carries the values through, but your composition script must read and apply them manually. |
 | `data-width` | div | On compositions | Composition width in pixels. |
 | `data-height` | div | On compositions | Composition height in pixels. |
 
@@ -151,6 +152,7 @@ Common sizes:
     - Each nested composition has its own `window.__timelines` entry, registered by its own `<script>` block
     - The framework automatically nests sub-timelines — do not manually add them to the parent timeline
     - Any composition can be nested inside any other — there is no special "root" type
+    - Per-instance values can be passed with `data-variable-values`, but the nested composition must read and apply those values itself
 
     For more on how compositions work, see [Compositions](/concepts/compositions).
   </Accordion>

diff --git a/packages/cli/src/docs/compositions.md b/packages/cli/src/docs/compositions.md
@@ -26,8 +26,14 @@ Use `npx hyperframes compositions` to see all compositions in a project.
 
 ## Variables
 
-Compositions can expose variables for dynamic content:
+HyperFrames does not automatically bind `data-var-*` attributes into your composition DOM.
 
 ```html
-<div data-composition-id="card" data-var-title="string" data-var-color="color"></div>
+<div
+  data-composition-id="card"
+  data-composition-src="compositions/card.html"
+  data-variable-values='{"title":"Hello","color":"#ff4d4f"}'
+></div>
 ```
+
+Read `data-variable-values` inside the nested composition and apply the values in your own script. Variable metadata for tooling is declared separately via `data-composition-variables` and read with `extractCompositionMetadata()`.