Drawing diagrams that work on Diagram

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 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.

For a polished, consistent house style for architecture and flow diagrams, the diagram-design skill is a good reference for agents.

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.
• Flow in one direction, usually left to right or top to bottom. Number the steps if order matters.
• Label every arrow with what moves along it (a request, an event, a file), not just that something connects.
• 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's source is the HTML file in the repo's diagrams/ folder. To change a diagram, edit that file and push it again; 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.