nateherkai/scroll-craft instruction manual

1. Purpose, scope, and Claude Code classification

Scroll Craft instruction manual

Scroll Craft is an MIT-licensed Agent Skill for designing and building distinctive, premium, scroll-driven landing pages. It targets service, product, food, and drink brands and treats scrolling as a timeline: video can scrub with scroll, sections can pin, rails can pan, copy can assemble, backgrounds can change, and pointer movement can drive non-scroll effects. Its deliverable is not merely animation. The documented process produces a brief, customer journey, page grammar, feeling curve, engineered peak, scroll score, bespoke signature move, generated or supplied assets, semantic HTML, and screenshot evidence.

**Claude Code classification:** `claude_extension`, using **context injection** and a **tool surface**, with **medium setup effort**. Evidence: the repository contains a Claude plugin manifest and a `SKILL.md` whose procedural guidance Claude Code can load, plus Node and shell helpers that the agent can run. It is also portable to Codex and other file-capable coding agents. No supplied file documents Claude lifecycle hooks, MCP, interception, or a standalone app, so those mechanisms should not be attributed to it.

The plugin is named `nateherk-design`, version 0.3.0. The skill’s allowed tools are Bash, Read, Write, Edit, Glob, Grep, and AskUserQuestion. The skill is intentionally opinionated: it rejects repeated template structures, generic AI aesthetics, unverified claims, and pages without one clear emotional peak. The engine supplies mechanics but does not generate the page DOM or choose a layout.

2. Installation, activation, and system requirements

Claude Code installation

Add the repository as a plugin marketplace, then install its plugin:

/plugin marketplace add nateherkai/scroll-craft

/plugin install nateherk-design

Describe the desired site normally or invoke the skill directly:

/nateherk-design:scroll-craft

If Claude Code reports `Run /reload-plugins to activate.`, run that command. For development from the repository without installation, the documented command is:

claude --plugin-dir ./plugins/nateherk-design

Codex and other agents

Keep the complete `plugins/nateherk-design/skills/scroll-craft/` folder intact, including references, scripts, templates, and engine. For Codex, copy that folder into the project’s `.agents/skills/` directory and ask Codex to use Scrollcraft. Other skill-aware agents should use their documented skill directory. A generic file-capable agent can be prompted with:

Read plugins/nateherk-design/skills/scroll-craft/SKILL.md and use it to build
my website. Follow the referenced design and verification workflow.

Adjust that path only when the repository is stored in a subfolder.

Requirements

All scripts require Node 18 or newer. Scrubbable video requires a full ffmpeg build; `SCROLLCRAFT_FFMPEG` can override automatic discovery. Verification requires Chrome and `playwright-core`, installed in the build folder. `SCROLLCRAFT_CHROME` overrides Chrome discovery. `KIE_AI_API_KEY` is optional and needed only for generated assets; supplied photos and footage are a fully supported no-key route. The repository reports actual builds only on Windows, although scripts search common Windows, macOS, and Linux locations.

3. Preflight and workspace management

Run setup from the repository root before planning assets or implementation:

node plugins/nateherk-design/skills/scroll-craft/scripts/doctor.mjs
node plugins/nateherk-design/skills/scroll-craft/scripts/workspace.mjs --ensure

`doctor.mjs` checks Node, a full ffmpeg build, Playwright, Chrome, the optional API key, and the resolved workspace. Required failures exit non-zero. This preflight is important because stripped ffmpeg builds can misleadingly report missing filters as command syntax problems, missing WebP support as a filename problem, and Playwright can resolve from the wrong directory.

`workspace.mjs --ensure` prints the selected workspace, creates it, and seeds an empty fingerprint registry. Workspace resolution uses the first match in this order:

1. `SCROLLCRAFT_HOME`.
2. The nearest `.scrollcraft.json` found while walking upward from the current directory, containing `{ "workspace": "path/to/builds" }`.
3. `<project root>/scrollcraft`, where project root is the nearest ancestor containing `.git`.

Each build belongs in `<workspace>/builds/<name>/`; the uniqueness registry is `<workspace>/FINGERPRINTS.md`. An empty initial registry is correct because it tracks only the user’s prior builds. `EXAMPLES.md` is the author’s illustrative filled registry, not a constraint.

If asset generation is planned, the documented balance check is:

node plugins/nateherk-design/skills/scroll-craft/scripts/kie.mjs probe

Copy `engine/scrollcraft.js` and `engine/scrollcraft.css` into the build folder. Do not modify those engine files per project. Custom behavior belongs in page-specific code driven by the engine’s `--sc-p` custom property and project-owned `data-sc-*` attributes.

4. Brief, authority, research, and visitor journey

Before generation, establish creative authority and write `<workspace>/builds/<name>/BRIEF.md`. Reuse information and assets already supplied. If the user explicitly delegates creative direction, label the brief `Self-authored under explicit creative delegation` and proceed without a redundant interview. If no delegation exists, ask once about eight topics: vibe and non-website references; section-by-section journey; energy curve; feeling at each stage and the one memorable moment; a unique site behavior; desired aesthetic range; continuous world versus distinct scenes; and existing assets.

Record supplied answers in the user’s words and separate evidence from authored assumptions. The brief must include all eight topics, a one-line-per-act feeling curve, one peak stated as what a visitor would tell a friend, the completed sentence “It’s the site where ___,” and any intentional silence so verification does not misclassify it as dead scroll. If a human is genuinely unreachable in an autonomous run, label the brief `Self-authored, not interviewed` and disclose that in the report.

Next establish five practical facts without repeating Step 0: what the offering is and who it serves; the single belief the visitor should hold at the end; one next action and one consistent label; available brand assets; and art direction. Brand-kit hard rules override the skill’s preferences.

Write a four-to-seven-beat journey before assets. A documented example is Recognition, Tension, Turn, Substance, Range, and Commitment. Each beat must change what the visitor knows or feels. Remove sections that serve no beat. Under delegated authority, record the selected journey and continue; otherwise show it when user input is needed.

5. Grammar, uniqueness gate, emotional score, and design rules

Choose one of eight mutually exclusive page grammars: filmic one-shot, chaptered editorial, live surface, continuous world, typographic poster, gallery, split stage, or rhythmic cutlist. Read `references/uniqueness.md` for each grammar’s required structure and bans. A new grammar is allowed only when its navigation, sequence, ending, and prohibitions genuinely define another structure. If filmic one-shot is selected, the final report must explain why the other seven did not fit.

Invent one bespoke **signature move** implemented in the page, not by editing or recoloring an engine effect. Then compare the plan with every row in `FINGERPRINTS.md`. It must differ from each existing build on at least four of six dimensions: grammar, navigation, hero, act-sequence shape, close, and signature move. If it fails, revise the plan rather than altering history.

Write the feeling curve before selecting devices. Adjacent acts cannot have the same feeling. Designate one peak, give it visibly more scroll span and asset budget, and make the preceding act quieter. Assign devices beat by beat, obeying the selected grammar. The score requires at least four device families, forbids the same family consecutively, and permits at most two scrub acts. Length must serve the journey; eight to fourteen viewport-heights is only a cinematic pacing reference.

The design floor permits no more than two type families, uses readable 45–75ch measures, a 4px spacing base, six color roles with one accent, and depth through offset shadows, edge light, distance blur/scale, overlap, and grain. Heroes should use independently planned background, subject, foreground, and atmosphere planes, with separate mobile art direction and useful static depth under reduced motion.

6. Asset generation, encoding, and page construction

Asset generation is optional. Existing authentic photos, footage, product details, and brand materials are preferred. When generating, first write one style preamble and reuse it verbatim across prompts. Inspect every output before use. The documented generic commands are:

node <skill>/scripts/kie.mjs still "<style preamble>\n\n<scene>" out/01-hero.png --ar 16:9 [--ref brand-can.png]
node <skill>/scripts/kie.mjs shot "<camera move>" out/01-hero.png out/01.mp4 --dur 5
bash <skill>/scripts/encode.sh out/01.mp4 assets/01.mp4
bash <skill>/scripts/encode.sh out/01.mp4 assets/01-m.mp4 mobile

Replace `<skill>` with the actual Scroll Craft skill directory. `kie.mjs still` creates a still, with an optional reference image; `kie.mjs shot` turns a source still and camera direction into a timed clip. `encode.sh` creates dense-keyframe, audio-free video suitable for seeking during scroll; the `mobile` argument creates the documented mobile variant.

Build from `references/template.html`, but treat it as a skeleton rather than a reusable layout. Write semantic HTML with real headings, paragraphs, links, and reading order. The engine reads `data-sc-*` attributes and never generates DOM. Keep custom project behavior outside the engine.

Theme the page with the documented six tokens and two fonts:

:root {
  --sc-canvas: #0A0806; --sc-surface: #16110E;
  --sc-ink: #F5EBDD; --sc-ink-soft: #A2968A;
  --sc-accent: #FF5A3D; --sc-accent-ink: #15110F;
  --sc-font-display: "Archivo", system-ui, sans-serif;
  --sc-font-text: "Geist", system-ui, sans-serif;
}

Never bake text into generated imagery. Use page markup so content remains sharp, selectable, translatable, and accessible.

7. Serving, automated verification, and human review

Install Playwright once in the build project, start the supplied server, and capture desktop, mobile, and reduced-motion runs:

cd <build project> && npm i playwright-core
node <skill>/scripts/serve.mjs --root . --port 4500 &
node <skill>/scripts/shoot.mjs --url http://localhost:4500 --out lab/shots
node <skill>/scripts/shoot.mjs --url http://localhost:4500 --out lab/mobile --width 390 --height 844
node <skill>/scripts/shoot.mjs --url http://localhost:4500 --out lab/reduced --reduced-motion

Replace the placeholders with the actual build and skill paths. `serve.mjs` serves the selected root on the requested port. `shoot.mjs` walks each act at six positions, waits for scrubbed video to settle, reports scroll that causes no visible change, identifies cues that never become fully opaque, checks line-level contrast on composited frames, detects clips stuck on a poster frame, and writes screenshots plus a contact sheet. Use headless automation with native pointer lock and capture disabled, as required by the documented workflow.

Automated success is not visual approval. Open and read `sheet.png`; assess composition, meaning, pacing, intermediate states, mobile framing, useful controls, downloads, and form outcomes. Tab through the page to check focus order. Scroll cold and record one felt word per act before reopening `BRIEF.md`; compare actual feelings with the intended curve and revise mismatches. Confirm the peak is the largest visual change with the most room and that the close resolves rather than fades away.

Finally, test a real phone when possible. Headless Chrome cannot reproduce iPhone decoding, autoplay policy, Low Power Mode, or touch behavior. On the first reported mobile defect, deploy `references/device-diag.html` beside the site. Fix defects and rerun captures.

8. Ship blockers, deliverables, helper inventory, and limitations

Do not ship clay-diorama defaults, scroll arrows, `01 / 06` counters, centered copy in every act, visible em dashes, invented statistics, gradient text, neon glow, autoplay audio, repeated adjacent devices, or an ending that merely becomes a footer. Do not animate layout properties such as width, height, top, or left; use transform and opacity, with clip-path for wipes. Do not use a full-frame dark overlay to repair contrast; place a scrim only beneath text. Never generate before the brief, plan acts before the feeling curve, omit the signature move or peak, violate the four-of-six fingerprint gate, edit the engine, or skip verification.

The final deliverable is the complete build folder including `BRIEF.md`, followed by a concise report containing: selected grammar and why alternatives lost; signature move; gate result against every prior row; visitor journey; intended feeling curve and peak; felt-versus-intended diff and resulting changes; device score; generated assets; screenshot verification; unverified items; local URL; and whether the brief was interviewed, delegated, or autonomously authored. Append the build’s row to `FINGERPRINTS.md` only after completion.

The repository inventory also names `worldflight-assert` among its scripts, but the supplied files provide no invocation or behavior specification; therefore this manual does not invent a command for it. `CHANGELOG.md` records build failures and resulting rules rather than serving as a feature list.

Documented limitations are material: only Windows builds are reported; macOS and Linux discovery exists but is unproven here. Generated video costs money, especially continuous-world sequences. Third-party generation requires `KIE_AI_API_KEY`. Real-device behavior remains outside the headless harness. Tool names and skill discovery differ across agents. The process is deliberately restrictive and is unsuitable when the goal is a conventional, repeatable template.