Build a high-fidelity, auto-playing, interactive product demo for a marketing/landing-page hero — a device or browser mockup that scripts the product's REAL UI so visitors instantly feel the product. Use when someone asks to create an interactive hero, an interactive hero demo, a "try it live" showcase, an animated product walkthrough, a scripted UI demo, or a Codex-style playable hero. Not for static screenshots or generic marketing copy.
Build a high-fidelity, auto-playing, interactive product demo for a marketing/landing-page hero — a device or browser mockup that scripts the product's REAL UI so visitors instantly feel the product. Use when someone asks to create an interactive hero, an interactive hero demo, a "try it live" showcase, an animated product walkthrough, a scripted UI demo, or a Codex-style playable hero. Not for static screenshots or generic marketing copy.
license
MIT
metadata
{"author":"chat-aside","version":"1.0"}
Build a high-fidelity, auto-playing, interactive demo that replaces (or augments) a
marketing homepage hero, so a visitor understands the product in seconds by watching it
drive itself — and can take over and explore.
Copy-paste code skeletons live in references/architecture.md — read it before writing the engine.
Reference implementation (optional). This skill was distilled from a working demo. If the
current repo happens to contain one (search for a hero-demo/ folder or a marketing hero
component, e.g. **/marketing/hero-demo/), read it first and mirror its patterns. If not, this
file plus references/architecture.md are self-contained — follow them directly.
The one principle
Fidelity comes from porting, not inventing. Do not design a "demo-ish" UI from scratch.
Find the product's real components and replicate them exactly: the same icons (down to inline
SVG paths), the same Tailwind classes, the same design tokens, the same animations. A demo that
looks 90% like the product reads as fake; one that looks identical reads as the product.
Workflow
0. Gather the source of truth (do this first, it dominates quality)
Before writing anything, study the REAL product UI and extract, verbatim:
Design tokens — the theme CSS variables / Tailwind config the product uses (e.g. shadcn
--background/--card/--muted/--primary, radius, shadows). Reuse them so colors match exactly.
If the product ships a .dark token set, render the demo inside a .dark wrapper and reuse
the SAME token classes (bg-card, text-muted-foreground, …) rather than hand-picking hexes.
Icons & logos — copy the exact inline SVGs / icon components (provider logos, etc.). Do not
substitute a lookalike icon library.
Component markup — read the real components and mirror their class strings, spacing,
border-radius, badges, empty states, and micro-copy (pull real strings from the product's i18n).
Signature animations — the product's own keyframes (a sync-highlight flash, a selection
color, a spinner). Port the keyframes into the site's global CSS, scoped to the demo root.
Dispatch a read-only explorer agent to produce a structured "visual reference" doc of the real
components, then port from it. Quote real class names in that doc.
1. Scaffold a componentized mockup
A device/browser shell (traffic lights, address bar, tab strip) → panes → leaf
components. Keep every piece a small, named component — you WILL add more scenes later.
Reuse the product's theme tokens inside the shell. Scope any product-specific CSS
(keyframes, custom utilities) under a single root class so it never leaks into the site.
All dark-mode (or whatever the product's default is). Don't build a theme the product lacks.
2. Build the scene-based timeline engine (the core — see references/architecture.md)
This architecture is what let the reference demo grow from 4 to 7 scripted scenes painlessly.
Single state object (DemoState) mutated by one patch(partial). Every visual — active
tab, streaming text, dialog phase, simulated cursor target, open tabs — is a field.
Scenes as an ordered array of cancellable async (ctx) => {} functions. ctx gives
patch, get, wait(ms), stream(text, onUpdate), and cancelled(). Each scene checks
cancelled() after every await and returns early.
Each scene self-seeds its entry state (patches the baseline it needs at the top) so it plays
correctly in sequence AND when jumped to directly from the stepper.
Engine runs scenes from a start index, loops, tracks activeIndex, and measures each
scene's real wall-clock duration to feed an accurate progress bar (deterministic scenes → exact
after the first loop).
Adding a new interaction later = write one scene function and append it to the array. Nothing
else changes; the stepper grows a circle automatically.
3. Simulate the user with a data-driven cursor
A CursorLayer mounted over the WHOLE mockup (so it can reach the toolbar AND the panes)
measures [data-cursor-target="…"] elements relative to its container and glides an SVG pointer
there with a spring. Optional lagging "comet" trail dots.
Scenes drive it declaratively: patch({ cursor: { target: "search-input" } }), then a
clickCursor() helper flips a clicking flag for a ripple. Tag every clickable target the
script touches with data-cursor-target.
Compose real micro-interactions from state: streaming tokens, a left-to-right "drag-select"
highlight, dialogs (publish/share) with idle→working→success phases, opening a new browser tab
that renders the produced artifact, dropdown menus. Reuse the product's real dialog/menu styling.
4. Controls: chapter stepper + play/pause
Replace the usual "hint" line with a stepper: numbered circles (one per scene), a
story-style progress bar that advances per scene using the measured duration, current
"N/total · label", and click-to-jump. Style it in the product's accent color.
A play/pause affordance (e.g. in the mockup toolbar) that stops and resets to the original
idle state, then restarts. Reflect play/pause state in the icon; add a hover tooltip.
5. Make it robust and polite
Autoplay only when in viewport (IntersectionObserver) and pause when scrolled away.
Any manual interaction pauses autoplay and snaps to a clean idle state (e.g. show the
finished conversation, close overlays) — never leave a blank or half-streamed frame.
Respect prefers-reduced-motion unless the product owner explicitly wants default-play; if you
default to playing, still keep a static, complete first paint for SSR / no-JS.
Self-host assets (avatars, logos) under public/; never hotlink a third-party CDN. Flag the
licensing of any borrowed asset — a lib's MIT code does not license its demo images.
Cancel every timer/interval on unmount and on scene cancellation; unique React keys everywhere.
6. Verify visually, not just by compiling
typecheck + production build after each chunk.
Drive the running dev server with headless Chromium (Playwright) and screenshot each key
state — wait for a target element/text to appear rather than sleeping a fixed time, so you
catch the exact frame. Read the screenshots and iterate until each state is faithful.
Also assert zero console errors (filter out sandbox/network noise) — this is how you catch
hydration and DOM-nesting bugs the type checker misses.
Gotchas learned the hard way
<div> inside <p> — a bubble/popover rendered inside a rendered-markdown <p> throws a
hydration error. Make such overlays <span> (with display:flex) — they're phrasing content.
Cursor can't reach a target if the layer's measurement container doesn't contain it. Mount
the cursor layer at the outermost mockup element so toolbar + panes are all reachable.
Duplicate React keys when two snippets/records derive the same key — derive keys from a
stable parent id + index, not from content.
Scenes that depend on prior scenes' state break when jumped to — always self-seed.
Progress bar drift — don't guess durations; measure the real elapsed time and reuse it.
.dark tokens don't resolve if the demo isn't inside a .dark (or the product's theme)
ancestor. Wrap the demo root.
Deliverable checklist
Mockup + panes are faithful to the real components (ported tokens, icons, class strings).
Scene engine: single state, cancellable self-seeding scenes, loop, jump, real-timed progress.
Simulated cursor drives at least: type, select/drag, click-through-a-dialog.
