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.
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-diagrams-23description: 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---56# Creating Diagrams78## Use Cases910Architecture docs, workflows, data flows, comparisons, file trees, sequence diagrams, state machines.1112## Operations1314### Format Selection1516| 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 |2122__Key tradeoffs:__2324* ASCII: works everywhere, clear git diffs, but manual layout is tedious25* Mermaid: auto-layout, parseable (`@mermaid-js/parser`), but requires renderer2627### Creating ASCII Diagrams2829Reference `references/ascii-patterns.md` for: box diagrams, flows, file trees, decision branches, sequence diagrams, layered architecture.3031### Creating Mermaid Diagrams3233Reference `references/mermaid-syntax.md` for: flowcharts, sequence diagrams, state diagrams, class diagrams, Gantt charts.3435## CRITICAL3637### Right Edge Alignment3839__All lines in a boxed diagram must end at the same column.__ Ragged right edges look broken.4041__Technique:__42431. Decide width first (e.g., 60 chars)442. Pad with spaces to hit that width453. Avoid deep nesting - prefer flat layouts464. Count characters when unsure4748```49WRONG (ragged right edges):50┌───────────────────────────┐51│ Frontend │52│ ┌──────┐ ┌───────┐ │53│ │ React│ │ Redux │ │54│ └──────┘ └───────┘│55└───────────────────────────┘56 ↑ inner boxes don't reach right edge5758RIGHT (all lines end at same column):59┌──────────────────────────────┐60│ Frontend │61│ ┌──────────┐ ┌──────────┐ │62│ │ React │ │ Redux │ │63│ └──────────┘ └──────────┘ │64└──────────────────────────────┘65```6667## Notes6869* Keep within 80-100 columns for terminal compatibility70* Label every box and arrow71* Prefer clarity over detail72* Follow logical flow: left-to-right or top-to-bottom7374## Appendix7576### Sources7778Synthesized from:7980* [ascii-visualizer](https://github.com/ArieGoldkin/devPrepAi/tree/main/.claude/skills/ascii-visualizer) by ArieGoldkin81* [Art](https://github.com/vdemeester/home/tree/main/dots/.config/claude/skills/Art) by vdemeester
majiayu000