scroll-storyteller

What this skill does

# Scroll Storyteller

Create immersive, interactive storytelling experiences using Anthropic's authentic design language: strict duotone palette, organic Bézier SVG paths, custom cursors, and chapter-based narratives.

## Workflow

Use `AskUserQuestion` to gather preferences, then generate:

| Step | Question | Options |
|------|----------|---------|
| 1 | Animation? | GSAP (rich) vs CSS-only (lightweight) |
| 2 | Mood? | Warm vs Cool vs Creative |
| 3 | Palette? | (show 3-4 based on mood) |
| 4 | Topic? | Biblical/Tech/Business/Personal/Custom |
| 5 | Chapters? | 3, 4, or 5 |
| 6 | Content per chapter | Title, description, keywords |

**Generate:**

```bash
bash ~/.claude/skills/scroll-storyteller/scripts/generate.sh my-story <palette> [--gsap] [--chapters N]
```

**Post-generation:** Customize content, create SVGs (see `references/structure-templates.md`)

## SVG Illustration Workflow

Each chapter needs a topic-relevant SVG that matches the narrative position:

| Position | Purpose | Composition | Example |
|----------|---------|-------------|---------|
| **Hero** | Set scene, show contrast | Wide (1000x1000), 2 silhouettes | David vs Goliath distant |
| **Chapter 1** | Introduce protagonist | Centered figure + context | Shepherd with sheep |
| **Chapter 2** | Show conflict/obstacle | Imposing, fills frame | Giant warrior |
| **Chapter 3** | Resolution/triumph | Dynamic, radiating | Victor + fallen + rays |
| **Chapter 4** | Deepening conflict (optional) | Crowded, escalating | Army masses, threats multiply |
| **Chapter 5** | Final climax (optional) | Action, decisive | Stone flying, impact moment |
| **Finale** | Symbolic summary | Centered symbol | Crown + light |

**Light/Dark Pattern by Chapter Count:**

- **3 chapters:** Ch1=Light → Ch2=Dark → Ch3=Light
- **4 chapters:** Ch1=Light → Ch2=Dark → Ch3=Light → Ch4=Dark
- **5 chapters:** Ch1=Light → Ch2=Dark → Ch3=Light → Ch4=Dark → Ch5=Light

**Process:**

1. Load `references/svg-illustration-guide.md` for theme → element mapping
2. Identify chapter position (hero/ch1/ch2/ch3/ch4/ch5/finale)
3. Extract topic keywords from chapter content
4. Select SVG elements from element library:
   - Characters: figure-small, figure-large, figure-triumphant, figure-action
   - Nature: hills, sun, tree, path, clouds, lightning, wind
   - Objects: staff, crown, shield, weapon, stone, obstacle
   - Abstract: radiate, rings, trajectory, converge, impact
5. Compose using position template
6. Apply palette mood style (see `references/design-harmony.md` → Palette Mood → SVG Style)
7. Add animation classes: `organic-path`, `fade-path`, `scale-path`

**SVG Checklist:**

- [ ] Uses only `var(--deep)` and `var(--foam)` colors
- [ ] All paths are organic Bézier curves (Q/C commands)
- [ ] No geometric primitives (circle, rect, ellipse)
- [ ] Opacity range matches palette mood
- [ ] Composition matches chapter position
- [ ] Symbolically represents chapter content

## Animation Styles

| Style | Library | Size | Best For |
|-------|---------|------|----------|
| **GSAP** | GSAP 3.x + ScrollTrigger | ~45KB | Rich interactions, SVG draw, orbits, timelines |
| **CSS-only** | None (IntersectionObserver) | 0KB | Lightweight, fast load, simple reveals |

### GSAP Features

- SVG path draw animations (strokeDasharray)
- Continuous orbit/rotation effects
- Scroll-linked timeline control
- Parallax with scrub
- Staggered animations with precise timing

### CSS-only Features

- IntersectionObserver reveals
- CSS transitions with delays
- Transform-based animations
- No external dependencies
- Smaller bundle size

## Duotone Palettes

| # | Theme | Light | Dark | Mood |
|---|-------|-------|------|------|
| 1 | **Anthropic** | `#FAF9F5` cream | `#141413` charcoal | Warm |
| 2 | **Midnight** | `#E8F4F8` ice | `#0D1B2A` navy | Cool |
| 3 | **Sepia** | `#F5F0E6` parchment | `#2C1810` espresso | Warm |
| 4 | **Forest** | `#F0F4F0` mist | `#1A2E1A` evergreen | Creative |
| 5 | **Dusk** | `#F4F0F8` lavender | `#1E1A2E` violet | Creative |
| 6 | **Ember** | `#FFF5F0` blush | `#2A1A14` ember | Warm |
| 7 | **Steel** | `#F0F2F5` silver | `#1A1C20` graphite | Cool |
| 8 | **Ocean** | `#F0F8F8` foam | `#0A1A1A` deep | Cool |

**Mood → Palette mapping:**

- **Warm**: 1 (Anthropic), 3 (Sepia), 6 (Ember)
- **Cool**: 2 (Midnight), 7 (Steel), 8 (Ocean)
- **Creative**: 4 (Forest), 5 (Dusk)

## Design Modes

| Mode | Description | When to Use |
|------|-------------|-------------|
| **Authentic** (default) | Strict duotone, organic paths | Editorial, brand storytelling |
| **Expressive** | Multi-color accents allowed | Product showcases, demos |

## Core Features

| Feature | Description |
|---------|-------------|
| **Custom Cursor** | Dual-layer cursor with smooth easing, mix-blend-mode |
| **Hero Section** | **GSAP**: Flowing organic lines (1000x1000 background). **CSS-only**: Desk lamp with animated light cone reveal |
| **Spotlight Layer** | Radial gradient follows cursor on dark sections |
| **Staggered Reveals** | Title words animate in sequence on load |
| **Chapter Structure** | Alternating light/dark sections with transitions |
| **Organic SVGs** | Hand-drawn Bézier paths, fill-only (no strokes) |
| **Parallax** | Subtle depth movement on scroll |

## Anthropic Design Language

### Strict Duotone Palette

| Element | Hex | CSS Variable |
|---------|-----|--------------|
| Cream (light) | `#FAF9F5` | `--cream` |
| Charcoal (dark) | `#141413` | `--charcoal` |

**Rule:** No other colors. All illustrations use exactly these two.

### Typography

| Role | Font | Fallback |
|------|------|----------|
| Display/Headings | Instrument Serif | Georgia, serif |
| Body/UI | Inter | -apple-system, sans-serif |

**Characteristics:**

- Large, editorial headings (clamp 3rem - 7rem)
- Light weight (300-400)
- Negative letter-spacing on display (-0.02em)
- Generous line-height (1.5-1.8)

### SVG Design Rules

| Rule | Description |
|------|-------------|
| **Fills only** | Never use strokes for main shapes |
| **Organic paths** | Complex Bézier curves, hand-drawn feel |
| **viewBox** | Always 1000x1000 or 500x500 (square) |
| **2-4 paths** | Keep compositions simple |
| **Layered** | Light shapes behind, dark in front |

**Anti-patterns:**

```
❌ <circle>, <rect>, <ellipse> (geometric)
❌ stroke="..." on main elements
❌ Multiple colors
✅ <path d="M... Q... C..."> with organic curves
```

### Topic-Driven SVG Generation

The `svg-generator.sh` helper automatically selects appropriate SVG templates based on chapter content:

| Keywords | Template | Best For |
|----------|----------|----------|
| identity, profile, self, unique | **Fingerprint + Verification** | Personal identity concepts |
| network, connect, distributed, system | **Central Hub + Network** | System architecture concepts |
| protect, secure, vault, lock | **Protected Vault + Links** | Security concepts |
| growth, learn, knowledge, tree | **Knowledge Tree** | Learning/growth concepts |
| enforce, filter, gate, barrier | **Gateway Arches** | Enforcement/validation |
| trust, hand, collaboration | **Hand Holding + Connection** | Partnership concepts |
| unify, finale, complete | **Concentric Symbol** | Conclusion/unity |

**Usage:**

```bash
# Source the generator in your script
source scripts/svg-generator.sh

# Generate SVG for a chapter (position: hero/ch1/ch2/ch3/ch4/ch5/finale)
generate_svg_for_chapter \
  "ch1" \
  "Digital Identity" \
  "Your unique identity on the blockchain" \
  "var(--foam)" \
  "var(--deep)" \
  "fade-path"
```

**Positions:** `hero` | `ch1` | `ch2` | `ch3` | `ch4` | `ch5` | `finale`

## Animation Patterns

For detailed GSAP and CSS animation patterns, see [`references/animation-patterns.md`](./references/animation-patterns.md)

**Animation Classes:**

| Class | Description | Usage |
|-------|-------------|-------|
| `organic-path` | Base class for all SVG paths | Always applied |
| `fade-path` | Fade in animation | Default for most paths |
| `scale-path` | Scale up