diagram-design

name diagram-design description Create branded architecture, IT current-state, flowchart, sequence, state machine, ER/data model, timeline, swimlane, quadrant, radar/spider, polar chart (polar/radial lollipop), loop/flywheel, nested, tree, org chart, layer stack, Venn, pyramid/funnel, treemap, bar, waterfall, line, Gantt and scatter charts, high-level, process, medallion, data flow, DP integration, DP security matrix, Sankey, fishbone, Wardley map, kanban, user journey, deployment, dependency graph, UML class, story map, or database schema diagrams as standalone HTML/SVG/PNG. Redraw .drawio/.drawio.png/.drawio.svg, Mermaid .mmd, or Excalidraw .excalidraw sources at a chosen size/detail; onboard brand tokens from a website; add semantic patterns, callouts, accessible motion, or sketchy/hand-drawn styling. license MIT metadata {"version":"2.6"} Diagram Design Create visual diagrams as self-contained HTML files with inline SVG and CSS, following an opinionated editorial design system. Forty visual types. Semantic patterns describe behavior independently; type references describe layout. Details load from references/ only when selected. 0. First-time setup — style guide gate Before generating your first diagram in a new project, verify the style guide has been customized. Don't silently ship default-skinned diagrams into a branded project. First check the project root for a .diagram-design marker and resolve it per references/profiles.md . A valid marker whose profile exists selects that file directly and skips this gate; profile: default also skips it. A malformed or missing-profile marker follows the visible failure handling in that reference. Never copy a marker-selected profile over the installed working copy. Open references/style-guide.md and check the default tokens. If they're still the shipped defaults (paper #f5f5f5 , ink #2d3142 , accent #eb6c36 atomic-tangerine), pause and ask the user : "This is your first diagram in this project. The style guide is still at the default (neutral white-smoke + atomic-tangerine). Do you want to customize it to match your brand first? Options: (a) pull from your website URL, (b) extract from an installed skill, (c) extract from a local folder / design-system directory, (d) paste tokens manually, (e) proceed with the default for now, (f) load a saved client profile." Then branch per the matching section of references/onboarding.md ; for (f) follow references/profiles.md . Once the style guide has been customized (or the user explicitly opted for default), skip this gate on subsequent runs. A leading profile header names the copied-in active profile. Without a header, any semantic-role value or typography family differing from shipped defaults means custom-unsaved : skip the gate and offer to save it as a profile. All-default tokens with no marker/header trigger the gate. At the end of every onboarding method, offer to save the result as a named client profile per references/profiles.md . 1. Philosophy The highest-quality move is usually deletion. Applied to schematics: Every node represents a distinct idea. Two nodes that always travel together are one node. Every connection carries information. If the relationship is obvious from layout, remove the line. Coral is editorial, not a flag. 1–2 focal nodes per diagram. Using it on 5 nodes erases the signal. The schematic isn't done when everything is added. It's done when nothing can be removed. Target density: 4/10. Enough to be technically complete. Not so dense it needs a guide. Above 9 nodes, it's probably two diagrams. 2. When to Use Use for any of the 40 visual types (§3) when a reader will learn more from a visual than from prose, a table, or a bulleted list. Don't use for: Quick unicode diagrams → use wiretext . Lists of things → table or bullets. Simple before/after → table. One-shape "diagrams" → just write the sentence. Before drawing, ask: Would the reader learn more from this than from a well-written paragraph? If no, don't draw. 3. Selection: semantic pattern, then visual type When behavior, state, enforcement, or risk carries the meaning, first load references/semantic-patterns.md and choose one primary pattern. Then choose the nearest visual type for layout. If no pattern matches, choose the type directly. Behavioral trigger Semantic pattern → nearest type Fan-in, queue depth, finite capacity, bottleneck Fan-in queue / bottleneck → Data flow Repeated Question / Input / Governance / Output slots across stages Stage framework with semantic slots → Process Conversation or loose input becomes a structured durable artifact Unstructured input → structured artifact → Data flow Two rule traces need pass/fail/skipped/not-reached and first divergence Paired policy-evaluation traces → Flowchart Trust boundaries plus permitted/forbidden ingress or deploy paths Secure paved road → Architecture Controls grouped by where they are enforced Governance / control catalog → Layer stack Defenses compensate for prior gaps and residual risk propagates Compensating security layers → Layer stack Hierarchical, ID-addressable decomposition needing per-block I/O, constraints, and a code link Traceable block decomposition → Tree The pattern owns semantic primitives and its tighter budget; the type owns layout grammar. Use references/animation.md only when motion is requested or materially clarifies ordered change; static remains the default. Visual-type guide (40) If you're showing… Use Reference Components + connections in a system Architecture type-architecture.md Legacy IT landscape grouped by phase/department; documents the before state in modernization proposals IT current-state type-it-state.md Decision logic with branches Flowchart type-flowchart.md Time-ordered messages between actors Sequence type-sequence.md States + transitions + guards State machine type-state.md Entities + fields + relationships ER / data model type-er.md Events positioned in time Timeline type-timeline.md Cross-functional process with handoffs Swimlane type-swimlane.md Two-axis positioning / prioritization Quadrant type-quadrant.md Multiple entities scored across 3–5 quantitative criteria Radar / Spider type-radar.md One quantitative series across cyclic categories; angle=category, radius=magnitude Polar chart type-polar.md Reinforcing cycle / flywheel where the last step feeds the first and a shared hub accumulates state Loop type-loop.md Hierarchy through containment / scope Nested type-nested.md Parent → children relationships Tree type-tree.md Human/agent/team ownership, reporting, routing, escalation Org chart type-org-chart.md Stacked abstraction levels Layer stack type-layers.md Overlap between sets Venn type-venn.md Ranked hierarchy or conversion drop-off Pyramid / funnel type-pyramid.md Quantitative comparison across categories Bar chart type-bar.md A start total bridged to an end total by signed contributions (budget bridge, headcount deltas) Waterfall type-waterfall.md Part-of-whole where the relative sizes are the story Treemap type-treemap.md Continuous trends over time, change between exactly two states (slopegraph), one distribution per series (ridgeline), or rank movement across several snapshots (bump) Line chart type-line.md Tasks and phases on a timeline Gantt type-gantt.md Distribution and correlation between two variables, three with area-sized marks (bubble), or one variable with a dot per item (beeswarm) Scatter plot type-scatter.md End-to-end data stack on a container cluster High-Level type-high-level.md Multi-actor sequential process with data handoffs Process type-process.md Multi-tier data storage with quality levels and access policies Medallion type-medallion.md Role-scoped data flow: who does what at each pipeline step Data flow type-data-flow.md Integration topology of a data platform — sources → core → consumers DP integration type-dp-integration.md Per-role / per-component access permissions matrix DP security matrix type-dp-security-matrix.md A quantity splitting and merging across stages, band width = amount Sankey type-sankey.md Causes of one observed effect, grouped by category (root-cause analysis) Fishbone type-fishbone.md Value chain against evolution — what to build, buy, and what is moving Wardley map type-wardley.md Work-in-progress by state, with WIP limits and blocked items Kanban type-kanban.md What a person does across stages of an experience, and how it feels User journey type-journey.md Where software runs — zones, hosts, artifacts, replicas, ports Deployment type-deployment.md What depends on what, with fan-in and cycles a tree cannot express Dependency graph type-dependency.md Classes with operations, inheritance, composition (other UML routes elsewhere) UML class type-uml-class.md Narrative backbone sliced into releases, with the cut line Story map type-story-map.md Physical tables: SQL types, constraints, indexes, column-level FKs Database schema type-db-schema.md Rules of thumb: If a 3-column table communicates the same thing, pick the table. If two types seem useful, pick the dominant axis; a semantic pattern may add behavior-specific primitives, not a second layout grammar. If you're past the complexity budget (§7), split into an overview + detail. Always load the chosen type reference linked in the guide before drawing. When routed above, also load semantic-patterns.md ; when animation is chosen, load animation.md . Confirm before drawing Before rendering, state the plan in one short message: the chosen visual type (and semantic pattern, if routed), the size preset, and anything the complexity budget (§7) will force out. If the user is reachable, let them redirect before you draw; if not, proceed and note the assumptions beside the deliverable. Skip the pause only when the request already pins type, size, and content exactly. 4. Universal Anti-patterns These mark "AI slop" schematics of any type: Anti-pattern Why it fails Dark mode + cyan/purple glow Looks "technical" without design decisions JetBrains Mono as blanket "dev" font Mono is for technical content — ports, commands, URLs. Names go in Geist sans. Identical boxes for every node Erases hierarchy Legend floating inside the diagram area Collides with nodes Arrow labels with no masking rect Bleeds through the line Vertical writing-mode text on arrows Unreadable 3 equal-width summary cards as default Generic grid — vary widths Shadow on any element Shadows are out. Borders are in. rounded-2xl on boxes Max radius 6–10px or none Coral on every "important" node Coral is 1–2 editorial accents, not a signaling system Reproducing Mermaid's renderer layout Imports automatic spacing and routing instead of making an editorial layout Any breach of the six §6 connector rules Diagonal slants, labels touching their stroke, masks clipped by a later node, overlapping paths, shared attach points, transit behind a non-endpoint box — each is an automatic fail; §6 states them in full Type-specific anti-patterns live in each type reference linked in the guide. 5. Design System The design system is skinnable. All colors, typography, and tokens live in a single source of truth — references/style-guide.md . This file describes semantic roles ( paper , ink , muted , accent , link , …). The default skin is a cool editorial palette (white-smoke paper, jet-black ink, atomic-tangerine accent, blue-slate muted, silver hairlines); to apply your own brand, either edit style-guide.md directly or run the URL-based flow described in references/onboarding.md . When specs below or in type references mention "ink", "accent", "muted", etc., look up the current hex value in style-guide.md . Semantic roles (at a glance) Role Purpose paper , paper-2 Page bg and container bg ink Primary text / stroke muted , soft Secondary text, default arrows, sublabels rule , rule-solid Hairline borders accent , accent-tint 1–2 focal elements per diagram link HTTP/API calls, external arrows Focal rule: accent goes on 1–2 elements max. Everything else is ink / muted / soft . If you're tempted to accent 4 things, you haven't decided what's focal yet. Node type → treatment Type Fill Stroke Focal (1–2 max) accent-tint accent Backend / API / Step white ink Store / State ink @ 0.05 muted External / Cloud ink @ 0.03 ink @ 0.30 Input / User muted @ 0.10 soft Optional / Async ink @ 0.02 ink @ 0.20 dashed 4,3 Security / Boundary accent @ 0.05 accent @ 0.50 dashed 4,4 Typography (summary — full spec in style-guide.md) Title — Instrument Serif, 1.75rem, 400 — H1 only Node name — Geist (sans), 12px, 600 — human-readable labels Sublabel — Geist Mono, 9px — ports, URLs, field types Eyebrow / tag — Geist Mono, 7–8px, uppercase, tracked — type tags, axis labels Arrow label — Geist Mono, 8px — annotation on arrows Editorial aside — Instrument Serif italic , 14px — callouts only CJK labels — Geist and Instrument Serif carry no Hangul or Han; extend the family and keep CJK at 12px+. Rules: Korean , Chinese . Mono is for technical content only — never as a blanket "dev" font, and never JetBrains Mono.