Concept Diagrams
Overview
Generate production-quality SVG diagrams with a unified flat, minimal design
system. Output is a single self-contained HTML file that renders identically in
any modern browser, with automatic light/dark mode.
Scope
Best suited for:
- Physics setups, chemistry mechanisms, math curves, biology
- Physical objects (aircraft, turbines, smartphones, mechanical watches)
- Anatomy, cross-sections, exploded layer views
- Floor plans, architectural conversions
- Narrative journeys (lifecycle of X, process of Y)
- Hub-spoke system integrations (smart city, IoT)
- Educational / textbook-style visuals in any domain
Look elsewhere first for:
- Software/cloud architecture with dark tech aesthetic → use
architecture-diagram
- Hand-drawn whiteboard sketches → use an excalidraw-style tool
Workflow
- Decide on the diagram type (see below)
- Lay out components using the Design System rules
- Write the full HTML page with inline SVG + CSS
- Save as a standalone
.html file via write_file
- User opens it directly in a browser — no server, no dependencies
write_file("diagram.html", "<full HTML with inline SVG + CSS>")
Diagram Types
| Type |
When |
| Process flow |
Sequential steps, lifecycle, pipeline |
| Hub-spoke |
Central system + connected components (IoT, smart city) |
| Exploded layers |
Component breakdown, cross-section |
| Comparison |
Side-by-side, before/after |
| Cycle |
Circular process, feedback loop |
| Hierarchy |
Org chart, taxonomy, tree |
| Timeline |
Chronological events |
Design System
Philosophy
- Flat, minimal, no 3D effects
- Semantic colors: 9 color ramps for different element types
- Sentence-case typography: not Title Case
- Automatic dark mode: CSS
prefers-color-scheme
Color Ramps (light/dark aware)
:root {
/* Primary elements */
--c-primary: #4A90D9;
--c-secondary: #50C878;
--c-accent: #F5A623;
/* Semantic */
--c-input: #7B68EE;
--c-output: #FF6B6B;
--c-process: #4ECDC4;
--c-data: #95E1D3;
--c-control: #C4A7E7;
--c-external: #DDD;
/* Light mode (default) */
--bg: #FAFAFA;
--text: #333;
--border: #E0E0E0;
}
@media (prefers-color-scheme: dark) {
:root {
--bg: #1A1A2E;
--text: #EEE;
--border: #333;
--c-external: #444;
}
}
SVG Structure
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Diagram Title</title>
<style>
body { margin: 0; padding: 40px; background: var(--bg); }
svg { display: block; margin: 0 auto; }
.label { font-family: -apple-system, sans-serif; font-size: 14px; fill: var(--text); }
.title { font-size: 18px; font-weight: 600; }
.box { fill: var(--c-primary); opacity: 0.15; stroke: var(--c-primary); stroke-width: 2; rx: 8; }
.arrow { stroke: var(--text); stroke-width: 2; fill: none; marker-end: url(#arrowhead); }
</style>
</head>
<body>
<svg width="800" height="600" viewBox="0 0 800 600">
<defs>
<marker id="arrowhead" markerWidth="10" markerHeight="7" refX="10" refY="3.5" orient="auto">
<polygon points="0 0, 10 3.5, 0 7" fill="var(--text)"/>
</marker>
</defs>
<!-- Diagram elements here -->
<rect class="box" x="50" y="50" width="200" height="80"/>
<text class="label title" x="150" y="90" text-anchor="middle">Input</text>
<path class="arrow" d="M 250 90 L 350 90"/>
<!-- ... more elements ... -->
</svg>
</body>
</html>
Pitfalls
- Too much detail: keep diagrams minimal. One concept per diagram.
- Inconsistent spacing: use a grid (e.g., 50px increments) for alignment.
- No dark mode: always include
prefers-color-scheme media query.
- Font not embedded: use system fonts (-apple-system, sans-serif) so the
HTML works without external font files.
- SVG overflow: set
viewBox correctly so the diagram isn't clipped.
1---2name: concept-diagrams3description: Minimal SVG diagrams as standalone HTML files.4license: MIT5---67# Concept Diagrams89## Overview1011Generate production-quality SVG diagrams with a unified flat, minimal design12system. Output is a single self-contained HTML file that renders identically in13any modern browser, with automatic light/dark mode.1415## Scope1617**Best suited for:**18- Physics setups, chemistry mechanisms, math curves, biology19- Physical objects (aircraft, turbines, smartphones, mechanical watches)20- Anatomy, cross-sections, exploded layer views21- Floor plans, architectural conversions22- Narrative journeys (lifecycle of X, process of Y)23- Hub-spoke system integrations (smart city, IoT)24- Educational / textbook-style visuals in any domain2526**Look elsewhere first for:**27- Software/cloud architecture with dark tech aesthetic → use28 `architecture-diagram`29- Hand-drawn whiteboard sketches → use an excalidraw-style tool3031## Workflow32331. Decide on the diagram type (see below)342. Lay out components using the Design System rules353. Write the full HTML page with inline SVG + CSS364. Save as a standalone `.html` file via `write_file`375. User opens it directly in a browser — no server, no dependencies3839```40write_file("diagram.html", "<full HTML with inline SVG + CSS>")41```4243## Diagram Types4445| Type | When |46|------|------|47| **Process flow** | Sequential steps, lifecycle, pipeline |48| **Hub-spoke** | Central system + connected components (IoT, smart city) |49| **Exploded layers** | Component breakdown, cross-section |50| **Comparison** | Side-by-side, before/after |51| **Cycle** | Circular process, feedback loop |52| **Hierarchy** | Org chart, taxonomy, tree |53| **Timeline** | Chronological events |5455## Design System5657### Philosophy58- **Flat, minimal, no 3D effects**59- **Semantic colors**: 9 color ramps for different element types60- **Sentence-case typography**: not Title Case61- **Automatic dark mode**: CSS `prefers-color-scheme`6263### Color Ramps (light/dark aware)6465```css66:root {67 /* Primary elements */68 --c-primary: #4A90D9;69 --c-secondary: #50C878;70 --c-accent: #F5A623;7172 /* Semantic */73 --c-input: #7B68EE;74 --c-output: #FF6B6B;75 --c-process: #4ECDC4;76 --c-data: #95E1D3;77 --c-control: #C4A7E7;78 --c-external: #DDD;7980 /* Light mode (default) */81 --bg: #FAFAFA;82 --text: #333;83 --border: #E0E0E0;84}8586@media (prefers-color-scheme: dark) {87 :root {88 --bg: #1A1A2E;89 --text: #EEE;90 --border: #333;91 --c-external: #444;92 }93}94```9596### SVG Structure9798```html99<!DOCTYPE html>100<html>101<head>102<meta charset="utf-8">103<title>Diagram Title</title>104<style>105 body { margin: 0; padding: 40px; background: var(--bg); }106 svg { display: block; margin: 0 auto; }107 .label { font-family: -apple-system, sans-serif; font-size: 14px; fill: var(--text); }108 .title { font-size: 18px; font-weight: 600; }109 .box { fill: var(--c-primary); opacity: 0.15; stroke: var(--c-primary); stroke-width: 2; rx: 8; }110 .arrow { stroke: var(--text); stroke-width: 2; fill: none; marker-end: url(#arrowhead); }111</style>112</head>113<body>114<svg width="800" height="600" viewBox="0 0 800 600">115 <defs>116 <marker id="arrowhead" markerWidth="10" markerHeight="7" refX="10" refY="3.5" orient="auto">117 <polygon points="0 0, 10 3.5, 0 7" fill="var(--text)"/>118 </marker>119 </defs>120 <!-- Diagram elements here -->121 <rect class="box" x="50" y="50" width="200" height="80"/>122 <text class="label title" x="150" y="90" text-anchor="middle">Input</text>123 <path class="arrow" d="M 250 90 L 350 90"/>124 <!-- ... more elements ... -->125</svg>126</body>127</html>128```129130## Pitfalls131132- **Too much detail**: keep diagrams minimal. One concept per diagram.133- **Inconsistent spacing**: use a grid (e.g., 50px increments) for alignment.134- **No dark mode**: always include `prefers-color-scheme` media query.135- **Font not embedded**: use system fonts (-apple-system, sans-serif) so the136 HTML works without external font files.137- **SVG overflow**: set `viewBox` correctly so the diagram isn't clipped.
HezaoHezao