# diagram-generation

> Mermaid diagram conventions — semantic colors, layout patterns, validation.

- Author: Pone Z Pyo
- Repository: zoulabo/line-hive
- Version: 20260209132217
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-09
- Source: https://github.com/zoulabo/line-hive
- Web: https://mule.run/skillshub/@@zoulabo/line-hive~diagram-generation:20260209132217

---

---
name: diagram-generation
description: Mermaid diagram conventions — semantic colors, layout patterns, validation.
---

# Diagram Generation

Project convention for Mermaid diagrams used in skill docs and README.

## Quick Reference
| Rule | Pattern |
|------|---------|
| Theme | `%%{init: {"theme": "default"}}%%` at top |
| Line breaks | `<br/>` (not `\n`) |
| Invisible links | `~~~` for horizontal arrangement |
| Dotted arrows | `-.->` for secondary relationships |
| Decision nodes | `{"Condition?"}` with `{}` braces |

## Color Palette
| Type | Fill/Stroke | Use |
|------|-------------|-----|
| Input | `#e3f2fd`/`#1565c0` | Source data |
| Process | `#f3e5f5`/`#7b1fa2` | Transformations |
| Output | `#e8f5e9`/`#2e7d32` | Results |
| Decision | `#fff3e0`/`#e65100` | Branching |
| Title | `#4a90d9`/`#2c5282` | Subgraph headers |

---

## ⚠️ Preventing Broken Diagrams

**MANDATORY**: Validate before saving. Broken inline Mermaid is common.

### Validation Steps
1. **VS Code Preview**: Cmd+Shift+V → check for red error boxes
2. **CLI check** (if preview unavailable):
   ```bash
   npx -y @mermaid-js/mermaid-cli -i file.md -o /tmp/test.svg
   ```

### Universal Syntax Breaks (All Diagram Types)

| ❌ Breaks | ✅ Safe | Applies To |
|-----------|---------|------------|
| `(text)` in labels | `[text]` or remove | flowchart, sequence |
| `"quoted"` relationship labels | unquoted `verb` | ERD, flowchart |
| Unescaped `#`, `&`, `<`, `>` | `#35;`, `&amp;`, `&lt;`, `&gt;` | all |
| Empty node `A[]` | `A[" "]` with space | flowchart |
| Nested `(())` | flatten or escape | all |

### ERD-Specific

| ❌ Breaks | ✅ Safe |
|-----------|---------|
| `varchar(255)` | `varchar` (no params) |
| `FK_UK` combined | single: `FK` or `UK` |
| `PK, FK` comma | one annotation only |

### Flowchart-Specific

| ❌ Breaks | ✅ Safe |
|-----------|---------|
| `A(round)` with special chars | `A["round"]` |
| `-->|long label with spaces|` | `-- label -->` |

### Sequence-Specific

| ❌ Breaks | ✅ Safe |
|-----------|---------|
| `A->>B: text (note)` | `A->>B: text` + separate Note |
| Participant with `-` | use `_` instead |

---

## Standard Flowchart Pattern
```mermaid
%%{init: {"theme": "default"}}%%
flowchart TB
  subgraph Input[" "]
    InputTitle["Input"]
    A["Source"] ~~~ B["Source"]
  end
  subgraph Process[" "]
    ProcessTitle["Process"]
    C["Step"] --> D["Step"]
  end
  A & B --> C
  D --> E{"Branch?"}
  E -- Yes --> F["Output"]

  style Input fill:#e3f2fd,stroke:#1565c0
  style Process fill:#f3e5f5,stroke:#7b1fa2
  classDef title fill:#4a90d9,stroke:#2c5282,color:#fff,font-weight:bold
  class InputTitle,ProcessTitle title
```

## SVG Rendering
```bash
cd migrations && npx tsx ../.github/scripts/mermaid-render.ts \
  --input ../.github/skills/<skill>/SKILL.md \
  --out ../.github/diagrams/<domain> --mmdc node_modules/.bin/mmdc
```

## SVG UI Mockups

For detailed UI layouts Mermaid can't represent, use hand-coded SVG in `.github/diagrams/<domain>/`.

```svg
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 900 600">
  <style>.title { font: bold 20px system-ui; fill: #1e1e1e; }</style>
  <rect x="50" y="50" width="800" height="500" rx="8" fill="white" stroke="#e0e0e0"/>
  <text x="70" y="80" class="title">Title</text>
</svg>
```

For editable mockups, use Excalidraw (`.excalidraw` files) and export SVG.