Menu
Clear documentation through visual excellence
Create and maintain ASCII visual dashboards for project tracking with parallel lane progress bars
Store and manage voice samples for TTS cloning — portable, version-controlled audio references
AI music generation via Replicate — 5 models for background tracks, lyrics, and sound design
Practitioner methodology for longitudinal case study research, evidence-based documentation, and publication-ready academic writing in AI-assisted development.
First impressions matter. Set projects up for success.
Cloud TTS via Replicate — 15 models, voice cloning, emotion control, and multi-language support
| name | markdown-mermaid |
| description | Clear documentation through visual excellence |
| tier | standard |
| inheritance | inheritable |
| applyTo | **/*.md,**/*mermaid*,**/*diagram* |
Clear documentation through visual excellence
A skill for markdown authoring, Mermaid diagramming, multi-tool visualization, VS Code integration, and cross-platform rendering consistency.
Do NOT write Mermaid code without this template. Copy-paste first, then customize:
%%{init: {'theme': 'base', 'themeVariables': {'lineColor': '#57606a', 'primaryColor': '#ddf4ff', 'primaryBorderColor': '#0969da', 'primaryTextColor': '#1f2328', 'edgeLabelBackground': '#ffffff'}}}%%
flowchart LR
A[Input]:::blue --> B[Process]:::purple --> C[Output]:::green
classDef blue fill:#ddf4ff,color:#0550ae,stroke:#80ccff
classDef green fill:#d3f5db,color:#1a7f37,stroke:#6fdd8b
classDef purple fill:#d8b9ff,color:#6639ba,stroke:#bf8aff
classDef gold fill:#fff8c5,color:#9a6700,stroke:#d4a72c
classDef red fill:#ffebe9,color:#cf222e,stroke:#f5a3a3
classDef neutral fill:#eaeef2,color:#24292f,stroke:#d0d7de
linkStyle default stroke:#57606a,stroke-width:1.5px
Three required components:
| Color Class | Use For | Example |
|---|---|---|
:::blue | Input, source, start | A[Audio]:::blue |
:::green | Output, result, data | C[Transcript]:::green |
:::purple | Processing, model | B[WhisperX]:::purple |
:::gold | Decision, condition | D{Valid?}:::gold |
:::red | Error, warning | E[Failed]:::red |
:::neutral | Context, optional | F[Cache]:::neutral |
Every Mermaid diagram MUST follow this 6-step protocol. No exceptions — this prevents forgotten palettes, broken layouts, and inconsistent styling.
| Step | Action | What to Do |
|---|---|---|
| A | Analyze | What data/process am I visualizing? Who is the audience? What diagram type fits? |
| T | Think | Which layout pattern? (Medallion/Lineage/Pipeline) How many nodes? Will it be too wide/tall? |
| A | Apply | COPY THE TEMPLATE ABOVE — init directive + classDef + linkStyle. No exceptions. |
| C | Create | Write the Mermaid code. Every node gets :::className. Every flowchart gets linkStyle default. |
| C | Check | Render the diagram. Verify: pastels (not saturated), layout (not lopsided), labels (readable), arrows (gray #57606a). |
| U | Update | Write the final diagram into the target .md file. Add **Figure N:** *description* label. |
Before writing any Mermaid code, answer these:
□ Diagram type selected (flowchart/sequence/gantt/quadrant/etc.)
□ Layout direction chosen (LR preferred for flow, TD for hierarchy)
□ Subgraph strategy decided (Medallion vs Lineage vs Pipeline)
□ Color assignments mapped (what color = what meaning)
□ Multi-line node labels use <br/> NOT \n
After creating the diagram, verify ALL of these:
□ Init directive is FIRST line inside mermaid block
□ edgeLabelBackground is '#ffffff' (white background for edge labels)
□ ALL nodes have style/classDef (no unstyled nodes)
□ Colors are GitHub Pastel v2 (NOT saturated: no #51cf66, #339af0, #fab005)
□ linkStyle default stroke:#57606a,stroke-width:1.5px (flowcharts)
□ Node labels use <br/> for line breaks, NOT \n
□ Diagram rendered and visually inspected
□ No dimension > 3x the other (use subgroups to balance)
□ Figure label added below diagram block
□ Written to target file (not just shown in chat)
| Violation | ATACCU Step That Catches It |
|---|---|
| Saturated colors instead of pastels | Apply Skills — load palette first |
| Missing init directive | Apply Skills — it's step 3 |
edgeLabelBackground: 'transparent' used | Apply Skills — use '#ffffff' (white background) |
\n in node labels (renders as literal text) | Create — use <br/> for line breaks |
| Missing linkStyle | Create — every flowchart needs it |
| Lopsided layout (7-way fan-out) | Think — choose layout pattern |
| Diagram only in chat, not in file | Update — write to .md file |
| No figure label | Update — add label |
VS Code 1.109 introduces native Mermaid rendering in chat via the renderMermaidDiagram tool.
When creating diagrams in Copilot Chat (not markdown files), use the native tool for:
User: Create a sequence diagram showing OAuth flow
Alex: [uses renderMermaidDiagram tool]
→ Interactive diagram appears in chat
→ User can pan/zoom/fullscreen
→ "Copy source" extracts code for docs
.md filesrenderMermaidDiagram for rapid iteration```mermaid code fence| File | Purpose |
|---|---|
markdown-light.css | VS Code preview styling |
polish-mermaid-setup.prompt.md | Interactive Mermaid configuration helper |
Setup: Copy CSS to .vscode/, add "markdown.styles": [".vscode/markdown-light.css"] to settings.
Mermaid Config: Run the "Polish Mermaid Setup" prompt to configure Mermaid rendering for your VS Code environment.
# Title
> Brief description or tagline
---
## Overview
Introductory paragraph explaining the purpose.
---
## Section 1
Content with proper formatting.
### Subsection 1.1
More detailed content.
---
## Tables
**Table N:** *Description of what the table shows*
| Column 1 | Column 2 |
| -------- | -------- |
| Data | Data |
---
## Diagrams
` ` `mermaid
flowchart LR
A --> B
` ` `
**Figure N:** *Description of what the diagram shows*
---
*Footer or closing statement*
Mandatory Labeling: Every diagram and table MUST have a label:
**Figure 1:** *Description in italics*
**Table 1:** *Description in italics*
Badges use Shields.io - a free service for generating status badges.
URL Structure:
https://img.shields.io/badge/{LABEL}-{MESSAGE}-{COLOR}?{OPTIONS}
Markdown Syntax:
[](#)
| Style | Appearance | Parameter |
|---|---|---|
| Flat | Minimal | style=flat |
| Flat-Square | Squared corners | style=flat-square |
| Plastic | Gradient | style=plastic |
| For-the-Badge | Large, bold | style=for-the-badge |
| Social | GitHub-like | style=social |
| Color | Name | Hex |
|---|---|---|
| 🔵 | blue | #007ec6 |
| 🟢 | green | #97ca00 |
| 🟡 | gold / yellow | #dfb317 |
| 🟠 | orange | #fe7d37 |
| 🔴 | red | #e05d44 |
| 🟣 | purple | #9f4bc9 |
| 🔷 | cyan | #25c2a0 |
| ⚫ | gray / grey | #555555 |
Custom Hex: Use any hex without # → ?color=1f2328
Shields.io integrates with Simple Icons for brand logos:
[](#)
Parameters:
logo=iconname - Icon from Simple Icons (lowercase, no spaces)logoColor=white - Icon color (usually white for dark backgrounds)Version Badge:
[](#)
Domain/Category Badge:
[](#)
Quality Badge:
[](#)
Status Badge:
[](#)
[](#)
[](#)
Professional documents use a badge row at the top:
# Document Title
[](#) [](#)
> Description tagline
---
| Character | Encode As |
|---|---|
| Space | _ (underscore) or %20 |
| Dash | -- (double dash) |
| Underscore | __ (double underscore) |
For live data from repos:
[](#)
[](#)
[](#)
Best Practice: Use actual emoji characters, not HTML entities or unicode escapes.
| Good ✅ | Bad ❌ |
|---|---|
# 🧠 Brain | # 🧠 Brain |
**💻 Local** | **\ud83d\udcbb Local** |
| What You're Showing | Best Tools | Example Use Cases |
|---|---|---|
| Process/Workflow | Mermaid Flowcharts, User Journey | Onboarding, approvals, troubleshooting |
| System Architecture | Mermaid Flowcharts with subgraphs, D2 | Microservices, API design |
| Relationships | Mermaid ER, Mindmaps, Graphviz | Database schemas, org charts |
| Time/Sequence | Mermaid Sequence, Gantt | API interactions, timelines |
| Data/Metrics | Mermaid XY Charts, Sankey, Quadrant | Performance, resource allocation |
| Audience | Primary Goal | Recommended Tools | Style |
|---|---|---|---|
| Executives | Strategic overview | D2, simple flowcharts | Clean, minimal |
| Architects | Technical accuracy | PlantUML, Mermaid C4 | Detailed, precise |
| Developers | Implementation | Mermaid Sequence, Class | Code-focused |
| Product Managers | User flows | User Journey, Flowcharts | Business-outcome |
| Documentation | Learning | All Mermaid types | Progressive disclosure |
| Platform | Best Tools | Why |
|---|---|---|
| GitHub/GitLab | Mermaid | Native rendering, no setup |
| Confluence/Wiki | Mermaid, PlantUML | Plugin support |
| VS Code | All tools (extensions) | Live preview |
| Presentations | D2, simple Mermaid | Executive-friendly |
Need diagram? → What are you showing?
├── Process/Workflow → Mermaid Flowchart
├── System Architecture → Mermaid with subgraphs (or D2 for exec)
├── Relationships → Mermaid ER/Mindmap (or Graphviz for complex)
├── Time/Sequence → Mermaid Sequence/Gantt
└── Data/Metrics → Mermaid XY/Sankey/Quadrant
| Tool | Native GitHub | Complexity | Best For |
|---|---|---|---|
| Mermaid | ✅ Yes | Low-Medium | General purpose, quick diagrams |
| PlantUML | ❌ No | Medium-High | Enterprise UML, AWS/Azure |
| Graphviz | ❌ No | High | Complex networks, dependencies |
| D2 | ❌ No | Low | Clean architecture overviews |
| WaveDrom | ❌ No | Medium | Digital timing diagrams |
{
"recommendations": [
"bierner.markdown-mermaid",
"vstirbu.vscode-mermaid-preview",
"mermaidchart.vscode-mermaid-chart",
"jebbs.plantuml",
"joaompinto.vscode-graphviz",
"terrastruct.d2",
"shd101wyy.markdown-preview-enhanced",
"yzane.markdown-pdf",
"bierner.markdown-preview-github-styles"
]
}
PlantUML (Enterprise UML):
@startuml
!theme aws-orange
participant User
participant System
participant Database
User -> System: Request
System -> Database: Query
Database --> System: Response
System --> User: Result
@enduml
Graphviz DOT (Complex Networks):
digraph G {
rankdir=TB;
node [shape=box, style=filled, fillcolor=lightblue];
A -> B;
A -> C;
B -> D;
C -> D;
}
D2 (Modern Architecture):
users -> web_server: HTTPS requests
web_server -> database: SQL queries
users.style.fill: "#e1f5fe"
web_server.style.fill: "#f3e5f5"
See the MANDATORY template at the top of this skill. That template is authoritative. This section is a quick reminder:
%%{init: {'theme': 'base', 'themeVariables': {'lineColor': '#57606a', 'primaryColor': '#ddf4ff', 'primaryBorderColor': '#0969da', 'primaryTextColor': '#1f2328', 'edgeLabelBackground': '#ffffff'}}}%%
flowchart LR
A[Source]:::blue -->|transform| B[Process]:::purple --> C[Output]:::green
classDef blue fill:#ddf4ff,color:#0550ae,stroke:#80ccff
classDef green fill:#d3f5db,color:#1a7f37,stroke:#6fdd8b
classDef purple fill:#d8b9ff,color:#6639ba,stroke:#bf8aff
classDef gold fill:#fff8c5,color:#9a6700,stroke:#d4a72c
classDef red fill:#ffebe9,color:#cf222e,stroke:#f5a3a3
classDef neutral fill:#eaeef2,color:#24292f,stroke:#d0d7de
linkStyle default stroke:#57606a,stroke-width:1.5px
Four things every diagram needs:
%%{init}%% directive with edgeLabelBackground: '#ffffff'classDef or style for node colorslinkStyle default stroke:#57606a for arrow color|text| with white background (from init)💡 For color theory and design principles, see the graphic-design skill. The palette values here come from that skill's color system, optimized for GitHub rendering.
| Type | Syntax | Best Use Case |
|---|---|---|
| Flowchart | flowchart TB/LR/BT/RL | Process flows, decision trees |
| Sequence | sequenceDiagram | API calls, interactions |
| State | stateDiagram-v2 | State machines, lifecycles |
| Class | classDiagram | OOP design, relationships |
| ER | erDiagram | Database schema |
| Gantt | gantt | Project timelines |
| Pie | pie | Simple proportions |
| Mindmap | mindmap | Concept hierarchies |
| Quadrant | quadrantChart | 2D positioning analysis |
| Git Graph | gitGraph | Branch workflows |
| XY Chart | xychart-beta | Data plotting |
| Sankey | sankey-beta | Flow analysis |
| Block | block-beta | Block diagrams |
A[Rectangle] B(Rounded) C([Stadium])
D[[Subroutine]] E[(Database)] F((Circle))
G>Asymmetric] H{Diamond} I{{Hexagon}}
J[/Parallelogram/]
A --> B Standard arrow
A --- B Line without arrow
A -.-> B Dotted arrow
A ==> B Thick arrow
A --"label"--> B Labeled edge
A -->|"label"| B Alternative label syntax
Note: Superseded by GitHub Pastel Palette v2 below. Kept for reference only.
| Purpose | Background | Border/Stroke |
|---|---|---|
| GitHub Light | #f6f8fa | #d1d9e0 |
| Text | - | #1f2328 |
| Lines | - | #656d76 |
| Success | #e8f5e9 | #2e7d32 |
| Info | #e3f2fd | #1565c0 |
| Warning | #fff3e0 | #ef6c00 |
| Special | #f3e5f5 | #7b1fa2 |
| Danger | #ffebee | #c62828 |
| Neutral | #f5f5f5 | #424242 |
Higher contrast, better accessibility. Always use this palette for new diagrams.
Node Style Pattern: style NODE fill:#FILL,color:#TEXT,stroke:#STROKE
| Purpose | Fill | Text | Stroke | Usage |
|---|---|---|---|---|
| Bronze/Peach | #fff1e5 | #953800 | #ffb77c | Data ingestion, raw layer |
| Silver/Gray | #eaeef2 | #24292f | #afb8c1 | Processing, transformation |
| Gold/Yellow | #fff8c5 | #9a6700 | #d4a72c | Business logic, highlights |
| Blue/Sky | #ddf4ff | #0550ae | #80ccff | Actions, primary operations |
| Purple | #d8b9ff | #6639ba | #bf8aff | DevOps, tracking, special |
| Green/Mint | #d3f5db | #1a7f37 | #6fdd8b | Success, validation, output |
| Red/Coral | #ffebe9 | #cf222e | #f5a3a3 | Errors, critical, warning |
| Neutral | #eaeef2 | #24292f | #d0d7de | Background, containers |
Arrow/Link Styling (CRITICAL for readability):
linkStyle default stroke:#57606a,stroke-width:1.5px
Complete Example:
flowchart LR
A[Source] --> |Transform| B[Target]
style A fill:#ddf4ff,color:#0550ae,stroke:#80ccff
style B fill:#d3f5db,color:#1a7f37,stroke:#6fdd8b
linkStyle default stroke:#57606a,stroke-width:1.5px
Key Principles:
Softer palette with uniform dark text. Good for governance, compliance, and presentation diagrams.
| Purpose | Fill | Stroke | Text |
|---|---|---|---|
| Primary | #cce5ff | #4a90d9 | #333 |
| Light Blue | #b3d9ff | #4a90d9 | #333 |
| Lavender | #e6d5f2 | #8b6eb3 | #333 |
| Mint | #c2f0d8 | #4db37d | #333 |
| Cream | #fff3b3 | #d4a849 | #333 |
| Soft Pink | #ffcccc | #cc6666 | #333 |
Init directive (Fishbowl):
%%{init: {'theme': 'base', 'themeVariables': {
'primaryColor': '#cce5ff',
'primaryBorderColor': '#4a90d9',
'primaryTextColor': '#333',
'secondaryColor': '#e6d5f2',
'tertiaryColor': '#c2f0d8',
'lineColor': '#666',
'edgeLabelBackground': '#ffffff'
}}}%%
When to choose Fishbowl over GitHub Pastel v2: Use Fishbowl when all nodes need equal visual weight (e.g., governance structures, compliance flows). Use GitHub Pastel v2 when nodes carry semantic meaning that should be color-coded by category.
Add as FIRST line inside mermaid block:
Default init directive (GitHub Pastel v2):
%%{init: {'theme': 'base', 'themeVariables': {
'primaryColor': '#ddf4ff',
'primaryBorderColor': '#0969da',
'primaryTextColor': '#1f2328',
'lineColor': '#57606a',
'edgeLabelBackground': '#ffffff'
}}}%%
Standard GitHub-compatible theme (legacy):
%%{init: {'theme': 'base', 'themeVariables': {
'primaryColor': '#f6f8fa',
'primaryBorderColor': '#d1d9e0',
'primaryTextColor': '#1f2328',
'lineColor': '#656d76',
'edgeLabelBackground': '#ffffff'
}}}%%
Quadrant chart theme:
%%{init: {'theme': 'base', 'themeVariables': {
'quadrant1Fill': '#d3f5db',
'quadrant2Fill': '#fff8c5',
'quadrant3Fill': '#ffebe9',
'quadrant4Fill': '#ddf4ff',
'quadrantPointFill': '#1f2328',
'quadrantTitleFill': '#1f2328'
}}}%%
Define style classes once and apply to multiple nodes. Cleaner than per-node style directives.
flowchart LR
A[Source]:::input --> B[Process]:::action --> C[Output]:::success
classDef input fill:#ddf4ff,color:#0550ae,stroke:#80ccff
classDef action fill:#fff8c5,color:#9a6700,stroke:#d4a72c
classDef success fill:#d3f5db,color:#1a7f37,stroke:#6fdd8b
classDef error fill:#ffebe9,color:#cf222e,stroke:#f5a3a3
classDef neutral fill:#eaeef2,color:#24292f,stroke:#d0d7de
classDef special fill:#d8b9ff,color:#6639ba,stroke:#bf8aff
classDef bronze fill:#fff1e5,color:#953800,stroke:#ffb77c
Pastel v2 classDef Quick Reference (copy-paste ready):
classDef blue fill:#ddf4ff,color:#0550ae,stroke:#80ccff
classDef green fill:#d3f5db,color:#1a7f37,stroke:#6fdd8b
classDef purple fill:#d8b9ff,color:#6639ba,stroke:#bf8aff
classDef gold fill:#fff8c5,color:#9a6700,stroke:#d4a72c
classDef red fill:#ffebe9,color:#cf222e,stroke:#f5a3a3
classDef bronze fill:#fff1e5,color:#953800,stroke:#ffb77c
classDef neutral fill:#eaeef2,color:#24292f,stroke:#d0d7de
Apply to multiple nodes: class A,B,C blue
Apply inline: A[Label]:::blue
Style subgraph backgrounds with the style directive using the subgraph ID:
flowchart LR
subgraph SG1["Phase 1"]
direction TB
A --> B
end
subgraph SG2["Phase 2"]
direction TB
C --> D
end
style SG1 fill:#ddf4ff,stroke:#80ccff,color:#0550ae
style SG2 fill:#d3f5db,stroke:#6fdd8b,color:#1a7f37
Key: Use fill for background, keep it light. The color property sets the title text color.
Gantt charts use different theme variables than flowcharts:
'taskBkgColor': '#ddf4ff',
'activeTaskBkgColor': '#d3f5db',
'activeTaskBorderColor': '#6fdd8b',
'doneTaskBkgColor': '#eaeef2',
'doneTaskBorderColor': '#d0d7de',
'critBkgColor': '#ffebe9',
'critBorderColor': '#f5a3a3',
'todayLineColor': '#cf222e',
'gridColor': '#d0d7de',
'sectionBkgColor': '#f6f8fa',
'altSectionBkgColor': '#ffffff',
'taskTextColor': '#24292f',
'sectionBkgColor2': '#f6f8fa'
}}}%%
Section formatting: Gantt sections inherit alternating background colors. Use section keyword to group related tasks:
gantt
title Project Timeline
dateFormat YYYY-MM-DD
section Phase 1
Task A :done, a1, 2026-01-01, 14d
Task B :active, a2, after a1, 7d
section Phase 2
Task C :crit, a3, after a2, 10d
'actorBkg': '#ddf4ff',
'actorBorder': '#80ccff',
'actorTextColor': '#0550ae',
'activationBkgColor': '#d3f5db',
'activationBorderColor': '#6fdd8b',
'signalColor': '#57606a',
'labelBoxBkgColor': '#fff8c5',
'labelTextColor': '#9a6700',
'noteBkgColor': '#fff8c5',
'noteTextColor': '#9a6700',
'noteBorderColor': '#d4a72c'
}}}%%
| Color | Association | Use For |
|---|---|---|
| 💙 Blue | Trust, reliability | Human partnership, collaboration |
| 💜 Purple | Consciousness, awareness | Identity, higher concepts |
| 💚 Green | Growth, learning | Cognitive processing, success |
| 🧡 Orange | Connection, energy | Memory networks, neural links |
| ❤️ Red | Power, achievement | Advanced capabilities, warnings |
Problem: Emojis stored as \ud83d\udcbb display as raw codes instead of 💻
Detection (PowerShell):
Get-ChildItem -Recurse -Filter "*.md" | Select-String -Pattern '\\u[0-9a-fA-F]{4}' | Group-Object Path
Prevention (VS Code settings):
{
"files.encoding": "utf8",
"files.autoGuessEncoding": false
}
| Escape | Emoji | Name |
|---|---|---|
\ud83e\udde0 | 🧠 | Brain |
\ud83d\udcbb | 💻 | Laptop |
\ud83d\ude80 | 🚀 | Rocket |
\ud83c\udfaf | 🎯 | Target |
\ud83d\udca1 | 💡 | Lightbulb |
\ud83d\udd0d | 🔍 | Search |
\ud83d\udd04 | 🔄 | Cycle |
\u2699\ufe0f | ⚙️ | Gear |
\ud83d\udd27 | 🔧 | Wrench |
\u26a1 | ⚡ | Lightning |
\ud83c\udf1f | 🌟 | Star |
\ud83c\udf19 | 🌙 | Moon |
\u2601\ufe0f | ☁️ | Cloud |
\ud83c\udf10 | 🌐 | Globe |
\ud83d\udcac | 💬 | Speech |
\ud83d\udcdd | 📝 | Memo |
\ud83d\udccb | 📋 | Clipboard |
\ud83d\udcc8 | 📈 | Chart Up |
\ud83d\udcbe | 💾 | Floppy |
\ud83d\udce6 | 📦 | Package |
\u2705 | ✅ | Check |
\u274c | ❌ | Cross |
\u26a0\ufe0f | ⚠️ | Warning |
\ud83d\udea8 | 🚨 | Siren |
\ud83d\udd12 | 🔒 | Lock |
\ud83d\udd11 | 🔑 | Key |
\ud83d\udcca | 📊 | Bar Chart |
\ud83d\udcc1 | 📁 | Folder |
\ud83d\udc1b | 🐛 | Bug |
\u2728 | ✨ | Sparkles |
\ud83c\udfc6 | 🏆 | Trophy |
\ud83e\udd16 | 🤖 | Robot |
\ud83d\udcda | 📚 | Books |
Problem: Arrow labels (|text|) appear with dark boxes in VS Code dark mode or break rendering
Root cause: Missing or incorrect edgeLabelBackground settings.
Fix: Always include edgeLabelBackground: '#ffffff' in your init directive:
%%{init: {'theme': 'base', 'themeVariables': {
'primaryColor': '#ddf4ff',
'lineColor': '#57606a',
'edgeLabelBackground': '#ffffff'
}}}%%
flowchart LR
A -->|label text| B
This provides a clean white background for edge labels, ensuring readability on any rendering surface.
⚠️ Never use
theme: 'dark'— usetheme: 'base'with the pastel palette instead.
\n vs <br/>)Problem: \n in node labels renders as a literal backslash-n in VS Code and some Mermaid versions:
❌ A["First line\nSecond line"] ← may render as "First line\nSecond line"
✅ A["First line<br/>Second line"] ← always works
Rule: Always use <br/> for multi-line node labels in flowcharts.
Problem: Diagrams have dark backgrounds in VS Code preview
Solution 2: Apply included markdown-light.css via settings
Problem: Diagrams become too wide (horizontal) or too tall (vertical), causing poor readability
Detection: Look for diagrams where one dimension is 3x+ the other
Pattern: Use opposing directions for outer flowchart vs. inner subgraphs:
%% Pattern 1: TD outer with LR inner (vertical stack of horizontal lanes)
flowchart TD
subgraph Phase1["Phase 1"]
direction LR
A --> B --> C
end
subgraph Phase2["Phase 2"]
direction LR
D --> E --> F
end
%% Pattern 2: LR outer with TB inner (horizontal flow of vertical stacks)
flowchart LR
subgraph Group1["Group 1"]
direction TB
A --> B --> C
end
subgraph Group2["Group 2"]
direction TB
D --> E --> F
end
Key Rules:
| Outer Direction | Inner Direction | Result |
|---|---|---|
| TD/TB | LR | Subgraphs stack vertically, content flows horizontally |
| LR | TB | Subgraphs flow horizontally, content stacks vertically |
Anti-Pattern 1: Single subgraph with opposing direction has no effect (nothing to stack)
%% WRONG - single subgraph, direction LR does nothing useful
flowchart TD
subgraph Only["Only Subgraph"]
direction LR
A --> B --> C --> D --> E %% Still very wide!
end
%% RIGHT - break into multiple subgraphs
flowchart TD
subgraph Phase1["Setup"]
direction LR
A --> B
end
subgraph Phase2["Execute"]
direction LR
C --> D
end
Anti-Pattern 2: Cross-subgraph edges defined inside subgraphs (causes layout confusion)
%% WRONG - edge to next subgraph defined inside source subgraph
flowchart TD
subgraph Phase1["Setup"]
direction LR
A --> B
B --> C %% C is in Phase2!
end
subgraph Phase2["Execute"]
direction LR
C --> D
end
%% RIGHT - cross-subgraph edges defined outside all subgraphs
flowchart TD
subgraph Phase1["Setup"]
direction LR
A --> B
end
subgraph Phase2["Execute"]
direction LR
C --> D
end
B --> C %% Cross-subgraph edge outside
subgraph Phase3["Complete"]
direction LR
E
end
Anti-Pattern 3: Independent subgraphs without connections default to vertical stacking
%% WRONG - no connections between subgraphs, ignores LR direction
flowchart LR
subgraph A["Group A"]
direction TB
A1 --> A2
end
subgraph B["Group B"]
direction TB
B1 --> B2
end
%% Result: Groups stack vertically despite LR!
%% RIGHT - invisible links force horizontal layout
flowchart LR
subgraph A["Group A"]
direction TB
A1 --> A2
end
subgraph B["Group B"]
direction TB
B1 --> B2
end
A ~~~ B %% Invisible link forces LR arrangement
Use these named patterns for consistent, well-proportioned diagrams. Each combines an outer flowchart direction with inner subgraph directions.
Use when: Phases/layers stack vertically, each containing a horizontal flow.
flowchart TD
subgraph Phase1["Phase 1: Ingestion"]
direction LR
A[Source] --> B[Validate] --> C[Store]
end
subgraph Phase2["Phase 2: Processing"]
direction LR
D[Load] --> E[Transform] --> F[Enrich]
end
Phase1 --> Phase2
Result: Compact rectangle. Good for pipelines, ETL stages, layered architectures.
Use when: Groups flow left-to-right, each containing a vertical stack.
flowchart LR
subgraph Cluster1["Input"]
direction TB
A1[Raw] --> A2[Clean]
end
subgraph Cluster2["Process"]
direction TB
B1[Compute] --> B2[Validate]
end
subgraph Cluster3["Output"]
direction TB
C1[Format] --> C2[Deliver]
end
Cluster1 --> Cluster2 --> Cluster3
Result: Wide timeline-like layout. Good for data lineage, system boundaries, progression.
Use when: Everything flows left-to-right (flat pipeline, no vertical stacking needed).
flowchart LR
A[Input] --> B[Stage 1] --> C[Stage 2] --> D[Output]
Result: Simple horizontal chain. Good for CI/CD, request flows, simple sequences.
| Your Content | Pattern | Outer | Inner | Typical Shape |
|---|---|---|---|---|
| Phases with steps inside | Medallion | TD | LR | Tall rectangle |
| Groups flowing in sequence | Lineage | LR | TB | Wide rectangle |
| Simple linear flow | Pipeline | LR | — | Narrow strip |
| Hierarchy, org chart | Tree | TD | — | Triangle |
| Complex interconnected | Medallion | TD | LR | Structured layers |
When subgraphs have no logical connections between them, Mermaid ignores the outer direction and stacks them vertically by default. Fix with invisible links (~~~):
flowchart LR
subgraph A["Group A"]
direction TB
A1 --> A2
end
subgraph B["Group B"]
direction TB
B1 --> B2
end
A ~~~ B %% Forces horizontal arrangement per outer LR
Rule: Always add ~~~ between independent subgraphs to enforce the outer direction.
Multiple independent groups: Chain invisible links: A ~~~ B ~~~ C ~~~ D
Problem: Subgraph titles get truncated in VS Code preview
Note: This is a VS Code Mermaid renderer bug. GitHub renders correctly.
Root Cause: VS Code calculates subgraph width from content nodes, NOT title text.
Workaround: Make content nodes wider so the subgraph expands:
%% BAD in VS Code - narrow nodes clip title
subgraph CONSCIOUS["🌟 Conscious Mind"]
A["Chat"]
B["Commands"]
end
%% GOOD - descriptive labels force wider box
subgraph CONSCIOUS["🌟 Conscious Mind"]
A["💬 Chat Participant"]
B["⚡ VS Code Commands"]
end
Problem: Nested quotes, parentheses, or reserved words cause cryptic parse errors
Rule 1: Don't nest quotes inside quoted node labels
%% ❌ FAILS - nested quotes
["Return with<br/>"🌐 Results<br/>(Info)"]
%% ✅ WORKS - no nested quotes
["🌐 Return Results<br/>Info"]
Rule 2: Avoid HTML tags inside node labels (some renderers choke on them)
%% ❌ RISKY - <i> tag may break parsing
SYN["synapses.json<br/><i>inert — rarely traversed</i>"]
%% ✅ SAFE - plain text with em dash
SYN["synapses.json — inert, rarely traversed"]
Rule 3: Avoid em dashes (—) in subgraph titles (some parsers treat them as operators)
%% ❌ RISKY - em dash in subgraph title
subgraph P1["Phase 1 — Compiled Graph"]
%% ✅ SAFE - colon or hyphen instead
subgraph P1["Phase 1: Compiled Graph"]
subgraph P1["Phase 1 - Compiled Graph"]
Rule 4: Place style directives for subgraphs outside the subgraph block
%% ❌ FAILS in some renderers - style inside subgraph
subgraph SG["My Group"]
style SG fill:#ddf4ff,stroke:#80ccff
direction TB
A --> B
end
%% ✅ WORKS everywhere - style after all subgraphs
subgraph SG["My Group"]
direction TB
A --> B
end
style SG fill:#ddf4ff,stroke:#80ccff
Critical: classDiagram has a different parser than flowchart. Syntax that works in flowcharts often breaks in class diagrams. Never assume cross-compatibility.
classDiagram reserves more keywords than flowcharts. Using them as classDef names or class annotations collides with the parser.
| Reserved Word | Why It Breaks | Safe Alternative |
|---|---|---|
abstract | Parsed as <<abstract>> annotation | abstractStyle, base, iface |
interface | Parsed as <<interface>> annotation | ifaceStyle, contract |
enumeration | Parsed as <<enumeration>> annotation | enumStyle, enumDef |
service | Parsed as <<service>> annotation | svcStyle, serviceType |
%% ❌ FAILS - "abstract" is a classDiagram keyword
classDef abstract fill:#ddf4ff,stroke:#80ccff
%% ❌ ALSO FAILS - "abstract" parsed as <<abstract>> annotation
class MemorySystem abstract
%% ✅ WORKS - renamed classDef avoids collision
classDef base fill:#ddf4ff,stroke:#80ccff
class MemorySystem base
class A,B,C styleName syntax works in flowchart but NOT in classDiagram. Each class needs its own class X styleName line.
%% ❌ FAILS in classDiagram - comma syntax not supported
class UserStore,SessionStore,CacheStore storage
%% ✅ WORKS - one line per class
class UserStore storage
class SessionStore storage
class CacheStore storage
Note: In flowchart, class A,B,C styleName is valid (skillCatalog.ts uses this correctly).
classDef in classDiagram only supports SVG presentation attributes. CSS text properties are silently ignored.
| Works | Silently Ignored |
|---|---|
fill, stroke, stroke-width, color | font-weight, font-style, font-size |
rx (border radius) | text-decoration, letter-spacing |
opacity | padding, margin |
%% ❌ SILENTLY IGNORED - font-weight does nothing
classDef important fill:#fff3e0,stroke:#ef6c00,font-weight:bold
%% ✅ WORKS - use only SVG attributes
classDef important fill:#fff3e0,stroke:#ef6c00,stroke-width:2px
The space in stroke-dasharray:6 3 breaks Mermaid's comma-delimited property parser in classDiagram. In flowchart it may work.
%% ❌ FAILS in classDiagram - space in value breaks parser
classDef dashed stroke-dasharray:6 3
%% ⚠️ MAY WORK - single value, no space
classDef dashed stroke-dasharray:5
%% ✅ SAFE in flowchart - space tolerated
classDef dashed stroke-dasharray:5 5
Rule: In classDiagram, avoid stroke-dasharray entirely or use a single integer value. In flowchart, stroke-dasharray:5 5 works.
Decimal values like stroke-width:2.5px can cause inconsistent rendering across Mermaid renderers.
%% ⚠️ INCONSISTENT - decimal may not render
classDef thick stroke-width:2.5px
%% ✅ SAFE - integer values
classDef thick stroke-width:2px
classDef thicker stroke-width:3px
Critical: architecture-beta is an experimental diagram type with a much stricter tokenizer than mature types. Assume nothing works unless proven.
Labels in [...] do not support spaces. Multi-word labels cause the parser to treat each word as a separate token.
%% ❌ FAILS - space in bracket label
service api(server)[API Gateway]
%% ✅ WORKS - no spaces (use underscores or camelCase)
service api(server)[APIGateway]
service api(server)[Api_Gateway]
Hyphens like 4-3-3 are parsed as edge connectors (-- or -), not literal characters. There is no escape mechanism.
%% ❌ FAILS - hyphens parsed as edge syntax
service formation(server)[4-3-3]
%% ✅ WORKS - no hyphens
service formation(server)[Formation433]
Common programming keywords may conflict with the parser:
| Avoid | Safe Alternative |
|---|---|
var | varStore, envVar |
in | input, inbound |
out | output, outbound |
%% comments that work in all other diagram types may cause parse errors in architecture-beta.
%% ❌ MAY FAIL - standard comments
%% This is my architecture
architecture-beta
%% ✅ SAFE - no comments at all
architecture-beta
(icon) syntax only works on service declarations. Using it on group causes a parse error.
%% ❌ FAILS - group does not accept (icon)
group cloud(cloud)[Infrastructure]
%% ✅ WORKS - group has only id and [label]
group cloud[Infrastructure]
%% ✅ WORKS - service accepts (icon)
service api(server)[API]
Rule: service id(icon)[Label] — icon required. group id[Label] — no icon, no parentheses.
This table summarizes which syntax features work in which diagram types:
| Feature | flowchart | classDiagram | architecture-beta |
|---|---|---|---|
class A,B,C style | ✅ | ❌ | N/A |
classDef with font-weight | ❌ (ignored) | ❌ (ignored) | N/A |
stroke-dasharray:5 5 | ✅ | ❌ | N/A |
Spaces in [labels] | ✅ | N/A | ❌ |
| Hyphens in labels | ✅ (quoted) | ✅ (quoted) | ❌ |
%% comments | ✅ | ✅ | ⚠️ |
(icon) on groups | N/A | N/A | ❌ |
Problem: Certain words are reserved syntax in specific diagram types. Using them as the first word in a task description or node label causes parse errors like got 'callbackname', got 'keyword', etc.
Gantt Chart Reserved Words (cause callbackname or keyword errors):
| Reserved | Why | Safe Alternative |
|---|---|---|
call | Click callback syntax | Invoke, Execute, Generate, Run |
click | Click handler syntax | Select, Choose, Trigger |
after | Dependency keyword (only at start) | Rephrase to not start with after |
done | Task state modifier | Use as tag :done, not in description |
active | Task state modifier | Use as tag :active, not in description |
crit | Task state modifier | Use as tag :crit, not in description |
%% ❌ FAILS - "Call" is reserved
Call Azure OpenAI embeddings API :p1c, after p1b, 2d
%% ✅ WORKS - rephrase to avoid reserved word
Generate Azure OpenAI embeddings :p1c, after p1b, 2d
Flowchart Reserved Words (cause unexpected parse behavior):
| Reserved | Why | Safe Alternative |
|---|---|---|
end | Subgraph terminator | Wrap in quotes: ["End"] |
subgraph | Block keyword | Wrap in quotes: ["Subgraph"] |
class | classDef application | Wrap in quotes: ["Class"] |
style | Style directive | Wrap in quotes: ["Style"] |
click | Click handler | Wrap in quotes: ["Click"] |
default | Default linkStyle target | Wrap in quotes: ["Default"] |
%% ❌ FAILS - "end" is reserved
A --> end
%% ✅ WORKS - quoted label
A --> E["End"]
classDiagram Reserved Words (cause parse errors when used as classDef names or class annotations):
| Reserved | Why | Safe Alternative |
|---|---|---|
abstract | Parsed as <<abstract>> stereotype | base, abstractStyle, iface |
interface | Parsed as <<interface>> stereotype | ifaceStyle, contract |
enumeration | Parsed as <<enumeration>> stereotype | enumStyle, enumDef |
service | Parsed as <<service>> stereotype | svcStyle, serviceType |
%% ❌ FAILS - "abstract" treated as keyword
classDef abstract fill:#ddf4ff,stroke:#80ccff
class MemorySystem abstract
%% ✅ WORKS - safe name
classDef base fill:#ddf4ff,stroke:#80ccff
class MemorySystem base
General Safety Rule: If a parse error occurs on a label or title, wrap it in double quotes ("text") or rephrase to avoid the reserved word. When in doubt, quote it.
Problem: Individual bars all render the same color despite plotColorPalette
Root Cause: xychart-beta only applies different colors to different data series (multiple bar or line commands), not individual bars in a single series.
%% ❌ FAILS - single series, all bars same color
xychart-beta
x-axis [A, B, C]
bar [1, 2, 3] %% All same color!
%% ✅ WORKS - multiple series, each gets color from palette
xychart-beta
x-axis [A, B, C]
bar [1, 2, 3] %% Color 1
bar [4, 5, 6] %% Color 2
Alternative Solutions:
Pie chart — Use pie with theming when showing proportions:
pie showData
title "Task Distribution"
"Task A" : 8
"Task B" : 4
Visual ASCII table — Use markdown table with visual bars:
| Task | Value | Visual |
| ---- | ----- | ------ |
| A | **8** | ████████░░░░ |
| B | **4** | ████░░░░░░░░ |
Stacked bar (grouped) — Split data into multiple series
Problem: C4Component syntax not fully supported in standard Mermaid
Solution: Use flowcharts with subgraphs instead:
flowchart TB
subgraph SYSTEM["🏦 System Name"]
A["📝 Component A"]
B["📊 Component B"]
end
USER(("👤 User"))
USER --> A
USER --> B
Problem: Blockquotes render with excessive vertical padding
Solution: Included in markdown-light.css:
blockquote p {
margin: 0 !important;
line-height: 1.5 !important;
}
When performing comprehensive diagram audits across a project or documentation set, follow this 4-step process:
Identify all Mermaid diagrams in the target scope:
# Find all markdown files with mermaid blocks
Get-ChildItem -Recurse -Filter "*.md" |
Select-String -Pattern '```mermaid' |
Group-Object Path |
Select-Object Name, Count
Create an inventory table to track diagram state:
| # | File | Diagram Type | Status | Issues |
|---|---|---|---|---|
| 1 | README.md | flowchart | ⚠️ | Missing init |
| 2 | arch.md | sequence | ✅ | None |
| 3 | flow.md | flowchart | ❌ | Parse error |
Status codes: ✅ OK, ⚠️ Needs fix, ❌ Broken
Apply fixes in batches by issue type:
Re-render all diagrams and confirm fixes:
Typical results: A 30-40 diagram audit catches 10-15 issues in the first pass.
KISS ≠ Remove all detail
KISS means removing unnecessary complexity while preserving meaningful information. If removing detail reduces understanding, keep it.