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:
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.
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.
