Skill

---
name: paper-to-storyboard
description: Convert an academic PDF paper into a single-page scrollytelling website (index.html + style.css + script.js + extracted figures + optional AI cover) using a fixed dark/light scroll-snap chassis. Use when the user provides a PDF and asks for a "storyboard", "scrollytelling page", "paper-to-web", "narrative website", or "convert paper to webpage".
---

# paper-to-storyboard

Turn an academic paper PDF into a dark, scroll-snap, single-page website with the same chassis as the reference example. The chassis (HTML scaffold, CSS layout/animations, vanilla JS IntersectionObserver) is fixed. Only the color palette and per-section content change per paper.

> **Run this skill on a strong model (Opus).** The hard part isn't the scripts — it's the judgement: mapping a paper onto the 9-slot narrative arc, rewriting body copy to fit display type, picking layouts and a palette, and composing the cover concept. Weaker models (e.g. Sonnet) tend to produce flat narratives, mis-assigned layouts, and verbatim-dumped paragraphs. If you're not on Opus, tell the user to switch with `/model opus` before invoking.

## Inputs

- `pdf_path` (required, absolute path)
- `out_dir` (default: `./storyboard/`)
- `palette` (optional: `warm | cool | earth | clinical | tech`) — if omitted, **ask the user** via AskUserQuestion
- `mode` (optional: `dark | light`) — if omitted, **ask the user**
- `typography` (optional: `editorial | modern | tech | academic`) — if omitted, **ask the user**
- `generate_cover` (optional: `true | false`) — if omitted, **ask the user**
- `title_override`, `subtitle_override` (optional)

When any of `palette`, `mode`, `typography`, `generate_cover` is explicitly supplied by the user when they invoke the skill, skip the corresponding question and use the supplied value.

### Style options

- **palette** — color family. Auto-pick from topic keywords; explicit `palette` arg wins.
- **mode** — `dark` keeps the reference chassis (white-on-dark with animated gradient + noise). `light` flips text to near-black, bg to light tints of the palette, button colors, overlays, and animation opacities.
- **typography** — font pairing:
  - `editorial`: Playfair Display + Inter (default — newspaper/longform feel)
  - `modern`: Space Grotesk + Inter (clean, product-design)
  - `tech`: JetBrains Mono + Inter (engineering / lab notebook)
  - `academic`: Crimson Pro + Source Sans (journal / scholarly)

## Workflow

Execute these steps in order. The skill directory is `~/.claude/skills/paper-to-storyboard/`. Run each script with absolute paths.

### 1. Ingest PDF text

```
python3 ~/.claude/skills/paper-to-storyboard/scripts/extract_text.py <pdf_path> <out_dir>/content.json
```

Produces `content.json` with `{title, authors, affiliations, abstract, doi, keywords, sections[], figures_meta[], stats_candidates[], tables[]}`.

`tables[]` holds ruled tables pulled by pdfplumber, each tagged with `numeric_columns` and a `chart_ready` flag (true = it has at least one label column and one numeric column). These are **ground-truth values** — prefer them as the data source for a `chart` slot (see step 6). Extraction is best-effort: it catches ruled tables well, may miss borderless ones, and can merge multi-line headers — always eyeball the `rows` before charting.

### 2. Extract figures

```
python3 ~/.claude/skills/paper-to-storyboard/scripts/extract_figures.py <pdf_path> <out_dir>/figures/
```

Produces `figures/figure1.png` … `figureN.png` and `figures/figures.json` with captions, page numbers, bboxes.

### 3. Make figures transparent

For each figure that will appear in the page (typically all of them):

```
python3 ~/.claude/skills/paper-to-storyboard/scripts/make_transparent.py <out_dir>/figures/figureN.png <out_dir>/figureN.png
```

This writes transparent PNGs directly into `out_dir/` (alongside the templates), where the HTML references them. The default mode is corner flood-fill (good for plot figures with white backgrounds). For photos/schematics, pass `--mode rembg`. If `rembg` isn't installed, it falls back to the flood-fill mode with a warning.

### 4. Ask the user for style choices

Before building the storyboard, read enough of the PDF to draft a 1-sentence topic summary, then use **`AskUserQuestion`** to let the user pick the visual style. Show your recommendation as the first option in each list, label it `(Recommended)`, and explain *why* in its description.

Issue these questions in a **single `AskUserQuestion` call** (batch them — don't ask one at a time):

1. **Palette** — 4 options out of `warm`, `cool`, `earth`, `clinical`, `tech` (recommended first, then 3 sensible alternatives for this paper).
   - Keyword guide for the recommendation: heat/energy/fire → `warm`; water/climate/ocean → `cool`; biology/ecology/agriculture/plants → `earth`; medicine/clinical/health/disease → `clinical`; computing/AI/ML/robotics → `tech`. Urban / cities / sociology papers often fit `cool` or `earth`. Default `warm`.

2. **Mode** — 2 options: `dark`, `light`.
   - Default `dark` (matches the reference chassis identity, more cinematic). Recommend `light` only when the paper is text-heavy with few or busy figures where readability dominates.

3. **Typography** — 4 options: `editorial`, `modern`, `tech`, `academic`.
   - Keyword guide for the recommendation: longform/humanities/policy → `editorial`; product / startup / design → `modern`; CS / AI / engineering → `tech`; medicine / scholarly / journal → `academic`.

4. **Generate cover?** — 2 options: `Generate (~$0.04)`, `Skip`.
   - In the `Generate` option's description, show the 1-sentence cover concept you'd send to the image model so the user can preview what they'd be paying for.
   - Recommend `Generate` if `OPENAI_API_KEY` is set, otherwise `Skip`.

Use the user's answers in the steps below. If the user picks `Skip` for cover, omit step 5 and don't add `cover_image` to the title section.

### 5. (Optional) Generate the title cover image

Only if the user picked `Generate` in step 4. Compose a 1-sentence `--concept` describing the paper:

```
python3 ~/.claude/skills/paper-to-storyboard/scripts/generate_cover.py \
  --concept "<one-sentence paper description>" \
  --palette <chosen palette> \
  --mode <dark|light> \
  --out <out_dir>/cover.png
```

Calls OpenAI `gpt-image-1` (~$0.04 medium, $0.25 high — defaults to medium). To preview the prompt without spending: add `--prompt-only`.

When `cover.png` exists in `out_dir` AND the title section in `storyboard.json` has `"cover_image": "cover.png"`, render.py automatically inlines it as the title-bg with a palette-tinted gradient overlay. If either is missing, the title slot falls back to the default gradient.

If `OPENAI_API_KEY` isn't set, generation will fail with a clear error — fall back to skipping the cover and proceed.

### 6. Map content to storyboard slots

Read `content.json` and `figures/figures.json`. Build a storyboard JSON object matching `schemas/storyboard.schema.json`. Save as `<out_dir>/storyboard.json`.

The schema has **9 fixed slots** (you may skip slot 6 if the paper has only one main result):

| Slot | Suggested layout(s) | Maps to |
|------|---------------------|---------|
| 0 — title | `title` | Paper title (rewritten as a hook), 1-line subtitle from abstract |
| 1 — hook | `split`, `quote` | First paragraph of Introduction ("why now") |
| 2 — problem | `split`, `split_reverse`, `quote` | The gap/limitation paragraph |
| 3 — method | `split`, `split_reverse`, `stacked` | One-line methods + schematic figure |
| 4 — keyFinding | `impact`, `impact_single`, `stats_grid`, `chart` | Headline number(s) |
| 5 — dataNarrative | `split`, `stacked` | Main results figure + body + insight callout |
| 6 — secondaryFinding | `split_reverse`, `comparison` | Temporal/subgroup result or A-vs-B contrast (skippable) |
| 7 — insight | `insight`, `quote` | Discussion takeaway, call-to-action or pull quote |
| 8 — credits | `credits` | Authors, affiliations, DOI link |

### Layout catalogue

- **`title`** — hero. Big heading + subtitle, optional `cover_image` background.
- **`split`** — text-left, figure-right (default workhorse).
- **`split_reverse`** — figure-left, text-right (alternate to break rhythm).
- **`split_no_image`** — text-only with optional `insight` callout.
- **`stacked`** — figure on top, text below. For wide/panoramic figures.
- **`fullbleed`** — figure fills the section as background, text overlays in a glass panel. **Avoid for paper figures** — most scientific charts don't read well at viewport scale and the glass panel competes with the data. Reserved for the rare atmospheric photo or hero rendering (not for plots/maps/diagrams from a paper).
- **`quote`** — large italic pull-quote with attribution. Lift a striking sentence verbatim.
- **`impact`** — two big numbers vs. each other.
- **`impact_single`** — one big number with a caption.
- **`stats_grid`** — 3–4 metric cards (`stat_items: [{number, label, accent}]`).
- **`chart`** — vanilla (no-CDN) bar chart that grows on scroll and shows exact values on hover/focus. Use it instead of `stats_grid` when 2–6 numbers form a *comparison the reader should see as bars* (e.g. an ablation, before/after, per-group precision). Spec lives in a `chart` object: `{type: "bar", unit, y_max, data_source, series: [{label, value, accent}]}`. **Only `bar` is supported** — line/scatter are intentionally excluded because their values can't be recovered reliably. **`data_source` is mandatory and load-bearing**: use `"table"` or `"text"` only when the numbers are ground-truth (a data table or values quoted in the prose); use `"estimated"` if you read them off a figure by eye — that renders an "approximate, not exact" caption so the reader isn't misled. Never fabricate values to fill a chart; if you can't source the numbers, use a non-chart layout.
- **`comparison`** — two/three side-by-side text columns (`columns: [{heading, body, accent}]`).
- **`insight`** — discussion takeaway with a call-to-action box.
- **`credits`** — authors + affiliations + DOI button.

`accent` modifiers (for `stats_grid` cards and `comparison` columns): `warm`, `cool`, `caution`, `extreme`. Empty = default.

Rules for filling slots:
- Rewrite paper prose into 1–3 short sentences per slot (paper prose is too dense for 1.2rem display type).
- Lift headline numbers and key definitions **verbatim** from the paper.
- For slot 4, the two big numbers should be a meaningful comparison (e.g., baseline vs treatment, outdoor vs indoor). If the paper has no natural comparison, use a single big number and one short descriptor.
- **Charts (slot 4 alt):** if `content.json` has a `chart_ready` table whose rows form a clean 2–6 bar comparison, prefer the `chart` layout over `stats_grid`. Read the actual `rows` (don't trust the merged header blindly), pick one label column + one numeric column, and emit a `chart` object with `data_source: "table"`. If the numbers come from prose instead, use `data_source: "text"`. **Only use `data_source: "estimated"` if you read values off a figure by eye — and prefer not to: a wrong value under a real citation is worse than no chart.** Never invent values.
- For each split-layout slot, pick a figure from `figures.json` by relevance (use the caption to judge). Same figure should not be reused across slots.
- If the paper has fewer than 4 figures, some split-layout slots become bare (drop the image_content div).

### 7. Emit the site

Copy the templates and substitute placeholders:

```
python3 ~/.claude/skills/paper-to-storyboard/scripts/render.py \
  --storyboard <out_dir>/storyboard.json \
  --palette <name> \
  [--mode dark|light] \
  [--typography editorial|modern|tech|academic] \
  --out <out_dir>
```

This writes `index.html`, `style.css`, `script.js` to `out_dir`. The transparent figures (step 3) should already be in `out_dir`.

### 8. Preview

```
python3 ~/.claude/skills/paper-to-storyboard/scripts/preview.py <out_dir>
```

Prints `http://localhost:8765/` and opens it on macOS.

## Reference

A fully filled `storyboard.json` example ships in this skill: `examples/reference_storyboard.json`. Additional rendered examples live under `examples/` in the repo (https://github.com/MaoranSun/paper-to-storyboard).

## Dependencies

```
pip install pdfplumber pymupdf pillow
# Optional, for background removal of complex figures:
pip install rembg
```