pixel-art-storyboard

# Pixel Art Storyboard

Take a short scene description (2-3 paragraphs, 1-3 elements, mood-driven) and turn it into a self-contained HTML file with one or more **canvas-rendered seamless-loop pixel art** scenes.

This is the bridge from **narrative input** to **animated visual output**. It pairs with `pixel-art-studio` (which handles palettes, dithering, quality scoring) by providing the workflow for going from "I want a cover for X" to "here is a working HTML you can open in a browser."

---

## When to use

| User says | Use this skill |
|---|---|
| "Make a cover for [book/album/game]" | Yes — single-cover workflow |
| "Animate this scene" + 1-3 paragraph description | Yes |
| "I want a looping pixel background showing X" | Yes |
| "Generate covers for these N books" | Yes — multi-cover grid layout |
| "Just draw a sprite of X" | Use `pixel-art-studio` directly (no scene narrative) |
| "Convert this image to pixel art" | Use `pixel-art-studio` preprocess.py |
| "Score the quality of my pixel art" | Use `pixel-art-studio` + `pixel-art-reviewer` agent |

---

## The 5-element scene framework

**Every scene description must specify these five elements**, either explicitly given by user or inferred from their input.

| Element | What | Example |
|---|---|---|
| **Subject** | 1-3 foreground icons that carry meaning | "Red apple in pale hands" |
| **Setting** | Background environment, depth layers (max 3) | "Deep night void, single distant star" |
| **Lighting** | Source, direction, mood | "Cool moonlight from upper-left, warm highlight on subject" |
| **Palette** | 3-6 named colors, NOT hex | "Midnight black, ivory skin, deep crimson, warm highlight" |
| **Motion** | What loops + period in seconds | "Highlight on apple orbits in 4s; petal drifts down once per loop" |

If user gives a vague brief ("a moody book cover"), **fill in the missing elements with sensible defaults** before generating, then list them in your output so they can confirm/adjust. Do NOT proceed without all 5 elements settled.

See `references/scene-description-framework.md` for full guidance and 3 worked examples (Romeo & Juliet, lonely cabin, cyberpunk alley).

---

## Workflow

### Step 1 — Parse the user's input into the 5-element framework

If user gave a paragraph synopsis: extract Subject + Setting + symbolic accents. Often the iconography is named explicitly (e.g. "the apple symbolizes forbidden fruit") — that's your Subject.

If user just gave a title: research the work (WebSearch for "X cover symbolism" or "X iconic imagery") to find the canonical visual icons. Use those as Subject.

Output a draft scene-description block:
```
SUBJECT: <1-3 icons>
SETTING: <1-3 layers of depth>
LIGHTING: <source + direction + mood>
PALETTE: <3-6 named colors + accent>
MOTION: <what loops + period>
```

### Step 2 — Pick the canvas/loop spec

| Choose | When |
|---|---|
| **64×96 (book aspect, 2:3)** | Book/album covers |
| **96×96 (square)** | Album art, Spotify-style square covers |
| **128×72 (landscape, 16:9)** | Game splash, banner |
| **64×64 (square)** | Game tile / icon set |
| **256×144 (wide)** | Twitch/YouTube banner |

Loop period (see `references/looped-animation-techniques.md` for full table):

| Loop | Feels like | Use |
|---|---|---|
| 2-3s | Alive, ambient | Idle breathe, water, candle |
| 4-6s | Subtle motion | Breathing, slow drift, ribbon flutter |
| 8-15s | Atmospheric breathing room | Petal fall, smoke plumes |
| 30-60s+ | Slow ambient | Day cycle, wave breaks |

### Step 3 — Design the canvas program

For each cover, write a `draw{Name}(ctx, W, H, t)` function where `t ∈ [0, 1)` is the loop phase. **All animation must derive from t** — no `Math.random()` (use seeded `hash(n)`), no `pos += dt` (use `sin(t * TAU)`), no off-palette ad-hoc colors.

Layer order (bottom to top):
1. **Background** (sky gradient, void, atmospheric base)
2. **Far depth** (stars, distant mountains, fog)
3. **Mid depth** (mid-ground objects, settings)
4. **Subject** (the iconographic foreground — the "apple in hands")
5. **Foreground motion** (falling petals, drifting embers, dust)

Each layer can have its own loop sub-period, but the parent loop must be the LCM (or use periods that don't drift visibly within reasonable view time).

See `templates/cover-template.js` for a starter canvas program.

### Step 4 — Compose into HTML

Single self-contained HTML file. Layout: 1 cover OR a responsive grid of covers (2×2 / 4×1 with `@media` breakpoints).

Style anchors (matches user's example aesthetic):
- Background `#0b0812` (near-black with violet undertone)
- Foreground text `#a896b4` (lavender-grey)
- Accent (titles, year tags) `#ffb4c8` (pale pink)
- Border `rgba(255,255,255,.06)` (barely-visible)
- Font: `"JetBrains Mono", ui-monospace, Menlo, monospace`
- Letter-spacing: 0.2-0.35em on titles (lots of breathing room)
- Cover image-rendering: `pixelated` + `crisp-edges` (forces nearest-neighbor scale)

See `templates/single-cover.html` for skeleton, `templates/grid-cover.html` for multi-cover layout.

### Step 5 — Test in browser

Use `preview_start` to launch a static server pointing at the output folder. Take `preview_screenshot` to verify visual. Check `preview_console_logs` for errors. Iterate.

If multiple covers: verify each independently animates (each on its own `requestAnimationFrame` driver) by waiting 2-3 seconds between screenshots and confirming visual change.

---

## Loop technique cheat-sheet

The single-most-important rule: **never accumulate state**. Always derive position/color from `t = (now - start) % period`.

```javascript
// CORRECT — phase-derived, drift-free
const t = ((now - start) % period) / period;
const offset = Math.sin(t * Math.PI * 2) * amplitude;

// WRONG — accumulates float drift, may seam visibly after hours
let pos = 0;
function frame(dt) { pos += velocity * dt; ... }
```

Five techniques to combine for richer motion (see `references/looped-animation-techniques.md`):

1. **Phase-based parametric** —