blog-graphics-pipeline

The toolchain under graphics/ produced the thirty-six visuals of "Designing docs for humans" and is the reference for every post that follows. One HTML page per visual, real screenshots of the product cut into padded crops, labels and leader lines drawn once, a glyphfield export as the ground, rendered headlessly and downsampled.

When to use

• A blog post, docs page or announcement needs illustrations of the real product: before/after crops, zone overlays, exploded components, hover or scroll interactions, type and spacing specimens, covers and OG images.
• The brief says "no text except labels", "use our backgrounds", "make it look like our site": those are this pipeline's defaults.

The files

Procedure

1. Start the static server from the repository root: pnpm graphics:serve (serves graphics/ on port 8765). Install once: pnpm install at the root brings heroicons for the label icons; pip install pillow for the downsampler; agent-browser and ffmpeg on the PATH.
2. Capture the sources you need into graphics/shots/hi/ as lossless webp and register them in SHOTS with their device pixel ratio. Follow the capture skill: the real page, the real theme toggles, the dev overlay hidden, the pointer parked off the page.
3. Measure the rectangles you will crop, in CSS px at 1440 by 900, and keep them in one object per page (N for the new docs, O for the old). Every crop, highlight and leader line derives from these.
4. Write each visual as one add(): crops at a scale that reads at blog size, no text under 26px once zoom-to-fit has run (label chips 28px, tags and badges 30px, numbered dots 56px), lines of 3px. Give each visual its own export in ASSIGN; never reuse a background twice in one post.
5. Generate, audit, render: node graphics/build/gen-visuals.js writes the HTML and graphics/build/manifest.json; node graphics/build/audit.js [ids] opens each one in the browser and fails on any text under the floor, listing overlapping boxes as warnings; graphics/build/render.sh [ids] shoots them. Review with python3 graphics/build/sheet.py, at thumbnail size, which is how the reader meets them.
6. Clips: record the interaction (stop-motion skill), then graphics/build/composite-videos.sh lays it over the still and writes the GIF (1600 wide, 256 colours, sierra dither) and an MP4 master.
7. Export: python3 graphics/build/export-blog.py --covers (add --dest for a landing checkout) writes the set, the dark and light header covers and both OG images. Bump the ?v= stamp on every reference in the post so caches refresh.
8. Hand off: the post embeds the set with the Carousel and HitList MDX components (see the MDX components skill); every visual also appears on /graphics in this repository, which reads the manifest.
9. Serve at device width. Render every blog image with next/image, the column's sizes (BLOG_COLUMN_SIZES) and quality 95, against a dense images.deviceSizes ladder, so a 1x, 2x or 3x screen gets a variant within a few percent of its device-pixel width. A browser shrinking the 3840px master to a 700px column blurs it; a variant at the device width matches a Lanczos resize exactly. Cut clips at 1400px.

Rules that came from review

• Resolution is rarely the blur. The article column is about 700 CSS px wide, so a 1600px stage shows at 0.44x: labels under 26px and crops under about 1.2x are unreadable. Scale the content, not the canvas.
• The floor applies to every text in every graphic, measured after zoom-to-fit: a composition wider than 90% of the frame is scaled down and takes its labels with it. When the audit flags a visual, narrow the composition (smaller crops, shorter labels, one label column) before enlarging the type, or the fit undoes the change.
• Draw the dither background at 2x the stage height, aspect kept, with square pixels: at 1x each dot lands on less than a device pixel and aliases into noise; smoothed, it goes soft; at 2x with image-rendering: pixelated every dot is a crisp 2px square and a non-16:9 stage (the social card) is never stretched.
• Dim article backgrounds (the BG_WASH of 0.64 leaves 36% of the export visible). Covers keep their full brightness.
• Pad every cutout 12px inside its frame and clip where a neighbour would bleed in (clip rectangles). Balance padding on both sides of a crop.
• No glass panels around diagrams, no titles or captions inside images, no sparkle icons on labels, only labels the reader needs.
• One idea per slide. A carousel is a set of different points, not the same point drawn five ways; rewrite a slide's content before restyling it.
• Red for what was removed, blue for the page and what replaced it. Lines start at one x and meet their targets at one offset; align them by construction, not by eye.
• Look at the render before shipping it: a contact sheet for the set, a 1:1 crop for anything with lines or small type.
• Blur that survives a sharp master is a delivery problem. Check what the page actually serves (currentSrc, decoded width against clientWidth × devicePixelRatio) before touching the pipeline; the fix is a variant at the device width, not a bigger master.

Related skills

docs-source-capture, glyphfield-headless-export, stop-motion-ui-capture, gt-blog-mdx-components, gt-docs-visual-tokens.