docs: add Claude Design HyperFrames entry point#353
Conversation
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
Iterates on the Claude Design entry-point skill based on empirical testing across three prompt archetypes. Addresses silent-failure bugs in the preview pane and codifies the fetch patterns that produced clean first-shot output. - Token-forward `preview.html` template. Claude Design's sandbox serves a "preview token required" placeholder to the iframe without the `?t=<token>` query forwarded, making the in-pane preview render black. The inline script copies `location.search` onto the `hyperframes-player` src, and is a no-op outside the sandbox. - Pre-load the HyperFrames runtime in `index.html` right after GSAP. The player's auto-inject of `@hyperframes/core` runtime is unreliable inside Claude Design's sandbox, so `currentTime` never advances. Pre-loading fixes it with no effect on `npx hyperframes render`. - Enforce `data-composition-id` ↔ `window.__timelines` key match rule. Mismatch silently prevents playback (the player cannot find the timeline, ready stays false). - Required fetch list of 5 upstream skills in priority order (hyperframes/SKILL.md, references/transitions.md, references/ typography.md, references/motion-principles.md, gsap/SKILL.md). Targets observed LLM defaults: Inter typography, stuck wipe overlays (`fromTo` + `immediateRender`), banned exit animations, same-ease-everywhere motion. - Visual direction rule: don't default to warm editorial for every brief — pick from `visual-styles.md`'s 8 presets or ask one clarifying question. Reinforces the Visual Identity Gate from `hyperframes/SKILL.md`. - Prune CLI-only entries (`hyperframes-cli`, `website-to-hyperframes`, `hyperframes-contrast`, `hyperframes-animation-map`) from the conditional list. Claude Design cannot execute CLI workflows. - Sync docs/guides/claude-design.mdx preview example with the token-forwarding pattern and document the runtime pre-load. Made-with: Cursor
URL-based invocation in Claude Design sometimes skips the runtime pre-load and token-forward rules even when they're present in the skill, because the agent "enhances" the preview template with decorative chrome and drops the `id="p"` + inline script. Add a Pre-delivery checklist the agent self-verifies against before saying "done" — names each past silent failure (missing runtime pre-load, missing location.search forward, decorated preview chrome, composition-id/timeline-key mismatch, .play() call on timeline) and instructs "fix before delivering". Positions the checklist between Preview contract and Output so the agent reads it as a final gate before wrapping up. Made-with: Cursor
…aming When the agent fetches both the entry skill and the core hyperframes/SKILL.md, it sees two contradictory framings for the reference files: - Entry skill: "fetch these 5 before writing any file" - Core skill header: "References (loaded on demand)" The core skill's header is correct for Claude Code (filesystem access, pull references as needed) but wrong for Claude Design (sandboxed, fetch is the only way rules enter context). Claude Design has been picking the weaker phrasing and skipping the required fetches. Add an explicit override paragraph immediately below "Fetch these first" naming the core skill's heading and instructing the agent to ignore it. Longer-term fix lives in the core skill itself but requires Miguel's review since it affects Claude Code behavior too. Made-with: Cursor
0ba6b6a to
974ef82
Compare
…ill-docs Made-with: Cursor # Conflicts: # README.md
…kill) Claude Design's self-audits revealed a structural problem with the thin-entry-point + fetch-5-references architecture. Actual empirical observations from the agent: - Fetch budget is ~3 per turn, resets on user message. - "Fetch 5 required" → in practice 0-3 get full reads, the rest are skimmed or skipped. The "required" list is aspirational. - Even successful fetches often get skimmed — Claude Design admitted "saw the page loaded, did not read through" for multiple required files. - Inline templates (the preview.html block) work perfectly — Claude Design copies them verbatim every time. - One-file skill of ~500-2000 lines is the sweet spot where Claude Design reads top-to-bottom in a single call. Restructure the skill to inline every load-bearing rule that was previously an external fetch: - Pre-delivery checklist (unchanged, still top) - preview.html verbatim template with token forward (unchanged) - Full composition contract: data-attribute tables, layout-before- animation, sub-composition <template> pattern, video/audio rules - Determinism ❌/✅ block with every banned pattern and its replacement - Scene transitions: 4 non-negotiable rules + energy→transition, mood→transition, duration presets, narrative-position tables - Shader transitions: all 14 official shader names (verified from package source registry.ts), init() config, shader-compatible CSS rules, when-not-to-use guidance - Typography: banned fonts list (verbatim), pairing rules, dark-bg optical compensation, OpenType features, safe modern font picks by category - Motion principles: easing-is-emotion, speed-communicates-weight, build/breathe/resolve structure, visual composition for frames - Visual direction: 8 named preset styles as a table (Swiss Pulse, Velvet Standard, Deconstructed, Maximalist Type, Data Drift, Soft Signal, Folk Frequency, Shadow Cut) with GSAP signature + shader pairing - GSAP essentials: transform aliases table, immediateRender gotcha with the exact wipe-bug pattern and its fix, autoAlpha guidance, position-parameter syntax, stagger - Registry blocks: how Claude Design can fetch block HTML directly (can't run hyperframes add CLI), list of 11 common blocks from the 39 available - Worked-examples pointer: registry/examples/ tree with specific picks by aesthetic (vignelli, swiss-grid, warm-grain, kinetic- type, product-promo, nyt-graph, decision-tree) - Optional feature references (fetch when needed): captions, tts, audio-reactive, css-patterns, dynamic-techniques, transcript- guide, registry skill Verified all 14 shader names against packages/shader-transitions/src/ shaders/registry.ts. Banned fonts list verified against references/ typography.md. Scene transitions tables verified against references/ transitions.md. No fabricated content. File goes from 138 to 681 lines — well within Claude Design's reported sweet spot (500-2000 lines) where it reads fully without paginating. Made-with: Cursor
…rub note
Two fixes caught by Claude Design during Test-v10 session:
1. The IIFE build of @hyperframes/shader-transitions exposes the
package as `window.HyperShader` (verified from the CDN bundle:
`var HyperShader=(()=>{...}`). The previous skill said
`window.HyperframesShaderTransitions.init(...)` which was
fabricated — that global doesn't exist. Claude Design caught this
mid-build ("The global is HyperShader, not
HyperframesShaderTransitions. Let me fix") and recovered, but
future runs should get it right the first time.
2. Add a note explaining why shader transitions are bad for
scrub-heavy previews: html2canvas captures scene textures at
transition time and holds them between transitions. Scrubbing to
an arbitrary time shows the stale texture until a new capture
completes, producing a visible blank gap. CSS transitions don't
have this problem — DOM is the render surface, every scrub
position renders cleanly. Recommend CSS transitions for
interactive-preview compositions; shader transitions for
cinematic renders where linear playback is the primary mode.
Made-with: Cursor
During Test-v10, Claude Design spent significant time debugging three issues the skill didn't address clearly. Each sentence below would have prevented the problem. 1. **Sub-composition preview loading.** The skill previously said `data-composition-src` loads sub-comps but didn't state when the runtime processes it. Claude Design hedged with a plain `<iframe src="sub.html?standalone=1">` thinking auto-nesting might be render-only — which produces an empty iframe because the `<template>` wrapper is inert under normal HTML rendering. Verified via `packages/core/src/runtime/compositionLoader.ts` that the runtime handles `data-composition-src` at both preview and render time. Added: "The HyperFrames runtime auto-nests sub-compositions in both preview AND render. Don't hedge with a plain <iframe>." 2. **Scene visibility ownership for shader-transition compositions.** The skill said `html2canvas` captures scene textures and the canvas composites them during transitions — but never said who owns `.scene` opacity *between* transitions. Claude Design set opacity:0 on all scenes and ended up with a dead state (everything hidden). Added: "HyperShader drives the transition overlay, NOT scene presence. You own scene show/hide via tl.set() with autoAlpha." 3. **Dev-time scrubbing deadlock.** The skill warns about scrub latency for shader transitions during user playback but not about rapid `tl.progress()` calls during dev-time inspection queuing html2canvas captures. Claude Design hit repeated save_screenshot timeouts from this. Added: "Dev-time scrubbing trap: pause first, then tl.time(t) once." Net: +18 lines targeting three specific failure modes observed in the field. Made-with: Cursor
…ix set Consolidates iterative improvements from the v12–v14 Claude Design test runs into a single canonical skill (629 lines, trimmed from 916). Every change is backed by an observed failure mode in an actual Claude Design output. Scene / shader correctness: - Clip contract mandatory on every scene (class="scene clip" + data-start + data-duration + data-track-index). Runtime's visibility gate then handles the mount/unmount timing that was previously left to manual tl.set() calls. - Scene content MUST be wrapped in <div class="scene-content">. HyperShader's captureIncomingScene() helper specifically hides this element during html2canvas so tl.from() pre-states don't leak into the shader texture. Not wrapping was the cause of the "boxes/rectangles during transitions" bug. - Transition timing rule: transition.time must be STRICTLY LESS than the scene boundary, transition.time + duration STRICTLY GREATER. Simplest safe placement: transition.time = boundary - duration/2. Transitions equal to the boundary cause a blink (outgoing scene already visibility:hidden when html2canvas fires → blank texture). - HANDS OFF scene-container autoAlpha — HyperShader owns scene opacity end-to-end in both browser preview and engine/render mode. - Don't strip visibility:hidden from inline scene styles "so scenes mount": the runtime's visibility gate handles mounting automatically. Inputs and research: - Visual direction is neutral — no preset palettes, no preset motion, no content-type → aesthetic mapping. Four-tier input model: attachments > pasted content > research > user URL. Research (web_search + web_fetch on blogs/press/Wikipedia) is first-class, not a SPA-fallback. - Sparse-brief rule: when the user provides no attachment / no brand / no palette / no aesthetic, ask ONE short question with concrete options before generating. Includes "just build" escape hatch with a concrete offered aesthetic. Handoff to end user: - README.md template with `npx hyperframes doctor` / `preview` / `render` commands, plus FFmpeg install instructions per OS. - Two-tier references section: foundational fallbacks (core skill, GSAP, CLI, player README, docs site, registry/examples) + feature-specific fetches (captions, TTS, audio-reactive, etc.). Pre-delivery checklist now 10 items including transition timing and scene-content wrapper. Made-with: Cursor
Claude Design empirically follows worked-example code pairs more reliably
than prose rules. The core framework skill already banned exit animations
before shader transitions, non-deterministic stagger, etc., but real
outputs (skill-test8, skill-test-9) kept violating them anyway. Adding
explicit WRONG/RIGHT code pairs closes that gap — same rule, different
pedagogy.
Four anti-patterns added, each tied to a bug observed in a real
Claude Design output this session:
1. Exit tweens before shader transitions — the shader captures an empty
outgoing scene if content has been faded out first. Matches Remotion's
TransitionSeries and the GSAP community consensus that transitions own
the visual handoff.
2. Non-deterministic `stagger: { from: "random" }` — GSAP's internal
random is unseeded; two renders produce different orderings, violating
deterministic-render and failing PSNR regression baselines.
3. `position: absolute` with hardcoded pixels on `.scene-content` — works
at 1920x1080 but breaks at any other aspect ratio.
4. SVG filter data URLs as `background-image` (e.g. feTurbulence grain) —
Safari's canvas-taint rules produce a tainted html2canvas output;
WebGL's texImage2D then throws SecurityError with no framework opt-out,
killing every shader transition in Safari + cross-origin iframe
environments like Claude Design's in-pane preview. Preferred
replacement: layered CSS radial-gradient dots. Escape hatch for
unavoidable SVG effects: mark with `data-no-capture`.
Also refreshes docs/guides/claude-design.mdx to reflect the V6.1 skill
additions (anti-patterns section, expanded deterministic-animation
notes, Safari SecurityError mention).
Made-with: Cursor
|
Reviewers — this PR has evolved substantially from Miguel's original Apr 20 description. Posting a proper What/Why/How/Test-plan to catch everyone up, since nothing in this thread explains the 10 commits between open and now. WhatShips a self-contained Claude Design + HyperFrames skill + Claude Design docs guide. Current state (HEAD):
WhyMiguel's original design (Apr 20): thin 76-line skill that tells Claude Design to fetch
The skill evolved through ~10 commits in response to each of these findings. The end state is a self-contained, pedagogy-driven skill that blocks Claude Design's defaults explicitly and inlines the content it needs instead of relying on fetches. HowChronological phases with commit refs:
Notable design decisions:
Test plan
Related PRs
Documentation updated
|
There was a problem hiding this comment.
Pull request overview
Adds a Claude Design–specific HyperFrames skill entry point and supporting documentation, plus updates @hyperframes/player CDN docs to reflect working ESM usage with a global-build fallback.
Changes:
- Introduces
skills/claude-design-hyperframes/SKILL.mdto guide Claude Design toward HyperFrames composition output (including preview/runtime constraints). - Adds a dedicated Claude Design docs guide and links it from Quickstart and Prompting surfaces.
- Updates player CDN documentation to prefer ESM (
type="module") and document the explicit global build fallback.
Reviewed changes
Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| skills/claude-design-hyperframes/SKILL.md | New Claude Design entry-point skill with detailed HyperFrames authoring + sandbox constraints and templates. |
| packages/player/README.md | Updates CDN snippet to ESM + adds explicit global build fallback. |
| docs/quickstart.mdx | Links Claude Design users to the new entry-point skill + guide. |
| docs/packages/player.mdx | Aligns docs with ESM CDN include and global build fallback. |
| docs/guides/prompting.mdx | Adds Claude Design-specific prompt/setup guidance. |
| docs/guides/claude-design.mdx | New guide for using HyperFrames from Claude Design (skill attachment, prompt shapes, preview template). |
| docs/docs.json | Adds the Claude Design guide to the Guides nav. |
| README.md | Adds Claude Design entry-point mention and includes the new skill in the skills table. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| - You're extracting a REUSABLE sub-comp that appears in multiple places (chart block, logo outro). | ||
| - A single scene is so complex it deserves its own file (full UI recreation, heavy data-vis). | ||
|
|
||
| If you do split, **HyperShader lives at the ROOT `index.html` ONLY** — never inside a sub-composition. HyperShader hardcodes `#gl-canvas` as its canvas ID (see `packages/shader-transitions/src/hyper-shader.ts:169`); multiple HyperShader instances can't share one canvas. When a sub-comp's HyperShader fails silently on canvas conflict, its fallback code calls `document.querySelectorAll(".scene")` document-wide and sets every scene's opacity to 0 — corrupting visibility across the whole document. Symptom: only scene-1 of each act shows, scenes 2+ never appear. |
There was a problem hiding this comment.
This source reference appears to be off: gl-canvas is created/queried at packages/shader-transitions/src/hyper-shader.ts:180-188 in the current code (not :169). Since this is meant as a precise breadcrumb, please update the line number (or drop the line number and just reference the file) to avoid sending readers to the wrong place.
| If you do split, **HyperShader lives at the ROOT `index.html` ONLY** — never inside a sub-composition. HyperShader hardcodes `#gl-canvas` as its canvas ID (see `packages/shader-transitions/src/hyper-shader.ts:169`); multiple HyperShader instances can't share one canvas. When a sub-comp's HyperShader fails silently on canvas conflict, its fallback code calls `document.querySelectorAll(".scene")` document-wide and sets every scene's opacity to 0 — corrupting visibility across the whole document. Symptom: only scene-1 of each act shows, scenes 2+ never appear. | |
| If you do split, **HyperShader lives at the ROOT `index.html` ONLY** — never inside a sub-composition. HyperShader hardcodes `#gl-canvas` as its canvas ID (see `packages/shader-transitions/src/hyper-shader.ts`); multiple HyperShader instances can't share one canvas. When a sub-comp's HyperShader fails silently on canvas conflict, its fallback code calls `document.querySelectorAll(".scene")` document-wide and sets every scene's opacity to 0 — corrupting visibility across the whole document. Symptom: only scene-1 of each act shows, scenes 2+ never appear. |
There was a problem hiding this comment.
Fixed in commit 8427e3a — dropped the specific line number and replaced with a phrase ("the canvas creation path") so the reference doesn't drift. Good catch, the actual code lives around :187-190 not :169.
| Use `@hyperframes/shader-transitions`. Exactly **13 shader names** are valid — any other string throws `[HyperShader] Unknown shader`: | ||
|
|
||
| `domain-warp`, `ridged-burn`, `whip-pan`, `sdf-iris`, `ripple-waves`, `gravitational-lens`, `cinematic-zoom`, `chromatic-split`, `swirl-vortex`, `thermal-distortion`, `flash-through-white`, `cross-warp-morph`, `light-leak`. |
There was a problem hiding this comment.
The shader catalog here claims there are exactly 13 valid shader names, but the actual registry currently includes 14 shaders (it also includes glitch). This guidance will cause false [HyperShader] Unknown shader errors for users who try glitch, and the count/list will drift from the source of truth. Update the count and include glitch in the allowed list (or point readers at the SHADER_NAMES list in packages/shader-transitions/src/shaders/registry.ts).
| Use `@hyperframes/shader-transitions`. Exactly **13 shader names** are valid — any other string throws `[HyperShader] Unknown shader`: | |
| `domain-warp`, `ridged-burn`, `whip-pan`, `sdf-iris`, `ripple-waves`, `gravitational-lens`, `cinematic-zoom`, `chromatic-split`, `swirl-vortex`, `thermal-distortion`, `flash-through-white`, `cross-warp-morph`, `light-leak`. | |
| Use `@hyperframes/shader-transitions`. Exactly **14 shader names** are valid — any other string throws `[HyperShader] Unknown shader`. Source of truth: `SHADER_NAMES` in `packages/shader-transitions/src/shaders/registry.ts`: | |
| `domain-warp`, `ridged-burn`, `whip-pan`, `sdf-iris`, `ripple-waves`, `gravitational-lens`, `cinematic-zoom`, `chromatic-split`, `swirl-vortex`, `thermal-distortion`, `flash-through-white`, `cross-warp-morph`, `light-leak`, `glitch`. |
There was a problem hiding this comment.
Fixed in commit 8427e3a — updated the count to 14 and added glitch to the inline list. I missed it originally because glitch is an unquoted key in the registry (valid JS identifier) while my earlier grep pattern required quoted strings. Also added a pointer to the authoritative packages/shader-transitions/src/shaders/registry.ts so the list can't silently drift again.
Address Copilot review comments on #353: 1. Shader count was "13" — actual registry has 14 (missed `glitch` which is an unquoted key in `packages/shader-transitions/src/shaders/ registry.ts` so my earlier grep pattern with quoted strings skipped it). Fix: update count to "14" and add `glitch` to the inline list. Also add a pointer to the authoritative registry file so the list doesn't silently drift again if new shaders land. 2. `hyper-shader.ts:169` line reference for the hardcoded `#gl-canvas` ID was wrong — the canvas is created/queried around line 187-190 in the current code. Since precise line breadcrumbs drift easily, drop the line number and reference the file with "the canvas creation path" instead. Same-branch follow-up to the earlier V6.1 anti-pattern commit. Made-with: Cursor
jrusso1020
left a comment
There was a problem hiding this comment.
Verdict: approve
Three coupled changes, all on-target:
-
New
skills/claude-design-hyperframes/SKILL.md— Claude Design-specific entry point. Opens with the right redirect (nocopy_starter_componentwithkind: "animations.jsx", no built-in "Animated video" skill, no React+Babel, no hand-rolled scale-to-fit wrappers), then teaches the HTML + paused-GSAP-timeline contract, sandbox-compatible preview with token forwarding, deterministic-render constraints, and four worked-example anti-patterns. This is surgical — each directive maps to a known Claude Design failure mode. -
New
docs/guides/claude-design.mdx— user-facing setup that correctly splits Claude Design from thenpx skills addpath (which is right for coding agents but wrong for Claude Design, since attachment beats URL empirically). The token-forwardingpreview.htmltemplate + the runtime-preload block inindex.htmlare the two mechanics the sandbox requires to not render black, and both are documented verbatim. Prompt patterns cover the four input shapes (rich brief with attachments, pasted content, sparse "let-it-ask", and static-URL brief) that actually work against Claude Design's fetch tools. -
@hyperframes/playerCDN fix — adds the explicitdist/hyperframes-player.global.jsfallback next to the default ESM include. Legitimate fix for consumers that can't use<script type="module">, and keeps the Claude Design guide's fallback example consistent with what the@hyperframes/playerREADME recommends.
CI is clean across the board: Format / Typecheck / Lint / Test / Test: runtime contract / Build / Windows tests / Render on Windows / Smoke: global install / Perf (fps, parity, drift, load, scrub) / regression / CodeQL / all three Analyze jobs / Validate docs / Semantic PR title. Mintlify dev/validate/export stalled in Miguel's local env per the PR notes, but the CI Validate docs job is green — so the docs-side validation didn't actually skip, Miguel's local fallback to broken-links + screenshots was just belt-and-suspenders.
Two non-blocking notes:
-
Cross-surface skill routing. The new skill's
description("Use for any request to create a video, animation, launch teaser, editorial explainer, product tour, social reel, or motion deliverable") overlaps heavily with the existinghyperframesskill's description. That's fine inside Claude Design (which attaches the file directly, no routing ambiguity), but Claude Code / Cursor / Codex auto-discover all ofskills/by convention — so on those surfaces, agents will see two skills with near-identical descriptions competing for the same brief. Consider tightening the description to lead with "Use when running inside Claude Design specifically. For Claude Code / Cursor / Codex, use thehyperframesskill instead." so cross-surface routing has a clean tie-breaker. 1-line edit; doesn't block. -
README.md rebase. My hf#461 just merged into
mainasd125d65and touched README.md in the exact same section (right after the Codex install block). Since this branch's base is3089c8ee(pre-#461), a rebase will need to resolve that single-hunk conflict — just re-insert the Claude Design paragraph after both the Codex block AND the Cursor paragraph that landed in #461. Trivial but worth knowing about before merge.
No blockers. Skills align with the plugin-distribution pattern (shared skills/ root, description-gated routing), the Claude Design branch is intentionally distinct from the plugin.json-driven surfaces because Claude Design doesn't have a plugin manifest, and the player CDN fix is a real bug. Ship on James's go-ahead.
Review by hyperframes
Replace the rule-heavy Claude Design skill with a template-first approach. Instead of teaching all rules from scratch (863 lines), provide pre-valid skeletons where structural rules are embedded. Claude Design fills in palette, content, and animations. Key changes: - Pre-valid HTML skeletons for social reel (vertical), launch teaser, product explainer, and cinematic title - Mixed transitions: 2-3 shader transitions at key moments, rest hard cuts (matches professional video practice) - autoAlpha toggles for non-anchor scenes (fixes invisible middle scenes caused by HyperShader's blanket opacity reset) - Explicit first-anchor opacity fix (HyperShader browser mode never auto-shows the first anchor scene) - No shaders on vertical (1080x1920) — WebGL canvas is hardcoded to 1920x1080 in webgl.ts - Inline animation patterns (counter, stroke draw, stagger, float, bar chart, orbit, highlight sweep, safe CSS grain) - Claude Design → Claude Code handoff workflow documented in README template and delivery step - Troubleshooting table for black preview, invisible scenes, seeking - Self-review checklist split: structural validity, brand accuracy, animation baseline - Skill description updated per review feedback on PR heygen-com#353 to disambiguate from the hyperframes skill on cross-surface routing Bugs fixed by this rewrite (confirmed across demov4-1 through demov4-6 and demov5-1 through demov5-5): - First shader anchor invisible in every composition - Non-anchor scenes killed by blanket querySelectorAll(".scene") opacity reset - visibility toggles insufficient (opacity:0 persists after reset) - Shaders on vertical compositions produce distorted transitions
Summary
claude-design-hyperframesskill entry point that tells Claude Design to fetch the upstream HyperFrames skills tree@hyperframes/playerCDN docs to show a working ESM include and the explicit global-build fallbackVerification
bunx oxfmt --check README.md docs/docs.json docs/guides/prompting.mdx docs/packages/player.mdx docs/quickstart.mdx packages/player/README.md docs/guides/claude-design.mdx skills/claude-design-hyperframes/SKILL.mdbun run lint:skillsbunx mintlify broken-links/tmp/hyperframes-pr-artifacts/claude-design-guide-source.png/tmp/hyperframes-pr-artifacts/player-docs-source.pngNotes
mintlify dev,mintlify validate, andmintlify exportstalled in this environment during preview/bootstrap, so I used the broken-links check plus screenshot-based browser fallback instead of claiming a full rendered-site pass.