A declared composition variable was written to the composition root as a CSS
custom property named after its own id, with no namespace. A variable called
accent therefore set --accent inline and shadowed the host theme for that
whole subtree.
That is worse than a naming clash. The accent enum values are green, blue and
violet, which are not colours, they are selectors a composition maps onto
theme slots. A representative composition maps blue to var(--accent, #18181b).
The runtime then set --accent to blue, so the lookup resolved to the CSS
keyword and no host theme could win. green and violet escaped only because
they route to --brand and --accent-2, which nothing shadowed, which is why
this survived: it was invisible for two of three values.
Variables are now written to --hf-var-<slug>. The bare name is still written
as a deprecated alias, but only for ids that are not reserved theme tokens,
which is what actually fixes the collision.
Four writers had the bug, not one: the runtime bindings, the scoped
getVariables path, the compiler stylesheet, and the SDK mutate and
apply-patches path. Fixing only the runtime left the compiler emitting the
bare name into compiled output, where a host theme supplied as an inline
style attribute still rendered the keyword. All four now route through one
helper, and the helper takes the raw id so callers cannot derive the name
themselves.
That last point closed a real defect rather than a tidy-up. Two sites derived
the property name differently, one verbatim and one slugged, so an id like
Accent produced two disjoint property sets: one path reserved it, the other
aliased it, and an SDK edit silently never landed. A test pins that every
injection path derives one name per id.
Docs that taught binding the bare name are corrected, including the capstone,
whose ink variable is reserved and would have re-skinned the ground while
quietly ignoring the ink. Rendered output is unchanged there, so the published
videos stay accurate.
**canvas.mdx pointed at a Design section that does not exist.** The table sent
readers to "3D". PropertyPanelFlat.tsx renders Text, Style, Layout, Motion,
Grade, Effects, Overlays, Media — no 3D. 3D Transform is a labelled block inside
Layout (propertyPanelFlatLayoutSection.tsx:302). The table also had no row for
Motion or Effects, while the approved media-effects guide tells readers to "open
Effects in the Inspector" — so the canonical map of the Inspector said that
section did not exist. Four rows fixed or added.
**The two-card reuse example could not do what its prose promised.** Both
concepts/compositions.mdx and concepts/variables.mdx omitted data-duration on the
nested-composition hosts, then said `data-start="card-pro"` means "start when
that one ends". With no duration, resolveDurationForElement returns null and
startResolver.ts:180-184 falls back to targetStart + offset = 0 — both cards
stacked at t=0 on one track, which html-schema.mdx:104 says must never happen and
:99 lists data-duration as required for nested-composition clips. Both copies now
carry it.
Sixth PR of the template-variables Studio stack — closing the loop from
preview to render to developer handoff.
- renders started from the Renders tab now carry the active preview
variable overrides (StartRenderOptions.variables → POST /render →
RenderConfig.variables), so "render" produces exactly what the user is
previewing.
- Variables panel "Use this template" footer: copy the effective values
(defaults merged with overrides) as JSON, or as a ready-to-run
`npx hyperframes render <comp> --variables '<json>'` command.
- gitignore: negate the renders/ output rule for the tracked
src/components/renders/ source dir — without it, pre-commit's format
re-stage (`git add {staged_files}`) hard-fails on any change to those
files.
- docs: the Studio panel docs/concepts/variables.mdx described was
aspirational — replace with the real Variables-in-Studio section
(declare/edit, render-truthful preview, render-with-values, handoff,
usage badges); document the new SDK variable APIs in
docs/sdk/reference/composition.mdx (declaration ops, read APIs,
setPreviewVariables).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Adds a dedicated concept page documenting how composition variables work end-to-end, from declaration to runtime resolution.
## What's covered
- Declaring variables via `data-composition-variables` on the `<html>` root — full schema with all 5 types (`string`, `number`, `color`, `boolean`, `enum`) and their type-specific options
- Reading resolved values in composition scripts with `__hyperframes.getVariables()`
- Per-instance overrides via `data-variable-values` on host elements (sub-composition embeds)
- CLI overrides via `--variables` / `--variables-file` and `--strict-variables` for strict validation
- Layering/precedence table showing how the three sources merge
- Lint and runtime validation (what undeclared/type-mismatch/enum-out-of-range mean)
- Programmatic access via `extractCompositionMetadata()` for tooling authors
Also adds the page to the Concepts nav group in `docs.json`.
Miguel Ángel