AI Resource Library Evaluated methodologies, workflows, and tools
← All resources

Diagram Design

adapt · https://github.com/cathrynlavery/diagram-design · by Cathryn Lavery · Evaluated 12 August 2026
diagramsagent-skillsdesign-systemsdesign-tokenshtmlsvgdrawiobloggingclaude-code

What it proposes

A single agent skill (Claude Code plugin, Pi package, or Codex skill install) that constrains an agent into producing editorial diagrams as self-contained HTML: no build step, no JavaScript, no external images, openable straight in a browser. The mechanism is a constraint set expressed as reference files rather than code. SKILL.md holds the philosophy and a type-selection guide; 27 diagram types each get their own type-<name>.md reference, loaded only when that type is selected, so a flowchart request pulls two files instead of thirty-six. The house rules are deliberately rigid: one accent color reserved for the one or two things the reader should look at first, target visual density 4/10, 1px hairline borders, no shadows, max 10px border radius, three font roles (serif title and italic callouts, sans node names, mono for technical sublabels only), and every coordinate, width, and gap divisible by four. Colors are never hard-coded in a type reference; everything resolves through semantic roles (paper, ink, muted, accent, link) defined in one references/style-guide.md. An onboarding flow points the agent at a website, extracts the palette and font stack from the rendered page, maps <body> background to paper, primary text to ink, the dominant CTA/link color to accent, and so on, checks WCAG AA contrast at the 9 to 12px sizes diagrams actually use, proposes an adjusted value when a brand color fails, and writes the tokens as a reviewable diff. A first-run gate refuses to silently ship default-skinned output into a project whose style guide was never customized. Two supporting paths exist: a draw.io importer that parses .drawio, .drawio.xml, and embedded PNG/SVG containers into a structured intermediate representation via a Python extractor, then redraws them under four dials (format, canvas size, detail level, audience) and prints a “fidelity ledger” naming everything merged, collapsed, or dropped; and an exporter that pulls the <svg> node out for Figma or Illustrator, or rasterizes via Playwright at 2x for slides.

Best used when

The recurring output is explanatory prose with structure worth drawing: technical blog posts, architecture write-ups, process documentation, internal runbooks, README diagrams. The value concentrates in the structural types (architecture, flowchart, sequence, swimlane, layer stack, tree, quadrant, pyramid, Venn, loop) where the hard part is not rendering but restraint, and where an unconstrained agent reliably produces the generic rounded-box output the skill exists to prevent. It also fits any setup that publishes to a surface with an established visual identity, since the token onboarding turns brand matching into a one-time twenty-token table instead of a per-diagram color negotiation. The size dial is more useful than it first looks: it changes the type ramp along with the viewBox, so the same source produces a legible projected slide and a legible inline doc figure rather than one scaled copy of the other. The draw.io path pays off specifically when inheriting a pile of legacy diagrams that need to be brought into one look, and the fidelity ledger makes the lossy redraw auditable instead of a silent rewrite. Install cost is genuinely low: markdown, HTML, and one Python script, with no daemon, no service dependency, and no build pipeline, which makes it cheap to try and cheap to abandon.

Poor fit when

Text-first work with no publishing surface gets nothing here. Note vaults, fiction drafting, tracking and logging vaults, and personal research archives rarely contain structure that a diagram explains better than a sentence, and the skill’s own guidance agrees: if a reader would learn more from a well-written paragraph, do not draw. The chart types in the list (bar, line, scatter, Gantt, radar) are the weakest part of the offer; charts are a data-encoding problem, not an editorial-layout problem, and any project that already has a considered charting approach should ignore that half rather than route data through a diagram skill. Frequency matters too: the constraint set only earns its keep if diagrams recur, and a project that needs one architecture sketch a year is better served by asking an agent directly, since a capable model already emits acceptable SVG unprompted. What the skill buys is not capability, it is the constraint set and the persisted brand tokens.

Several rough edges are worth pricing in. The README oversells and miscounts, claiming 29 types against a body listing 27, and carries UTM-tagged links to the author’s own properties throughout, which is a signal about maintenance priorities. Managed installs may overwrite references/style-guide.md on package update, meaning the customized brand tokens (the single most valuable artifact the setup produces) can be silently reverted; the editable symlink install avoids this and should be treated as the default rather than the advanced option. PNG export requires Playwright and a Chromium download, a heavy dependency for rasterization, though the SVG path avoids it entirely. Export is also diagram-only: the editorial cards and headers of the -full variants do not survive, so the richest variant is effectively browser-or-PDF only. Finally, the aesthetic is opinionated to the point of being a signature; token swapping changes colors and fonts but not the hairline-and-whitespace character, so anyone wanting a visibly different look is fighting the skill rather than configuring it.

Verdict

adapt. The core idea is right and the packaging is unusually cheap for what it does, but the useful half is narrower than the type list implies. Take the structural and editorial diagram types, the semantic-token style guide, and the onboarding flow that binds those tokens to an existing visual identity; leave the chart types to whatever already handles data encoding, since a diagram skill is the wrong home for them. Install from a clone or symlink rather than a managed package, because the customized style guide is the whole point and a package update should not be able to overwrite it. The realistic payback surface is published technical writing, where diagrams recur often enough for a constraint set to compound and a consistent look actually matters to a reader; a project without that surface should file this under things worth knowing rather than things worth installing.