/storyboard-html-preview

name: storyboard-html-preview
description: Render a shotkit storyboard (shots.json, text-overlays.json, brand-lock.snapshot.md) into one self-contained HTML preview that a reviewer can open, share or print. Use when the user asks to preview, share, export or print a storyboard or shot list, for example "preview the storyboard", "share this storyboard", "export the storyboard to HTML" or "a print version of the shot list". A request to share, export or print something that is not a storyboard is not for this skill. It runs when the user asks for it; storyboard-architect offers it and does not start it.

Storyboard HTML Preview

You are turning structured storyboard files into a single shareable HTML document. The output is what an editor, stakeholder, or client opens in a browser without thinking about it.

The constraint is non-negotiable: **single file, no build step, no server, works offline.** Any time the output requires "run this build command" or "host this somewhere," the skill has failed.

When to use

Trigger when the user:

• Asks to preview, share, or export a storyboard or shot list
• Wants a printable version of a storyboard
• Says yes when storyboard-architect offers a preview
• Hands off `storyboard.md` + `shots.json` + asks for a deliverable for review

Share, export and print requests about anything else are not for this skill. It does not start on its own after a storyboard-architect run; the architect offers it and the user picks.

Where the tools and packs are

After `./install.sh`, the validators and helpers are in `~/.claude/shotkit-tools/` and the brand packs are in `~/.claude/shotkit-brand-packs/`. A `--project` install puts both under `./.claude/` instead. From a repo clone they are `tools/` and `brand-packs/`. The commands below give the installed path first and the clone path second. The tools need `pip install pyyaml jsonschema`.

What you produce

One file: `preview.html`. Self-contained. Inline CSS. No JavaScript dependencies (vanilla JS only, embedded). The brand fonts are linked from Google Fonts, with a system fallback stack behind each one, so the page reads the same offline in the fallback fonts. No external images (placeholder slots; if generated images exist, embed as base64 OR reference relative paths).

output/
├── run.json                   # input, for the run id and date
├── storyboard.md              # input
├── shots.json                 # input
├── text-overlays.json         # input
├── brand-lock.snapshot.md     # input
├── frames/round-N/            # input, if generation has happened
├── critiques/round-N/         # input, for the verdict badges
└── preview.html               # ← what this skill produces

If the user has generated frames, the HTML references them via relative paths so the file works when the whole `output/` folder is shared. Resolve a shot's frame in this order:

1. An entry in `shot.assets.generated` marked `accepted: true` 2. The newest entry in `shot.assets.generated` 3. `frames/round-{highest}/{shot_id}.{png,jpg,jpeg,webp}` 4. `generated/{shot_id}.{ext}`, the pre-3.0.0 flat layout

Data first, convention second. The data says which frame was accepted; the path convention only says which file sits in the folder.

If no frames exist yet, the HTML uses styled placeholder cards with the shot spec, still useful for review and handoff.

Workflow

Step 1. Read inputs

Required:

• `shots.json`
• `text-overlays.json`
• `brand-lock.snapshot.md`

Optional:

• `run.json` (for the run id and date; without it the page says "not recorded")
• `storyboard.md` (for narrative context, surface the brief at the top)
• `frames/round-N/{shot_id}.{png,jpg,jpeg,webp}` (if generation has happened)
• `critiques/round-N/{shot_id}.critique.json` (for verdict badges)

Validate before rendering, and stop if it fails:

python ~/.claude/shotkit-tools/validate_shots.py output/
# from a repo clone:
# python tools/validate_shots.py output/

Step 2. Extract brand parameters

From `brand-lock.snapshot.md`, extract:

• Palette (hex values), mapped by role onto the CSS variables
• Display, body, and mono fonts
• Brand voice / mood, used in subtle copy choices

A font value in a brand-lock carries more than a family, for example `Archivo Bold 700 wdth 80`. Split it before it goes into CSS:

• the family (`Archivo`) goes into `font-family`, in quotes, ahead of a system fallback

stack: `"Archivo", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif`

• the weight (`700`, or a name such as `Bold`) goes into `font-weight`
• a width (`wdth 80`) goes into `font-stretch` as `80%`

Writing the whole value into `font-family` makes the declaration invalid, and the page renders in the browser default. Use the brand-lock's mono font for labels, ids and timings. When it declares none, use the system mono stack.

The HTML preview should *feel* like the brand without going overboard. Quiet branding, not loud.

Step 3. Generate the HTML

When the tools are installed, render with the CLI. It does every step below and writes `preview.html` into the output folder:

python ~/.claude/shotkit-tools/shots-to-html.py output/
# from a repo clone:
# python tools/shots-to-html.py output/

Build the page by hand, following the steps below, only where the tools are not available (for example a Claude.ai upload).

Use `templates/preview.html.tpl` as the structural template. Read it before generating.

The HTML structure:

<!DOCTYPE html>
<html>
<head>
  <meta>
  <title>{project title}</title>
  <style>
    /* All CSS inline. ~200 lines. Brand-aware. */
    /* Print stylesheet included. */
  </style>
</head>
<body>
  <header>
    <!-- Project title, duration, aspect, generated timestamp -->
  </header>

  <section class="brief">
    <!-- Brief summary if storyboard.md provides one -->
  </section>

  <section class="series-lock">
    <!-- Character / environment / lighting / color grade -->
  </section>