Graphics pipeline

How the illustrations for the General Translation blog are made, from the brief to the carousel, with the toolchain that lives in graphics/. It produced the thirty-six visuals of "Designing docs for humans" and is the procedure every post after it runs. The gt-graphics skill (skills/gt-graphics, /skills/gt-graphics) carries the same rules into agent sessions; this document is the long form.

What a visual isCopy Anchor Link

One HTML page, 1600 by 900, rendered headlessly at 7680 wide and downsampled to 3840. The page holds real screenshots of the product cut into padded crops, labels and leader lines drawn once, and a glyphfield export as the ground. Nothing in it is invented: every rectangle is a measured region of a captured page, every label names something the reader can find in the product.

The rules the set settled on, each learned from a review:

• No text except labels. No titles, captions or descriptions inside an image; the post carries the prose.
• One idea per slide. A carousel is a set of different points; a slide that restates its neighbour gets new content, not a new style.
• Real crops, not mockups. The one illustrative mock in the set is labelled as a mock.
• Red for what was removed, blue for the page and what replaced it.
• No glass panels, no sparkle icons, no over-rounded boxes: the graphics obey the same hit list the post publishes.

SizingCopy Anchor Link

The article column is about 700 CSS px wide, so a 1600px stage is shown at 0.44x. Everything is sized for that, not for a full-screen viewer:

Resolution was never the blur. At 1x the dither's one-pixel dots landed on less than a device pixel and aliased into noise; at 2x with smooth scaling they read as a halftone. Small labels were the other half of it.

The floor is measured after zoom-to-fit, not as declared. A composition wider than 90% of the frame is scaled down, and its 28px labels with it, so when the audit reports text under the floor the usual fix is to make the composition narrower (smaller crops, shorter labels, one label column) rather than to enlarge the type. MIN_TEXT in gen-lib.js holds the floor.

The filesCopy Anchor Link

Generated folders (graphics/build/visuals/, graphics/out/, graphics/rec/stopmo*/) are ignored by git; everything in them comes back from the scripts.

ProcedureCopy Anchor Link

1. Install once: pnpm install at the root (heroicons for the label icons), pip install pillow, and agent-browser and ffmpeg on the PATH.
2. Serve: pnpm graphics:serve keeps graphics/ on port 8765.
3. Capture sources into graphics/shots/hi/ (see "Capturing") and register them in SHOTS with their density.
4. Measure the rectangles you will cut, in CSS px at 1440 by 900, into the page objects in gen-visuals.js.
5. Write each visual as one add(id, area, name, bg, why, () => html). Assign it its own export in ASSIGN.
6. pnpm graphics:gen writes the HTML and the manifest; pnpm graphics:audit [ids] measures every text against the floor and lists overlapping boxes (fix the failures, judge the warnings); pnpm graphics:render [ids] shoots them; python3 graphics/build/sheet.py [ids] tiles them for review.
7. For a clip, record (see "Clips"), then graphics/build/composite-videos.sh.
8. pnpm graphics:export writes the webp set and GIFs into public/static/blogs; --dest points at a landing checkout. Bump the ?v= stamp on every reference in the post.
9. Check the set on /graphics and the post on /blog.
10. Let the page serve each image at the width it is shown. The masters are 3840px wide and the column is about 700 CSS px, so a browser left to shrink them itself blurs them (measured: about an eighth of the edge contrast on a 2x screen, none for a variant at the device width). Every blog image goes through next/image with the column's sizes and the dense images.deviceSizes ladder in next.config.ts, at quality 95; clips are cut at 1400px, the column's 2x width.

CapturingCopy Anchor Link

Sources come from a landing dev server built from main, captured with agent-browser at a device pixel ratio of 4 or 5 at 1440 by 900, the Next.js dev portal hidden, the pointer parked on plain text. Themes come from agent-browser set media light|dark; the docs follow the preference when no theme is stored. Menus open with their real control. The old docs lived on an SSO-protected Vercel preview; those were captured by serializing the DOM from a signed-in Chrome to the local server and screenshotting the saved page. Convert captures to lossless webp; the library reads webp sizes.

BackgroundsCopy Anchor Link

The exports are Kevin's glyphfield project, rendered headlessly through window.glyphfield.studio (graphics/glyph/gfexport.sh). The generator draws one export per visual at exactly 2x the stage and dims it under article visuals; covers keep the full export. Blue duotone variants carry the covers. Every cover has a light-theme twin (light: true on coverExploded and coverWiremap): the same ground and scale, the docs captured in their light theme, the wireframe plate in paper and ink. The post lists the light cover under imagesLight and the blog shows the one for the reader's theme.

ClipsCopy Anchor Link

The recorder keeps one or two frames per second at 4x, so interactions are captured as stop-motion: pause the Web Animations, step currentTime between screenshots, assemble with ffmpeg at variable frame durations. Screenshots re-fire trusted pointer events on the last clicked element, so the capture blocks real pointer events in the region and drives hovers synthetically. The composite reads the crop rectangle from the rendered visual, overlays the clip, and writes a 30fps MP4 master and the GIF the post embeds: 1600 wide, 256 colours, sierra dither, rectangle diffing.

Handing off to a postCopy Anchor Link

The post embeds the set with the Carousel and HitList MDX components of the landing blog (children with string attributes; the blog's MDX renderer strips expression props). Covers ship as 3840 webp and the OG image as a 2400 by 1260 PNG; the landing app serves webp covers at quality 95, because dithered artwork smears at the default 75. Posts live in the generaltranslation/content submodule, so a change is two pull requests. When the post needs anything from gt-cloud (a new MDX component, images under public/static/blogs/, redirects or navigation entries), the gt-cloud pull request merges first and the content pull request second; in the other order the post publishes with missing images or a failed build. The content repository's preview app needs a simple version of every component or its build fails. gt-website (references/blog.md, read against gt-cloud main on 2026-10-05) holds both rules. This repository keeps the authoritative copy of the three docs-redesign posts under content/blog and their graphics under public/static/blogs, read by /blog and /graphics.

Where it went wrong, and the fixCopy Anchor Link

• A captured Lucide glyph is a <rect> plus a path (copy, sidebar). The inliner used to strip width/height from every element, so the rect collapsed and only a corner path drew. It now resizes the root tag only.
• With the static server down, render.sh shot Chrome's error page and the export shipped it. The render now skips a page that never centres.