At 16:10 UTC on September 10, cathrynlavery/diagram-design was up 1,287 GitHub stars for the day. GitHub's repository API soon showed 37,476 stars and 2,377 forks for a project created in April. That speed is today's useful developer signal: people are pulling design judgment into the agent layer. Diagram Design gives Claude Code, Codex, Factory Droid and Pi a rulebook for turning briefs into self-contained HTML and SVG files.
The project is moving faster than its metadata. The GitHub description still advertises 38 diagram types, the current README says 39, and the skill guide now specifies 40. Its Codex plugin manifest reached version 2.6.21 on September 10. That mismatch is a practical warning: teams should pin a commit or inspect the installed plugin instead of treating the repository tagline as the contract.
A design system the agent can read
Diagram Design is a collection of agent instructions, reference documents, SVG templates and Python checks. A supported coding agent reads the skill, decides whether a visual will carry more information than prose, chooses a grammar, then writes an ordinary file. The repository architecture keeps behavior rules separate from the files for each visual type, so a request does not load the entire catalog into the agent's context.
Selection begins with meaning. A queue with finite capacity routes through a bottleneck pattern before the agent chooses a data-flow layout; a policy comparison routes to paired evaluation traces and then a flowchart. The 40 current grammars cover familiar architecture and sequence diagrams alongside Wardley maps, Sankey flows, story maps and physical database schemas. The type-selection table gives each one a defined job rather than asking the model to improvise a canvas.
The most useful rules concern subtraction. The skill targets a density of 4 out of 10, limits the accent color to one or two focal nodes, and says a diagram with more than nine nodes probably needs to be split. Connections that add no information should disappear. Those constraints in the project's design philosophy address a common agent failure: every item gets the same box, the same visual weight and another arrow.
Why this repository found an audience
GitHub stars measure attention rather than rendered quality. Still, 1,287 in one daily snapshot, followed by a live total above 37,000, points to a specific frustration with agent-made diagrams. The project author says she built the skill after receiving generic rounded-box graphics from Claude and spending about 30 minutes repairing them in Figma. Her solution was to encode the recurring editorial decisions in the public repository.
Brand setup is unusually explicit. The onboarding flow can sample a public website, read its computed colors and font families, map them to semantic roles, run WCAG AA contrast checks and show a proposed diff before writing the style guide. It also records sampled URLs and any font fallback in a fidelity receipt. The onboarding specification treats fetched page content as untrusted data and limits it to visual signals.
Ordinary output is static HTML with inline SVG and CSS. The templates require an accessible name and description, unique IDs for each figure, and hidden treatment for decorative icons. Static diagrams need no JavaScript or external image service, according to the README's accessibility and output notes. Web fonts can still be remote, so self-contained here describes the diagram code and imagery rather than guaranteed offline typography.
Typography receives its own engineering rules. Hangul and Traditional Chinese labels extend the default font stacks with Noto faces, keep a 12px floor and use per-character width budgets for boxes. The style guide says Simplified Chinese relies on locally available fallbacks because its Noto face is absent from the shipped font link. That gap can change line wrapping between reviewers' machines, so localized output still needs a rendered check.
Motion is optional and has four named modes: none, reveal, step and loop. The first frame must remain complete without JavaScript, while reduced-motion output displays the final static state and disables playback controls. The animation contract rejects remote scripts, arbitrary inline code and runtime geometry. This makes animation a controlled explanation layer instead of a second rendering system.
Imports are editorial redraws
Existing material can enter through a draw.io container. Mermaid files and Excalidraw scenes have separate parsers. The tool extracts components, relationships, groups and direction, then discards the old coordinates, palette and fonts before laying the content out again. The Mermaid import guide calls the operation a redraw because it does not reproduce Mermaid's renderer output.
Four controls shape an import: format, destination size, detail and audience. Faithful detail allows up to 24 nodes, balanced allows 12, and simplified allows 7. Audience changes labels rather than node count. Every import ends with a fidelity ledger that states what stayed and records each merge or omission, as described in the README's import section. That receipt gives a reviewer something more precise to inspect than a polished picture.
The parsers also draw a clear trust boundary. Mermaid extraction reads bounded text without evaluating JavaScript, opening click targets, launching a browser or making network calls. Labels and directives remain inert input even if they contain instruction-like text. Unsupported grammar produces an error instead of an approximation, according to the importer's documented procedure.
Editable output comes with setup costs
SVG export extracts the figure and preserves its title and description. PNG export uses Playwright to capture the SVG at twice its logical size by default, with a transparent background. The export guide requires a manual request and a local browser installation. It also normalizes RGBA colors for PowerPoint and warns that some offline tools may substitute remote fonts.
Codex users can install the marketplace and plugin with two commands from the project's current installation instructions:
codex plugin marketplace add cathrynlavery/diagram-design
codex plugin add diagram-design@diagram-design
The repository now carries 28 Python test scripts and 23 verifier scripts under scripts/. Its CI workflow checks accessibility, geometry, imports, motion, quantitative chart rules and rendered pixels across a three-OS matrix. The run for commit 562dbdf, which bumped plugin manifests to 2.6.21, completed successfully on September 10. These checks cover the shipped rules; they do not certify a user's agent-generated figure.
Several checks test whether a chart's numbers survive the drawing process. The workflow verifies Sankey flow conservation and waterfall running totals. Separate jobs test treemap areas, bubble sizes, bump-chart ranks and beeswarm packing. That is more consequential than a color linter: a good-looking quantitative graphic can still tell the wrong story. The current CI definition makes those invariants reviewable source rather than relying on a screenshot alone.
The pace has changed the testing picture quickly. Our earlier review of Diagram Design covers the setup reality at commit 4faae66 on August 25: 35 Python packages installed in 15 seconds, the build took 4 seconds, and the generic harness found no standard test target. Current main now exposes the narrower test and verification scripts described above, so the commit belongs beside any claim about maturity.
Where the rulebook fits
A team already using a coding agent for documentation can keep the result as editable HTML or SVG, review it in a browser and commit it beside the text it explains. People expecting drag handles will have a harder time. Fixing a collision means changing SVG coordinates or asking the agent for another pass, and the export documentation explicitly avoids adding editing controls to the output.
The import rules also define when to keep an older tool. Diagram Design intentionally throws away Mermaid's automatic layout and draw.io's hand-placed coordinates. Projects that need compact declarative source or exact manual placement should retain those originals and use this project only for a presentation copy. The fidelity rules preserve meaning while allowing the visual arrangement to change.
The next evidence to watch is release discipline. GitHub's releases page currently lists no published release, while the Codex manifest is already at 2.6.21 and the public type counts disagree. A tagged artifact with synchronized documentation would make upgrades easier to audit. Render checks still need to stay green. Until then, the sensible unit of adoption is a tested commit, followed by a human browser check of every diagram that ships.