Diagram Creator
Generate stunning, self-contained HTML diagrams with professional typography, smooth animations, and an infinite canvas you can pan and zoom like Miro. Output is always a single .html file that opens directly in any browser — zero dependencies. Supports 5 themes and 8 topology layouts.
Input Handling
Accept any of these inputs and auto-process them:
| Input type | How to handle |
|---|---|
| Topic/description | "Docker networking", "OAuth 2.0 flow" — use directly |
| Markdown (.md,.mdx) | Extract structure from headings, lists, tables, relationships |
| JSON / YAML (.json,.yaml,.yml,.jsonl) | Parse structure — keys become nodes, nesting becomes layers |
| Code files (.py,.ts,.js,.go,.rs,.java,.rb,.php,.swift,.kt,.c,.cpp,.cs,.scala, etc.) | Extract classes, functions, imports, inheritance — diagram the architecture |
| Config / Infra (.toml,.ini,.env,.tf,.hcl, Dockerfile, docker-compose.yml, Makefile, nginx.conf) | Map services, variables, dependencies, infrastructure |
| API specs (.openapi.yaml,.swagger.json,.graphql,.proto) | Extract endpoints, types, service relationships |
| Database schemas (.sql,.prisma,.dbml) | Map tables, columns, foreign keys, relationships |
| CI/CD pipelines (.github/workflows/*.yml,.gitlab-ci.yml, Jenkinsfile) | Visualize pipeline stages and deployment flows |
| Data files (.csv,.tsv) | Identify columns as entities, rows as relationships |
| Microsoft Office (.xlsx,.xls,.docx,.doc,.pptx,.ppt) | Extract tables, headings, slide structure, org charts, SmartArt |
| Package manifests (package.json, requirements.txt, Cargo.toml, go.mod, pom.xml) | Map dependency trees |
| Existing diagrams (.drawio,.puml,.mermaid) | Read spec and re-render with this design system |
| PDF / Docs (.pdf,.txt,.rst,.adoc) | Read content, extract core structure |
| Notebooks (.ipynb) | Extract code cells, data flow, library dependencies |
If it's a file, this skill can diagram it. For formats not listed, read the content and extract whatever structure exists.
When receiving a file path, read the file, detect the extension, and intelligently extract what matters for the diagram. Don't ask the user to reformat — figure it out.
If the input is genuinely ambiguous (no clear structure to extract), ask clarifying questions before proceeding. See "Pre-generation Questions" below.
Pre-generation Questions
Always ask these questions before generating, unless the answer is completely obvious from the input. Ask one question at a time — wait for the user's answer before moving to the next. Present every question as a numbered list so the user can simply reply with a number.
Skip a question ONLY when the answer is unambiguous — e.g., "diagram of Docker bridge networking" makes topology (nested) and detail level (medium) obvious. When in doubt, ask.
Question flow (one at a time, in this order):
- What to visualize? (skip only if input is already specific) Present 2-3 interpretations of the input as numbered options, plus an "Other" option. Tailor the options to what the user actually asked — don't use generic placeholders.
What do you want to visualize? 1) [interpretation A] 2) [interpretation B] 3) Other — describe below → Reply with the number: - Layout? (skip if only one topology realistically fits — choose automatically in Step 0) Only list the 2-3 topologies that could realistically fit, not all 8. Adapt options based on the previous answer.
Layout? 1) Left-to-right — sequential flow 2) Timeline — vertical step sequence → Reply with the number: - Detail level?
Detail level? 1) High-level — main entities only, understand in 5 seconds 2) Medium — entities with key info, labeled connections (default) 3) Detailed — full technical breakdown, all metadata → Reply with the number (default: 2): - Theme?
Theme? 1) Dark (default) 2) Light 3) Corporate 4) Neon 5) Minimal → Reply with the number (default: 1):
Once you have all the answers, proceed autonomously through all remaining steps without further questions.
Step 0 — Choose the Topology
Pick exactly one topology based on what fits the content best:
| Topology | When to use | Examples |
|---|---|---|
nested | Hierarchical containment, layers wrapping layers | Docker networking, K8s pods, OSI model, VPC subnets |
left-to-right | Sequential flow from A to Z | OAuth flow, CI/CD pipeline, user journey, request lifecycle |
hub-and-spoke | Central node connected to N surrounding nodes | API gateway, microservices, load balancer, team structure |
timeline | Ordered vertical sequence of events/steps | Deploy pipeline, project roadmap, historical events |
grid | Matrix/table comparison, feature grids | Feature comparison, skill map, competitive landscape |
tree | Hierarchical branching, org charts | Org chart, file tree, decision tree, taxonomy |
funnel | Progressive narrowing, conversion stages | Sales funnel, data pipeline, filtering process |
comparison | Side-by-side 2-3 options | Product vs product, technology choices, before/after |
Step 1 — Plan the Content
Before writing HTML, plan these elements in your thinking:
- Topic: one sentence describing what the diagram shows
- Detail level: choose one of three levels. Default to medium unless context suggests otherwise:
- High-level — Only the main entities of the system. Aggregate similar entities into single boxes (e.g., "Backend Services" instead of listing 10 microservices). No metadata in boxes — just name and role. Minimal connection labels. No callouts, badges, or notes. The viewer should understand the structure in 5 seconds. - Medium (default) — The entities needed to understand how the system works, without sub-components. Each box gets 1-2 metadata relevant to the domain (infra: port and protocol; org chart: role and team; flow: input/output of each step). Label connections where it adds clarity. Callouts only for non-obvious key concepts. The viewer who knows the domain should understand the diagram without further explanation. - Detailed — Everything: sub-components, configurations, technical notes. All relevant metadata per box (ports, protocols, versions, env vars, states). Badges, explanatory callouts, side notes. Goal: complete technical reference for people working on the system. How to choose: (1) If the user specifies a level explicitly, use it. (2) If context clarifies intent — a presentation implies high-level, a technical doc for the team implies detailed — match it. (3) Otherwise default to medium. (4) If the chosen level produces too many elements for the topology, aggregate entities into groups rather than changing level or topology.
- Layers/Steps: each level with name, description, and accent color. For left-to-right topology, count the steps and apply the step count scaling table from
references/topology-layouts.mdto set step max-width and arrow width accordingly - Nodes: each box with emoji, name, and metadata density matching the detail level above
- Connections: what each arrow represents (label density matches detail level)
- Special Components: callout boxes, badges, info panels (reduce or skip for high-level)
- Legend Entries: one per accent color used
Step 1.5 — Choose the Theme
If the user specifies a theme, use it. Otherwise default to dark.
| Theme | Best for | Keywords |
|---|---|---|
dark (default) | Technical diagrams, dev docs | "dark", default |
light | Presentations, documentation sites | "light", "chiaro", "presentation" |
corporate | Business plans, pitch decks | "corporate", "business", "professional" |
neon | Creative, gaming, social media | "neon", "cyberpunk", "vibrant" |
minimal | Clean docs, technical specs | "minimal", "clean", "simple" |
See references/themes.md for the exact :root values and overrides per theme.
Step 2 — Build the HTML
Read the reference files for detailed CSS/layout specifications:
references/typography-and-colors.md— fonts, palette, backgroundreferences/themes.md— theme system with 5 color schemesreferences/topology-layouts.md— layout rules for each of the 8 topologiesreferences/components.md— node cards, badges, callouts, legend, animationsreferences/safety-rules.md— mandatory layout constraints for all topologiesreferences/canvas.md— infinite canvas with pan & zoom (Miro-like navigation)
Follow every rule in those references exactly. The design system is battle-tested — don't improvise fonts, colors, or layout patterns.
Always include the infinite canvas system from references/canvas.md. This lets users pan (click+drag) and zoom (scroll wheel) the diagram freely, like a whiteboard.
Step 3 — Output
- Single
.htmlfile, all CSS in<style>, all JS in<script> - No external dependencies except Google Fonts via
@import - No CSS frameworks, no JS libraries (vanilla JS for hub-and-spoke coordinates and canvas pan/zoom)
- Valid HTML5 with
<!DOCTYPE html>as first line - Must render correctly opened directly in a browser
- Responsive down to 360px viewport width
Save as diagram-[topic-slug].html in the current working directory. Open it in the browser with open (macOS) or xdg-open (Linux). Tell the user where it was saved.