Let AI Draw the Architecture Diagram—Don't Rush to Open Figma

When laying out an architecture diagram in Figma, the time usually goes into two things: alignment and restyling.

Recently, an open-source Skill handed these two steps to AI tools. The project is called Diagram Design, and the author is Cathryn Lavery. Once installed, tools that support Agent Skills, such as Claude Code, Codex, and Cursor, can generate diagrams directly from natural language and output a self-contained HTML file containing inline SVG. Double-click to open it in a browser, and you can also export SVG or PNG.

An Agent Skill can be understood as a work manual installed for AI tools, containing rules, templates, and scripts. The question it answers is very concrete: do the diagrams AI draws actually look presentable? For most AI-generated diagrams, the problem isn't structure; it's taste. Rounded boxes, shadows, rainbow colors—at a glance, it's a template.

Diagram Design's approach is to write taste as constraints: one accent color, one or two focal points, 1px hairlines, no shadows, a maximum corner radius of 10px, and all coordinates and spacing on a 4px grid. It uses only three typefaces: Instrument Serif for headings and italic annotations, Geist for node names, and Geist Mono for technical sublabels such as ports, URLs, and field types. In the README, the author wrote a rather blunt line: 'The highest-quality move is usually deletion.' Every node has to earn its place.

It ships with 45 chart types, including sequence diagrams, flowcharts, architecture diagrams, Gantt charts, quadrant charts, ER diagrams, swimlane diagrams, and org charts. Each type has three static variants: light minimal, dark minimal, and full editorial style. There is no build step, no JavaScript, and no dependency on external images. By default, it pulls three typefaces from Google Fonts—the only network request; after switching to system fonts, it can run fully offline.

Brand adaptation is another convenience. Tell the AI, 'onboard diagram-design to https://yoursite.com', and it will scrape the homepage, extract the primary color, body text color, secondary color, accent color, and font stack, map them to semantic tokens such as paper, ink, muted, accent, and link, first provide a diff, and after confirmation write them into style-guide.md. It also checks WCAG AA contrast and provides a fidelity receipt listing sampled URLs, color roles, font families, and sources. For multiple clients, you can save named profiles; put a .diagram-design marker in the project to switch between them.

Import is also supported. Files from draw.io, Mermaid, Excalidraw, and PlantUML can be thrown at it to be redrawn. The key here is 'redraw': components, relationships, groups, and direction are preserved; source coordinates, source colors, source fonts, and hand-dragged diagonals are not. It offers four knobs: format chooses html, svg, png; size chooses document embed, 16:9 slide, social image, A4 print; detail chooses faithful, balanced, simplified; audience chooses engineer, mixed, executive. At the end of each import, there is a fidelity ledger telling you which nodes were merged, collapsed, or dropped.

The drawbacks are spelled out just as plainly. Output quality depends on the model you use; the same prompt can produce different layouts twice. The output is not an editable source format, there is no text that can go into a pull request for diffing, and there is no canvas for you to drag boxes around. The repository's own words: if docs live in Git and change every sprint, Mermaid is still a better fit; Diagram Design is for that one diagram you're about to publish.

Someone in the replies reminded people to check Chinese fonts before exporting, otherwise characters can easily show up as squares. That's a practical reminder. What it saves is alignment and color matching; it does not replace Figma's collaborative source files. For multi-person annotations, component libraries, and design-system handoff, you still need another trip.

Install command:

npx skills add cathrynlavery/diagram-design

Repository: https://github.com/cathrynlavery/diagram-design

Online gallery: https://cathrynlavery.github.io/diagram-design/

For complex diagrams, which type would you draw with it first? Architecture diagrams, sequence diagrams, or that roadmap you have to re-layout for every presentation?