diagram-design: Editorial Diagrams for Claude Code and Other AI Coding Hosts

The problem diagram-design solves in AI-assisted documentation

When you ask Claude Code or another AI coding host to produce a diagram, the default output is either a Mermaid block or a collection of generic rounded boxes. Mermaid renders inconsistently across platforms, its default styling is hard to adjust, and the result rarely matches the visual standard of the surrounding content. The author of diagram-design describes the friction precisely in the README: every time a diagram was needed, the result looked nothing like the rest of the site, requiring either a 30-minute session in Figma or skipping the diagram entirely.

diagram-design solves this by giving AI coding hosts a skill with opinionated defaults. Every output is a self-contained HTML file with inline SVG. There is no build step, no JavaScript dependency, and no external image to load. Opening the file in a browser is the entire workflow. The repository ships three static variants for each layout type: minimal light, minimal dark, and full-editorial, so the output fits either a light or dark context without post-processing.

The type library: what is covered in version 2.5.10

The original release shipped with layout types covering architecture, IT current-state, flowchart, sequence, state machine, ER and data model, timeline, swimlane, quadrant, radar and spider, loop and flywheel, nested, tree, org chart, layer stack, Venn, pyramid and funnel, bar chart, treemap, line chart, Gantt, scatter plot, high-level, process, medallion, data flow, DP integration, and DP security matrix.

Version 2.0 added the Loop type with a shared-memory hub and write-back dashed lines. Version 2.3 added semantic system patterns and optional accessible motion. Version 2.5.10 added ten more layout grammars: Sankey, fishbone, Wardley map, kanban, user journey, deployment, dependency graph, UML class, story map, and database schema. The semantic pattern system, introduced in 2.3, allows a queue, policy trace, or trust boundary to be described separately from layout so an existing type can be reused without expanding the type count.

The skill can also redraw existing diagrams. The README states it handles draw.io, Mermaid, and Excalidraw sources, converting them to the chosen format, size, and detail level. That conversion path is the most practical entry point for teams migrating from Mermaid.

Loading diagram-design and generating a first diagram

The repository is structured as an agent skill. The top-level layout includes `skills/`, `commands/`, `prompts/`, and integration directories for each supported host: `.claude-plugin/` for Claude Code, `.codex-plugin/` for Codex, and `.factory-plugin/` for Factory Droid. The README lists Claude Code, Codex, Factory Droid, Pi, and Agent Skills-compatible hosts as supported targets.

To use the skill, clone the repository and point your AI coding host at the appropriate integration directory. The README notes compatibility with Claude Code, Codex, Factory Droid, Pi, and other Agent Skills-compatible hosts. There is no package to install and no npm or pip command to run. The skill files in the `skills/` directory are what the AI host reads to understand how to generate a diagram.

To see what the output looks like before generating anything, open any file in the `docs/screenshots/` directory directly in a browser. Each screenshot shows the rendered output for its layout type in the light, dark, and full-editorial variants. The README confirms: "Open any of them directly in a browser. There is no build step, JavaScript, or external image dependency."

The design constraints behind every output

The README documents the design philosophy explicitly. The guiding principle is deletion: every node in a diagram must earn its place. The accent color is reserved for the one or two elements the reader should look at first. The target density is 4 out of 10, meaning most of the space is deliberately empty.

This is a specific design opinion, not a default. The system does not try to fit all the information you supply; it forces selection. For a developer writing documentation, this means the skill will produce a diagram that is legible at a glance rather than comprehensive. If the goal is to show every component of a system, the output will need iteration because the skill's constraints will push back against completeness in favour of clarity.

The README also states there are no shadows and no generic rounded boxes. This is a reaction to the default Mermaid and Figma outputs that appear in most AI-generated documentation. The editorial quality claim in the README is backed by that constraint: every type ships with a consistent visual grammar rather than a collection of shape templates.

What diagram-design does not handle

diagram-design produces static HTML files. The output does not update when data changes, cannot be embedded with live bindings into a dashboard, and does not export to PNG or PDF without a screenshot. For teams who need diagrams that refresh from a database or API, this is the wrong tool.

The skill also requires an AI coding host to generate diagrams. A non-technical collaborator cannot open the repository, point to a layout type, and produce a diagram without going through Claude Code or another supported host. There is no web interface, no drag-and-drop editor, and no form for entering diagram data. That means diagram-design does not replace tools like Miro or Lucidchart for cross-functional teams where some members do not use AI coding tools.

The optional motion introduced in version 2.3 is for ordered explanations only. The README specifies that static output remains the default; motion is not available for all layout types and is not a general animation system.

diagram-design versus Mermaid in a Claude Code workflow

Mermaid is the default diagram output for most AI coding assistants because it is text-based and easy to generate. Its output is predictable for simple flowcharts and sequence diagrams, and GitHub renders it natively in Markdown files. Those are real advantages.

The trade-offs become visible at the edges of Mermaid's type coverage. Wardley maps, Sankey diagrams, medallion architectures, and DP security matrices are not in Mermaid's type set. diagram-design covers all of them as of version 2.5.10. The visual output is also more controlled: the three-variant system (minimal light, minimal dark, full-editorial) gives consistent results across rendering contexts, whereas Mermaid's rendering depends on the host platform's theme settings.

The cost is that diagram-design outputs an HTML file, not an inline Mermaid block. GitHub will not render it in a README. For documentation that lives in a GitHub repository and is read on github.com, Mermaid is the more practical choice. For documentation published on a website, exported as a PDF, or embedded in a Gradio or Streamlit app, the HTML output of diagram-design is easier to control.

Editorial conclusion

diagram-design is the right tool for developers who generate documentation or explanatory content inside Claude Code, Codex, or Factory Droid and want diagrams that are visually consistent and immediately viewable in a browser without a build step. It is not the right tool for teams who need interactive diagrams with live data bindings, export to PNG or PDF, or a GUI for non-technical collaborators to edit. The repository's last push was on 2026-09-27, and the MIT licence places no restriction on commercial use.

Frequently asked questions

Official sources

1. Official README
2. Project repository