| 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:
-
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."
-
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.
-
Create the output directory: frontend/public/blog/<post-slug>/. Every illustration for this post goes here.
-
For each blueprint/worksheet: Copy the relevant template, customize text/labels/data, save to the post directory. Reference from the markdown as .
-
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.
-
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.
-
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.
-
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):
"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
FAL_KEY=... .claude/skills/blog-illustration/scripts/generate-recraft.sh config.json
.claude/skills/blog-illustration/scripts/inline-svg-grid.py frontend/public/blog/<slug>/grid.svg
.claude/skills/blog-illustration/scripts/build-html-preview.py docs/blog-<slug>.md
.claude/skills/blog-illustration/scripts/palette-force.py frontend/public/blog/<slug>/case-figma.svg
