Principle
Diagrams should clarify, not complicate. Start simple, add detail only when needed. A 5-box flowchart beats a 50-node sprawl.
When User Describes a System or Flow
- Identify diagram type — Is this a flow, architecture, sequence, or data model?
- Choose format — Mermaid (default), PlantUML (complex), ASCII (inline), SVG (custom)
- Draft minimal version — Core elements only, no decoration
- Iterate — Add detail based on feedback
Diagram Types
| Type |
Use For |
Format |
| Flowchart |
Processes, decisions, workflows |
Mermaid flowchart |
| Sequence |
API calls, interactions, protocols |
Mermaid sequenceDiagram |
| Architecture |
System components, infrastructure |
Mermaid flowchart or C4 |
| ER/Data model |
Database schemas, relationships |
Mermaid erDiagram |
| Class |
Object structure, inheritance |
Mermaid classDiagram |
| State |
Lifecycles, status transitions |
Mermaid stateDiagram-v2 |
| Timeline |
Project phases, history |
Mermaid timeline |
| Mindmap |
Brainstorming, concept mapping |
Mermaid mindmap |
Output Methods
| Method |
When |
| Mermaid code block |
User can render (docs, GitHub, Notion) |
| Render to PNG/SVG |
User needs image file |
| ASCII inline |
Quick sketch in chat |
| HTML + Mermaid.js |
Interactive viewing |
Rendering Mermaid to Image
# Using mmdc (mermaid-cli)
npx -y @mermaid-js/mermaid-cli mmdc -i diagram.mmd -o diagram.png -b transparent
# Or via browser tool
# Write HTML with Mermaid, screenshot the rendered diagram
Mermaid Quick Reference
Flowchart:
flowchart LR
A[Start] --> B{Decision}
B -->|Yes| C[Action]
B -->|No| D[End]
Sequence:
sequenceDiagram
User->>API: Request
API->>DB: Query
DB-->>API: Result
API-->>User: Response
ER Diagram:
erDiagram
USER ||--o{ ORDER : places
ORDER ||--|{ ITEM : contains
Style Guidelines
- Left-to-right (LR) for processes, top-to-bottom (TB) for hierarchies
- Max 10-15 nodes per diagram, split if larger
- Consistent naming — all caps for systems, lowercase for actions
- Subgraphs to group related components
- Color sparingly — highlight critical paths only
Common Requests
| Request |
Interpret As |
| "Draw my API flow" |
Sequence diagram: client → API → services |
| "Show the architecture" |
Flowchart with subgraphs for components |
| "Database schema" |
ER diagram with relationships |
| "How the auth works" |
Sequence or flowchart depending on complexity |
| "User journey" |
Flowchart with decision points |
Anti-Patterns
- ❌ Too many nodes (split into multiple diagrams)
- ❌ Decorative icons without meaning
- ❌ Mixing abstraction levels (database tables next to business concepts)
- ❌ Arrows in all directions (confuses flow)
- ❌ Labels too long (use short names, add legend if needed)
1---2name: diagram3description: Generate diagrams from descriptions with Mermaid, PlantUML, or ASCII for architecture, flows, sequences, and data models.4---56## Principle78Diagrams should **clarify, not complicate**. Start simple, add detail only when needed. A 5-box flowchart beats a 50-node sprawl.910## When User Describes a System or Flow11121. **Identify diagram type** — Is this a flow, architecture, sequence, or data model?132. **Choose format** — Mermaid (default), PlantUML (complex), ASCII (inline), SVG (custom)143. **Draft minimal version** — Core elements only, no decoration154. **Iterate** — Add detail based on feedback1617## Diagram Types1819| Type | Use For | Format |20|------|---------|--------|21| Flowchart | Processes, decisions, workflows | Mermaid `flowchart` |22| Sequence | API calls, interactions, protocols | Mermaid `sequenceDiagram` |23| Architecture | System components, infrastructure | Mermaid `flowchart` or `C4` |24| ER/Data model | Database schemas, relationships | Mermaid `erDiagram` |25| Class | Object structure, inheritance | Mermaid `classDiagram` |26| State | Lifecycles, status transitions | Mermaid `stateDiagram-v2` |27| Timeline | Project phases, history | Mermaid `timeline` |28| Mindmap | Brainstorming, concept mapping | Mermaid `mindmap` |2930## Output Methods3132| Method | When |33|--------|------|34| Mermaid code block | User can render (docs, GitHub, Notion) |35| Render to PNG/SVG | User needs image file |36| ASCII inline | Quick sketch in chat |37| HTML + Mermaid.js | Interactive viewing |3839### Rendering Mermaid to Image4041```bash42# Using mmdc (mermaid-cli)43npx -y @mermaid-js/mermaid-cli mmdc -i diagram.mmd -o diagram.png -b transparent4445# Or via browser tool46# Write HTML with Mermaid, screenshot the rendered diagram47```4849## Mermaid Quick Reference5051**Flowchart:**52```mermaid53flowchart LR54 A[Start] --> B{Decision}55 B -->|Yes| C[Action]56 B -->|No| D[End]57```5859**Sequence:**60```mermaid61sequenceDiagram62 User->>API: Request63 API->>DB: Query64 DB-->>API: Result65 API-->>User: Response66```6768**ER Diagram:**69```mermaid70erDiagram71 USER ||--o{ ORDER : places72 ORDER ||--|{ ITEM : contains73```7475## Style Guidelines7677- **Left-to-right (LR)** for processes, **top-to-bottom (TB)** for hierarchies78- **Max 10-15 nodes** per diagram, split if larger79- **Consistent naming** — all caps for systems, lowercase for actions80- **Subgraphs** to group related components81- **Color sparingly** — highlight critical paths only8283## Common Requests8485| Request | Interpret As |86|---------|--------------|87| "Draw my API flow" | Sequence diagram: client → API → services |88| "Show the architecture" | Flowchart with subgraphs for components |89| "Database schema" | ER diagram with relationships |90| "How the auth works" | Sequence or flowchart depending on complexity |91| "User journey" | Flowchart with decision points |9293## Anti-Patterns9495- ❌ Too many nodes (split into multiple diagrams)96- ❌ Decorative icons without meaning97- ❌ Mixing abstraction levels (database tables next to business concepts)98- ❌ Arrows in all directions (confuses flow)99- ❌ Labels too long (use short names, add legend if needed)
dvcrn