blog-illustration

---
name: blog-illustration
description: |
  Create publication-quality illustrations for Arnen blog posts. Supports three
  visual archetypes: hand-coded SVG blueprints/worksheets (engineering-drawing
  register), AI-generated editorial illustrations via Recraft V4 Pro on fal.ai
  (locked to the Arnen 3-color palette), and composite SVG grids that inline
  multiple illustrations into one self-contained file portable across Next.js,
  Substack, Notion, and raw browser previews.
when_to_use: |
  Trigger phrases: "illustrate this post", "make images for the [topic] essay",
  "create the OG/hero illustration", "generate the case-study grid", "draw a
  worksheet/blueprint for [section]". Also use proactively when a new blog
  draft lands in `docs/blog-*.md` and references undefined images.
allowed-tools: Read, Write, Edit, Bash, WebFetch
---

# blog-illustration

Generate publication-quality illustrations for the Arnen blog. Every output is locked to the Arnen brand register — three-color palette, hard shadows, mid-century engineering-drawing typography — so the article's visual system stays coherent regardless of which archetype you reach for.

## When to use

A new blog draft references an image that doesn't exist yet, or the user asks for an illustration to support a section of an essay. This skill covers everything from a hand-coded "engineering blueprint" SVG to a four-cell AI-illustration grid composited into one portable file.

## The three archetypes

Pick by the *role* the image plays in the reader's experience:

| Archetype | Use when | How | Cost | Time |
|---|---|---|---|---|
| **Blueprint** | Communicating a formula, system diagram, or labeled relationship between concepts | Hand-coded SVG from `templates/blueprint.svg` | Free | ~5 min |
| **Worksheet** | Reader-carried artifact: questions to answer, fields to fill, a "do this now" prompt | Hand-coded SVG from `templates/worksheet.svg` | Free | ~5 min |
| **Editorial illustration** | Visual case study, concept embodiment, or visual anchor for a long section | Recraft V4 Pro via `scripts/generate-recraft.sh` | $0.40 / generation | ~30 sec per image, plus iteration |
| **Composite grid** | Showing multiple parallel cases at once (1×N, 2×2, 3×N) | `templates/grid-2x2.svg` + `scripts/inline-svg-grid.py` | Free (post-processing) | ~2 min |

## Standard workflow

For a new blog post that needs illustration:

1. **Read the draft.** Identify which sections would carry an image well. Three rules:
   - Don't illustrate every section. Aim for one image per ~1,500 words.
   - Pick *load-bearing* concepts: the formula, the worked example, the canonical cases.
   - Match archetype to role (table above), not to "where would an image fit visually."

2. **Plan placements with the user.** Surface a list like:
   ```
   Part 2 (formula) → Blueprint SVG
   Part 4 (canonical cases) → 2×2 Editorial grid (Recraft)
   Part 9 (worked example) → Worksheet SVG
   ```
   Confirm before generating anything. AI generations cost real money; hand-coded SVGs cost real time. Don't surprise the user with a $3 bill or a 90-minute SVG session.

3. **Create the output directory:** `frontend/public/blog/<post-slug>/`. Every illustration for this post goes here.

4. **For each blueprint/worksheet:** Copy the relevant template, customize text/labels/data, save to the post directory. Reference from the markdown as `![alt text](/blog/<slug>/<filename>.svg)`.

5. **For each editorial illustration:**
   - Draft the prompt in the Recraft prompt formula (see `references/recraft-recipes.md`)
   - Add it to a config JSON (see `templates/recraft-config.example.json`)
   - Run `scripts/generate-recraft.sh <config.json>`
   - **Show the result to the user before generating siblings.** Style drift between cells is the most expensive failure mode.

6. **For a composite grid:** Generate the cells first, place them in the same directory as the grid SVG, then run `scripts/inline-svg-grid.py <grid.svg>`. The grid will inline the cells as nested `<svg>` elements — portable everywhere.

7. **Preview locally:** `scripts/build-html-preview.py docs/blog-<slug>.md` builds a standalone HTML at `/tmp/blog-preview.html` with all images resolved to absolute file paths. Faster than spinning up Next.js for a sanity check.

8. **If colors drift off-palette:** Run `scripts/palette-force.py <file.svg>` to coerce any near-palette colors (peach, salmon, teal, cyan) back to the exact 3-color register. Uses hue-aware routing (not exact-RGB matching), so it catches the entire family of Recraft drift colors. Read `references/gotchas.md` for why Recraft sometimes drifts.

## Brand register (summary — full details in `references/brand-register.md`)

- **Palette:** Evergreen `#002420`, Action Orange `#FF4F00`, White `#FFFFFF`. *No other colors.* No gradients, no glows, no blur.
- **Typography:** `Instrument Serif` (headings), `JetBrains Mono` (labels/tags, ALL CAPS, wide letter-spacing), `Inter` (body, rarely on illustrations).
- **Shadows:** Hard shadows only. Solid offset shapes, never `feGaussianBlur`. Typical offset: 3px-6px.
- **Borders:** 1.5px-2px stroke, sharp corners (no `border-radius` on outer chrome; small radii OK on inner controls).
- **Engineering-drawing chrome:** `DWG-XX` numbers, `REV XX.XX`, `SCALE 1:1`, corner tick marks at illustration boundaries. Always include — this is the visual "tell" that distinguishes Arnen illustrations from generic SaaS marketing art.

## Recraft prompt formula (full details in `references/recraft-recipes.md`)

Every Recraft prompt is structured as four blocks, in order:

```
<SUBJECT>. <COMPOSITION/POSE/FRAMING>.

STYLE LOCK: Arnen modernist-utility editorial illustration. Strict 3-color
palette: evergreen #002420, orange #FF4F00, white #FFFFFF only. No gradients,
no shadows except solid offset shapes, no glows, no blur. Bold geometric line
art, mid-century editorial register, hand-drawn precision. Flat icon style.
Background: pure solid white, no scene, no environment.
```

Plus the `colors` parameter as RGB **objects** (not hex strings — fal.ai's schema rejects strings):

```json
"colors": [
  {"r": 0,   "g": 36,  "b": 32},
  {"r": 255, "g": 79,  "b": 0},
  {"r": 255, "g": 255, "b": 255}
]
```

The textual style lock and the structured `colors` parameter are both required. One without the other lets the model drift.

## Failure-mode quick reference (full details in `references/gotchas.md`)

- **`FAL_KEY` empty or unset** → script fails fast with a clear message. Get a key at <https://fal.ai/dashboard/keys>, set `FAL_KEY=...` in your shell.
- **macOS bash 3.2** → no associative arrays. All scripts use POSIX-portable patterns (`case` blocks, parallel arrays).
- **Recraft drifts off-palette** (peach skin tones, salmon accents, teal/cyan) → run `palette-force.py`. Or strengthen the prompt's "only" clause.
- **Grid renders with empty cells in some editors** → cells were referenced via external `<image href>`. Run `inline-svg-grid.py` to inline them as nested `<svg>` elements.
- **fal.ai balance $0** → generation 400s. Top up at <https://fal.ai/dashboard/billing>. ~$5 covers a full essay.
- **Recraft regenerates with style drift between cells** → don't generate siblings in a batch when the first one isn't dialed in. Generate one, approve, *then* generate the rest with that prompt as the locked baseline.

## Files in this skill

```
.claude/skills/blog-illustration/
├── SKILL.md                                    # this file
├── scripts/
│   ├── generate-recraft.sh                     # Recraft V4 Pro batch generator
│   ├── inline-svg-grid.py                      # composite-SVG inliner
│   ├── build-html-preview.py                   # standalone HTML preview
│   └── palette-force.py                        # off-palette color corrector
├── references/
│   ├── brand-register.md                       # full visual system
│   ├── recraft-recipes.md                      # working Recraft prompts
│   └── gotchas.md                              # every failure mode encountered
└── templates/
    ├── blueprint.svg                           # engineering-drawing starter
    ├── worksheet.svg                           # reader-carried-artifact starter
    ├── grid-2x2.svg                            # 2×2 composite grid wrapper
    └── recraft-config.example.json             # Recraft batch config starter
```

## One-line invocations

```bash
# Generate Recraft illustrations from a config file
FAL_KEY=... .claude/skills/blog-illustration/scripts/generate-recraft.sh config.json

# Inline external SVG references into a grid wrapper
.claude/skills/blog-illustration/scripts/inline-svg-grid.py frontend/public/blog/<slug>/grid.svg

# Build a standalone HTML preview of an article
.claude/skills/blog-illustration/scripts/build-html-preview.py docs/blog-<slug>.md

# Force any near-palette colors back to the strict 3-color register
.claude/skills/blog-illustration/scripts/palette-force.py frontend/public/blog/<slug>/case-figma.svg
```