html-to-image

name

html-to-image

description

Render hand-coded HTML/CSS into crisp PNG images for architecture diagrams, blog cover art, technical posters, and any case where precise typography, layout, and brand control matter more than what a text-to-image model can deliver. Use this skill whenever the user wants a diagram, infographic, cover image, poster, or visual asset built from code (not generated by an image model), or whenever they reference past work like "another Compass-style architecture diagram" or "a header image for my blog post." Pairs with the frontend-design skill — frontend-design picks the aesthetic, this skill handles the HTML→PNG pipeline.

HTML to image

A workflow for turning a hand-coded HTML file into a high-resolution PNG. The skill captures the mechanical parts — viewport, DPR, font-load timing, crop, dual delivery — so the conversation can stay focused on visual decisions.

Setup

scripts/render.py requires Python 3.10+ (uses X | Y union and tuple[int, int] builtin-generic typing) + the Playwright Python package + the Chromium browser binaries Playwright manages itself.

Quick check (this both imports the module and launches Chromium — if it prints ready, you're done):

python3 -c "from playwright.sync_api import sync_playwright; p=sync_playwright().start(); b=p.chromium.launch(); b.close(); p.stop(); print('ready')"

If it fails, install:

pip install playwright
python3 -m playwright install chromium

Always invoke via python3 -m playwright, not the bare playwright CLI. On systems with a global Node install, which playwright often resolves to the JavaScript Playwright CLI, which downloads browsers to a different location than Python's Playwright looks in — so playwright install chromium will appear to succeed (exit 0, no output) while the Python module still can't find Chromium. The python3 -m form routes through the Python package and writes to the right place.

Chromium binaries land in ~/.cache/ms-playwright/ by default (or $PLAYWRIGHT_BROWSERS_PATH if set — e.g. some sandboxes use /opt/pw-browsers/). The Python module knows where to look; you generally shouldn't need to touch the path yourself.

If the install prompt is interactive (user-facing skill run, not a smoke test), confirm with the user before downloading — Chromium + headless shell are ~280 MB.

When to reach for this skill

• "Draw an architecture diagram for X" / "make an infographic about Y"
• "I need a cover image for my blog post about Z"
• "Generate a poster / explainer / one-pager"
• Anything where the user previously praised a code-rendered image and wants more in that style
• Anything where text-to-image would mangle the typography or get the labels wrong

If the user only wants a live web component (no PNG export), skip this skill — use frontend-design alone.

Pair with frontend-design

This skill is the pipeline. It says nothing about visual style. Before writing HTML, consult the frontend-design skill for the aesthetic direction (typography, color, composition, avoiding generic AI looks). The split:

• frontend-design → what the image should look like
• html-to-image → how to render it crisply and deliver it

Both apply on every job.

Workflow

1. Clarify intent before drawing

For non-trivial diagrams, ask up to three clarifying questions before writing any HTML. Typical ones:

• Is the audience technical, leadership, or mixed?
• Are there parts that are "ours" vs. "ecosystem / external" that need visual separation?
• Any brand color or logo to anchor on, or stay neutral?

If the user says "just go" or doesn't answer, commit to a default and state it in one line ("Going with neutral blue-gray + a single accent; will swap if you prefer something else"). Don't stall on confirmation.

2. Set up the working directory

Iterate on the HTML inside a scratch directory (e.g. /tmp/html-to-image-work/ or the project's working area). Only copy the final files to the user's intended location at delivery. This keeps half-finished artifacts out of the way.

3. Write the HTML

A few conventions the render script depends on:

• Wrap the printable content in a .canvas (or .container, or main) element. The render script crops to this by default, stripping browser margin / body padding so the PNG has no whitespace around the artwork.
• Load web fonts via <link> in <head>, not @import inside CSS. Faster, and networkidle will actually wait for them.
• Inline SVG for icons. No external icon fonts (FontAwesome etc.) — they're a render-timing hazard.
• All CSS inline in <style>. Keeps the artifact single-file and trivially shareable.

If the design uses many components, write a Python build script with f-string templates rather than one monolithic HTML — it makes iteration much faster.

4. Render

Use scripts/render.py. The script handles 2x DPR, networkidle wait, the extra 2-second wait for web fonts, and cropping.

python scripts/render.py diagram.html --preset architecture

Presets (viewport in CSS pixels; PNG is 2x):

Preset	Viewport	When to use
architecture	1360×1080	Dense layered diagrams for leadership reviews
architecture-s	1280×980	Side-by-side architecture, narrower aspect
blog-cover	1200×675	16:9 banner / hero for blog posts
blog-square	1200×1200	Single-concept square for social or inline use
poster	1440×1800	Tall poster, conference handout, explainer

Or pass --width W --height H for custom dimensions. --full-page disables cropping. --selector ".my-class" overrides the crop target.

5. Visual self-check

Always view the rendered PNG before reporting back. Common failures the eye catches but the script doesn't:

• Fonts didn't load (text falls back to system font and looks wrong)
• Icon SVGs misaligned or too small at print size
• Content overflows the .canvas and gets clipped
• Whitespace asymmetry, awkward grid breaks
• Colors that look fine on screen but lose contrast at 2x

If any issue: edit HTML, re-render, re-view. Two or three iterations is normal.

6. Deliver both files

Hand over both the PNG (high-res, drop straight into slides / blog / docs) and the HTML (editable source for the next round of changes). Mention this dual delivery in the wrap-up so the user knows the HTML is theirs to keep tweaking.

Common gotchas

Fonts paint after networkidle. Networkidle fires when network is quiet, but Google Fonts often paints a frame or two later. The script waits an extra 2000ms. If a render still shows fallback fonts, bump the wait — don't remove it.

full_page=True includes body padding. This is the wrong default for diagrams. Always crop to .canvas / .container / main (the script does this automatically). Only use --full-page for full-bleed designs.

1x screenshots look soft. Always use device_scale_factor=2 (baked into the script). The PNG ends up at 2× CSS dimensions — e.g., a 1360-wide viewport produces a 2720-wide PNG. That's what makes it look crisp when embedded in slides at 100% zoom or viewed on retina.

SVG icons drift at small sizes. Inline SVG with viewBox="0 0 N N" and explicit width/height in CSS, not attribute sizes. Stroke widths look thicker at 2x than they did during design — verify in the PNG, not the browser.

Background color of the page matters. If the design is light, set body { background: #fff } (or the canvas's intended outer color). When cropped to .canvas, the body color won't show, but it prevents transparent edges if you ever switch to --full-page.

Style guidance lives in frontend-design

This skill intentionally has no opinions about color palettes, typography pairings, or aesthetic direction. Those decisions are case-by-case and the frontend-design skill covers them well. Resist the urge to copy the visual style of a previous diagram unless the user explicitly asks for it — diagrams that all look the same are a sign the skill has been over-prescribed.