99d13e6e4a
- apply.sh: direct-run guard (only curl | bash allowed) - apply.sh: DEV_ROOT passed as explicit arg from bootstrap - apply.sh: .ai/ copied to dev root as real folder; projects symlink there - apply.sh: counters + detailed summary (version prev→new, templated, refreshed, no-docs) - apply.sh: find errors silenced, no crash on empty dev root - .ai-superpower: added warning comment about deletion side effects - .gitignore: .ai-instructions.conf → .ai-superpower.version - scripts/: removed (hello.sh, scan-projects-with-git.sh, verify-docs-folder.sh, add-ai-context-to-docs-folder.sh) - templates: monorepo sections split into AI instructions + developer instructions - README.md: rewritten to match current architecture and behaviour - docs/apply-requirements.md: FR-2.4, FR-3, FR-5, FR-6, FR-7, FR-8 updated - docs/apply-usecases.md: full detailed Mermaid flowchart replacing placeholder
68 lines
1.6 KiB
Markdown
68 lines
1.6 KiB
Markdown
# Mermaid Diagram Instructions
|
|
|
|
---
|
|
|
|
## Edge Labels
|
|
|
|
Use `-- "text" -->` syntax, **not** `-->|text|` syntax.
|
|
|
|
`|` inside `-->|label|` breaks parsing if the label contains a pipe character (e.g. `curl | bash`). Quoted syntax always works:
|
|
|
|
```
|
|
✅ A -- "curl | bash" --> B
|
|
❌ A -->|curl | bash| B
|
|
```
|
|
|
|
---
|
|
|
|
## 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.
|