An architecture diagram with ten components already exceeds Diagram Design's general nine-node limit. The skill tells the agent to split it into an overview and a detail view. That constraint is worth examining after an October 10 GitHub Trending snapshot recorded 1,189 stars gained in a day: this project gives AI agents rules for deciding how much a diagram should show, then makes them account for the omissions. Its instructions put those decisions ahead of drawing.
Diagram Design, by Cathryn Lavery, packages instructions and templates for coding agents that produce a single HTML file containing SVG. The repository lists 44 visual types and support for several agent hosts. Its appeal for developers is a way to turn an explanation into a graphic without making every layout decision manually. The cost becomes clearer when you import an existing diagram: the agent preserves its meaning, discards its styling, and may compress its contents.
A diagram has to earn its space
The main skill file asks whether a paragraph or table would explain the subject as well. If so, it tells the agent to skip the drawing. When behavior matters, the agent first selects a semantic pattern, such as a queue bottleneck or a lifecycle, and then chooses the visual type. A sequence of events and a map of services need different arrangements even when they describe the same system.
The layout reference sets a general ceiling of nine nodes and 12 arrows or transitions, with tighter limits for particular types. A deployment view gets six nodes and eight paths. A database schema shows at most five tables, with eight columns shown per table. Above the budget, the instruction is to split the picture. Those limits make the tool better suited to explaining a selected part of a system than reproducing a complete inventory.
Structure also has a physical specification. Node dimensions, gaps and padding follow a four-pixel grid. The connector rules require right-angle routes, separate attachment points, and gaps between arrows and their labels. These are instructions an agent must follow, rather than a promise that every model will follow them correctly. They give a reviewer specific defects to look for instead of an open-ended request to improve the picture.
Imports come with an account of what changed
The Mermaid import guide makes the distinction explicit: an import is a redraw. Mermaid supplies components, relationships and a declared direction. Its themes, classes and renderer layout don't carry over. Supported input grammars include flowcharts, sequence diagrams, state diagrams and entity-relationship diagrams. The agent must preserve meaningful edge labels, sequence order and fragments, state guards, and entity cardinality while choosing a new arrangement.
That makes the fidelity ledger part of the deliverable. The same guide requires source and drawn counts, plus every merge, collapse or drop. Its worked example extracts nine nodes, including two containers, then draws six nodes and seven transitions. An unconnected legacy note is removed and recorded. For a developer reviewing a migration diagram, that accounting is useful: a shorter picture can be deliberate, but the missing material must remain visible in the accompanying explanation.
Unsupported syntax has a different outcome. The extractor workflow tells the agent to stop and report errors rather than approximate an unsupported diagram. It also treats labels and URLs as untrusted data, discarding click targets without opening them. A diagram copied from another repository can therefore supply relationships without acquiring authority to tell the agent what to do next.
Local checks cover the file, not the architecture
The packaged self-check script uses Python's standard library and checks accessible SVG structure and single-file safety rules. It looks for a usable title and description, rejects executable attributes, and restricts remote assets. When motion is present, it checks the structural contract and permits only the canonical motion controller. These are useful checks on the generated artifact. They cannot establish whether a service really writes to a database or whether a diagram accurately describes your authorization flow.
The script's own description calls it a subset of the repository checks. An installed agent can run it against a generated HTML file, but passing that check doesn't mean the full contributor validation ran. Our review of Diagram Design covers the setup reality from an earlier sandbox run. Its September 30 results are a dated baseline, rather than verification of today's source or every diagram an agent might produce.
The visual rules include measurable contrast requirements. In the current style guide, regular text must clear 4.5:1 against its actual background, and essential non-text marks must clear 3:1. The light accent is darkened because the original brand orange is too faint on the paper color. A site's palette can supply the starting colors, but matching that palette still leaves a readability test to pass.
The destination changes the drawing
A diagram intended for a slide needs different type sizes from one embedded in documentation. The output specification separates format, canvas size, detail and audience before redrawing begins. Its documentation preset uses a 960-by-600 canvas, while the widescreen slide preset uses 1280 by 720 and larger labels. Resizing the same finished picture cannot substitute for those decisions when its text has to be read from farther away.
On phones, the specification keeps the SVG at a readable width inside a local horizontal scroller. It gives a concrete failure example: a 12-pixel label on a 1280-wide canvas shrinks to 8.4 pixels when pinned at 900 pixels. It also warns that a hidden-overflow ancestor can clip a diagram while a page-overflow check reports nothing wrong. Reviewers need to check whether the entire drawing is reachable, not simply whether the page fits the screen.
Exports have their own limits. The export guide says SVG and PNG output contain the diagram alone, dropping surrounding headers and summary cards. SVG preserves vector text and carries diagram CSS, with identifiers rewritten to prevent collisions when several figures share a page. PNG captures the browser-rendered figure. If your presentation needs the explanatory cards too, exporting the SVG element will leave those behind.
PNG export also requires Python Playwright and a compatible browser already provisioned by the host. The documented procedure stops when that dependency is unavailable. For animated files, it requests a complete static frame before capture. Those details matter if you're considering automation: generating the HTML and obtaining a reliable image are separate operations with different runtime requirements.
Brand matching still involves external requests
The onboarding instructions let the agent extract a palette and typography from a website or local design source, propose a style-guide change, and save a named profile. They require the agent to distinguish an exact public font match from a fallback. A font family declared in CSS is insufficient evidence if it failed to load. That is a sensible constraint for diagrams intended to sit beside a publication's existing typography.
LittleMight's privacy policy says Diagram Design has no server, accounts, analytics or telemetry, and sends the publisher no usage data. Prompts and supplied files still pass through the agent you choose under that provider's rules. Website onboarding fetches the requested site, and generated diagrams load Google Fonts by default. The policy says those font requests expose the viewer's IP address and browser details, without sending the diagram's content.
For offline distribution, the current style guide has a system-font option that omits the remote font link and uses fallback stacks. It warns that fallback faces have different metrics, so label padding must remain intact. That gives you a concrete choice for an internal architecture document: keep the intended web typography, or remove that dependency and check the resulting spacing.
Revisions will decide its usefulness
The README acknowledges that output depends on the model and that the same prompt can produce different layouts. It recommends Mermaid for documentation that lives in Git and changes regularly. HTML and SVG remain inspectable files, but revising a laid-out drawing puts more review work on coordinates and visual relationships than editing a compact declarative source. Diagram Design's strongest case is a figure prepared for publication, with a human checking what it says.
The changelog records recent fixes for imported arrowheads, composite states, clipped mobile output and exported typography. It also lists contrast checks and the offline-font option under unreleased changes, so a checkout of the default branch and an installed package may differ. Watch whether subsequent releases preserve meaning through repeated edits and keep those corrections in the versions people actually install. For your next architecture redraw, compare the fidelity ledger with the source before approving the image. That's where a missing component can become a misleading explanation.