Concept Diagrams Skill: Flat Minimal SVG Diagrams as HTML

Concept Diagrams is a skill for Hermes Agent that turns ideas into clean, flat SVG diagrams delivered as a single self-contained HTML file. You would reach for it when you need an educational, textbook-style visual: a physics setup, a chemistry mechanism, a floor plan, or a hub-spoke system map. It is a general-purpose fallback when no specialized diagram skill fits, and it produces output that looks consistent and professional in any modern browser, with automatic light and dark mode.

What it does

The skill gives you a design system and a set of templates so you can generate SVG diagrams that share a unified flat, minimal aesthetic. Instead of hand-coding every style, you apply CSS classes that the template provides. The result is a standalone .html file the user can open directly, with no server and no dependencies.

The design system enforces flat colors, no gradients or shadows, consistent typography, and dark-mode readiness. You get nine color ramps, each with seven stops, and a set of rules for how to use them. The skill also includes a validation checklist so you can catch common mistakes before you hand the file over.

You can produce many diagram types: flowcharts, structural containment views, API endpoint maps, microservice topologies, data flows, physical objects, infrastructure integrations, and UI mockups. For the more complex types, the skill ships reference files with ready-made CSS classes and shape primitives.

Before you start

This is an optional skill, so you install it on demand. The skill path is optional-skills/creative/concept-diagrams, version 0.1.0, authored by v1k22 and ported into hermes-agent. It is MIT licensed and works on linux, macos, and windows.

You will need the template file, which you load with skill_view. The template embeds the full CSS design system, including the c-* color classes, text classes, light/dark variables, and arrow marker styles. Your SVG relies on those classes being present on the hosting page, so you must always use the template as the wrapper.

There are no special permissions or platform-specific setup steps. The only real prerequisite is that you understand the design rules before you start laying out a diagram, because the output quality depends on following them.

Workflow

The skill follows a straightforward five-step process:

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, pasting your SVG where the template says ``.
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.

If the user wants a browsable gallery of multiple diagrams, you can optionally use a local preview server, described later.

Load the HTML template with this command:

skill_view(name="concept-diagrams", file_path="templates/template.html")

Design System

Philosophy

The design system is built on four principles:

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

There are 9 color ramps, each with 7 stops. You put the class name on a `` or shape element, and 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 `` MUST carry a class (t, ts, or th). No unclassed text.
dominant-baseline="central" on all text inside boxes.
text-anchor="middle" for centered text in boxes.

Width estimation (approx):

14px weight 500: ~8px per character
12px weight 400: ~6.5px per character
Always verify: box_width >= (char_count × px_per_char) + 48 (24px padding each side)

Spacing & Layout

ViewBox: viewBox="0 0 680 H" where H = content height + 40px buffer.
Safe area: x=40 to x=640, y=40 to y=(H-40).
Between boxes: 60px minimum gap.
Inside boxes: 24px horizontal padding, 12px vertical padding.
Arrowhead gap: 10px between arrowhead and box edge.
Single-line box: 44px height.
Two-line box: 56px height, 18px between title and subtitle baselines.
Container padding: 20px minimum inside every container.
Max nesting: 2-3 levels deep. Deeper gets unreadable at 680px width.

Stroke & Shape

Stroke width: 0.5px on all node borders. Not 1px, not 2px.
Rect rounding: rx="8" for nodes, rx="12" for inner containers, rx="16" to rx="20" for outer containers.
Connector paths: MUST have fill="none". SVG defaults to fill: black otherwise.

Arrow Marker

Include this `` block at the start of every SVG:

<defs>
  <marker id="arrow" viewBox="0 0 10 10" refX="8" refY="5"
          markerWidth="6" markerHeight="6" orient="auto-start-reverse">
    <path d="M2 1L8 5L2 9" fill="none" stroke="context-stroke"
          stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
  </marker>
</defs>

Use marker-end="url(#arrow)" on lines. The arrowhead inherits the line color via context-stroke.

CSS Classes (Provided by the Template)

The template page provides:

Text: .t, .ts, .th
Neutral: .box, .arr, .leader, .node
Color ramps: .c-purple, .c-teal, .c-coral, .c-pink, .c-gray, .c-blue, .c-green, .c-amber, .c-red (all with automatic light/dark mode)

You do not need to redefine these, just apply them in your SVG. The template file contains the full CSS definitions.

SVG Boilerplate

Every SVG inside the template page starts with this exact structure:

<svg width="100%" viewBox="0 0 680 {HEIGHT}" xmlns="http://www.w3.org/2000/svg">
  <defs>
    <marker id="arrow" viewBox="0 0 10 10" refX="8" refY="5"
            markerWidth="6" markerHeight="6" orient="auto-start-reverse">
      <path d="M2 1L8 5L2 9" fill="none" stroke="context-stroke"
            stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
    </marker>
  </defs>

  <!-- Diagram content here -->

</svg>

Replace {HEIGHT} with the actual computed height (last element bottom + 40px).

Node Patterns

Single-line node (44px):

<g class="node c-blue">
  <rect x="100" y="20" width="180" height="44" rx="8" stroke-width="0.5"/>
  <text class="th" x="190" y="42" text-anchor="middle" dominant-baseline="central">Service name</text>
</g>

Two-line node (56px):

<g class="node c-teal">
  <rect x="100" y="20" width="200" height="56" rx="8" stroke-width="0.5"/>
  <text class="th" x="200" y="38" text-anchor="middle" dominant-baseline="central">Service name</text>
  <text class="ts" x="200" y="56" text-anchor="middle" dominant-baseline="central">Short description</text>
</g>

Connector (no label):

<line x1="200" y1="76" x2="200" y2="120" class="arr" marker-end="url(#arrow)"/>

Container (dashed or solid):

<g class="c-purple">
  <rect x="40" y="92" width="600" height="300" rx="16" stroke-width="0.5"/>
  <text class="th" x="66" y="116">Container label</text>
  <text class="ts" x="66" y="134">Subtitle info</text>
</g>

Diagram Types

Choose the layout that fits the subject:

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, for curved bodies, for tapered shapes, / for cylindrical parts, nested `` 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 `` has class t, ts, or th.
Every `` inside a box has dominant-baseline="central".
Every connector or 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 or shape elements, never on connectors.
Arrow `` 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 port
cd .diagrams && python -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:, 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:

File	Type	Demonstrates
`hospital-emergency-department-flow.md`	Flowchart	Priority routing with semantic colors
`feature-film-production-pipeline.md`	Flowchart	Phased workflow, horizontal sub-flows
`automated-password-reset-flow.md`	Flowchart	Auth flow with error branches
`autonomous-llm-research-agent-flow.md`	Flowchart	Loop-back arrows, decision branches
`place-order-uml-sequence.md`	Sequence	UML sequence diagram style
`commercial-aircraft-structure.md`	Physical	Paths, polygons, ellipses for realistic shapes
`wind-turbine-structure.md`	Physical cross-section	Underground/above-ground separation, color coding
`smartphone-layer-anatomy.md`	Exploded view	Alternating left/right labels, layered components
`apartment-floor-plan-conversion.md`	Floor plan	Walls, doors, proposed changes in dotted red
`banana-journey-tree-to-smoothie.md`	Narrative journey	Winding path, progressive state changes
`cpu-ooo-microarchitecture.md`	Hardware pipeline	Fan-out, memory hierarchy sidebar
`sn2-reaction-mechanism.md`	Chemistry	Molecules, curved arrows, energy profile
`smart-city-infrastructure.md`	Hub-spoke	Semantic line styles per system
`electricity-grid-flow.md`	Multi-stage flow	Voltage hierarchy, flow markers
`ml-benchmark-grouped-bar-chart.md`	Chart	Grouped bars, dual axis

Load any example with:

skill_view(name="concept-diagrams", file_path="examples/<filename>")

Quick Reference: What to Use When

User says	Diagram type	Suggested colors
"show the pipeline"	Flowchart	gray start/end, purple steps, red errors, teal deploy
"draw the data flow"	Data pipeline (left-right)	gray sources, purple processing, teal sinks
"visualize the system"	Structural (containment)	purple container, teal services, coral data
"map the endpoints"	API tree	purple root, one ramp per resource group
"show the services"	Microservice topology	gray ingress, teal services, purple bus, coral workers
"draw the aircraft/vehicle"	Physical	paths, polygons, ellipses for realistic shapes
"smart city / IoT"	Hub-spoke integration	semantic line styles per subsystem
"show the dashboard"	UI mockup	dark screen, chart colors: teal, purple, coral for alerts
"power grid / electricity"	Multi-stage flow	voltage hierarchy (HV/MV/LV line weights)
"wind turbine / turbine"	Physical cross-section	foundation + tower cutaway + nacelle color-coded
"journey of X / lifecycle"	Narrative journey	winding path, progressive state changes
"layers of X / exploded"	Exploded layer view	vertical stack, alternating labels
"CPU / pipeline"	Hardware pipeline	vertical stages, fan-out to execution ports
"floor plan / apartment"	Floor plan	walls, doors, proposed changes in dotted red
"reaction mechanism"	Chemistry	atoms, bonds, curved arrows, transition state, energy profile

When not to use it

The source explicitly points you elsewhere for certain subjects. If the user wants dedicated software or cloud infrastructure architecture with a dark tech aesthetic, consider architecture-diagram if it is available. For hand-drawn whiteboard sketches, consider excalidraw if available. For animated explainers or video output, look for an animation skill.

If a more specialized skill exists for the subject, prefer that. This skill is the general-purpose fallback, and its clean educational aesthetic is a reasonable default for almost any subject, but it is not the best fit for those three cases.

Limits and gotchas

Several rules in the design system are easy to miss and will degrade the output if you ignore them.

Stroke width is strict. Use 0.5px on all node borders. A 1px or 2px border breaks the flat, minimal look.
Connector paths must have fill="none". SVG defaults to fill: black, which will show up as a solid block if you forget.
Color classes go on shapes, not connectors. Putting a c-* class on a `` connector will not work as expected.
Text must be classed. Every `` needs t, ts, or th. Unclassed text will not get the right size or weight.
Max nesting is 2-3 levels. Deeper containers become unreadable at the fixed 680px width.
The arrow marker block must be present in every SVG. Without it, marker-end="url(#arrow)" will not render an arrowhead.
The preview server must bind to 127.0.0.1 only. Never use 0.0.0.0, and never hard-code a port. The server is optional and opt-in; prefer the standalone HTML file.

What pairs with this

The source lists two related skills: architecture-diagram and excalidraw. Use architecture-diagram when you need a dark tech aesthetic for software or cloud infrastructure, and excalidraw when the user wants a hand-drawn whiteboard feel. For everything else, Concept Diagrams is the default choice.

Concept Diagrams: Flat Minimal SVG Diagrams as HTML