` and forwards the Claude Design sandbox's preview token into the iframe src. Without the token forward, the in-pane preview renders black (the sandbox serves a `"preview token required"` placeholder to the iframe).
+Claude Design reads inputs in this order of reliability: **attachments > pasted content > web research > URLs**.
-Copy this template verbatim:
+| Input type | What it gives Claude Design |
+| --- | --- |
+| Screenshots / PDFs / brand guides | Palette, typography, UI patterns, tone — strongest source |
+| Pasted hex codes, typefaces, copy | Authoritative for what it covers |
+| Brand name (well-known) | Claude Design can research blogs, press, Wikipedia |
+| SPA URL (React/Vue homepage) | Returns near-empty shell — pivot to blog/press instead |
-```html
-
-
-
-
- HyperFrames Preview
-
-
-
-
-
-
-
-
+The more specific your prompt, the better the output. Include palette, fonts, duration, and scene ideas when you have them.
+
+## Known limitations
+
+- **In-pane preview** — scrubbing is unreliable in Claude Design's iframe sandbox. Download and use `npx hyperframes preview` locally for reliable playback.
+- **No linting** — Claude Design can't run `npx hyperframes lint`. The template-first skeletons handle structural validity, but the self-review checklist is the only QA before download.
+- **No shaders on vertical** — HyperShader's WebGL canvas is hardcoded to 1920x1080. Vertical (1080x1920) compositions use hard cuts only.
+- **3 fetch limit** — Claude Design limits web fetches per turn. All critical rules are inlined in the skill; external references are for edge cases only.
+- **Seeking backwards** — scrubbing backwards in the in-pane preview can show blank frames (async capture race condition). Forward seeking usually works.
+
+## The handoff to your coding agent
+
+Claude Design's output is a valid first draft. Open it in Claude Code, Cursor, Codex, or any AI coding agent with terminal access:
+
+```bash
+npx skills add heygen-com/hyperframes # one-time setup
+npx hyperframes lint # verify structure
+npx hyperframes preview # open the studio
```
-When `location.search` is empty (opened locally, outside Claude Design's sandbox), the token-forward line is a no-op and the player loads `./index.html` as expected.
+Then iterate:
-The composition (`index.html`) must also pre-load the HyperFrames runtime right after GSAP so the player can drive playback inside Claude Design's sandbox:
-
-```html
-
-
-```
-
-If a classic script tag is needed instead of ESM, use the global player build with the same token-forwarding script:
-
-```html
-
-
-
-```
-
-See [`@hyperframes/player`](/packages/player) for the full API and framework examples.
-
-## What the skill teaches Claude Design
-
-The skill is self-contained — it includes every HyperFrames-specific contract and every known Claude Design sandbox workaround, so Claude Design rarely needs to fetch additional references. Highlights:
-
-- An explicit opening redirect: Claude Design is told NOT to reach for its default video artifacts (`copy_starter_component` with `kind: "animations.jsx"`, the built-in "Animated video" skill, React + Babel JSX, hand-rolled scale-to-fit stage wrappers). This is the single change that most reliably keeps Claude Design on the HyperFrames path
-- Correct `data-*` composition structure, the clip contract on scenes, and paused GSAP timelines registered on `window.__timelines`
-- Shader-transition timing rules: transitions must span the scene boundary (not start at it), animated content must be wrapped in `` so its pre-animation state doesn't leak into the WebGL texture, and the `scenes.length === transitions.length + 1` invariant (with `flash-through-white` as the invisible-bridge escape hatch)
-- Sandbox-compatible preview: token-forwarding `preview.html` template, runtime pre-load in `index.html`, `data-composition-id` ↔ `__timelines` key match (and a convention that the root element's DOM `id` matches too)
-- Attachment-first input model: read screenshots / PDFs / reference videos when provided, otherwise ask one short clarifying question before generating
-- A banned-font list (including Fraunces, Inter Tight, and common AI defaults) plus a banned-pairings line to break the training-data monoculture
-- Deterministic render-safe animation choices (no `Date.now()`, no unseeded `Math.random()`, no `repeat: -1`, no `stagger: { from: "random" }`)
-- Four worked-example anti-patterns with WRONG/RIGHT code pairs — exit tweens before shader transitions, non-deterministic `stagger` origins, absolute-positioned content containers, and SVG filter data URLs as `background-image` (the last one causes `SecurityError` on Safari + cross-origin iframe environments)
-- A `README.md` template for the end user with `npx hyperframes doctor` / `preview` / `render` commands and FFmpeg install instructions
+- "Make scene 3's entrance snappier"
+- "Add a counter animation to the stat in scene 5"
+- "Tighten the pacing — scenes 4 and 6 feel too long"
+- "Change the shader on transition 2 to glitch"
## Next steps
diff --git a/docs/guides/prompting.mdx b/docs/guides/prompting.mdx
index 69a3cc765..47e94d479 100644
--- a/docs/guides/prompting.mdx
+++ b/docs/guides/prompting.mdx
@@ -29,13 +29,18 @@ In Claude Code, restart the session after installing. Skills register as **slash
## Claude Design
-Claude Design uses a different setup. Instead of local slash commands, point it at the GitHub-hosted Claude Design entry point for HyperFrames:
+Claude Design uses a different setup. Download [`SKILL.md`](https://raw.githubusercontent.com/heygen-com/hyperframes/main/skills/claude-design-hyperframes/SKILL.md) and **attach it to your chat** (don't paste the URL — file attachments produce better output):
```text
-Use https://github.com/heygen-com/hyperframes/blob/main/skills/claude-design-hyperframes/SKILL.md and make a 30-second product video about [topic]. Deliver index.html, preview.html, and README.md.
+Use the attached skill. 25-second LinkedIn video for my startup.
+
+Problem: Sales teams waste 3 hours/day on manual CRM updates.
+Solution: AutoCRM — AI that logs every call, email, and meeting.
+Traction: 200+ teams, $1.2M ARR, 18% MoM growth.
+CTA: autocrmhq.com
```
-That entry point tells Claude Design to fetch the broader [`skills/`](https://github.com/heygen-com/hyperframes/tree/main/skills) tree, apply the same HyperFrames rules, and use `@hyperframes/player` for preview pages. See the [Claude Design guide](/guides/claude-design) for the recommended prompt shape.
+Claude Design produces a valid first draft (brand identity, scene content, animations, transitions). Download the ZIP and refine in any AI coding agent with `npx hyperframes preview` running. See the [Claude Design guide](/guides/claude-design) for the full workflow.
## The two prompt shapes
diff --git a/docs/quickstart.mdx b/docs/quickstart.mdx
index 86e815a48..fb40364a7 100644
--- a/docs/quickstart.mdx
+++ b/docs/quickstart.mdx
@@ -16,7 +16,7 @@ npx skills add heygen-com/hyperframes
This teaches your agent (Claude Code, Cursor, Gemini CLI, Codex) how to write correct compositions and GSAP animations. In Claude Code the skills register as slash commands — `/hyperframes` for composition authoring, `/hyperframes-cli` for CLI commands, and `/gsap` for animation help. Invoking the slash command loads the skill context explicitly, which produces correct output the first time.
- Claude Design uses a different entry path. Point Claude Design at [`skills/claude-design-hyperframes/SKILL.md`](https://github.com/heygen-com/hyperframes/blob/main/skills/claude-design-hyperframes/SKILL.md) so it can fetch the repo's `skills/` tree and generate a HyperFrames handoff. See the [Claude Design guide](/guides/claude-design).
+ Claude Design uses a different entry path. Download [`skills/claude-design-hyperframes/SKILL.md`](https://github.com/heygen-com/hyperframes/blob/main/skills/claude-design-hyperframes/SKILL.md) and attach it to your Claude Design chat. It produces a valid first draft you can refine in any AI coding agent. See the [Claude Design guide](/guides/claude-design).
### Try it: example prompts