html-shot — a design in, the image assets out

Render an HTML file, a URL, or an SVG into a pixel-perfect static image with Playwright (headless Chromium): any CSS renders faithfully, and CJK text and emoji come from system fonts with nothing to bundle. A local file is served over a throwaway 127.0.0.1 server, so Chromium resolves every reference itself — relative paths, site-absolute /xxx, @import, srcset, fonts named inside a stylesheet — and a card renders correctly with the project's dev server down.

You never have to leave CSS. The skill handles what to shoot (the whole body, one element, the full page), how sharp (supersampling, --dpr), and what ships (format, palette size, and for an icon set, the per-platform files).

Two entry points, one engine:

When to use

• Generating or refreshing an og:image / social preview card (1200×630) for a site or repo.
• Turning a design written in HTML/CSS — badge, banner, diagram, certificate — into a PNG.
• Screenshotting a page or one element of it, from a URL or a local file.
• Rasterising an SVG — a logo or app-icon master at an exact size, with transparency — when the mark leans on filters that only a browser renders faithfully.
• Anything where the copy is CJK, emoji, or mixed-script: system fonts do the work, so there is no font to subset or bundle.

When not to use

• The copy is all-English and you cannot install a browser (CI container, tiny lambda) — Satori / @vercel/og renders a CSS subset with no Chromium, at the cost of supplying fonts yourself.
• You need a chart or a diagram from data — reach for a plotting/diagram tool and shoot the result only if you also need it as an image.
• The HTML comes from somewhere you do not trust: it really executes here (see How local files are served).

Procedure

1. First run only — install the engine (below). If it is already installed, render.mjs just works; if it is not, the script exits with the exact install command to run.

2. Write or copy the HTML. Two starters, and they size themselves differently on purpose:

   • template.example.html — a card. body gets an explicit width/height in px and the output size flows from there.
   • icon.example.html — a transparent mark or app icon. The shape sits on a child element (a background on body propagates to the root canvas and ignores its border-radius), and every size is in vmin, so the mark fills whatever size it is rendered at. icons.mjs renders it once at 1024 and downsamples from there.

3. Render with render.mjs (see Usage).

4. Look at the output image before reporting success. Read the PNG back — clipped text, a missing glyph, or a font that silently fell back are all visible in one glance. A referenced asset that 404s prints a note — line naming the path and makes the exit code non-zero (the image is still written, marked ⚠).

5. With --transparent, the eye cannot check it — every viewer paints transparent pixels white. Ask the file instead (sharp ships with this skill):

   node -e "require(process.argv[1])(process.argv[2]).stats().then(s=>console.log(s.isOpaque?'NO alpha — the page paints its own background':'transparent'))" {SKILL_DIR}/node_modules/sharp badge.png
   

   Both paths go in as arguments, not spliced into the quoted JS: inside a JS string a Windows path is a run of escape sequences (\node_modules begins with a newline), and the spliced form throws Cannot find module on every backslash path.

First run (install the engine, once)

Needs Node ≥ 20.9 — that is sharp's floor (playwright only asks for 20); render.mjs checks before importing and says so rather than failing with a module error that reads like a broken install.

cd {SKILL_DIR} && npm install && node node_modules/playwright/cli.js install chromium

Run npm install inside the skill directory as shown, not npm --prefix {SKILL_DIR} install: when the directory is reached through a symlink (a checkout linked into the agent's skills directory), --prefix rewrites package-lock.json with absolute paths. The Chromium step is instant if the browser is already in Playwright's shared global cache.

Playwright's supported platforms (its own system-requirements list; older releases are untested and the browser may not launch): Windows 11+ / Windows Server 2019+ / WSL, macOS 14+, and Debian 12–13 / Ubuntu 22.04–26.04 on x86-64 or arm64. There is no musl build, so Alpine images (node:*-alpine) cannot run this — use a glibc base such as node:22-slim in CI. (sharp does have musl builds, so the install succeeds and only the browser launch fails, which reads like a mystery.)

On Linux (servers, containers, WSL, CI) two extra things are needed — macOS and Windows have both already:

# 1. Chromium's shared libraries (needs sudo; skip if the browser already launches)
node {SKILL_DIR}/node_modules/playwright/cli.js install --with-deps chromium

# 2. CJK + emoji system fonts, or non-Latin text renders as tofu boxes (□□□)
sudo apt install fonts-noto-cjk fonts-noto-color-emoji   # Debian/Ubuntu

{SKILL_DIR} is this skill's own directory — whatever path the agent reports when it loads the skill (~/.claude/skills/html-shot, ~/.agents/skills/html-shot, a project-local .skills/, …). Footprint: ~47 MB of dependencies, plus ~700 MB of browser on disk — Playwright installs both chromium (~430 MB) and chromium_headless_shell (~270 MB); the ~150 MB figure quoted elsewhere is the compressed download. Both are cached globally and shared across projects, so it is paid once per Playwright version. The first install takes a few minutes. There is no need to probe whether it is installed — run render.mjs and it will tell you, with the command to run.

Usage

node {SKILL_DIR}/render.mjs <input.html|input.svg|url> <output.(png|jpg|webp)> [options]

Size is automatic: with no --width/--height, the actual rendered box of body is measured — including the default-margin offset, so a page without margin:0 is not cropped off-center. The card comes out as big as you made it in CSS, and resizing later means editing one place in the template. (A body with no width is still a block element, so it fills the default 1200px viewport width.) Animations are settled before the box is measured and at shot time — finite ones jump to their end state, infinite ones are cancelled — so the measurement and the frame agree and repeated runs are identical.

Sizing follows one rule everywhere — output pixels = CSS size × --dpr — in all three modes (fixed size, --selector, --full). --scale only decides how far to supersample before scaling back down. Option combinations that get ignored (passing --base alongside a URL, say) print a note rather than being silently dropped.

Making the file smaller. A card is flat artwork, and a truecolour PNG stores it as if it were a photograph. --palette roughly halves it and --colors 16 cuts it to a sixth, with no visible change (the bundled template.example.html, a 1200×630 CJK card: 85 KB truecolour → 37 KB at 256 → 15 KB at 16 → 6 KB at 4, i.e. roughly a half, a sixth and a twelfth); dithering is off because on flat fills it only adds noise. Use it on cards, marks and diagrams; leave it off for photographs and long smooth gradients, where too few colours band — there --format webp --quality 82 is the better trade. Alpha survives quantisation.

Examples:

# Social card: as big as body says
node {SKILL_DIR}/render.mjs card.html public/og.png

# 2x / smaller webp / transparent badge / dark-scheme card
node {SKILL_DIR}/render.mjs card.html public/og@2x.png --dpr 2
node {SKILL_DIR}/render.mjs card.html public/og.webp --quality 82
node {SKILL_DIR}/render.mjs badge.html badge.png --transparent
node {SKILL_DIR}/render.mjs card.html og-dark.png --scheme dark

# Custom size / full page / single element / URL
node {SKILL_DIR}/render.mjs card.html cover.png --width 1600 --height 900
node {SKILL_DIR}/render.mjs https://example.com shot.png --full
node {SKILL_DIR}/render.mjs page.html hero.png --selector ".hero"

# Flat artwork at a third / a tenth of the bytes
node {SKILL_DIR}/render.mjs card.html public/og.png --palette
node {SKILL_DIR}/render.mjs mark.html favicon.png --colors 16

# An SVG rasterised by Chromium, at the size you ask for
node {SKILL_DIR}/render.mjs logo.svg logo-1024.png --width 1024 --transparent

# One element out of a preview sheet, with the sheet's own framing stripped
node {SKILL_DIR}/render.mjs brand.html favicon.png --selector "#mark" --transparent --dpr 2 \
  --style "body,.cell{background:transparent!important;padding:0!important}"

Icon sets

node {SKILL_DIR}/icons.mjs <source.svg|.html|.png|url> <outdir> [--preset P] [--only LIST] [--pwa] [--bg C] [--small SRC]

Same engine — it shells out to render.mjs for a 1024×1024 transparent master (--scale, --wait, --base, --style and --channel pass through to that render), then fans the master out into the handful of files the target actually reads, under the names it expects.

How many files you need is a different question from which target you are building for. The preset picks the names; --only picks how many. Most icons in the wild are just a page icon, and for those one file is the whole job:

--only takes ico,svg,apple,pwa on the web presets and ico,icns,png on the app ones, so any subset works. --pwa stays opt-in because a site that is not installable never reads those two files — and they cannot share an output directory with --preset next (the manifest fetches /icon-192.png from the site root, i.e. public/, while the next preset writes into app/), so build them in two passes: --preset next into app/, then --only pwa into public/.

Of the default three, apple-touch is the one to drop when nobody will add the page to an iOS home screen. Keep the SVG — it is what modern browsers display, and with an SVG source it costs a file copy. Keep the .ico — browsers and crawlers request /favicon.ico whether or not you ship one, so leaving it out trades tens of KB (60 KB from the bundled icon.example.html) for a 404 on every cold visit.

The run ends by printing the exact <link> lines to paste into <head>, only for the files it actually wrote, and with each href derived from <outdir>: a leading public/ or static/ is the served root and is stripped, so static/img yields /img/favicon.svg, while any other directory is assumed to be the root and says so. (favicon.ico needs no line when it lands at that root — elsewhere nothing auto-discovers it, and the output tells you to point the framework's favicon setting at it instead. Next's App Router wires its files up by filename.) Copy them from the output rather than writing them by hand.

Four rules are baked in, because each one is a silent failure otherwise:

• apple-touch-icon is written opaque, always. iOS composites alpha onto black, so a rounded mark would ship with black corners. It is flattened onto --bg (default #ffffff) and the alpha channel removed; for a rounded mark pass the mark's own fill, so the corners disappear under iOS's own mask. A see-through --bg is refused rather than baking the icon solid black behind a ✔.
• No single image is upscaled past the master. apple-touch, the PWA pair, the desktop size ladder and the icon.png fallback are each clamped to what the source has to give, and the clamp is announced — including in the printed manifest snippet, which quotes the sizes on disk. The .ico/.icns containers are the exception (png2icons fills their ladders from whatever it is handed), so give it a 1024 px square master and the question does not arise.
• An SVG is passed through, never synthesised. A vector source is copied to favicon.svg/icon.svg as-is — the file modern browsers display, and the only one that can carry a prefers-color-scheme dark variant. A raster source simply gets no SVG.
• --small takes a second drawing for the 16 and 32 px .ico entries. A logo with real detail turns to mush at 16 px no matter how good the downsampling; the fix is a simpler drawing, not a better filter.

Deliberately not emitted, because nothing reads them any more: the apple-touch size ladder (iOS scales 180 down itself), browserconfig.xml / mstile-*.png, mask-icon.svg, and *-precomposed.png.

One sheet, many assets

A brand sheet — every mark, logo lockup and card variant on one page — is the comfortable way to design them, and --selector shoots any one of them. The sheet's own framing gets in the way: the swatch cell behind a rounded mark paints its own white, and an element shot keeps whatever shows through the corners, so --transparent alone comes back opaque. --style removes the framing for the duration of the shot; it is injected before anything is measured, so a rule that changes layout is reflected in the output size rather than fighting it.

for m in mark1 mark2 logo; do
  node {SKILL_DIR}/render.mjs brand.html "$m.png" --selector "#$m" --transparent --dpr 2 \
    --style "body,.cell{background:transparent!important;padding:0!important}"
done

Rasterising an SVG

Hand render.mjs an .svg and it is wrapped in a minimal page (margin:0, the svg pinned to the viewport). The default size comes from the SVG's own width/height, else its viewBox — so a viewBox="0 0 100 100" icon comes out 100×100 unless you say otherwise. Give one of --width/--height and the other follows the SVG's aspect ratio.

The viewBox is what makes it scale. Without one the artwork sits at its authored size in the top-left corner of whatever frame you asked for. When the root declares a width/height, the missing viewBox is synthesised from them; a viewBox that is present but unreadable (malformed, or viewBox="") is overwritten in place and noted, never appended alongside (the parser keeps the first occurrence). When the root declares neither, nothing can be inferred and the render says so. A raster input (.png, .jpg, …) is refused outright — it would otherwise be served as HTML and come out as mojibake.

Go through the browser rather than sharp's own SVG rasteriser when the mark leans on filters (feTurbulence, feDisplacementMap): the two engines disagree there, and if that texture is the design only the browser gives you the design. Plain shapes look the same either way, and for those sharp alone is lighter. For filter-heavy marks --scale 1 stays closest to a 1× browser screenshot, since supersampling resamples the generated grain. An SVG's own <text> is drawn with system fonts and the wrapper carries no lang, so CJK fallback follows the rendering machine's locale — convert text to paths for the same bytes on every machine.

Making an og card

Write the design as an HTML file whose body has a fixed size (e.g. width:1200px; height:630px), and reference fonts however is natural — site-absolute url("/fonts/x.woff2") resolves against public/, relative url("fonts/x.woff2") against the HTML's own directory. Copy template.example.html to your own og.html, edit it, then

node {SKILL_DIR}/render.mjs og.html public/og.png

Add <meta property="og:image"> to the page yourself afterwards. A GitHub repo's Social preview has to be uploaded by hand in Settings (the gh CLI cannot set it).

For a transparent mark — an app icon, a favicon master, a badge — start from icon.example.html instead and add --transparent. It is built around the trap: the shape lives on a child element, because a background on body is propagated to the root canvas and the canvas ignores body's border-radius.

How local files are served (and the boundaries)

A local HTML input is not pasted into the page — it is served from a throwaway HTTP server bound to 127.0.0.1 on a random port, shut down as soon as the shot is taken. Chromium then resolves references the same way it would on a real site, which is why @import, srcset, fonts named inside a stylesheet, and assets injected by scripts all just work.

• Two directories answer requests: the input HTML's own directory (so img/logo.png next to the card resolves), then --base — the nearest public/ by default — so site-absolute /fonts/x.woff2 finds public/fonts/x.woff2. Nothing outside those two is served: paths are fully resolved first, so neither /../ nor a symlink inside a root can reach outside it.
• The public/ search is deliberately narrow: the directory must be spelled exactly public on disk, and the walk stops at the project root (the first directory holding package.json or .git) — otherwise a case-insensitive match on Windows/macOS would adopt the OS's own shared folder (C:\Users\Public, ~/Public) as a served root. Pass --base to be explicit.
• A file:// URL is treated as a local file, not a remote page: same roots, charset and missing-asset accounting as a plain path.
• A missing asset is loud: the request prints a note — line naming the path, and the run exits non-zero (the image is still written, for inspection) — CI cannot silently ship a card with a hole in it.
• Only this render's Chromium can talk to the server: every request must carry a per-run random token; any other local process that finds the port gets 403.
• Everything in those two directories is reachable by the page. Point --base at the asset directory rather than a project root if that matters.
• The HTML genuinely executes in local Chromium, JavaScript and outbound requests included. Do not point this at HTML you do not trust.
• A page that omits <meta charset> is still read as UTF-8 — the server sends the charset.

Common mistakes