diff --git a/docs/docs.json b/docs/docs.json index 986d6b003..4876a4d93 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -71,6 +71,32 @@ "concepts/determinism" ] }, + { + "group": "Prompt Guide", + "pages": [ + "prompting/overview", + { + "group": "Fundamentals", + "pages": [ + "prompting/anatomy", + "prompting/examples", + "prompting/specification-dial", + "prompting/vocabulary", + "prompting/iterating", + "prompting/rules-and-anti-patterns" + ] + }, + { + "group": "Making it look good", + "pages": [ + "prompting/visual-specs", + "prompting/motion", + "prompting/generated-artwork", + "prompting/recreating-references" + ] + } + ] + }, { "group": "Guides", "pages": [ @@ -86,7 +112,6 @@ "guides/copilot-cli", "guides/claude-design", "guides/open-design", - "guides/prompting", "guides/hyperframes-vs-remotion", "guides/gsap-animation", "guides/keyframes", @@ -410,5 +435,11 @@ "socials": { "github": "https://github.com/heygen-com/hyperframes" } - } -} + }, + "redirects": [ + { + "source": "/guides/prompting", + "destination": "/prompting/overview" + } + ] +} \ No newline at end of file diff --git a/docs/guides/prompting.mdx b/docs/guides/prompting.mdx deleted file mode 100644 index 49907ccc6..000000000 --- a/docs/guides/prompting.mdx +++ /dev/null @@ -1,298 +0,0 @@ ---- -title: Prompt Guide -description: "How to prompt Claude Code, Cursor, Codex, Google Antigravity, GitHub Copilot CLI, and other AI agents to author Hyperframes compositions — with copy-pasteable examples and vocabulary tables." ---- - -Hyperframes is built for AI agents — compositions are plain HTML, the CLI is non-interactive, and the framework ships [skills](https://github.com/vercel-labs/skills) that teach agents the patterns docs alone don't cover. This guide shows how to prompt agents effectively once skills are installed — the vocabulary that changes output, the iteration patterns that save time, and the rules that prevent breakage. - -## One-time setup - -Install the skills in your project (or globally for your agent): - -```bash -npx skills add heygen-com/hyperframes -``` - -The installer shows a picker. Select the **core skills** below — every project needs them. In Claude Code, restart the session after installing; the skills register as **slash commands**. Start at `/hyperframes`: it orients you to the whole surface and routes "make me a video" requests to the right workflow. - -**Core skills — install all of these** - -| Slash command | What it loads | -| ----------------------- | -------------------------------------------------------------------------- | -| `/hyperframes` | **Read first.** The entry skill — capability map + video router; sends "make me a video" intent to the right workflow | -| `/hyperframes-core` | Composition contract — HTML structure, `data-*` attributes, clips, tracks | -| `/hyperframes-animation`| All animation — motion rules, scene blueprints, transitions, and the runtime adapters (GSAP, Lottie, Three.js, Anime.js, CSS, WAAPI, TypeGPU) | -| `/hyperframes-creative` | Creative direction — design spec, palettes, typography, narration, beats | -| `/hyperframes-cli` | Dev-loop CLI — `init`, `lint`, `validate`, `inspect`, `preview`, `render`, `doctor` | -| `/media-use` | Asset preprocessing — `tts`, `transcribe`, `remove-background` | -| `/hyperframes-registry` | Block and component installation via `hyperframes add` | -| `/general-video` | The general authoring workflow — fallback for any video that doesn't match a specific workflow below | - -**Optional workflows — add the ones that match your inputs** (`/hyperframes` routes to whichever you've installed) - -| Slash command | Input → output | -| ------------------------ | --------------------------------------------------------------------------- | -| `/product-launch-video` | A product URL / brief / script → launch or promo video | -| `/website-to-video` | A general website / URL → a video of the site (tour / showcase / social clip) | -| `/faceless-explainer` | Arbitrary text (no URL) → faceless explainer with its own TTS narration | -| `/pr-to-video` | A GitHub PR → code-change explainer | -| `/embedded-captions` | An existing talking-head video → the same footage with captions / subtitles | -| `/talking-head-recut` | An existing talking-head video → footage packaged with designed graphic cards | -| `/motion-graphics` | A short, unnarrated, design-led motion graphic (logo sting, kinetic type, stat / chart) | -| `/music-to-video` | A music track (audio file or video) → a beat-synced video (lyric, slideshow, or kinetic promo) | -| `/slideshow` | A presentation / pitch deck / interactive deck — discrete slides, fragment reveals, branching | -| `/remotion-to-hyperframes` | Port an existing Remotion (React) composition to HyperFrames HTML | - - - To skip the picker and install everything (core + every workflow) in one shot, run `npx skills add heygen-com/hyperframes --all`. And start Hyperframes prompts with `/hyperframes` (or invoke the skill another way for non-Claude agents) — it loads the routing + composition context explicitly so the agent picks the right workflow and gets the rules right the first time. - - -## Claude Design - -Claude Design uses a different setup. Download [`claude-design-hyperframes.md`](https://github.com/heygen-com/hyperframes/blob/main/docs/guides/claude-design-hyperframes.md) from GitHub (click the ↓ button), then **attach it to your chat** (don't paste the URL — file attachments produce better output): - -```text -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 -``` - -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 - -Most successful Hyperframes prompts fall into one of two shapes. - -### Cold start — describe the video - -You tell the agent what you want from scratch. Best for greenfield work where you have the creative direction in your head. - -> Using `/hyperframes`, create a 10-second product intro with a fade-in title over a dark background and subtle background music. - -> Make a 9:16 TikTok-style hook video about [topic] using `/hyperframes`, with bouncy captions synced to a TTS narration. - -Cold-start prompts work best when you specify: - -- **Duration** (e.g. "10 seconds", "30s", "5 scenes of 3s each") -- **Aspect ratio** ("16:9", "9:16 vertical", "1:1 square") — defaults to 1920x1080 otherwise -- **Mood / style** ("minimal Swiss grid", "warm grain analog", "high-energy social") -- **Key elements** (title, lower third, captions, background video, music) - -### Warm start — turn context into a video - -You give the agent something to work with — a URL, a doc, a CSV, a transcript — and ask it to synthesize that into a video. This is where Hyperframes shines because the agent does the research/summarization step *and* the production step in one flow. - -> Take a look at this GitHub repo https://github.com/heygen-com/hyperframes and explain its uses and architecture to me using `/hyperframes`. - -> Summarize the attached PDF into a 45-second pitch video using `/hyperframes`. - -> Read this changelog and turn the top three changes into a 30-second release announcement video using `/hyperframes`. - -> Turn this CSV into an animated bar chart race using `/hyperframes`. - -Warm-start prompts produce richer, more grounded videos because the agent is writing about *something specific* instead of inventing copy. - -## Iterating - -Hyperframes is a conversation. After the first render, talk to the agent the way you'd talk to a video editor — don't re-prompt from scratch: - -> Make the title 2x bigger. - -> Swap to dark mode. - -> Add a fade-out at the end and a lower third at 0:03 with my name and title. - -> The captions are too small and they overlap the lower third. Move them up and shrink them. - -> Replace the background music with `assets/track.mp3`. - -The agent already has the composition open and the skills loaded — small targeted edits produce better results than long re-specifications. - -## Vocabulary that changes output - -The skills map natural-language adjectives to specific framework settings. Using the right word gets you the right result without specifying technical details. - -### Motion & easing - -Describe how motion should *feel* and the agent picks the matching GSAP ease: - -| Say this | Agent uses | Feels like | -| ----------- | ---------------- | ------------------------------ | -| smooth | `sine` / `power1`| Natural deceleration | -| snappy | `power4.out` | Quick and decisive | -| bouncy | `back.out` | Overshoots then settles | -| springy | `elastic.out` | Oscillates into place | -| dramatic | `expo.out` | Fast start, long glide | -| dreamy | `sine.inOut` | Slow, symmetrical | - -**Timing shorthand:** fast (0.2s) = energy, medium (0.4s) = professional, slow (0.6s) = luxury, very slow (1–2s) = cinematic. - -### Caption tones - -Describe the *energy* of your captions and the agent picks matching typography, size, and animation: - -| Tone | Typography | Animation | Size range | -| ------------ | ---------------------- | ------------ | ---------- | -| Hype | Heavy weight fonts | Scale-pop | 72–96px | -| Corporate | Clean sans-serif | Fade + slide | 56–72px | -| Tutorial | Monospace | Typewriter | 48–64px | -| Storytelling | Serif | Slow fade | 44–56px | -| Social | Rounded, playful | Bounce | 56–80px | - -``` -"Hype-style captions with scale-pop" -"Calm, elegant subtitles with slow fades" -"Karaoke-style word highlighting" -``` - -Per-word styling also works: - -``` -"Make brand names larger with accent color" -"Add bounce to emotional keywords" -"Highlight numbers differently" -``` - -### Transitions - -Every multi-scene composition benefits from transitions. Describe the energy level: - -| Energy | CSS option | Shader option | -| ------- | ---------------- | ------------------- | -| Calm | Blur crossfade | Cross-warp morph | -| Medium | Push slide | Whip pan | -| High | Zoom through | Glitch, ridged burn | - -Or describe by mood: - -``` -"Warm transitions for this wellness brand" -"Cold, clinical transitions for tech" -"Playful bouncy transitions" -"Dramatic zoom for the reveal" -``` - -### Audio-reactive animation - -Map audio frequency bands to visual properties. The agent uses these defaults: - -| Audio band | Maps to | Visual effect | -| ---------- | --------- | ------------------- | -| Bass | `scale` | Pulse on the beat | -| Treble | `glow` | Shimmer intensity | -| Amplitude | `opacity` | Breathing | -| Mids | `borderRadius` | Shape morphing | - -``` -"Make the text pulse with the beat" -"Add bass-driven scale to the logo" -"Create glow that responds to treble" -``` - - - Keep audio-reactive effects subtle for text (3–6% intensity). Go bigger for backgrounds (10–30%). - - -### Marker highlights - -Hand-drawn emphasis effects for text: - -| Mode | Effect | Best for | -| ----------- | ------------------ | ------------- | -| `highlight` | Marker sweep | Key phrases | -| `circle` | Hand-drawn ellipse | Single words | -| `burst` | Radiating lines | Hype moments | -| `scribble` | Chaotic scratch | Rough emphasis| -| `sketchout` | Cross-hatch lines | Crossing out | - -``` -"Add a marker highlight sweep on 'revolutionary'" -"Circle this keyword with hand-drawn effect" -"Add burst lines around 'AMAZING'" -``` - -### Text-to-speech voices - -HyperFrames supports three TTS providers: **HeyGen** (Starfish voices, requires sign-in via `npx hyperframes auth`), **ElevenLabs** (requires API key), and **Kokoro** (free, runs locally, no API key needed). The agent asks which provider to use — or picks automatically in autonomous mode. Describe the content and the agent picks a voice, or request one directly: - -| Content type | Kokoro voices | -| ------------- | -------------------------- | -| Product demo | `af_heart`, `af_nova` | -| Tutorial | `am_adam`, `bf_emma` | -| Marketing | `af_sky`, `am_michael` | - -``` -"Generate narration for this script" -"Create voiceover with a professional female voice" -"Add TTS with British male voice at 1.1x speed" -"Use HeyGen TTS for this narration" -``` - -### Rendering quality - -| Quality | Use for | -| ---------- | ------------------------ | -| `draft` | Fast iteration | -| `standard` | Review and feedback | -| `high` | Final delivery | - -``` -"Quick draft render" -"Render at high quality" -"Export as transparent WebM" -``` - -## Rules to know - -The skills enforce these automatically, but if you hand-edit compositions or debug issues, these are the rules that matter: - -1. **Register all timelines** on `window.__timelines` — the renderer can't seek animations it doesn't know about. -2. **Video elements must be `muted`** — audio goes in separate `