Imported from gmotyl/pavilio (skills/pavilio-mermaid-chart/SKILL.md). Install upstream with npx skills add gmotyl/pavilio --skill pavilio-mermaid-chart. Copyright stays with the author.

Mermaid Chart Guide for Design Docs

The panel renders mermaid diagrams with automatic dark-mode coloring. To get the best visual output, follow these patterns.

How the panel colors diagrams

Flowcharts

• Subgraph clusters get distinct colors by declaration order — the order you wrote the subgraph blocks, not where mermaid ends up placing them: 1st = cyan, 2nd = red, 3rd = green, 4th = blue, 5th = purple, 6th = yellow (cycles)
• Nodes inside a subgraph inherit the subgraph's color (darker fill, matching border)
• Nodes outside subgraphs get a neutral teal color
• Use subgraphs to visually group related steps — the panel colors them automatically

Sequence Diagrams

• rect sections get distinct colors by vertical order: 1st = red, 2nd = green, 3rd = blue, 4th = purple (cycles)
• Actors each get a unique color from an 8-color palette (amber, green, blue, cyan, violet, pink, emerald, yellow), in order of first appearance
• Lifelines and activation bars match their actor's color
• Message arrows are colored by the sending actor — a solid call (->>) takes the source actor's color; a dotted response (-->>) takes a brightened tint of that same color. So every message a given actor sends shares its hue; there is no fixed blue/amber.
• Notes render in dark teal

The palette rotation above (flowchart clusters, sequence sections/actors) is applied only to flowcharts and sequence diagrams. Every other diagram type gets the shared dark base theme instead — see Other diagram types.

Flowchart patterns

A node belongs to the first subgraph that mentions it

This is the single biggest source of "the diagram renders but looks wrong". Mermaid assigns a node to a cluster by where the node is mentioned, not by where it was first declared. Write the fan-out edge inside the subgraph and the shared node is swallowed by it:

```mermaid
flowchart TD
    A[Entry point] --> B[Shared step]

    subgraph Current broken path
      B --> C1[Problem step]
    end

    subgraph Fixed path
      B --> C2[Corrected step]
    end
```

B is dragged inside Current broken path — the shared step gets that cluster's color, and the edge into the second subgraph crosses out of a box it never belonged to. Keep every subgraph body limited to its own nodes and declare the cross-links at root level instead:

```mermaid
flowchart TD
    A[Entry point] --> B[Shared step]
    B --> C1
    B --> C2

    subgraph Current broken path
      C1[Problem step] --> D1[Failure]
    end

    subgraph Fixed path
      C2[Corrected step] --> D2[Success]
    end

    D2 --> E[Exit point]
```

Now A and B stay at root (neutral teal), the two clusters sit side by side, and D2 --> E still pulls the exit node out to root. A bare B --> C1 at root level does not claim C1 — only a mention inside a subgraph block does — so the cross-links are safe to write before or after the blocks.

Use subgraphs for before/after or current/fixed

Put the problematic flow in the first subgraph and the fixed flow in the second, following the shape above. Declaration order drives the palette, so a two-way comparison comes out cyan (first) and red (second).

Root nodes for entry/exit points

Keep shared entry and exit nodes outside subgraphs so they get the neutral teal color, visually separating them from the grouped paths.

Node labels

• Use \n for line breaks in labels: A[First line\nSecond line]
• Avoid starting label text with / — mermaid interprets [/text] as a parallelogram shape. The panel auto-fixes this, but it's cleaner to avoid it
• Keep labels concise — long text overflows node boundaries

Subgraph titles

A bare subgraph Title accepts only plain words: letters, digits, spaces. Any punctuation — an em dash, comma, slash, colon, parenthesis — is a lexical error that kills the whole diagram (Lexical error … Unrecognized text). Node labels and Note over text are unaffected, which is why only the subgraph line blows up.

Use the id + quoted-string form whenever the title is more than plain words:

flowchart TD
    subgraph screen["Screen tab — unchanged"]
        S1[Read cell] --> S2[Render]
    end
    subgraph fixed["Answer tab (new)"]
        F1[Read cell] --> F2[Speak]
    end

The id (screen, fixed) is what edges and style lines reference; the quoted string is what renders. Plain-word titles like subgraph Current broken path stay fine as they are.

Three-way comparisons

For before/during/after patterns, use three subgraphs:

```mermaid
flowchart TD
    subgraph Before
      A1[Old state]
    end
    subgraph Migration
      B1[Transition step]
    end
    subgraph After
      C1[New state]
    end
```

Colors: Before = cyan, Migration = red, After = green.

Sequence diagram patterns

Use rect blocks for current/fixed sections

The rect color values in the markdown source are ignored by the dark theme — the panel overrides them. But include them for GitHub/other renderers:

```mermaid
sequenceDiagram
    participant A as Service A
    participant B as Service B

    rect rgb(255, 245, 245)
    Note over A,B: Current broken behavior
    A->>B: request without token
    B-->>A: 401 unauthorized
    end

    rect rgb(245, 255, 245)
    Note over A,B: Fixed behavior
    A->>B: request with valid token
    B-->>A: 200 OK
    end
```

First rect = red tint (broken/current), second rect = green tint (fixed).

Arrow conventions

Arrows inherit the sending actor's hue, so keep calls (->>) and responses (-->>) semantically correct and the coloring follows automatically.

Notes for section labels

Use Note over spanning all participants to create section headers:

Note over A,Z: Section title

alt/opt/loop blocks

Use for conditional logic within a section. These render as smaller outlined boxes inside the section rect:

alt condition text
    A->>B: path 1
else other condition
    A->>C: path 2
end

Other diagram types (ERD, C4, state, git graph, gantt, pie, class)

Flowcharts and sequence diagrams are the two types with bespoke panel coloring. The types below are fully supported and render cleanly, but they do not get the per-group/per-entity palette rotation. Instead the panel applies a shared dark base theme plus three global normalizations to every diagram:

• all text → light grey #e4e4e7
• all plain lines → grey #52525b
• default/black arrows → blue #3b82f6; boxes and nodes → dark teal #1a3a3a with a teal border

Consequence: don't lean on color to distinguish groups in these types — everything is one palette. If a concept genuinely needs colored grouping (current vs proposed, frontend vs backend), model it as a flowchart with subgraphs instead. Use the types below for what they express structurally.

Entity-relationship (erDiagram) — data models & DB schemas

```mermaid
erDiagram
    PROJECT ||--o{ SESSION : has
    SESSION ||--|{ TERMINAL : contains
    PROJECT {
      string name
      string path
    }
```

State (stateDiagram-v2) — lifecycles & state machines

```mermaid
stateDiagram-v2
    [*] --> Idle
    Idle --> Busy : work starts
    Busy --> Attention : waits for input
    Attention --> Idle : input given
    Busy --> Idle : work done
```

Class (classDiagram) — domain models & type relationships

```mermaid
classDiagram
    class SessionMeta {
      +string id
      +string project
      +ActivityState state
    }
    SessionMeta --> ActivityState
```

C4 (C4Context / C4Container) — system architecture at a level

C4 support is experimental in mermaid; stick to C4Context and C4Container and keep it small.

```mermaid
C4Context
    Person(user, "User")
    System(panel, "Panel", "React + Express")
    Rel(user, panel, "uses")
```

Git graph (gitGraph) — branching & release flow

```mermaid
gitGraph
    commit
    branch feature
    checkout feature
    commit
    checkout main
    merge feature
```

Gantt (gantt) — timelines & rollout phases

```mermaid
gantt
    title Rollout
    dateFormat YYYY-MM-DD
    section Phase 1
    Design      :a1, 2026-01-01, 5d
    Build       :after a1, 7d
```

Pie (pie) — proportional breakdown

```mermaid
pie title Time by area
    "Frontend" : 45
    "Backend" : 30
    "Infra" : 25
```

When to use which diagram

Checklist for design docs

• Diagram type matches the concept (see the table above) — not always a flowchart
• Need colored grouping? Use a flowchart/sequenceDiagram — other types are single-palette
• Multi-step flow? Add a flowchart TD with subgraphs for current vs fixed
• Cross-system interaction? Add a sequenceDiagram with rect sections
• Subgraphs ordered: broken/current first, fixed/new second
• Entry and exit nodes outside subgraphs
• Subgraph titles with punctuation (—, ,, /, () use subgraph id["Title"], never the bare form
• Solid arrows (->>) for calls, dotted (-->>) for responses — color follows the sending actor
• Note over for section labels in sequence diagrams
• Labels concise, \n for line breaks