Why use it: this is the main use of the tool. No shell command creates diagrams — choosing the type, choosing the content and writing the SVG is done by agent does, based on SKILL.md and the files references/type-*.md.
What this file produces: a file .html self-contained (inline SVG + inline CSS), openable with file://, no build needed, no server needed.
This entire file is text typed in chat. Don't paste it into the terminal. The shell part is in
04and06.
1. Minimal prompt
Make me an architecture diagram of my app: frontend, backend, database, Redis cache.
I need a quadrant showing Q2 projects by impact vs effort.
Give me a sequence of a bearer call with token refresh on 401.
The agent will: choose the type → load references/type-<loại>.md accordingly → confirm with you before drawing → build the HTML → save the file.
The confirmation step is mandatory per SKILL.md §3 ("Confirm before drawing"). If the agent just draws without asking, it is skipping the skill.
2. Choose the type — 39 options, choose by what you are showing
SKILL.md §3 does not ask "what diagram do you want" but "what are you showing". Condensed table by group:
Structure & systems
| Showing… | Type |
|---|---|
| Components + connections within a system | Architecture |
| Legacy IT landscape grouped by phase/department (the before state of the modernization proposal) | IT current-state |
| Where the software runs — zone, host, artifact, replica, port | Deployment |
| What depends on what, with fan-in and cycles that a tree cannot express | Dependency graph |
| Hierarchy by containment / scope | Nested |
| Parent → child relationship | Tree |
| Ownership/reporting/routing/escalation of people or agents | Org chart |
| Stacked layers of abstraction | Layer stack |
| Class + operation + inheritance + composition | UML class |
Flow & time
| Showing… | Type |
|---|---|
| Decision logic with branches | Flowchart |
| Messages between actors in chronological order | Sequence |
| States + transitions + guards | State machine |
| Cross-department process with handoffs | Swimlane |
| Events placed on a timeline | Timeline |
| Tasks and phases on a timeline | Gantt |
| Reinforcing cycle (flywheel), the last step feeds the first | Loop |
| Sequential multi-actor process with data handoffs | Process |
| User journey across stages + emotions | User journey |
| Story backbone cut by release, with cut lines | Story map |
| Work by status, with WIP limits and blocked items | Kanban |
Data
| Currently showing… | Type |
|---|---|
| Entities + fields + relationships | ER / data model |
| Physical tables: SQL types, constraints, indexes, column-level FKs | Database schema |
| End-to-end data stack on a container cluster | High-Level |
| Multi-tier storage with quality levels and access policies | Medallion |
| Data flow by role: who does what at each pipeline step | Data flow |
| Data platform integration topology: sources → core → consumption | DP integration |
| Permission matrix by role / component | DP security matrix |
Quantitative
| Currently showing… | Type |
|---|---|
| Quantitative comparison across categories | Bar chart |
| Continuous trend over time; change between exactly 2 states (slopegraph); one distribution per series (ridgeline); rank shifts across multiple points (bump) | Line chart |
| Distribution and correlation of 2 variables; 3 variables with marks sized by area (bubble); 1 variable with one dot per item (beeswarm) | Scatter plot |
| Two-axis positioning / prioritization | Quadrant |
| Multiple entities scored on 3–5 quantitative criteria | Radar / Spider |
| One quantitative series across cyclical categories; angle=category, radius=magnitude | Polar chart |
| Part-of-whole where relative size is the story | Treemap |
| A quantity splitting and merging across stages, band width = amount | Sankey |
| Ranked hierarchy or conversion drop-off rates | Pyramid / funnel |
| Overlap between sets | Venn |
| Causes of an effect, grouped by category (root cause analysis) | Fishbone |
| Value chain compared against evolution — what to build, what to buy, what is shifting | Wardley map |
Three rule-of-thumb rules, verbatim SKILL.md §3:
- If a 3-column table can say the same thing, choose the table.
- Two types are both reasonable → choose by dominant axis. A semantic pattern may add primitives, not add a second layout grammar.
- Exceeds the complexity budget (§7) → split into overview + detail.
3. Semantic pattern — choose behavior first, shape after
When new behavior is what matters, the skill chooses semantic pattern first, then chooses the visual type. Seven patterns are routed (references/semantic-patterns.md):
- Fan-in queue and bottleneck
- Repeated stage cell
- Unstructured input transformation
- Paired policy trace
- Security paved road
- Governance catalog
- Compensating security layer
Each pattern declares: trigger, primitive, budget, anti-pattern, static fallback, and the nearest visual type.
Example prompt:
Show the ingestion queue with its bottleneck — use the fan-in semantic pattern.
Draw the paved road for our deploy path, with the compensating controls layered on.
4. Motion — OFF by default
references/animation.md defines 4 modes: none (default), reveal, step, loop. Hard rules:
- Output is usually static and script-free. Motion must be explicitly requested.
- Every file with motion must have a complete first static frame and deterministic timing.
prefers-reduced-motion→ show the full static frame, hide/disable controls.- Motion HTML uses only the controller reviewed in
template-motion.html, verbatim. Arbitrary inline scripts, remote assets, CSS@import, and executable HTML attributes are all rejected (linterlint-skin.pyhard-blocks — see06). - ADR 0003:
revealis the only allowed autoplay.
Prompt:
Make it animated with the reveal mode, respecting reduced motion.
Self-contained preview example: skills/diagram-design/assets/example-policy-trace-animated.html.
5. Four dials — say it and get it right immediately
These four "dials" apply to both new and imported diagrams (references/output-spec.md):
| Dial | Value | Default |
|---|---|---|
| format | html, svg, png, html+png |
html |
| size | doc-inline, doc-wide, slide-16x9, slide-4x3, social-og, social-square, print-a4-landscape, print-letter-landscape, fit |
doc-inline |
| detail | faithful (≤24 nodes, split into zones), balanced (≤12), simplified (≤7) |
balanced |
| audience | engineer, mixed, executive |
mixed |
audience governs word choice, not the number of elements — this is where it is very often misunderstood.
Actual viewBox table (output-spec.md §2):
| Preset | viewBox | Ratio | PNG @2 | Used for |
|---|---|---|---|---|
doc-inline |
0 0 960 600 |
8:5 | 1920×1200 | Blog, README, docs |
doc-wide |
0 0 1280 720 |
16:9 | 2560×1440 | Docs full-width, Confluence/Notion |
slide-16x9 |
0 0 1280 720 |
16:9 | 2560×1440 | Slide deck |
slide-4x3 |
0 0 1024 768 |
4:3 | 2048×1536 | Old deck |
social-og |
0 0 1200 632 |
~1.9:1 | 2400×1264 | Link preview X/LinkedIn — leave 64px margin on all sides, the link-card will crop |
social-square |
0 0 1080 1080 |
1:1 | 2160×2160 | Post feed |
print-a4-landscape |
0 0 1120 792 |
~1.41:1 | @3 → 3360×2376 | Handout in |
print-letter-landscape |
0 0 1056 816 |
~1.29:1 | @3 → 3168×2448 | Handout in (US) |
fit |
inferred from the content | any | @2 | Vector handoff |
Type:
Same diagram at slide-16x9, simplified, executive audience.
6. Start from a template instead of from zero
These three templates are copied via shell but filled via chat — so keep them here for continuity:
cp skills/diagram-design/assets/template.html my-diagram.html # light tối giản
cp skills/diagram-design/assets/template-full.html my-diagram.html # editorial + summary card
cp skills/diagram-design/assets/template-motion.html my-diagram.html # có motion, accessible
Then type in chat: "fill my-diagram.html with an architecture diagram of …".
7. What the skill will REFUSE to do (and why)
SKILL.md §4 "Universal Anti-patterns" and §9 "Pre-Output Checklist (Taste Gate)" run before writing the file. One-sentence philosophy, verbatim: "The highest-quality move is usually deletion."
Three things guaranteed in every output:
- Accessible SVG:
role="img",aria-labelledbyresolvable,<title>/<desc>is the first child. IDs are prefixed by diagram and by variant, so multiple inline SVGs on one page don't compete for an accessible name. Decorative icons are hidden from assistive tech. - One file, no external dependencies: no remote assets other than the approved Google Fonts stylesheet, no external scripts other than the canonical motion controller, no executable attributes.
- 4px grid and a complexity budget per type.
If you force it beyond the budget, it will propose splitting overview + detail rather than cramming.
8. Done with this step when
- There is one file
.htmlopened withfile://displays correctly. - Run
python3 <skill-dir>/scripts/self_check.py file.htmlworksOK(see06). - The colors in the file are your brand, not atomic-tangerine.
Next: already have a diagram from draw.io/Mermaid, then go to 04/05; want to export PNG/SVG, then 05; want to lock quality with CI, then 06.