Creating Diagrams
Use Cases
Architecture docs, workflows, data flows, comparisons, file trees, sequence diagrams, state machines.
Operations
Format Selection
| Format |
Best For |
Renders In |
| ASCII |
AI-maintained docs, terminals, code comments, git diffs |
Everywhere |
| Mermaid |
Complex auto-layout, dependency trees, sequence diagrams |
Markdown renderers |
| Tables |
Comparisons, feature matrices |
Markdown |
Key tradeoffs:
- ASCII: works everywhere, clear git diffs, but manual layout is tedious
- Mermaid: auto-layout, parseable (
@mermaid-js/parser), but requires renderer
Creating ASCII Diagrams
Reference references/ascii-patterns.md for: box diagrams, flows, file trees, decision branches, sequence diagrams, layered architecture.
Creating Mermaid Diagrams
Reference references/mermaid-syntax.md for: flowcharts, sequence diagrams, state diagrams, class diagrams, Gantt charts.
Adding Mermaid Live Links
Add one-click preview URLs above mermaid code blocks.
# Pipe diagram to script (run from project with pako installed)
echo 'sequenceDiagram
A->>B: Hello' | node scripts/mermaid-url.js
Add URL on line before code fence for one-click preview.
CRITICAL
Right Edge Alignment
All lines in a boxed diagram must end at the same column. Ragged right edges look broken.
Technique:
- Decide width first (e.g., 60 chars)
- Pad with spaces to hit that width
- Avoid deep nesting - prefer flat layouts
- Count characters when unsure
WRONG (ragged right edges):
┌───────────────────────────┐
│ Frontend │
│ ┌──────┐ ┌───────┐ │
│ │ React│ │ Redux │ │
│ └──────┘ └───────┘│
└───────────────────────────┘
↑ inner boxes don't reach right edge
RIGHT (all lines end at same column):
┌──────────────────────────────┐
│ Frontend │
│ ┌──────────┐ ┌──────────┐ │
│ │ React │ │ Redux │ │
│ └──────────┘ └──────────┘ │
└──────────────────────────────┘
Notes
- Keep within 80-100 columns for terminal compatibility
- Label every box and arrow
- Prefer clarity over detail
- Follow logical flow: left-to-right or top-to-bottom
Appendix
Sources
Synthesized from:
1---2name: creating-diagrams3description: This skill should be used when the user asks to "create a diagram", "draw a flowchart", "visualize the architecture", "show me how X works", "add a diagram to the docs", "create an ASCII diagram", "make a Mermaid chart", or needs visual representation of systems, workflows, data flows, or comparisons. Supports both ASCII (for AI-maintained docs, terminals, code comments) and Mermaid (for rendered markdown).4---5
6# Creating Diagrams
7
8## Use Cases
9
10Architecture docs, workflows, data flows, comparisons, file trees, sequence diagrams, state machines.
11
12## Operations
13
14### Format Selection
15
16| Format | Best For | Renders In |
17| ----------- | -------------------------------------------------------- | ------------------ |
18| __ASCII__ | AI-maintained docs, terminals, code comments, git diffs | Everywhere |
19| __Mermaid__ | Complex auto-layout, dependency trees, sequence diagrams | Markdown renderers |
20| __Tables__ | Comparisons, feature matrices | Markdown |
21
22__Key tradeoffs:__
23
24* ASCII: works everywhere, clear git diffs, but manual layout is tedious
25* Mermaid: auto-layout, parseable (`@mermaid-js/parser`), but requires renderer
26
27### Creating ASCII Diagrams
28
29Reference `references/ascii-patterns.md` for: box diagrams, flows, file trees, decision branches, sequence diagrams, layered architecture.
30
31### Creating Mermaid Diagrams
32
33Reference `references/mermaid-syntax.md` for: flowcharts, sequence diagrams, state diagrams, class diagrams, Gantt charts.
34
35### Adding Mermaid Live Links
36
37Add one-click preview URLs above mermaid code blocks.
38
39```bash
40# Pipe diagram to script (run from project with pako installed)
41echo 'sequenceDiagram
42 A->>B: Hello' | node scripts/mermaid-url.js
43```
44
45Add URL on line before code fence for one-click preview.
46
47## CRITICAL
48
49### Right Edge Alignment
50
51__All lines in a boxed diagram must end at the same column.__ Ragged right edges look broken.
52
53__Technique:__
54
551. Decide width first (e.g., 60 chars)
562. Pad with spaces to hit that width
573. Avoid deep nesting - prefer flat layouts
584. Count characters when unsure
59
60```
61WRONG (ragged right edges):
62┌───────────────────────────┐
63│ Frontend │
64│ ┌──────┐ ┌───────┐ │
65│ │ React│ │ Redux │ │
66│ └──────┘ └───────┘│
67└───────────────────────────┘
68 ↑ inner boxes don't reach right edge
69
70RIGHT (all lines end at same column):
71┌──────────────────────────────┐
72│ Frontend │
73│ ┌──────────┐ ┌──────────┐ │
74│ │ React │ │ Redux │ │
75│ └──────────┘ └──────────┘ │
76└──────────────────────────────┘
77```
78
79## Notes
80
81* Keep within 80-100 columns for terminal compatibility
82* Label every box and arrow
83* Prefer clarity over detail
84* Follow logical flow: left-to-right or top-to-bottom
85
86## Appendix
87
88### Sources
89
90Synthesized from:
91
92* [ascii-visualizer](https://github.com/ArieGoldkin/devPrepAi/tree/main/.claude/skills/ascii-visualizer) by ArieGoldkin
93* [Art](https://github.com/vdemeester/home/tree/main/dots/.config/claude/skills/Art) by vdemeester
majiayu000