scrollcraft

1---2name: scrollcraft3description: "Premium scroll-driven landing pages; scroll = timeline."4version: 1.0.05author: 'nateherkai (upstream scroll-craft), ported by Hermes Agent'6license: MIT7platforms: [linux, macos, windows]8metadata:9  hermes:10    tags: [web-development, landing-page, scrollytelling, animation, design, frontend]11    category: web-development12    homepage: https://github.com/nateherkai/scroll-craft13    related_skills: []14---15 16# scrollcraft17 18Scroll is the only input every visitor already knows. This skill treats it as a19timeline: the wheel is a scrubber, the page is a film with real text on top,20and each section behaves differently enough that the visitor keeps going.21 22**What you produce:** an interview brief, a page grammar, a customer-journey23map, a feeling curve with one engineered peak, a scroll score, one signature24move, assets, one real HTML page on a token-driven design floor, and a strip of25screenshots proving it holds up at every scroll position.26 27Use for: "scrollytelling", "scroll animation site", "a site where scrolling28plays a video", "Apple-style landing page", "3D scroll world", "make my brand a29scroll experience", "this looks like a template", or any request for a site30that should feel like an experience rather than a document.31 32## What this is not33 34It is not "generate a flythrough and drop text on it." That produces one device35applied to a whole page, recognisable at a glance. Four spine rules:36 371. **Variety is the product.** At least four device families, never the same38   device twice in a row. Read [references/devices.md](references/devices.md).392. **The world is photographic** unless the brand is genuinely illustrated.40   Clay/low-poly diorama is banned as a default. Read [references/worlds.md](references/worlds.md).413. **No continuous chain** unless the brief is literally "one continuous42   journey" (then see [references/worldflight.md](references/worldflight.md)).434. **A different world is not a different page.** Structure is a separate axis;44   decide it deliberately. Read [references/uniqueness.md](references/uniqueness.md).45 46## Step 0: The interview47 48**Always ask the user in chat before building anything.** Real questions, asked49and answered in the conversation, written down — not a brief inferred from the50brand name. Eight questions in one pass:51 521. **Vibe in three to five words**, plus up to three references from any medium53   (film, album cover, shop, magazine, game — not "sites you like").542. **The scroll journey, section by section, in their words.**553. **The energy curve** — where calm, where intense.564. **How should someone feel while scrolling, stage by stage, and what is the57   ONE moment they should remember?** Becomes the feeling curve and the peak.58   See [references/feel.md](references/feel.md).595. **One thing this site should do that no site they have seen does** — the60   seed of the signature move.616. **How far from premium-minimal?** Offer the range in62   [references/uniqueness.md](references/uniqueness.md) §5: brutalist,63   maximalist, playful, retro, dense, editorial, premium-minimal.647. **One unbroken world, or distinct scenes?** The biggest structural fork, and65   it is their call.668. **What assets do they already have?** Footage, photos, product shots, brand67   kit. "Nothing" is fine and means a fully generated world.68 69Write the answers verbatim into `<workspace>/builds/<name>/BRIEF.md` (use70write_file) before any act planning. BRIEF.md must contain the eight answers,71the feeling curve (one line per act: emotion, then cause), the peak (as the72sentence a visitor would say to a friend), the completed "It's the site where73___" sentence, and any authored silence. If the user is genuinely unreachable74in a fully autonomous run, self-author BRIEF.md, mark it75`Self-authored, not interviewed`, and say so in the report.76 77## Bootstrap78 79Run the preflight rather than checking by hand (it catches a stripped ffmpeg80that reports missing filters as syntax errors):81 82```bash83node <skill>/scripts/doctor.mjs84node <skill>/scripts/workspace.mjs --ensure   # prints workspace, seeds registry85```86 87Workspace resolution order: `SCROLLCRAFT_HOME` env var; nearest88`.scrollcraft.json` (`{ "workspace": "..." }`) walking up from cwd;89`<project root>/scrollcraft`. Builds live at `<workspace>/builds/<name>/`, the90fingerprint registry at `<workspace>/FINGERPRINTS.md` (seeded from91[templates/FINGERPRINTS.md](templates/FINGERPRINTS.md), starts empty — the gate92stops you repeating *yourself*).93 94Copy `engine/scrollcraft.js` and `engine/scrollcraft.css` into the build95folder. **Never edit the engine per-project.** Theme with tokens; write your96own markup. Bespoke behaviour is bespoke JS in the page, driven off `--sc-p`97and your own `data-sc-*` attributes.98 99## Step 1: The brief, journey first100 101Ask the subject open, in plain prose. Then ask only what Step 0 did not cover:102what is this and who is it for; the one sentence the page installs; the one103next action (one label, used everywhere); what they already have; art104direction from [references/worlds.md](references/worlds.md). Then write the105**journey**: four to seven beats, each a shift in what the visitor knows or106feels. Beats are the spine; a section serving no beat is cut. Confirm the107journey with the user before generating assets — assets are the expensive part.108 109## Step 2: Grammar, gate, then score110 111Full detail in [references/uniqueness.md](references/uniqueness.md).112 113- **Pick a grammar.** Eight, mutually exclusive. Choosing filmic one-shot means114  saying in the report why the other seven lost. Nav, hero and close follow115  from the grammar.116- **Invent the signature move.** One bespoke interaction coded in the page, not117  a parameter change to a kit device. Interview question 5 is the seed.118- **Run the fingerprint gate.** The planned build must differ from every row in119  `<workspace>/FINGERPRINTS.md` on at least 4 of 6 dimensions: grammar, nav120  treatment, hero device, act-sequence shape, close pattern, signature move.121  If it fails, change the plan, not the log.122- **Write the feeling curve before the score table** (method:123  [references/feel.md](references/feel.md)). Then assign each beat a device in124  a written table (beat / device / why).125 126Checks before building: grammar bans hold; 4+ device families; no device127twice in a row; at most two `scrub` acts; no two adjacent acts with the same128feeling; one peak with the largest span; total page length 8–14129viewport-heights.130 131## Step 3: Assets132 133Full pipeline, prompt scaffolds and model notes: [references/assets.md](references/assets.md).134 135**Hermes-native paths first:**136 137- **User-supplied footage and photos** — no key, no spend, a first-class route.138  Grade and encode them.139- **The `image_generate` tool** for stills: one style preamble reused verbatim140  in every prompt is what makes six images look like one shoot. Inspect every141  asset (vision_analyze) before use; rerolling beats shipping a bad frame.142 143**Optional upstream path — kie.ai** (vendored verbatim as144[scripts/kie.mjs](scripts/kie.mjs)): photoreal stills and camera-move clips.145Requires the `KIE_AI_API_KEY` environment variable (export it in your shell;146there is no bundled env file in this port). Check balance with147`node <skill>/scripts/kie.mjs probe`; a still costs cents, a 5s clip more.148 149```bash150node <skill>/scripts/kie.mjs still "<style preamble>\n\n<scene>" out/01-hero.png --ar 16:9151node <skill>/scripts/kie.mjs shot  "<camera move>" out/01-hero.png out/01.mp4 --dur 5152bash  <skill>/scripts/encode.sh out/01.mp4 assets/01.mp4153bash  <skill>/scripts/encode.sh out/01.mp4 assets/01-m.mp4 mobile154```155 156**Encode for scrubbing, not playback.** `encode.sh` sets a dense GOP because157seeking walks from the previous keyframe; a normal web encode scrubs like mud.158It also strips audio.159 160## Step 4: Build the page161 162Write real HTML — real `<h1>`, real `<p>`, real reading order. The engine reads163`data-sc-*` attributes off your markup and drives it; it never generates DOM.164Start from [references/template.html](references/template.html). Device165patterns: [references/devices.md](references/devices.md). Spacing, type, depth,166colour: [references/taste.md](references/taste.md) — read it before writing167markup. Theme by overriding tokens, six values and two fonts:168 169```css170:root {171  --sc-canvas: #0A0806;  --sc-surface: #16110E;172  --sc-ink:    #F5EBDD;  --sc-ink-soft: #A2968A;173  --sc-accent: #FF5A3D;  --sc-accent-ink: #15110F;174  --sc-font-display: "Archivo", system-ui, sans-serif;175  --sc-font-text:    "Geist", system-ui, sans-serif;176}177```178 179## Step 5: Verify by scrolling it180 181Not optional. Every scroll position is a different frame; failures live between182the two you looked at. Full procedure: [references/verify.md](references/verify.md).183 184```bash185cd <build project> && npm i playwright-core     # once186node <skill>/scripts/serve.mjs --root . --port 4500 &187node <skill>/scripts/shoot.mjs --url http://localhost:4500 --out lab/shots188node <skill>/scripts/shoot.mjs --url http://localhost:4500 --out lab/mobile --width 390 --height 844189node <skill>/scripts/shoot.mjs --url http://localhost:4500 --out lab/reduced --reduced-motion190```191 192The harness walks each act at six positions, waits for scrub video to settle,193reports dead scroll, cues that never reach full opacity, and composited194contrast; it writes a contact sheet. Then read `sheet.png` yourself195(vision_analyze) — the harness proves a clip advances, not that the page means196anything. Run the feel check ([references/feel.md](references/feel.md) §6):197scroll cold, one word per act, diff against BRIEF.md. Where they disagree the198page is wrong, not the brief.199 200A green run does not cover a real phone (video decoder, autoplay policy, Low201Power Mode). On any reported mobile defect, deploy202[references/device-diag.html](references/device-diag.html) beside the site on203the first round and let the device answer.204 205## Hard rules (ship-blockers)206 207No clay diorama default; no "scroll to explore" cues or animated mouse icons;208no `01 / 06` section counters; at most one eyebrow per three sections; no209visible em dashes; vary the copy anchor; no device twice in a row; never build210before the interview; one engineered peak, not zero or three; the close211resolves instead of fading to a footer; curve before devices; one bespoke212signature move; 4-of-6 fingerprint clearance against every row; never edit the213engine; no full-frame dark overlay for contrast (scrim only where text sits);214no text baked into images; no invented statistics; no `transition: all` or215animating width/height/top/left (`transform`/`opacity`; `clip-path` for216wipes); no gradient text or neon glow; no audio on scrub clips; never ship217without Step 5.218 219## Output220 221The build folder including BRIEF.md, then a short report: grammar and why the222other seven lost, signature move, fingerprint gate result per row, journey,223feeling curve and peak, feel-check diff, score table, what you generated, what224you verified with screenshots, and what you could not verify. Append the225build's row to `<workspace>/FINGERPRINTS.md`.226 227## Pitfalls228 229- `scripts/shoot.mjs` needs Playwright (`npm install playwright` or230  `playwright-core` plus a Chrome install). Hermes' `browser_exec` tool is the231  lighter alternative for scroll-screenshot verification: serve the build,232  scroll in steps, capture screenshots, and inspect them yourself.233- `scripts/kie.mjs` needs `KIE_AI_API_KEY` and paid credit; prefer234  `image_generate` or user assets when the budget is unclear.235- `encode.sh` and `doctor.mjs` expect a full ffmpeg build; distro-stripped236  ffmpeg reports missing filters as command syntax errors — run237  `scripts/doctor.mjs` first.238- Upstream script invocations above are copied from upstream docs and239  unverified by this port beyond `node --check` syntax validation — trust240  `--help`/source if drifted.241- The upstream repo ships worked examples and a change log that are not242  vendored in this port; see the upstream repository if you want them.243