From 95ca0200d4cd81c2a5ef8fce7cf07b1a7a685607 Mon Sep 17 00:00:00 2001 From: ukimsanov Date: Thu, 23 Apr 2026 20:52:40 -0400 Subject: [PATCH] docs: update all Claude Design references for template-first skill Update docs, quickstart, prompting guide, and README to reflect: - Template-first approach (attach file, not paste URL) - Claude Design produces drafts, refine in any AI coding agent - Known limitations (vertical shaders, seeking, no linting) - Practical example prompts (feature announcement, founder pitch) - Removed outdated references (invisible bridges, fetch-the-skills-tree) Co-Authored-By: Claude Opus 4.6 (1M context) --- README.md | 18 +-- docs/guides/claude-design.mdx | 204 +++++++++++++++------------------- docs/guides/prompting.mdx | 11 +- docs/quickstart.mdx | 2 +- 4 files changed, 109 insertions(+), 126 deletions(-) diff --git a/README.md b/README.md index c2c1879d5..0ca718a23 100644 --- a/README.md +++ b/README.md @@ -33,7 +33,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 — invoke `/hyperframes` to author compositions, `/hyperframes-cli` for CLI commands, and `/gsap` for animation help. -For Claude Design, use the GitHub-hosted entry point at [`skills/claude-design-hyperframes/SKILL.md`](https://github.com/heygen-com/hyperframes/blob/main/skills/claude-design-hyperframes/SKILL.md) and let Claude fetch the repo's `skills/` tree from there. See the [Claude Design guide](https://hyperframes.heygen.com/guides/claude-design). +For Claude Design, 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 chat. Claude Design produces a valid first draft; refine it in any AI coding agent. See the [Claude Design guide](https://hyperframes.heygen.com/guides/claude-design). For Codex specifically, the same skills are also exposed as an [OpenAI Codex plugin](./.codex-plugin/plugin.json) — sparse-install just the plugin surface: @@ -184,14 +184,14 @@ HyperFrames ships [skills](https://github.com/vercel-labs/skills) that teach AI npx skills add heygen-com/hyperframes ``` -| Skill | What it teaches | -| --------------------------- | ------------------------------------------------------------------------------------------------------- | -| `claude-design-hyperframes` | Claude Design entry point that pulls the upstream `skills/` tree and standardizes player-based previews | -| `hyperframes` | HTML composition authoring, captions, TTS, audio-reactive animation, transitions | -| `hyperframes-cli` | CLI commands: init, lint, preview, render, transcribe, tts, doctor | -| `hyperframes-registry` | Block and component installation via `hyperframes add` | -| `website-to-hyperframes` | Capture a URL and turn it into a video — full website-to-video pipeline | -| `gsap` | GSAP animation API, timelines, easing, ScrollTrigger, plugins, React/Vue/Svelte, performance | +| Skill | What it teaches | +| --------------------------- | ------------------------------------------------------------------------------------------------------------------ | +| `claude-design-hyperframes` | Template-first Claude Design skill — pre-valid skeletons, produces video drafts for refinement in any coding agent | +| `hyperframes` | HTML composition authoring, captions, TTS, audio-reactive animation, transitions | +| `hyperframes-cli` | CLI commands: init, lint, preview, render, transcribe, tts, doctor | +| `hyperframes-registry` | Block and component installation via `hyperframes add` | +| `website-to-hyperframes` | Capture a URL and turn it into a video — full website-to-video pipeline | +| `gsap` | GSAP animation API, timelines, easing, ScrollTrigger, plugins, React/Vue/Svelte, performance | ## Contributing diff --git a/docs/guides/claude-design.mdx b/docs/guides/claude-design.mdx index 069652222..91ccee584 100644 --- a/docs/guides/claude-design.mdx +++ b/docs/guides/claude-design.mdx @@ -1,31 +1,37 @@ --- title: Claude Design -description: "Use HyperFrames from Claude Design with a GitHub-hosted skill entry point that pulls the repo's existing skills and preview patterns." +description: "Create HyperFrames video drafts in Claude Design using a template-first skill, then refine in any AI coding agent." --- -Claude Design needs a different setup than Claude Code, Cursor, or Codex. The local `npx skills add heygen-com/hyperframes` flow is the right path for coding agents. For Claude Design, attach the HyperFrames skill file to your chat — empirically that produces sharper, more rule-compliant output than pasting the URL. +Claude Design produces a **valid first draft** of a HyperFrames video — brand identity, scene content, layout, animations, and transitions. You then download the ZIP and refine in any AI coding agent (Claude Code, Cursor, Codex, Windsurf, etc.) with linting and live preview. -## Get the skill +## Get started - - - Save the file, then drag it into a Claude Design chat as an attachment. - - - Read the skill, copy sections, or link to it in a prompt. - - + + + Save [`SKILL.md`](https://raw.githubusercontent.com/heygen-com/hyperframes/main/skills/claude-design-hyperframes/SKILL.md) to your computer. + + + Start a new chat at [claude.ai](https://claude.ai) with Claude Design enabled. + + + Drag the SKILL.md file into the chat. Describe what you want — include screenshots, brand assets, or a palette if you have them. + + + Claude Design produces `index.html`, `preview.html`, `README.md`, and `DESIGN.md`. Download the ZIP. + + + Open the project in Claude Code, Cursor, Codex, or any agent with terminal access for animation polish, timing, and production QA. + ```bash + npx skills add heygen-com/hyperframes # install skills (one-time) + npx hyperframes lint # should pass with zero errors + npx hyperframes preview # open the studio + ``` + + - **Prefer attaching the file over pasting the URL.** Claude Design reads file attachments natively with detail preserved. URL-driven runs produce usable output but consistently miss more rules than attachment-driven runs. + **Attach the file, don't paste the URL.** Claude Design reads file attachments natively with detail preserved. URL-driven runs produce usable output but consistently miss more rules. ## Which setup to use @@ -36,40 +42,51 @@ Claude Design needs a different setup than Claude Code, Cursor, or Codex. The lo | Claude Code | `npx skills add heygen-com/hyperframes`, then use `/hyperframes` | | Cursor / Codex / Gemini CLI | `npx skills add heygen-com/hyperframes` | -## Prompt shape for Claude Design +## How the skill works -Claude Design does not use slash commands. Lead with the skill file (attached or URL), describe the video, and ideally give Claude Design something to synthesize from — screenshots, a brand PDF, a reference video, a pasted palette, or at minimum a vibe in words. +The skill gives Claude Design **pre-valid HTML skeletons** — the structural rules (data attributes, timeline registration, scene visibility, preview token forwarding) are already embedded. Claude Design fills in the creative work: -The skill reads inputs in this order of reliability: **attachments → pasted content → web research → URLs**. A modern SPA homepage returns almost nothing via `web_fetch` because JavaScript isn't executed, so brand-accurate output on brief like "make a video for linear.app" depends on attaching screenshots or letting Claude Design search for the brand's blog, press, or Wikipedia. +1. **Palette + typography** — CSS custom properties on `:root` +2. **Scene content** — text, images, layout inside `.scene-content` wrappers +3. **Animations** — GSAP entrance tweens and mid-scene activity +4. **Transitions** — hard cuts for most scenes, shader transitions at 2-3 key moments -Strong Claude Design prompts usually include: +This template-first approach means the output passes `npx hyperframes lint` with zero errors on first download — Claude Code can start refining immediately without structural fixes. -- the attached skill file (or its URL) -- the source material: screenshots, a brand PDF, a reference video, pasted copy, or a URL -- duration and aspect ratio -- tone or visual direction (if you have one — otherwise let Claude Design ask) -- explicit deliverables: `index.html`, `preview.html`, `README.md` - -## Copy-paste prompts +## Example prompts - + ```text - Use the attached skill. Make a 30-second 16:9 product walkthrough for my app, - matching the design in these screenshots. 5 scenes: hero, three features, - closing CTA. Shader transitions between scenes. + Use the attached skill. I just shipped dark mode for my app. Make me a + 15-second Instagram reel announcing it. + + - App name: Taskflow + - Primary color: #6C5CE7 + - The vibe is clean, minimal, dark + - Key stat: "47% of users requested this" ``` - + ```text - Use the attached skill. 30s hero reel with this copy for each scene: + Use the attached skill. 25-second LinkedIn video for my startup. - 1. "The fast web broke us." - 2. "Every app optimized for attention. None for thought." - 3. "Something is changing. Blogs are back." - 4. "Welcome to the slow web." + 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 - Dark theme, editorial, serif typography (not Playfair). + Professional but not corporate. Think Linear or Vercel energy. + ``` + + + ```text + Use the attached skill. 10-second reel. Just one big number: + + "$4.2 billion processed in Q1 2026" + + Dark background, the number should animate up from zero. Subtle, + confident. End with logo placeholder and "stripe.com" ``` @@ -77,86 +94,47 @@ Strong Claude Design prompts usually include: Use the attached skill. Make a 30-second launch video for Orbit. ``` - The skill will ask ONE short question offering five input channels - (screenshot, PDF, reference video, vibe word, must-have element) plus - a "just build" escape hatch before generating. - - - ```text - Use the HyperFrames Claude Design skill at - https://github.com/heygen-com/hyperframes/blob/main/skills/claude-design-hyperframes/SKILL.md - and turn https://www.anthropic.com/news/claude-design-anthropic-labs into a - 45-second editorial explainer. Keep copy close to the article's real headlines. - ``` + The skill asks ONE short clarifying question before generating. -## Preview with `@hyperframes/player` +## What to include in your prompt -When Claude Design generates a `preview.html`, it embeds the composition with `` 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