| name | diagram |
| type | skill |
| category | instruction |
| description | Creating diagrams in any style — Mermaid flowcharts (structured, code-based) or Excalidraw (hand-drawn, organic). Use style parameter to select. |
| triggers | ["create flowchart","mermaid diagram","process flow","draw diagram","mind map","visual diagram","diagram"] |
| modifies_files | true |
| needs_task | true |
| mode | execution |
| domain | ["design"] |
| allowed-tools | Read,Write,Edit,Skill |
| version | 1.0.0 |
| permalink | skills-diagram-skill |
| title | Diagram Design Skill |
Diagram Design Skill
Taxonomy note: This skill provides domain expertise (HOW) for creating diagrams. See [[aops-core/skills/remember/references/TAXONOMY.md]] for the skill/workflow distinction.
Purpose: Create diagrams that communicate clearly. Choose the right style for the job.
Style Selection
Invoke with a style argument:
diagram(style="mermaid", ...) — structured, code-based Mermaid flowcharts for process flows, decision trees, system diagrams
diagram(style="excalidraw", ...) — hand-drawn, organic Excalidraw diagrams for mind maps, concept maps, informal architecture sketches
Quick heuristic: Use mermaid when the diagram lives in documentation and needs version control. Use excalidraw when the diagram is for presentations, exploration, or visual communication where feel matters.
Style: mermaid
Purpose: Create Mermaid flowcharts that are clear, readable, and visually attractive.
Key principle: One message per chart. Hierarchy and chunking. Obvious flow. Distinct shapes for distinct semantics.
When to Use Mermaid
- Creating flowcharts for documentation
- Designing process flows, decision trees, or system diagrams
- Documenting execution flows or workflows
- Any task requiring code-based structured diagrams
Universal Chart Craft
Define One Message Per Chart
- Write a one-line purpose before starting ("This chart shows how a session moves from prompt to cleanup")
- Remove anything that doesn't serve that message
- Use separate charts for deep sub-processes
Use Hierarchy and Chunking
- Group related steps into visual blocks (subgraphs: "INIT", "PROMPT", "HYDRATE")
- Keep each block under 6-9 nodes
- If it grows, split to a new chart or link out
Make the Flow Obvious
- Use consistent direction (top-down or left-right)
- Minimize backward arrows and edge crossings
- Put the "happy path" on a straight spine; move exceptions/loops to the side
Use Distinct Shapes for Distinct Semantics
| Shape | Mermaid Syntax | Use For |
|---|
| Rectangle | [text] | Process steps |
| Diamond | {text} | Decisions |
| Rounded | ([text]) | Start/End |
| Parallelogram | [/text/] | Data/IO |
| Stadium | ([text]) | Terminals |
Write Tight, Scannable Labels
- Start with a verb ("Invoke skill", "Verify criteria", "HALT + ask user")
- Aim for 3-9 words
- Split long text across
<br/> lines or move detail to notes/legends
Color and Styling
Maintain visual hierarchy and accessibility through deliberate color choices and consistent typography.
See [[references/color-and-styling]] for palettes, accessibility guidelines, and typography rules.
Layout Strategy: Horizontal Space First
Default assumption: Charts are too tall. Optimize for horizontal spread - most users' screens are wider than tall.
Choose Direction Based on Content
| Content Type | Direction | When to Use | Result |
|---|
| Linear process (≤8 steps) | LR | Simple pipelines, single thread | 1 tall row, many columns (BEST) |
| Branching/decisions | TD | Multiple branches, complex logic | Wider at branch points |
| Parallel workflows | LR with direction TB subgraphs | Phases left-to-right, steps top-down | Compact horizontal grouping |
| Complex systems (>15) | LR + ELK layout | Systems with cross-links, multi-layer | Optimal automatic distribution |
PRINCIPLE: Prefer LR layout for 80% of use cases. It naturally spreads horizontally, matching screen dimensions.
Use ELK for Complex Diagrams
For diagrams with many nodes (>15) or cross-links, ELK layout produces dramatically better results:
---
config:
layout: elk
elk:
mergeEdges: true
nodePlacementStrategy: SIMPLE
---
Mixed-Direction Subgraphs
Place phases horizontally, let steps flow vertically within:
flowchart LR
subgraph PHASE1["Phase 1"]
direction TB
A1[Step 1] --> A2[Step 2]
end
subgraph PHASE2["Phase 2"]
direction TB
B1[Step 1] --> B2[Step 2]
end
PHASE1 --> PHASE2
Critical: Link between subgraphs, not between internal nodes. Internal-to-external links force direction inheritance.
Mermaid-Specific Techniques
Master advanced layout tricks, initialization blocks, and professional styling.
See [[references/mermaid-techniques]] for spacing configurations, multi-layer alignment, and semantic styling.
Quality and Anti-Patterns
Ensure your charts meet high standards and avoid common Mermaid pitfalls.
See [[references/quality-and-anti-patterns]] for a final quality checklist and a list of common layout, visual, and structural sins.
Phase-Based Organization (Recommended for Complex Flows)
For flows with many steps (10+ nodes), organize into numbered phases rather than one long chain.
flowchart TB
subgraph INIT["① INITIALIZATION"]
direction TB
S0([Start]) --> S1[Load Config]
S1 --> S2[Validate]
end
subgraph EXEC["② EXECUTION"]
direction TB
E1[Process] --> E2{Check}
E2 -->|OK| E3[Continue]
E2 -->|Fail| E1
end
subgraph END["③ CLEANUP"]
direction TB
C1[Save] --> C2([End])
end
INIT --> EXEC --> END
%% Side panels for auxiliary systems
subgraph AUX["⚡ AUXILIARY"]
A1[Helper 1]
A2[Helper 2]
end
E1 -.-> A1
C1 -.-> A2
style INIT fill:#ecfdf5,stroke:#059669,stroke-width:2px
style EXEC fill:#fefce8,stroke:#ca8a04,stroke-width:2px
style END fill:#f5f5f5,stroke:#737373,stroke-width:2px
style AUX fill:#fef2f2,stroke:#ef4444,stroke-width:1px,stroke-dasharray: 5 5
Key principles:
- Numbered phase labels (① ② ③) - Creates visual hierarchy and reading order
- Phase subgraphs link to each other -
INIT --> EXEC --> END keeps main flow clean
- Auxiliary systems in dashed side panels - Hooks, agents, external services
- Minimal cross-connections - Only essential interactions, always dashed
- Color-coded phases - Distinct hues per phase (green → yellow → gray for start → process → end)
Mermaid Templates and Examples
See [[references/templates-and-examples.md]] for complete templates including:
- Horizontal process flow (simple linear)
- Multi-phase workflow (phases with internal steps)
- Complex system flow (hook pipelines with ELK layout)
Style: excalidraw
Purpose: Create hand-drawn, organic diagrams that communicate clearly and feel human.
Key principle: Rigid, corporate diagrams fail to engage. Sloppy, hand-drawn aesthetics with spatial mind-map layouts capture attention and convey meaning effectively.
Special Note: Task Visualization
For task visualization specifically, use the automated task_viz.py script instead of this skill:
uv run python skills/tasks/scripts/task_viz.py $ACA_DATA current-tasks.excalidraw
The script generates a complete force-directed layout of goals, projects, and tasks. Only invoke this diagram skill with style=excalidraw AFTER the script runs if manual refinement or customization is needed.
Aesthetic Defaults (CRITICAL)
Always use these settings for the hand-drawn feel:
| Property | Value | Why |
|---|
roughness | 2 | Maximum sketchiness - embrace the hand-drawn aesthetic |
fontFamily | 1 (Virgil/xkcd script) | Handwritten font, NOT Helvetica |
strokeStyle | "solid" | But with high roughness looks hand-drawn |
fillStyle | "hachure" | Sketchy hatching, not solid fills |
Arrow style:
- Use curved arrows with multiple points (click-click-click, not drag)
- Arrows must route around unrelated boxes, never through them
- Bind arrows to shapes (
startBinding, endBinding) so they adapt when boxes move
Layout style:
- NO rigid alignment - don't align everything on vertical/horizontal axes
- Radial/clustered positioning - mind map in all directions, not top-to-bottom
- Embrace asymmetry - "randomness dressed up as creativity"
- Use zoom for hierarchy - big things BIG (use Excalidraw's unlimited canvas), children progressively smaller
Core Visual Design Principles
1. Visual Hierarchy
Identical content looks completely different based on presentation. Position and style choices are critical.
Create hierarchy through:
- Size contrast: Titles (XL) > Subtitles (L) > Body (M) > Labels (S)
- Color contrast: Darker = more important, lighter = supporting
- Spatial position: Top/center = primary focus
- Grouping: Related elements clustered together
- Weight variation: Stroke width signals importance
Anti-pattern: Everything the same size/color/weight = visual chaos
Anti-pattern: Big blocks of text in boxes. Keep labels SHORT (1-5 words). Don't overload the user's view.
Mind Mapping Design Principles
For mind maps and concept maps, apply four fundamental design principles: Proximity (group related elements), Alignment (consistent positioning), Contrast (hierarchy through visual differences), and Repetition (unified patterns).
Key guidelines: Use keywords over paragraphs, keep labels concise (1-5 words), visual over textual.
See [[references/mind-mapping-principles.md]] for complete principles and examples.
2. The Two-Phase Design Process
Phase 1: Structure (ignore aesthetics)
- Map all components and relationships
- Focus purely on accuracy and completeness
- Don't worry about positioning or visual appeal
- Challenge assumptions about connections and flow
Phase 2: Visual Refinement (maintain structure)
- Reposition elements for clarity and flow
- Apply consistent styling
- Create visual rhythm and balance
- Optimize whitespace and alignment
Why this works: Ensures diagrams are both technically correct AND visually appealing.
3. Whitespace is a Design Element
Whitespace (negative space) is not "empty"—it's a powerful tool for:
Macro whitespace (between major sections):
- Separates conceptual groups
- Creates breathing room
- Guides eye flow through the diagram
- Establishes rhythm and pacing
Micro whitespace (within groups):
- Spacing between text lines
- Padding around elements
- Gap between connected items
- Distance between labels and shapes
Rule of thumb: If it feels crowded, it IS crowded. Add more space than you think you need.
Technical Elements
Colors: User's preferred muted terminal theme (see [[references/theme-colors.md]]) - muted gold, soft greens, blues, on WHITE backgrounds (NOT dark). Maintain 4.5:1 contrast ratio for accessibility.
Typography: XL (40-48px) titles, L (24-32px) headers, M (16-20px) body, S (12-14px) labels
Shapes: Rectangles (most versatile), circles (start/end/actors), diamonds (decisions), ellipses (organic feel for mind maps)
Arrows: Thin (1-2px) default, medium (3-4px) emphasis, must bind to shapes, click-click-click for multi-point. Curved arrows for organic/mind-map layouts. Directional arrows free up positioning - children can be placed anywhere around parent (not just below) to avoid overlap.
Icons: Material Symbols (recommended) or built-in libraries. Recolor to theme, use sparingly. See [[references/icon-integration.md]].
Layout: Prefer organic, spatial, mind-map layouts over rigid hierarchies. Spread elements to prevent arrow overlap - arrows are directional, so children can be positioned anywhere around parent (360° freedom). Grid snapping for precision, radial/clustered positioning for mind maps.
Grouping: Always bind text to containers using containerId property (programmatic) or group manually (select both → Cmd/Ctrl+G). Text should auto-size to container width. This ensures text moves WITH its box. See [[references/text-container-pattern.md]] for JSON binding pattern.
CRITICAL - Arrow Binding: Arrows MUST use startBinding and endBinding to anchor to boxes. This ensures arrows adapt when boxes are moved. Never create floating arrows.
See [[references/technical-details.md]] for complete specifications on colors, typography, shapes, arrows, layout, layering, and fill patterns. See [[references/theme-colors.md]] for user's preferred color palette. See [[references/text-container-pattern.md]] for text-in-container binding.
Process: Creating a Professional Excalidraw Diagram
Step 1: Analyze & Plan
Before opening Excalidraw:
- What's the purpose? (explain concept, show flow, document architecture)
- Who's the audience? (technical experts, stakeholders, general public)
- What's the key message? (main takeaway)
- What level of detail? (high-level vs. comprehensive)
Step 2: Content Structure
In Excalidraw (ignore aesthetics):
- List all components/concepts
- Map all relationships
- Identify hierarchy levels
- Verify accuracy and completeness
- Get feedback if possible
Step 3: Visual Design
Now make it beautiful:
-
Establish visual hierarchy
- Size elements by importance
- Choose color scheme (2-4 colors max)
- Set typography scale
-
Create spatial organization
- Position for flow direction
- Group related elements
- Add generous whitespace
- Align everything obsessively
-
Apply consistent styling
- Same colors for same meanings
- Same shapes for same types
- Same arrow styles for same relationships
- Same spacing patterns throughout
-
Refine and polish
- Check alignment (select all → align)
- Verify contrast and readability
- Remove visual clutter
- Test at different zoom levels
Step 4: Export with Quality
Export settings:
- Use WHITE background (default, always preferred)
- Enable background (unless transparency needed)
- Use 2x or 3x scale for high resolution
- Choose "Embed scene" to preserve editability
- Export formally (don't screenshot)
Excalidraw Common Patterns & Templates
See [[references/common-patterns.md]] for diagram templates: System Architecture, Process Flow, Concept/Mind Map, Graph/Network, and Comparison Matrix patterns.
Component Libraries & Resources
Built-in libraries (~/.claude/skills/diagram/libraries/): 6 curated libraries available - awesome-icons, data-processing, data-viz, hearts, stick-figures, stick-figures-collaboration.
Material Symbols (RECOMMENDED for new icons): Professional icon set from Google Fonts. Import SVGs, recolor to theme palette. See [[references/icon-integration.md]] for complete workflow.
Quick start: Load via Excalidraw library panel → "Load library from file" → Select from ~/.claude/skills/diagram/libraries/
Usage tips:
- Recolor to theme ([[references/theme-colors.md]]): Gold
#c9b458, Green #8fbc8f, Blue #7a9fbf, Orange #ffa500, Red #ff6666
- Use sparingly for emphasis (1-3 icons per section)
- Don't mix too many styles (pick Material Symbols OR library icons, not both)
- Size appropriately (M size: 20-24px for most use cases)
See [[references/library-guide.md]] for library loading, [[references/icon-integration.md]] for Material Symbols integration, [[references/theme-colors.md]] for color palette.
Excalidraw Quality Checklist
Before considering a diagram complete:
Visual hierarchy:
Alignment & spacing:
Color & contrast:
Arrows & flow:
Polish:
Excalidraw Anti-Patterns to Avoid
Visual sins:
- ❌ Rainbow explosion (too many colors)
- ❌ Size chaos (random sizing)
- ❌ Alignment laziness (nothing lines up)
- ❌ Whitespace phobia (cramming everything)
- ❌ Arrow spaghetti (crossing paths everywhere)
- ❌ Text walls (paragraphs in shapes)
- ❌ Inconsistent styling (different fonts, colors, shapes for same purposes)
The boring diagram:
- ❌ All boxes same size
- ❌ All text same size
- ❌ Single color throughout
- ❌ No visual hierarchy
- ❌ Generic layout
- ❌ Zero whitespace
- ❌ No attention to alignment
Result: Technically accurate but visually dead. Nobody wants to look at it.
Tools & Shortcuts
Essential Keyboard Shortcuts
Drawing:
R or 2 → Rectangle
D or 3 → Diamond
O or 4 → Ellipse
A or 5 → Arrow
L or 6 → Line
T or 7 → Text
X → Freedraw tool
E → Eraser
Editing:
Cmd/Ctrl + D → Duplicate
Cmd/Ctrl + Arrow → Duplicate + connect with arrow
Shift + V/H → Flip vertical/horizontal
- Arrow keys → Move 1px (Shift+Arrow for 5px)
Alt + / → Stats for nerds (exact pixel dimensions)
Cmd/Ctrl + ' → Toggle grid
Cmd/Ctrl + G → Group selection
Cmd/Ctrl + Shift + G → Ungroup
Cmd/Ctrl + K → Add link to selected element
Selection:
- Click drag → Select multiple
Cmd/Ctrl + A → Select all
- Right-click → Context menu (align, arrange, etc.)
Cmd/Ctrl + Click → Add to selection
- Hold
Shift while resizing → Maintain aspect ratio
Layers/Z-order:
Cmd/Ctrl + ] → Bring forward
Cmd/Ctrl + [ → Send backward
Cmd/Ctrl + Shift + ] → Bring to front
Cmd/Ctrl + Shift + [ → Send to back
View:
Cmd/Ctrl + Wheel → Zoom in/out
Space + Drag → Pan canvas
Cmd/Ctrl + 0 → Reset zoom to 100%
Cmd/Ctrl + 1 → Zoom to fit all elements
Productivity Tips (2025 Best Practices)
Essential techniques:
- Snapping:
Alt/Option + S for precision alignment
- Multi-point arrows: Click-click-click (not drag) for clean paths
- Duplicate + connect:
Cmd/Ctrl + Arrow for flowcharts
- Stats for nerds:
Alt + / for exact pixel dimensions
- Link elements:
Cmd/Ctrl + K for clickable diagrams
See [[references/productivity-tips.md]] for complete list of 12 productivity techniques and keyboard shortcuts.
Browser Extensions
Excalisave: Save unlimited canvases locally
Excalidraw Custom Font: Use custom .woff2 fonts
Visualization from Data
Paste table → chart:
- Copy two-column data
- Paste into Excalidraw
- Auto-generates bar/line chart
- Fully editable afterward
Technical Integration
MCP Server (Optional Advanced Feature)
For real-time canvas manipulation, see [[references/mcp-server-setup.md]].
Use cases:
- Programmatic diagram generation
- Live collaborative editing
- Automation workflows
Not needed for: Manual diagram creation, which is the primary use case.
JSON Format (Advanced)
For direct file manipulation or automation, see [[references/json-format.md]].
Use cases:
- Batch processing diagrams
- Custom tooling integration
- Programmatic generation without MCP server
Not needed for: Standard diagram creation.
Alternative: Mermaid Conversion
Excalidraw can import Mermaid.js diagrams and convert to hand-drawn style.
When to use: Quick generation of standard diagram types (flowcharts, sequence diagrams)
Limitation: Limited styling control, generic layouts—often needs significant manual refinement to look good.
Recommendation: Direct creation in Excalidraw produces better visual results.
Excalidraw Summary
The Goal: Create diagrams that are both accurate AND visually compelling.
Core Principles:
- Visual hierarchy through size, color, position
- Mind mapping principles: Proximity, Alignment, Contrast, Repetition
- Two-phase process: structure first, aesthetics second
- Whitespace as a design element, not empty space
- Consistent styling throughout (colors, sizes, spacing)
- Alignment obsession for professional polish
Remember: Boring diagrams fail to communicate, no matter how accurate. Invest in visual design to make your ideas memorable and impactful.
Quick wins:
- WHITE backgrounds ALWAYS - muted colors on white, not dark backgrounds
- Use theme colors ([[references/theme-colors.md]]): Muted gold, soft greens, blues - NO bright pure colors
- Load library components or Material Symbols for visual interest
- Prefer organic layouts: Mind maps, spatial clusters, curved arrows - NOT rigid hierarchies
- Align elements for professional polish, but embrace asymmetry and creative positioning
- Add way more whitespace than you think you need (80-120px between clusters)
- Vary sizes significantly to create hierarchy (XL → L → M → S)
- Use radial/clustered layouts for goal → project → task visualizations
- Export at 2-3x scale
- Icons sparingly: 1-3 per section, recolored to theme ([[references/icon-integration.md]])
For goal/project/task visualizations (mind-map style):
- Central goals (largest, muted gold
#c9b458, XL text: 40-48px)
- Projects spatially distributed around goals (medium, varied theme colors, L text: 24-32px)
- Tasks clustered near projects (size varies: LARGE for active/blocked, SMALL for completed)
- Active tasks: M text (16-20px), soft green
#8fbc8f, PROMINENT
- Completed tasks: S text (12-14px), gray
#888888, DE-EMPHASIZED
- Curved arrows connecting related elements (organic feel)
- Cluster related projects spatially (not in rigid rows)
- Use opacity and color to show status (blocked=red, active=green, queued=orange)
- Add icons for status indicators (check_circle, pending, block) from Material Symbols