From 22bcd7a18bae76d98fa4bb280be1c69e4f3c998f Mon Sep 17 00:00:00 2001 From: James Date: Sun, 3 May 2026 16:34:04 +0000 Subject: [PATCH] docs: clarify declaration vs override attributes (PR #603 review) James pointed out (compositions.md:33, SKILL.md:121) that the prose referenced `data-variable-values` while the example below showed `data-composition-variables`, leaving readers to wonder if the two names referred to the same thing. They don't: one declares, the other overrides per-instance. Both are now named at first mention and the declare-vs-override split is called out explicitly. - packages/cli/src/docs/compositions.md: replaced the single intro sentence with a two-bullet list ("data-composition-variables declares, data-variable-values overrides per-instance") and a follow-up explaining where the CLI fits in. - skills/hyperframes-cli/SKILL.md: rewrote the parametrized-renders paragraph so declaration (data-composition-variables) and override (--variables) are distinct sentences, with the per-instance attribute parenthetical for completeness. Co-Authored-By: Claude Opus 4.7 (1M context) --- packages/cli/src/docs/compositions.md | 7 ++++++- skills/hyperframes-cli/SKILL.md | 2 +- 2 files changed, 7 insertions(+), 2 deletions(-) diff --git a/packages/cli/src/docs/compositions.md b/packages/cli/src/docs/compositions.md index 5af91e5c1..5cd4cb9a2 100644 --- a/packages/cli/src/docs/compositions.md +++ b/packages/cli/src/docs/compositions.md @@ -26,7 +26,12 @@ Use `npx hyperframes compositions` to see all compositions in a project. ## Variables -Declare variables on the composition's `` root, then read them inside any composition script with `window.__hyperframes.getVariables()`. Override per-instance via `data-variable-values` on the host element, or at render time via `npx hyperframes render --variables '{...}'`. +Two attributes work together: + +- **`data-composition-variables`** on the `` root *declares* the variables (id, type, label, default). +- **`data-variable-values`** on a sub-comp host element *overrides* values for that one instance. + +Inside any composition script, `window.__hyperframes.getVariables()` returns the merged result of declarations + overrides. CLI `npx hyperframes render --variables '{...}'` provides a top-level override that layers the same way. ```html diff --git a/skills/hyperframes-cli/SKILL.md b/skills/hyperframes-cli/SKILL.md index 6e0749897..399a35790 100644 --- a/skills/hyperframes-cli/SKILL.md +++ b/skills/hyperframes-cli/SKILL.md @@ -118,7 +118,7 @@ npx hyperframes render --docker # byte-identical **Quality guidance:** `draft` while iterating, `standard` for review, `high` for final delivery. -**Parametrized renders:** declare variables on `` and read them inside the composition with `window.__hyperframes.getVariables()`. Override at render time with `--variables '{"title":"Q4 Report"}'`. Missing keys fall through to declared defaults, so the same composition runs unchanged in dev preview and in production renders. See the `hyperframes` skill for the full pattern. +**Parametrized renders:** the composition declares its variables on the `` root with `data-composition-variables` (id/type/label/default per entry) and reads them in any script via `window.__hyperframes.getVariables()`. The CLI `--variables '{"title":"Q4 Report"}'` overrides those declared defaults for one render — missing keys fall through, so the same composition runs unchanged in dev preview and in production. (Sub-comp hosts can also override per-instance via `data-variable-values` — see the `hyperframes` skill.) ## Transcription