From f6088d3b52601fc23182c7c9b79bdeec397b0ce5 Mon Sep 17 00:00:00 2001 From: Ben Potter Date: Wed, 13 May 2026 16:57:49 +0000 Subject: [PATCH] docs(.claude/skills/svg-docs-diagrams): skill for authoring SVG docs diagrams Captures the conventions learned while iterating on the Claude Code self-hosted runners diagrams: * viewBox sizing for the ~657 CSS-pixel docs prose column, with a table mapping viewBox font sizes to on-page font sizes. * The 'paint-order: stroke' white halo pattern for arrow labels so they stay readable over zone-tinted backgrounds. * Card title wrapping rules so titles don't overflow a 144 px card. * Locked-to-one-user badge and per-instance suffix conventions for surfacing the things readers most need to see. * A reproducible test loop: render the docs page (not the raw SVG) with a copy-pastable headless Chrome script, then verify the click-through full-size view with a computer_use subagent. * Pitfalls: subagents reusing stale screenshots, Next.js asset caching, and headless Chrome rendering SVGs at sub-natural width when the file is opened directly. Ships with two reference files: 'render-diagram.sh' (a cache-busting docs-page screenshot script) and 'template.svg' (a starter SVG with all conventions baked in). --- .claude/skills/svg-docs-diagrams/SKILL.md | 305 ++++++++++++++++++ .../references/render-diagram.sh | 69 ++++ .../svg-docs-diagrams/references/template.svg | 100 ++++++ 3 files changed, 474 insertions(+) create mode 100644 .claude/skills/svg-docs-diagrams/SKILL.md create mode 100755 .claude/skills/svg-docs-diagrams/references/render-diagram.sh create mode 100644 .claude/skills/svg-docs-diagrams/references/template.svg diff --git a/.claude/skills/svg-docs-diagrams/SKILL.md b/.claude/skills/svg-docs-diagrams/SKILL.md new file mode 100644 index 0000000000..f6bc1b8f63 --- /dev/null +++ b/.claude/skills/svg-docs-diagrams/SKILL.md @@ -0,0 +1,305 @@ +--- +name: svg-docs-diagrams +description: "Author and iterate on SVG architecture diagrams embedded in Coder docs pages. Covers viewBox sizing for the docs column, readable arrow labels, the docs-page test loop with headless Chrome, and the recurring pitfalls." +--- + +# SVG Docs Diagrams + +Use this skill when you are writing or editing an SVG diagram that ships in +`docs/images/**` and renders inside a docs page. + +Coder docs render at a fixed prose column width (`max-w-[65ch]`, roughly +650 to 680 CSS pixels regardless of viewport). Every diagram is scaled to +that column. A diagram that looks great at native 1920px will be +unreadable on the page. This skill captures the conventions that produce +diagrams that read at column width and still look correct when a reader +clicks the image to view it full-size. + +## When to use this skill + +- Adding a new SVG to `docs/images/**` for an existing or new doc page. +- Iterating on an existing diagram (font sizes, layout, arrow routing). +- Debugging an overlap, overflow, or unreadable label complaint. +- Removing or splitting a diagram that is too dense for the column width. + +Do not use this skill for PNG screenshots, icon SVGs, or third-party +brand SVGs. + +## File layout + +```text +docs/images/guides// + .svg + .svg +``` + +Reference each SVG from Markdown as a plain `` tag so you control +the alt text and the path. The frontend renders SVGs at the column +width and lets the reader click for a full-size view, so the SVG must +look correct at both sizes. + +```markdown +One sentence that fully describes the diagram for screen readers. +``` + +## Authoring rules + +### viewBox sizing + +The docs column is ~657 CSS pixels wide. The SVG is scaled to fit. To +keep text readable on the page, target a viewBox aspect ratio where the +horizontal scale factor is no smaller than 0.5. That means a viewBox +width of about 1000 to 1180 works well. Wider than 1280 and side-card +text becomes unreadable. + +For a square-ish concept diagram: `viewBox="0 0 1000 460"` is a good +default. + +For a flow diagram: `viewBox="0 0 960 360"` keeps things proportionate +and matches the existing flow diagrams in +`docs/images/guides/claude-code-self-hosted-runners/`. + +Always set `preserveAspectRatio="xMidYMid meet"` and a `width` attribute +matching the viewBox width. + +### Text size minima + +Compute the on-page font size as +`viewBoxFontSize × (657 / viewBoxWidth)`. Aim for these on-page sizes: + +| Role | On-page target | Example viewBox size at width 1000 | +|---------------------|----------------|------------------------------------| +| Layer / zone title | 16 px or more | 26 to 30 px | +| Card title | 9 to 10 px | 14 to 16 px | +| Body / mono text | 7 to 8 px | 11 to 14 px | +| Arrow label | 7 to 8 px | 11 to 12 px | +| Footnote | 8 to 9 px | 13 to 14 px | + +Body text rendering below 7 px on the page is unreadable. Either shrink +the viewBox, shorten the copy, or drop the text from the diagram and +put it in the surrounding Markdown instead. + +### Arrow labels + +Floating gray text over a tinted zone background is hard to read, +especially at the docs column width. Always give arrow labels a white +halo so they stay legible regardless of background color: + +```css +.arrow-label { + font-size: 11.5px; + font-weight: 600; + fill: #111827; + paint-order: stroke; + stroke: #ffffff; + stroke-width: 3px; + stroke-linejoin: round; +} +``` + +`paint-order: stroke` paints the stroke before the fill, producing a +clean white outline that does not eat the glyphs. Bump +`stroke-width` until labels are clearly readable on the page; 3px in +the viewBox is usually enough. + +### Card title wrapping + +SVG `` does not wrap. A two-word card title like +"Developer surfaces" or "Package registries" overflows a 144 px wide +card at 15 px bold. When a title is longer than about 10 to 12 +characters, split it into two `` elements stacked vertically: + +```xml +Developer +surfaces +``` + +Account for the extra height in the card rect. + +### Visible identity and lock semantics + +When a runner, workspace, or process is locked to a single user, show +that on the diagram with a pill badge. Do not bury it in the +description. Example: + +```xml + + + Locked to 1 user + +``` + +The reader should see the lock at a glance, not have to parse a +paragraph. + +### Differentiating repeated items + +If the diagram shows N instances of the same concept (sessions, pool +slots, replicas) and they differ in some way, surface that difference +in the labels. Three identical-looking session cards with identical +`cwd: /workspace` lines hide the per-session subtree. Use a unique +suffix per instance: + +```xml +_sessions/cse_01ST +_sessions/cse_a4Bf +_sessions/cse_9pXk +``` + +### Always include accessible metadata + +Every SVG must have `` and `<desc>` elements referenced by +`aria-labelledby` on the root `<svg>`. The `<desc>` should be one or +two sentences that fully describe what the diagram shows; this is what +screen readers announce and what search indexes pick up. + +```xml +<svg ... role="img" aria-labelledby="diag-title diag-desc"> + <title id="diag-title">Short title + Longer prose description. + ... + +``` + +## Test loop + +Treat diagrams like code: change, render, eyeball, repeat. The docs +dev server is the source of truth, not native SVG rendering. + +### Render the diagram inside the actual docs page + +Start the docs dev server (see the project's existing dev instructions; +in this repo it's coder.com running on port 4001 with `DOCS_ROOT` +pointed at the coder/coder checkout). + +Then render the docs page with headless Chrome and screenshot it. See +`references/render-diagram.sh` in this skill directory for a +copy-pastable script. + +```bash +bash .claude/skills/svg-docs-diagrams/references/render-diagram.sh \ + http://localhost:4001/docs/ai-coder/claude-code-self-hosted-runners \ + /tmp/svg-preview/page.png +``` + +### Click into the full-size view + +The docs frontend lets the reader click the inline image to view it at +its natural size. Verify both: + +- The inline rendering at column width: text is readable, no overlap. +- The clicked-open view: text is sharp, no overflow past card borders. + +If only the inline version has problems, the viewBox is too wide. If +only the full-size has problems, individual elements are mispositioned. + +### Use a `computer_use` subagent for the click-through + +Headless Chrome can capture the inline rendering, but verifying the +clicked-open full-size view and the overall feel is best done with a +`computer_use` subagent. Spawn one with a clear list of checks: + +```text +For the diagram on : +1. Click through to the full-size view. +2. For each of these labels, report OK or OVERFLOWS / OVERLAPS: + - "