Diagram
← Developer reference

Drawing diagrams that work on Diagram

Which kind of diagram fits what you want to show, what a diagram file can contain, how to lay it out so it reads well, and which rendering tools (Mermaid, SVG, D2, Graphviz, Excalidraw) to reach for.

A diagram on Diagram is one HTML file that a browser renders. You describe what you want in plain language; the agent turns it into that file. This page is what the agent should know to do it well.

The file

  • One self-contained HTML document per diagram, with a <title> (it becomes the diagram's title and link-preview text).
  • Inline everything: CSS in <style>, JS in <script>, drawings as inline <svg>. Scripts, styles, and fonts from a CDN such as jsDelivr or Google Fonts are fine. Files next to it in the repo are not reachable.
  • Under 900KB. Inline SVG is small; embedded bitmaps are not.
  • Sandboxed: no cookies, localStorage, sessionStorage, IndexedDB, or form submission. Clicks, hover, zoom, animation, and links that open a new tab all work. See Security.
  • Fills the frame: the page is shown full-window. Center the drawing, let it scale with the viewport (viewBox on SVG, max-width: 100%), and leave some margin.

Pick the kind of diagram

Decide what the diagram should be before drawing it: the kind that best shows what the person wants to see. Boxes and arrows suit some questions and get in the way of others.

To show Draw
Steps with decisions and branches A flowchart, with every branch drawn, not a single line
Who talks to whom, in order (requests between services) A sequence diagram
The states something moves through (an order, a ticket) A state machine
How a system is put together An architecture diagram (C4, components, cloud)
How data moves through a pipeline A data flow
Tables and how they relate A data model (ER diagram)
When things happened A timeline
Who does what, when, for how long A Gantt chart
Who reports to whom, or anything nested A tree or org chart
Options side by side A comparison table or matrix
Numbers A chart (bar, line, pie)
A place or layout A map or floor plan
The parts of a physical thing An exploded view or cutaway
Ideas around one theme A mind map
A screen or app A wireframe

When two fit, pick the one that answers the question asked; a page can combine them (a timeline above a table, say).

Pick a technique

Want Use Notes
Flowcharts, sequence, state, ER, class, Gantt, timelines, mind maps Mermaid from jsDelivr Fastest to write and edit. See the Mermaid guide.
Architecture and system maps with a custom look Hand-written inline SVG, or HTML boxes with SVG arrows Most control. Good for layered architecture, request flows, data pipelines.
Large auto-laid-out graphs D2 or Graphviz, exported to SVG and pasted inline Layout engines handle dozens of nodes better than hand placement.
Sketchy whiteboard style Excalidraw, exported as SVG Paste the SVG inline.
Charts with data Inline SVG, or a chart library from a CDN Keep the data in the file.
Gantt charts, timelines, comparisons, floor plans HTML and CSS grid, or inline SVG A grid lines things up by week, year, column or room.
Exploded views, cutaways, physical objects Hand-written inline SVG (isometric works well) Draw the parts apart along one axis with leader lines to their labels.

For a polished editorial style, the diagram-design skill is a good reference for agents. It draws more than 40 kinds of diagram, from architecture and sequence to charts, Gantt charts and exploded views, each as one HTML file with inline SVG, and it can take your colors and fonts from your website ("onboard diagram-design to https://yoursite.com"). Install it with npx skills add cathrynlavery/diagram-design. What it draws saves to Diagram like any other diagram.

Make it look like your company

Diagrams read best, and get shared more, when they look like the product they describe. Before drawing, find the brand and reuse it:

  • In a repo, look at the app itself: CSS variables or theme files, the Tailwind config, the fonts it loads, its logo. Use the same colors (a background, text, a muted tone, one or two accents), the same fonts from their CDN, and a light or dark look to match.
  • In a chat, ask once: “What does your product look like? A link to your site, your brand colors, or a screenshot is enough.” If there's nothing to go on, use a clean neutral style.
  • Write it down so every diagram matches: in a repo, diagrams/brand.md with the colors, fonts, and any logo URL. Each diagram still carries its styles inline (it can't load files from the repo), so copy them from there.

Make it readable

  • Say what it's for. A title and a one-line subtitle ("How a checkout request reaches Stripe") at the top.
  • When it has arrows, keep them flowing one way (left to right or top to bottom) and label each with what moves along it (a request, an event, a file). Number steps only when order matters.
  • Group related parts in labeled containers: services in a cluster, the browser vs. the server, your code vs. third parties.
  • Few colors, used for meaning: one accent for the thing the diagram is about, muted tones for the rest, and a small legend if color encodes something.
  • Readable text: 14px or larger, short labels, real names from the codebase (OrderService, orders table).
  • Light and dark: set a background color explicitly, or support both with prefers-color-scheme.
  • Interactive when it helps: hover to show details, click to expand a group. Keep it working without interaction.

Keeping it current

The diagram lives on Diagram. To change it, ask your AI: it edits the saved diagram, the link stays the same, and every version is kept. When the code it describes changes, ask the agent to update the diagram in the same change.