Generate flat, minimal light/dark-aware SVG diagrams as standalone HTML files, using a unified educational visual language with 9 semantic color ramps, sentence-case typography, and automatic dark mode. Best suited for educational and non-software visuals — physics setups, chemistry mechanisms, math curves, physical objects (aircraft, turbines, smartphones, mechanical watches), anatomy, floor plans, cross-sections, narrative journeys (lifecycle of X, process of Y), hub-spoke system integrations (smart city, IoT), and exploded layer views. If a more specialized skill exists for the subject (dedicated software/cloud architecture, hand-drawn sketches, animated explainers, etc.), prefer that — otherwise this skill can also serve as a general-purpose SVG diagram fallback with a clean educational look. Ships with 15 example diagrams.
Generate flat, minimal light/dark-aware SVG diagrams as standalone HTML files, using a unified educational visual language with 9 semantic color ramps, sentence-case typography, and automatic dark mode. Best suited for educational and non-software visuals — physics setups, chemistry mechanisms, math curves, physical objects (aircraft, turbines, smartphones, mechanical watches), anatomy, floor plans, cross-sections, narrative journeys (lifecycle of X, process of Y), hub-spoke system integrations (smart city, IoT), and exploded layer views. If a more specialized skill exists for the subject (dedicated software/cloud architecture, hand-drawn sketches, animated explainers, etc.), prefer that — otherwise this skill can also serve as a general-purpose SVG diagram fallback with a clean educational look. Ships with 15 example diagrams.
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
Hub-spoke system integrations (smart city, IoT networks, electricity grids)
Educational / textbook-style visuals in any domain
Quantitative charts (grouped bars, energy profiles)
Look elsewhere first for:
Dedicated software / cloud infrastructure architecture with a dark tech aesthetic (consider architecture-diagram if available)
Hand-drawn whiteboard sketches (consider excalidraw if available)
Animated explainers or video output (consider an animation skill)
If a more specialized skill is available for the subject, prefer that. If none fits, this skill can serve as a general-purpose SVG diagram fallback — the output will carry the clean educational aesthetic described below, which is a reasonable default for almost any subject.
Workflow
Decide on the diagram type (see Diagram Types below).
Lay out components using the Design System rules.
Write the full HTML page using templates/template.html as the wrapper — paste your SVG where the template says <!-- PASTE SVG HERE -->.
Save as a standalone .html file (for example ~/my-diagram.html or ./my-diagram.html).
User opens it directly in a browser — no server, no dependencies.
Optional: if the user wants a browsable gallery of multiple diagrams, see "Local Preview Server" at the bottom.
The template embeds the full CSS design system (c-* color classes, text classes, light/dark variables, arrow marker styles). The SVG you generate relies on these classes being present on the hosting page.
Design System
Philosophy
Flat: no gradients, drop shadows, blur, glow, or neon effects.
Minimal: show the essential. No decorative icons inside boxes.
Consistent: same colors, spacing, typography, and stroke widths across every diagram.
Dark-mode ready: all colors auto-adapt via CSS classes — no per-mode SVG.
Color Palette
9 color ramps, each with 7 stops. Put the class name on a <g> or shape element; the template CSS handles both modes.
Class
50 (lightest)
100
200
400
600
800
900 (darkest)
c-purple
#EEEDFE
#CECBF6
#AFA9EC
#7F77DD
#534AB7
#3C3489
#26215C
c-teal
#E1F5EE
#9FE1CB
#5DCAA5
#1D9E75
#0F6E56
#085041
#04342C
c-coral
#FAECE7
#F5C4B3
#F0997B
#D85A30
#993C1D
#712B13
#4A1B0C
c-pink
#FBEAF0
#F4C0D1
#ED93B1
#D4537E
#993556
#72243E
#4B1528
c-gray
#F1EFE8
#D3D1C7
#B4B2A9
#888780
#5F5E5A
#444441
#2C2C2A
c-blue
#E6F1FB
#B5D4F4
#85B7EB
#378ADD
#185FA5
#0C447C
#042C53
c-green
#EAF3DE
#C0DD97
#97C459
#639922
#3B6D11
#27500A
#173404
c-amber
#FAEEDA
#FAC775
#EF9F27
#BA7517
#854F0B
#633806
#412402
c-red
#FCEBEB
#F7C1C1
#F09595
#E24B4A
#A32D2D
#791F1F
#501313
Color Assignment Rules
Color encodes meaning, not sequence. Never cycle through colors like a rainbow.
Group nodes by category — all nodes of the same type share one color.
Use c-gray for neutral/structural nodes (start, end, generic steps, users).
Use 2-3 colors per diagram, not 6+.
Prefer c-purple, c-teal, c-coral, c-pink for general categories.
Reserve c-blue, c-green, c-amber, c-red for semantic meaning (info, success, warning, error).
Light/dark stop mapping (handled by the template CSS — just use the class):
Light mode: 50 fill + 600 stroke + 800 title / 600 subtitle
Dark mode: 800 fill + 200 stroke + 100 title / 200 subtitle
Typography
Only two font sizes. No exceptions.
Class
Size
Weight
Use
th
14px
500
Node titles, region labels
ts
12px
400
Subtitles, descriptions, arrow labels
t
14px
400
General text
Sentence case always. Never Title Case, never ALL CAPS.
Every <text> MUST carry a class (t, ts, or th). No unclassed text.
dominant-baseline="central" on all text inside boxes.
Flowchart — CI/CD pipelines, request lifecycles, approval workflows, data processing. Single-direction flow (top-down or left-right). Max 4-5 nodes per row.
Structural / Containment — Cloud infrastructure nesting, system architecture with layers. Large outer containers with inner regions. Dashed rects for logical groupings.
API / Endpoint Map — REST routes, GraphQL schemas. Tree from root, branching to resource groups, each containing endpoint nodes.
Microservice Topology — Service mesh, event-driven systems. Services as nodes, arrows for communication patterns, message queues between.
Data Flow — ETL pipelines, streaming architectures. Left-to-right flow from sources through processing to sinks.
Physical / Structural — Vehicles, buildings, hardware, anatomy. Use shapes that match the physical form — <path> for curved bodies, <polygon> for tapered shapes, <ellipse>/<circle> for cylindrical parts, nested <rect> for compartments. See references/physical-shape-cookbook.md.
Infrastructure / Systems Integration — Smart cities, IoT networks, multi-domain systems. Hub-spoke layout with central platform connecting subsystems. Semantic line styles (.data-line, .power-line, .water-pipe, .road). See references/infrastructure-patterns.md.
UI / Dashboard Mockups — Admin panels, monitoring dashboards. Screen frame with nested chart/gauge/indicator elements. See references/dashboard-patterns.md.
For physical, infrastructure, and dashboard diagrams, load the matching reference file before generating — each one provides ready-made CSS classes and shape primitives.
Validation Checklist
Before finalizing any SVG, verify ALL of the following:
Every <text> has class t, ts, or th.
Every <text> inside a box has dominant-baseline="central".
Every connector <path> or <line> used as arrow has fill="none".
No arrow line crosses through an unrelated box.
box_width >= (longest_label_chars × 8) + 48 for 14px text.
box_width >= (longest_label_chars × 6.5) + 48 for 12px text.
ViewBox height = bottom-most element + 40px.
All content stays within x=40 to x=640.
Color classes (c-*) are on <g> or shape elements, never on <path> connectors.
Arrow <defs> block is present.
No gradients, shadows, blur, or glow effects.
Stroke width is 0.5px on all node borders.
Output & Preview
Default: standalone HTML file
Write a single .html file the user can open directly. No server, no dependencies, works offline. Pattern:
# 1. Load the template
template = skill_view("concept-diagrams", "templates/template.html")
# 2. Fill in title, subtitle, and paste your SVG
html = template.replace(
"<!-- DIAGRAM TITLE HERE -->", "SN2 reaction mechanism"
).replace(
"<!-- OPTIONAL SUBTITLE HERE -->", "Bimolecular nucleophilic substitution"
).replace(
"<!-- PASTE SVG HERE -->", svg_content
)
# 3. Write to a user-chosen path (or ./ by default)
write_file("./sn2-mechanism.html", html)
Tell the user how to open it:
# macOS
open ./sn2-mechanism.html
# Linux
xdg-open ./sn2-mechanism.html
Optional: local preview server (multi-diagram gallery)
Only use this when the user explicitly wants a browsable gallery of multiple diagrams.
Rules:
Bind to 127.0.0.1 only. Never 0.0.0.0. Exposing diagrams on all network interfaces is a security hazard on shared networks.
Pick a free port (do NOT hard-code one) and tell the user the chosen URL.
The server is optional and opt-in — prefer the standalone HTML file first.
Recommended pattern (lets the OS pick a free ephemeral port):
# Put each diagram in its own folder under .diagrams/mkdir -p .diagrams/sn2-mechanism
# ...write .diagrams/sn2-mechanism/index.html...# Serve on loopback only, free portcd .diagrams && python3 -c "
import http.server, socketserver
with socketserver.TCPServer(('127.0.0.1', 0), http.server.SimpleHTTPRequestHandler) as s:
print(f'Serving at http://127.0.0.1:{s.server_address[1]}/')
s.serve_forever()
" &
If the user insists on a fixed port, use 127.0.0.1:<port> — still never 0.0.0.0. Document how to stop the server (kill %1 or pkill -f "http.server").
Examples Reference
The examples/ directory ships 15 complete, tested diagrams. Browse them for working patterns before writing a new diagram of a similar type:
