render-visual skill
scripts**DELIVERY SKILL** — Produce polished diagrams, slides and social cards as crisp PNGs, JPEGs or PDFs by authoring HTML/SVG and rendering it with a local headless Chromium. Eight themes (ember, slate, paper, terminal, blueprint, frost, neon, sepia), one flag. Lays mermaid flowchart text out into a figure, deterministically. Also frames screenshots and photos in a browser, phone or terminal frame, or cropped to a shape. USE FOR: architecture and flow diagrams, slide decks, og/social cards, blog and README figures, any designed image a doc needs. DO NOT USE FOR: data charts from datasets (use a plotting library), capturing a live UI, photo retouching, or any surface without a shell — write inline SVG. TRIGGERS: mermaid, flowchart TD, graph TD, diagram, flow chart, architecture visual, swimlane, tree view, cluster, deployment, mind map, slide deck, presentation, og card, social card, banner, blog figure, browser frame, device mockup, render a png, export a pdf or jpeg, make an image, visual.
- GitHub stars
- 11
- Files
- 78
- Last commit
- Aug 26, 2026
- License
- MIT
- Allowed tools
- —
What does the render-visual skill do?
render-visual is an agent skill. **DELIVERY SKILL** — Produce polished diagrams, slides and social cards as crisp PNGs, JPEGs or PDFs by authoring HTML/SVG and rendering it with a local headless Chromium. Eight themes (ember, slate, paper, terminal, blueprint, frost, neon, sepia), one flag. Lays mermaid flowchart text out into a figure, deterministically. Also frames screenshots and photos in a browser, phone or terminal frame, or cropped to a shape. USE FOR: architecture and flow diagrams, slide decks, og/social cards, blog and README figures, any designed image a doc needs. DO NOT USE FOR: data charts from datasets (use a plotting library), capturing a live UI, photo retouching, or any surface without a shell — write inline SVG. TRIGGERS: mermaid, flowchart TD, graph TD, diagram, flow chart, architecture visual, swimlane, tree view, cluster, deployment, mind map, slide deck, presentation, og card, social card, banner, blog figure, browser frame, device mockup, render a png, export a pdf or jpeg, make an image, visual.
How to install the render-visual skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the render-visual skill in Plugin
/plugin marketplace add imshaikot/render-visual-skill /plugin install render-visual-skill@render-visual-skill
Install the render-visual skill in Claude Code
~/.claude/skills/render-visual/SKILL.md
$ npx degit imshaikot/render-visual-skill/skills/render-visual ~/.claude/skills/render-visualInstall the render-visual skill in Claude Code (project)
.claude/skills/render-visual/SKILL.md
$ npx degit imshaikot/render-visual-skill/skills/render-visual .claude/skills/render-visualInstall the render-visual skill in Codex
~/.agents/skills/render-visual/SKILL.md
$ npx degit imshaikot/render-visual-skill/skills/render-visual ~/.agents/skills/render-visualInstall the render-visual skill in Gemini CLI
~/.gemini/skills/render-visual/SKILL.md
$ npx degit imshaikot/render-visual-skill/skills/render-visual ~/.gemini/skills/render-visualInstall the render-visual skill in Claude.ai
npx degit imshaikot/render-visual-skill/skills/render-visual render-visual && zip -r render-visual.zip render-visual # claude.ai → Customize → Skills → + → Create skill → Upload a skill → render-visual.zip
SKILL.md
View on GitHubrender-visual — designed PNGs from HTML, no design tool
Every image this skill produces is a small HTML/SVG page screenshotted by headless Chrome: fully versioned, diffable, regenerable in seconds when the copy changes, and styled by a theme file instead of hand-picked colors.
| Template | Canvas | For |
|---|---|---|
$SKILL/templates/diagram.html |
1360×740 | Architecture and flow figures: nodes, labeled arrows, a return path, a line-crossing bridge |
$SKILL/templates/slide.html |
1920×1080 | Presentation slides: kicker, headline with a gradient phrase, up to three points, footer |
$SKILL/templates/card.html |
1200×630 | Social/og cards: mark, headline, one-paragraph pitch, chips, bottom rule |
$SKILL/templates/sequence.html |
1360×740 | Sequence diagrams: lifelines, calls and returns, activations — static, or animated step by step |
$SKILL/templates/swimlane.html |
1360×740 | Cross-functional flows: lanes that own the steps, labelled handoffs, an exception path that never leaves its lane |
$SKILL/templates/tree.html |
1360×740 | Hierarchies, both idioms: an indented tree view (files, nav, an outline) beside the same tree drawn node-link |
$SKILL/templates/cluster.html |
1360×740 | What runs inside a boundary: control plane, worker nodes, pods, and the state that outlives a rebuild |
$SKILL/templates/deployment.html |
1360×740 | Which artifact lands on which machine, over which protocol: el-cube nodes, «stereotypes», artifact chips — see §5 |
$SKILL/templates/flowchart.html |
computed | Mermaid flowcharts. A vertically long process chart — decisions, branch labels, subgraph boundaries, retry loops. Never hand-authored: scripts/mermaid.mjs generates it from mermaid text — see §10 |
$SKILL/templates/mindmap.html |
1360×740 | A question in the middle and the answers around it: six branches, two leaves each, one branch emphasised |
$SKILL/templates/code.html |
1360×740 | Code snippets in a themed window (Carbon-style): hand-highlighted tokens, line numbers, a highlight line, diff rows — see §7 |
$SKILL/templates/charts.html |
parts sheet | Browsable catalogue of the chart and BI parts — pie, donut, bar, line, area, stacked, scatter, funnel, gauge, heatmap, sparkline, KPI tile, table, dashboard. Schematic figures, not plotted data — see §5 |
$SKILL/templates/palette.html |
1360×980 | Theme specimen: the tokens, both fonts, the gradient, the alpha ladders, the parts dressed by that theme. A catalogue, never a deliverable — see §4 |
$SKILL/templates/elements.html |
parts sheet | Browsable catalogue of the frames, infrastructure shapes, deployment node and icon glyphs in $SKILL/parts/. Reference them, don't copy them. Never a deliverable — see §5 |
| Theme | Mood | Fonts |
|---|---|---|
ember |
Warm dark — amber-hued neutrals, cyan/ember/magenta accents | Inter Tight + JetBrains Mono |
slate |
Cool dark — violet-leaning neutrals, jewel accents | Space Grotesk + IBM Plex Mono |
paper |
Light editorial — warm paper, serif display, print restraint | Fraunces + IBM Plex Mono |
terminal |
Near-black phosphor — mono everything, green/amber | JetBrains Mono |
blueprint |
Drafting board — cyanotype navy, chalk lines, a grid that reads | Archivo + Roboto Mono |
frost |
Light UI — cool white, glass surfaces, indigo/teal | Manrope + JetBrains Mono |
neon |
After hours — indigo dark, high-chroma magenta and cyan | Chakra Petch + Fira Code |
sepia |
Aged press — cream stock, brown ink, typewriter mono | Newsreader + Courier Prime |
To see one whole, render the specimen sheet in it:
node "$SKILL/scripts/render.mjs" "$SKILL/templates/palette.html" palette.png --theme blueprint
0. Find the skill first
Every path in this file is relative to the directory holding this SKILL.md, not to the
working directory. You are almost never invoked from inside the skill — it is installed
somewhere central and you are working in someone's project — so resolve that directory once
and prefix every command below with it. $SKILL is written for it throughout.
SKILL=/absolute/path/to/the/directory/containing/this/SKILL.md
If you have lost that path, find it — the layout is always <skill>/scripts/render.mjs:
ls -d ~/.claude/skills/render-visual ~/.agents/skills/render-visual \
./.claude/skills/render-visual ./.agents/skills/render-visual 2>/dev/null
Nothing here needs the working directory to be the skill. Outputs go wherever you say.
1. Workflow
-
Settle theme, template and format before touching a file. Three choices shape everything after, and none of them is yours to default silently:
-
Theme. A theme named in the request wins. Otherwise use the one recorded in
.render-visual.json(below). Failing both, ask — offer the theme table above by mood and let the user pick. Never choose silently: the wrong palette is a re-render at best and an off-brand deliverable at worst. -
Template. Read the task against the template table's "For" column and shortlist what fits. A request that names one — "a swimlane", "an og card" — is the answer. One clear match: take it and say which in the handoff. Several plausible: ask, naming the shortlist and what each would emphasise. Mermaid flowchart text settles this on its own: generate it, do not pick a template and draw it by hand — §10.
-
Format. PNG, JPEG or PDF. A request that names one — "as a PDF", "make it a jpg" — is the answer, and so is an output path that already ends in
.pdfor.jpg. Otherwise use the format recorded in.render-visual.json. Failing both, ask, naming what each is for: PNG for anything going into a README, a web page or a social card, and the only one that can carry transparency; JPEG for a photo-heavy figure or an attachment where weight is the constraint, at a third to a half the bytes; PDF for print, for a figure that will be zoomed, or for a deck that wants vector. The destination usually settles it — ask about the destination rather than the file extension if that is easier to answer.
Where nobody can answer — CI, a scripted run — fall back in the same order: the file, then the closest match, then PNG, stated plainly in the output.
Remember the answers. A project that has decided once should not be asked twice. Standing choices live in
.render-visual.jsonat the project root — theme, where finished images land, scale, anything settled that would otherwise be re-asked:{ "theme": "slate", "format": "png", "output": "docs/figures/", "scale": 2 }Read it before asking anything; after a first round of answers, offer to write it — ask before creating it, it lives in the user's project. The prompt always beats the file. The renderer itself never reads it: pass
--themeexplicitly on every command, so a typo still fails loud instead of falling back to a wrong palette. -
-
Copy the nearest template into the working directory (never edit the templates in place — they are the exemplars):
cp "$SKILL/templates/diagram.html" my-figure.htmlNothing else needs copying.
--themeinlines the theme's CSS at render time, so nothemes/directory has to sit beside your figure. -
Replace the placeholder content. Structure before prose: nodes and arrows for a diagram, one claim per slide, one key fact per chip.
-
Render:
node "$SKILL/scripts/render.mjs" my-figure.html my-figure.png --theme slate -
Look at the PNG. Read it back and inspect it before calling it done — every first render has a defect a human spots instantly: a label overlapping a node, a line bisecting text, a heading a word too long for its box. Fix and re-render; iteration is cheap.
2. The renderer
$SKILL/scripts/render.mjs — plain Node, zero dependencies.
node "$SKILL/scripts/render.mjs" <input.html> <output.(png|jpg|pdf)> [--size WxH] [--scale N] [--theme name] [--format name] [--transparent]
- Size is read from the
width: Npx; height: Mpxon the input's<body>— keep that declaration intact.--sizeoverrides. - Scale defaults to 2: a 1360×740 canvas becomes a 2720×1480 PNG, right for retina, Medium, and READMEs.
--format png|jpeg|pdfpicks the output format. Leave it off and the output file's own extension decides, socard.jpgandposter.pdfneed no flag. The two never disagree quietly:out.png --format pdfis fatal rather than resolved, because either way of guessing writes a file whose name lies about its contents.- PNG is the master and the default — lossless, the only one that can carry alpha.
- JPEG is transcoded from a master PNG that has already passed the content guard,
so it costs one extra Chrome pass and lands at roughly half the bytes. It has no
alpha channel, so
--transparentis refused rather than silently blackened. - PDF is printed in the same launch as a proof screenshot, at exactly the canvas
size: an injected
@pagerule pins the page box and the box is checked afterwards. Without that rule Chrome quietly lays the figure out on US Letter and exits 0, which is why the input needs a<head>to inject into. PDF is vector, so--scaleis refused — it is already resolution-independent at any zoom.
--themeinlines one of the skill's own themes into a temp copy of the page, so one source file renders in any theme and the figure needs nothemes/directory beside it. An unknown name is fatal and lists what exists; a page with no theme stylesheet to replace is fatal too, because rendering it unthemed would quietly give you the wrong colours.--transparentrenders with a real alpha channel: the body's ground is unpainted and the glow/dots furniture is stripped, so the figure drops onto any surface — docs and slides with their own backgrounds, web pages, video overlays. Composes with--theme(pickpaperover light surroundings, a dark theme over dark). Note--surfacekeeps its 8% translucency, so a busy backdrop shows through faintly — a frosted-glass look; if that fights the content, place the PNG on a calmer area.<g data-part="...">is replaced with that part's markup from$SKILL/parts/before the render, so a figure references shapes instead of carrying copies of them. See §5.data-image="./shot.png"puts an image on the page — inside a device frame, cropped to a shape, or as a background. Local files only; they are read and inlined before the render, and anything unreadable is fatal rather than an invisible hole. See §6.- A missing local stylesheet is fatal, and checked before Chrome launches. Every color
is a theme token, so a broken
<link>does not degrade the render — it empties it, into a blank white page that screenshots as a perfect success. Passing--themesidesteps this entirely; without it, keep the page's own stylesheet resolvable. - A contentless render is fatal too, in every format. After the screenshot the PNG is
decoded and rejected if its luminance spread says nothing but background and furniture
got painted — the failure a resolved-but-empty stylesheet or content positioned outside
the body box produces, which Chrome otherwise reports as a perfect success. A truncated
PNG and one that came out the wrong size are rejected in the same pass. JPEG and PDF are
covered by the same guard rather than a weaker one, which is the reason for the shapes
above: a JPEG is only ever encoded from a master that passed, and a PDF is only ever
accepted beside a proof shot that passed. The rejected file is left in place so you can
look at it — including the proof or master, which stays in
$TMPDIR/render-visual/until the next render reaps it. - Chrome discovery: standard install paths on macOS, Linux, and Windows are probed,
then
PATH;CHROME_PATHoverrides and is fatal if it does not resolve. Any Chromium works (Chrome, Chromium, Brave, Edge). On Ubuntu the snap-packaged Chromium gets a private/tmpand cannot see the paths written for it — prefer a deb Chrome or Brave there, or setCHROME_PATH. - Chrome often hangs after writing the screenshot. The renderer waits on the output
file, not the process, then kills it — with
SIGKILL, notSIGTERM: headless Chrome swallowsSIGTERMduring startup and lives on holding its profile. Do the same in any custom pipeline. - Everything temporary lives in one place,
$TMPDIR/render-visual/: warm Chrome profiles (profile,profile-1, …) claimed per process via pid lockfiles, the prepared page copies, and animation frames. Concurrent renders never share a profile (Chrome would refuse) and each stays warm; a cold one costs first-launch setup. Every run reaps Chromes left on an unclaimed slot before it starts, and a render that still hits a bad slot retries on another, so an interrupted run cannot wedge the next one. Nothing is written into the directory you are rendering from — a read-only input directory works fine. - Theme fonts come from
fonts.googleapis.com. With no network the render still succeeds, but falls back to system fonts and will not match the previews. If that matters, render on a connected machine or accept the substitution — the layout is unaffected.
The harness
Two scripts back the guarantees above. Neither is needed for a normal render.
node "$SKILL/scripts/doctor.mjs" # preflight: reap orphans, clear stale locks, report
node "$SKILL/scripts/doctor.mjs" --prune # also delete idle warm profiles to reclaim disk
node "$SKILL/scripts/selftest.mjs" # ~2m: assert every concurrency and cleanup invariant
node "$SKILL/scripts/selftest.mjs" --quick # ~90s: same, minus the animation test
Reach for doctor.mjs when renders fail with "is another instance using profile" — that
is an orphaned Chrome holding a slot, and --prune also answers "why is my temp dir
hundreds of MB". Run selftest.mjs after changing anything in scripts/: it renders into
a throwaway TMPDIR, so it never touches the machine's warm profiles and can assert that
it left nothing behind. It covers concurrent renders agreeing byte for byte, overlapping
--theme runs not contaminating each other, interrupted runs leaving no orphan, and both
blank-render guards.
3. Animated sequence diagrams — no ffmpeg required
$SKILL/templates/sequence.html marks every message with data-step="N". Opened plain it renders
the complete diagram (a static figure). Opened with ?step=N it shows steps below N dimmed,
step N highlighted, and the rest hidden. ?f=0..1 is the tween fraction within that step's
reveal, and ?fx= picks the reveal preset — so every frame of a smooth animation is still
just a URL.
$SKILL/scripts/animate.mjs renders each step as a short tween (several frames at --fps, in
parallel Chrome instances) plus a dwell frame, and assembles a looping GIF in pure Node:
Chrome's PNG frames are decoded with the built-in zlib, median-cut quantized to a shared
palette with ordered dithering, and LZW-encoded by hand. Frames after the first store only
the changed region (transparent-pixel deltas), so tween frames cost little. GIF is a 1989
format; it does not need ffmpeg.
node "$SKILL/scripts/animate.mjs" my-sequence.html my-sequence.gif --theme ember --fx pop
| Flag | Default | |
|---|---|---|
--fx |
slide | reveal preset: slide (fade + drop-in), fade, pop (scale overshoot); data-fx="name" on any element overrides per element |
--fps |
25 | tween frame rate; 20/25/50 play back exactly (GIF timing is 10ms units, 50fps is the format's ceiling) |
--transition |
450 | ms of tween per step reveal; 0 = the old one-frame-per-step look |
--delay |
900 | ms of dwell on each completed step |
--hold |
2600 | ms on the final, complete frame before the loop restarts |
--jobs |
4 | parallel Chrome instances (each keeps its own warm profile) |
--scale |
1 | GIFs get heavy fast — stay at 1x unless the canvas is small |
--theme / --size |
— | as in render.mjs |
--keep-frames |
off | keep the per-frame PNGs for inspection |
Images (§6) work here too and are read once for the whole run, not once per frame — but every frame still carries them, so keep a source that appears in a GIF small.
Rules of thumb: steps are numbered 1..N with no gaps; give activations the step of the call that starts them; a GIF that tells the story in under ~8 steps is one people actually watch. GitHub READMEs autoplay GIFs; Medium accepts them as uploads.
4. The aesthetic rules
Themes define tokens; templates consume only tokens. Never hard-code a color in a template.
Accent semantics — one accent per meaning, never decoration:
| Token | Meaning |
|---|---|
--a1 |
The primary thing, forward paths |
--a2 |
Actions, returns, what flows back |
--a3 |
External parties, alternates, alerts |
--a4 |
Success, confirmation |
Alpha grades — every colour token has a component twin: --a1-raw…--a4-raw,
--ink-raw, --ground-raw, --surface-raw, each three bare OKLCH numbers. Ask them for any
transparency you need:
.badge { background: oklch(var(--a1-raw) / 12%); border: 1px solid oklch(var(--a1-raw) / 45%); color: var(--a1); }
.scrim { background: oklch(var(--ground-raw) / 72%); } /* a caption band over a photo */
The solid token is built from the same components (--a1: oklch(var(--a1-raw))), so a wash
can never drift from the colour it is a wash of. Grades that read: 6–12% a wash to sit
text on, 20–35% a fill meant to be seen, 45% an edge, 70%+ a scrim over an image.
A grade is still the accent — the semantics above hold, so a 12% --a3 wash means external,
not a nice pink. In SVG this needs a CSS class like every other var(); a presentation
attribute will not resolve it. templates/palette.html renders the whole ladder for whichever
theme you hand it, which is the fastest way to pick a grade.
Gradient text (--grad) is for one phrase per image, on the headline. The ramp is
tuned per theme; do not compose your own across near-complementary hues — the midpoint
greys out.
Furniture stack, bottom to top: ground → blurred glow circles (--glow1/--glow2 at
--glow-opacity; paper and sepia set it to 0, frost keeps a pale one) → the dot lattice (masked radially so it
fades at the edges) → content. Do not add new furniture kinds; restraint is the style.
Diagrams: nodes are rounded rects (rx=14) in --surface with a --line border, a
small stroke glyph in the node's accent, a display-font title, and a mono subtitle. Arrows
are 1.8px with 7px triangle markers in the line's own color; labels sit above the line
in the same color. In SVG, set colors via CSS classes (.s1/.f1 etc.) — var() does not
resolve in presentation attributes.
Type: display font for titles only; mono for labels, chips, kickers, footers, and
anything technical. Kickers are small mono, letter-spaced, uppercase, --ink-faint.
Files in this skill
78render-visual skill questions
How do I install the render-visual skill in Claude Code?
Run npx degit imshaikot/render-visual-skill/skills/render-visual ~/.claude/skills/render-visual. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the render-visual skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.