ScrollCraft.skill

ScrollCraft.skill

## scrollcraft: Output

Based on the three skill files (README.md, EXAMPLES.md, SKILL.md), here is the **skill specification and workflow output**:

### **Skill Metadata**
- **Name**: scrollcraft
- **Author**: nate herkelrath (@nateherk-design)
- **Type**: Claude Code skill for scroll-driven landing page generation
- **License**: MIT
- **Status**: Production-ready (12 builds shipped, fingerprint registry active)

---

### **What scrollcraft Does**

Scrollcraft is a premium scroll-timeline page generator that treats scroll as the primary input medium. Rather than applying a single animation to a whole page, it:

1. **Interviews the human** (8-question brief about vibe, journey, energy, and assets)
2. **Picks a page grammar** from 8 mutually exclusive structural models
3. **Invents a signature move** — one bespoke interaction that only exists on this page
4. **Generates or uses real assets** via kie.ai or the user's own photography/footage
5. **Builds semantic HTML** on a token-driven design system floor
6. **Verifies with automated screenshots** at every scroll position to catch dead scroll, contrast failures, and unfinished video

The result: **eight completely different page skeletons from the same engine**, each one unrepeatable via the fingerprint gate.

---

### **The 8 Page Grammars (Mutually Exclusive)**

| Grammar | Navigation | Hero | Acts | Close | Example | Status |
|---------|------------|------|------|-------|---------|--------|
| **Filmic one-shot** | Fixed top bar + CTA | Full-bleed scrub video, kinetic type | 6-7 acts, 13.6-13.8vh | Pinned stage, spotlight, magnet CTA | perkform, nateherk, agency, saas | Claimed 4x |
| **Live surface** | Console chrome + scroll-bound readout + bottom rail | Product surface already in state (no media) | 7 acts, ~12.1vh, zero scrub | Command prompt, copy button | vesper-v2 | Claimed 1x |
| **Continuous world (worldflight)** | Map with scroll-bound numeric gauge + clickable waypoints | Handmade world already in motion | 9-10 legs, 8-12vh, seam-locked chain | Flight lands somewhere new, CTA as object inside world | descent, orrery | Claimed 2x |
| **Chaptered editorial** | Margin folio + persistent accumulating tray | Title page (type on paper, no media above fold) | 11 acts, ~13.4vh, hard-cut inversions | Full-screen colophon, CTA as running text | maison | Claimed 1x |
| **Typographic poster** | No navigation (wordmark absorbed into composition) | One extreme-scale real-text word as entire first screen | 5 acts, 10.5-10.8vh, zero video | Full bone inversion in normal flow | scrollcraft-showcase | Claimed 1x |
| **Gallery / catalog** | Clickable specimen index with color swatches + scroll spy | First object already in view, framed and labeled | 9 acts, ~13.4vh, one scrub + one pan | Last object is the visitor (live canvas of their marks) | pigment | Claimed 1x |
| **Split stage** | Divider seam as chrome (state labels, chapter rail, progress) | Same frame shown in cold + ready states, headline crosses seam | 6 flow acts, 11.0vh, one custom-scrubbed clip | Divider retreats to 0%, giving full viewport to one side | phase | Claimed 1x |
| **Rhythmic cutlist** | Loud full-width bar whose content IS the signature move | Still frame cut away in <1vh, h1 set small | 15 short acts, 13.19vh, zero pinned acts, zero video | Abrupt full-bleed accent slab, CTA as final cut | airfield, lane | Claimed 2x |

**Unclaimed grammars**: None — all 8 are spoken for in the registry.

---

### **Hard Rules (Ship-Blockers)**

| Never | Why |
|-------|-----|
| Clay diorama / low-poly / claymation as the default world | Photographic, real, or illustrated (per brand). Defaults read as generated |
| "Scroll" cue, arrow, animated mouse icon | They see the hero; they know |
| `01 / 06` section counters | Sequence is not information |
| Same device twice in a row | Variety is the product |
| Generating anything before the interview | BRIEF.md first |
| A page with no engineered peak, or three competing peaks | One peak. It gets asset budget, silence before it, max scroll room |
| Gradient text, neon glow, zero-offset colored halo shadows | Weight and size for emphasis; proper shadows only |
| Text baked into generated images | Real markup, always |
| Invented statistics in counters | Only real numbers |
| Shipping without Step 5 verification | Run screenshots; read contact sheet; feel-check against brief |

---

### **The Fingerprint Gate (Uniqueness Constraint)**

**Rule**: A new build must differ from **every existing row** on at least **4 of 6 dimensions**:

1. **Grammar** — the page structure (one of 8)
2. **Nav treatment** — how the user navigates
3. **Hero device** — how the page opens
4. **Act-sequence shape** — act count, total vh, device sequence
5. **Close pattern** — how the page ends and resolves
6. **Signature move** — one bespoke interaction that only exists on this site

If a planned build fails the gate, **change the plan, not the registry.**

#### Claimed Signature Moves (Cannot Reuse)
- `vesper-v2`: Scroll as a playhead over a persistent trace rail with piecewise-linear clock
- `airfield`: Split-flap character animation driven by scroll (320 flaps, 40-char set)
- `scrollcraft-showcase`: Measured scroll velocity gives letters different physical masses
- `pigment`: Pointer as pigment-loaded brush + auto-smears on visitor canvas
- `descent`: Pointer-driven mask that reveals the world + dwell-triggered bioluminescent particles
- `orrery`: Persistent population of 60 markers; individually nameable, react by stopping, cascade at close
- `phase`: Heatprint — touch/pointer paths temporarily bloom ready state through cold version
- `lane`: Two chrome rails merge into one

---

### **The 5-Step Workflow**

#### **Step 0: The Interview** (Required)
Ask the human these 8 questions, in order, answered in one pass:

1. **Vibe** (3-5 words + 3 references from any medium — NOT sites)
2. **Scroll journey** (section by section, in their words)
3. **Energy curve** (where calm, where intense)
4. **Feeling curve** (emotion per stage, stage by stage; the ONE moment they remember)
5. **One signature thing** (something no site they've seen does)
6. **Aesthetic range** (brutalist ↔ maximalist)
7. **One world or distinct scenes?** (worldflight or cutlist)
8. **Assets already owned** (footage, photos, product shots, brand kit)

**Output**: `<workspace>/builds/<name>/BRIEF.md` with:
- All 8 interview answers (verbatim)
- Feeling curve (emotion → what causes it, one line per act, written **before** acts exist)
- The peak (the moment, written as a sentence someone would say to a friend)
- The "tell someone" sentence: "It's the site where ___"
- Any authored silence (so verification doesn't flag it as dead scroll)

#### **Step 1: Bootstrap** (Infrastructure)
```bash
node <skill>/scripts/doctor.mjs              # preflight: ffmpeg, Node 18+, playwright, Chrome, API key
node <skill>/scripts/workspace.mjs --ensure  # creates workspace, seeds registry
```

Resolution order (first hit wins):
1. `SCROLLCRAFT_HOME` env var
2. Nearest `.scrollcraft.json` walking up from cwd
3. `<project root>/scrollcraft` (where .git is)

#### **Step 2: Grammar, Gate, then Score**

**Pick a grammar** — one of the 8 (and explain why the other 7 didn't fit the interview in the report).

**Invent the signature move** — from interview Q5. One thing nobody else has done. Not a parameter. Not a spotlight recolor. A bespoke JS interaction in the page, driven off `--sc-p` custom property.

**Run the fingerprint gate**:
```
Read <workspace>/FINGERPRINTS.md
Check if planned build differs from EVERY row on 4+ of 6 dimensions
If it fails, change the plan, not the log
```

**Write the feeling curve** (emotion per act, written **before** acts):
```
Emotion: what on screen causes it
Recognition: they see themselves in it
Tension: the problem is named
Turn: the reversal
Substance: why it holds
Range: choice
Commitment: the ask
```

**Build the score table** (device per beat):
```
| Beat | Device | Why this one |
| Recognition | scrub | hand-driven camera is strongest open |
| ... (4+ distinct families; no family twice in a row) |
```

Checks:
- Grammar's bans hold
- 4+ distinct device families
- No device twice in a row
- At most 2 scrub acts
- No two adjacent acts same feeling
- One peak, it's the largest span, act before it is quieter
- Total page: 8–14vh (longer ≠ more immersive, just slower)
- Do NOT land in the 6-7 acts at 13.6–13.8vh band (claimed by filmic one-shot cluster)

#### **Step 3: Generate Assets**

```bash
# Still
node <skill>/scripts/kie.mjs still \
  "<style preamble>\n\n<scene>" \
  out/01-hero.png \
  --ar 16:9 [--ref brand-can.png]

# Motion clip
node <skill>/scripts/kie.mjs shot \
  "<camera move>" \
  out/01-hero.png \
  out/01.mp4 \
  --dur 5

# Encode for scrubbing (not playback)
bash <skill>/scripts/encode.sh out/01.mp4 assets/01.mp4
bash <skill>/scripts/encode.sh out/01.mp4 assets/01-m.mp4 mobile
```

**Three moves that make it premium**:
1. One **style preamble**, reused verbatim in every prompt (this is what makes six images look like one shoot)
2. **Look at every asset before using it** (generation is cheap; rerolling is cheaper than shipping bad frame)
3. **Encode for scrubbing** (normal web encode plays perfectly, scrubs like mud; `encode.sh` sets dense GOP)

**Cost**: Generated video is not free. A 10-leg continuous-world flight is a real spend. A page from user's own assets costs nothing.

#### **Step 4: Build the Page**

Write **real HTML**. Real `<h1>`, `<p>`, links, reading order. The engine reads `data-sc-*` attributes; it never generates DOM.

Start from `references/template.html`.

**Theme by overriding 6 CSS tokens + 2 fonts**:
```css
: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;
  --sc-font-text:    "Geist", system-ui;
}
```

**Read before writing**:
- `references/devices.md` — 9 scroll devices and the cue contract
- `references/taste.md` — spacing scale (4px base), type floor (45–75ch), depth (5 tools), colour (6 roles + 1 accent)
- `references/uniqueness.md` — the 8 grammars, their bans, the gate

Copy `engine/scrollcraft.js` and `engine/scrollcraft.css` into build folder. **Never edit the engine per-project.**

#### **Step 5: Verify by Scrolling** (Required)

```bash
cd <build> && npm i playwright-core
node <skill>/scripts/serve.mjs --root . --port 4500 &

# Desktop
node <skill>/scripts/shoot.mjs \
  --url http://localhost:4500 \
  --out lab/shots

# Mobile (390x844)
node <skill>/scripts/shoot.mjs \
  --url http://localhost:4500 \
  --out lab/mobile \
  --width 390 --height 844

# Reduced motion
node <skill>/scripts/shoot.mjs \
  --url http://localhost:4500 \
  --out lab/reduced \
  --reduced-motion
```

**The harness reports**:
- **Dead scroll** — scroll that changes nothing on screen
- **Cues never reaching full opacity** — text only ever faded
- **Contrast measured on composited page** at brightest frame under each line, per-line direction
- **Legs stuck on poster** — clip that never decoded

Then **YOU do the part the harness cannot**:
1. **Read `sheet.png`** — proves a clip advances; cannot tell you composition or meaning are good
2. **Tab through for focus order**
3. **Feel-check**: Scroll cold, write one word per act for what you felt. Open BRIEF.md and diff against intended curve. Where they disagree, the page is wrong, not the brief.
4. **Confirm on sheet**: Peak is the largest visual change, holds most scroll room, last screen resolves instead of fading

**Also test on a real phone** — headless Chrome doesn't replicate iPhone's video decoder, autoplay policy, Low Power Mode, or touch scroll.

**Fix what you found. Shoot again.**

---

### **Output Deliverable**

The build folder containing:
- `index.html` (semantic, real text)
- `BRIEF.md` (interview, curve, journey)
- `engine/scrollcraft.js` and `engine/scrollcraft.css` (untouched)
- `assets/` (encoded clips and stills)
- `lab/shots/`, `lab/mobile/`, `lab/reduced/` (verification screenshots)

**The report**:
1. Grammar chosen and why the other 7 lost
2. Signature move (the bespoke interaction)
3. Fingerprint gate result (differed on 4+ dimensions against each row? YES/NO)
4. Journey (the 4–7 beats)
5. Feeling curve (intended) vs. felt curve (from cold scroll) — what changed
6. Score table (device per beat)
7. What was generated, what was verified, what couldn't be verified
8. Was BRIEF.md interviewed or self-authored?
9. Local URL

**Then append the build's row to `<workspace>/FINGERPRINTS.md`** with all 6 dimensions documented.

---

### **Current Registry Status (12 Builds)**

All 8 grammars are now claimed. The registry includes:

- **4 filmic one-shot** (perkform, nateherk, agency, saas) — landing page template cluster
- **1 live surface** (vesper-v2) — ops console timeline
- **2 continuous world** (descent, orrery) — handmade model vs. location flight
- **1 chaptered editorial** (maison) — printed magazine structure
- **1 typographic poster** (scrollcraft-showcase) — type is the imagery
- **1 gallery/catalog** (pigment) — museum specimen index
- **1 split stage** (phase) — cold/ready product comparison
- **2 rhythmic cutlist** (airfield, lane) — full-bleed hard cuts with character/rail animation

**What's taken**: One-canvas-plus-one-accent palettes, fixed top bar nav, full-bleed scrub hero, 13.6–13.8vh act band, pinned spotlight close, six claimed signature moves.

**What's still open**: Grammars (none), unique nav shapes (folio, divider, no nav all used; margin chrome variants possible), hero devices (every variant taken), close patterns (colophon, prompt, canvas, plate, slab, inversion all used), new signature moves (none of the eight remaining can be reused).

---

### **Key Principles**

1. **Scroll is timeline** — not decoration. Every scroll position is a different frame.
2. **Variety is the product** — not theme. Four+ device families, none twice in a row.
3. **One engineered peak** — not three competing peaks. Peak gets asset budget, silence, room.
4. **No clay diorama default** — photographic, real, or brand-illustrated. Generated worlds read as generated.
5. **Fingerprint gate enforces unrepeatable** — every build must differ structurally, not just aesthetically.
6. **Semantic HTML always** — never generated DOM, never baked text. Real markup.
7. **Verify by scrolling** — not just at rest. Screenshots prove dead scroll, contrast, and video playhead settlement.

---

### **Skill Status**

✅ **Production-ready**  
✅ **12 builds shipped**  
✅ **Fingerprint gate active** (prevents template convergence)  
✅ **No grammars remaining**  
✅ **Token-driven design floor** (6 colors + 2 fonts)  
✅ **Automated verification** (headless screenshot harness)  
✅ **Interview-first workflow** (no assumptions)

**Next**: Any new build must compete against all 12 existing rows on the gate; it is nearly impossible to clear at this point without inventing a new grammar or discovering an entirely new nav/device combination the eight existing pages don't occupy.