a6eb4da214
- .ai/ instruction set (root, behavior, skills, constraints) - apply.sh workflow documentation (apply.md) - architecture documentation (docs/architecture.md) - .github/copilot-instructions.md for VS Code auto-load - .gitignore (tmp/, .ai-instructions.conf)"
53 lines
1.4 KiB
Markdown
53 lines
1.4 KiB
Markdown
# Mermaid Diagram Instructions
|
|
|
|
## Color Contrast — CRITICAL
|
|
|
|
All Mermaid diagrams MUST have sufficient color contrast. AI-generated diagrams often fail this.
|
|
|
|
**Rule**: always pair background with explicit text color.
|
|
|
|
| Background type | Text color |
|
|
|----------------|------------|
|
|
| Light (`#e6ffe6`, `#ffcccc`, `#fff3cd`) | `color:#000` |
|
|
| Dark (`#009900`, `#cc0000`, `#0055cc`) | `color:#fff` |
|
|
| Default (no fill) | no color needed |
|
|
|
|
```mermaid
|
|
graph LR
|
|
A[Input]:::good --> B[Process]:::bad --> C[Output]:::good
|
|
classDef good fill:#009900,color:#fff
|
|
classDef bad fill:#cc0000,color:#fff
|
|
```
|
|
|
|
**Never**:
|
|
```
|
|
style NodeA fill:#ffcccc ❌ no text color — unreadable
|
|
style NodeB fill:#66ff66 ❌ bright color, no contrast defined
|
|
```
|
|
|
|
---
|
|
|
|
## Size
|
|
|
|
- **Abstract diagram**: max 5-7 nodes — full scope, high level
|
|
- **Section diagrams**: max 3-5 nodes — one subsystem only
|
|
- Too many arrows = diagram is wrong scope, split it
|
|
|
|
---
|
|
|
|
## When to Use What
|
|
|
|
| Situation | Use |
|
|
|-----------|-----|
|
|
| Flows, sequences, architecture | Mermaid `graph` or `sequenceDiagram` |
|
|
| File/folder structure | ASCII tree |
|
|
| Timeline | Mermaid `gantt` |
|
|
| Both structure and flow needed | Both, separately |
|
|
|
|
---
|
|
|
|
## If Diagram Would Be Too Complex
|
|
|
|
Do not simplify by removing important nodes.
|
|
Instead: split into two diagrams — one high-level, one zoomed-in detail.
|