nathan
b5ea5b175c
Phase 1-4 Complete: Setup, Core Extraction, ITIL Specialty, Documentation - Created v6/ folder with 3-layer architecture (core + skills + specialties) - Extracted Frank.core.agent.md with universal personas and base commands - Copied 7 skill modules (CRAFT, CoT, ToT, RAG, Markdown, Mermaid, Advanced Reasoning) - Created specialty.itil.instructions.md for IT Service Management (ITIL v4) - Added comprehensive ARCHITECTURE.md with usage patterns and migration guide - Created v6/copilot-instructions.md for VS Code integration - Organized legacy DOCX files into _Frank_/docx/ subdirectory - Updated all cross-references to use v6 relative paths Design Principles: - Portability first: zero environment-specific paths - Modular composition: load only what you need - Multi-specialty support: combine domain experts - Version compatibility: all files tagged v6.0 Ref: Session plan in /memories/session/plan.md Next: Phase 3 (remaining specialties: devops, prompt-engineering, data-analysis, sccm)
156 lines
4.3 KiB
Markdown
156 lines
4.3 KiB
Markdown
---
|
|
description: "Style guide for Mermaid.js diagrams. Enforces consistency, readability, and maintainability."
|
|
applyTo: "**/*.md"
|
|
---
|
|
|
|
# Mermaid Diagram Style Guide
|
|
|
|
## 1. Introduction
|
|
This guide establishes standards for creating code-based diagrams using **Mermaid.js**. Because diagrams are treated as code, they must be clean, readable, and version-controllable.
|
|
|
|
**Core Principle:** A diagram's source code should be as readable as the rendered image.
|
|
|
|
## 2. Graph Direction
|
|
Choose the orientation based on the data flow.
|
|
* **Rule:** Use `TD` (Top-Down) for hierarchies, decision trees, and organizational charts.
|
|
* **Rule:** Use `LR` (Left-Right) for pipelines, timelines, and sequential data flows.
|
|
* **Rule:** Use `flowchart` instead of the older `graph` keyword for better rendering support.
|
|
|
|
>Example of Top-Down:
|
|
```mermaid
|
|
flowchart LR
|
|
Input --> Process --> Output
|
|
```
|
|
|
|
## 3. Node Identifiers
|
|
|
|
Separate the **Node ID** from the **Node Label**.
|
|
|
|
* **Rule:** Use semantic, `kebab-case` or `snake_case` IDs. Avoid single letters (`A`, `B`, `C`).
|
|
* **Rule:** IDs must be descriptive enough to understand links without reading the label.
|
|
* **Why:** If you change the label text later, you won't break the logic/connections.
|
|
|
|
**Good:**
|
|
|
|
```mermaid
|
|
flowchart TD
|
|
user_input[User enters credentials] --> validate_login{Valid?}
|
|
validate_login -- Yes --> db_query[(Database)]
|
|
|
|
```
|
|
|
|
**Bad:**
|
|
|
|
```mermaid
|
|
flowchart TD
|
|
A[User enters credentials] --> B{Valid?}
|
|
B -- Yes --> C[(Database)]
|
|
|
|
```
|
|
|
|
## 4. Standard Shapes
|
|
|
|
Use consistent shapes to convey meaning immediately.
|
|
|
|
* **Rule:** Use `[]` (Rectangle) for standard processes/steps.
|
|
* **Rule:** Use `{}` (Rhombus) **only** for decisions/conditionals.
|
|
* **Rule:** Use `[()]` (Cylinder) for databases and storage.
|
|
* **Rule:** Use `(())` (Circle) for start/end points or connectors.
|
|
|
|
## 5. Connections & Arrows
|
|
|
|
Keep connections clean.
|
|
|
|
* **Rule:** Use `-->` for standard flow.
|
|
* **Rule:** Use `-.->` (dotted) for optional, asynchronous, or future flows.
|
|
* **Rule:** Add text labels to arrows *only* when a decision is made or the relationship needs clarification.
|
|
* **Rule:** Use pipes `|text|` for arrow labels, not the older syntax.
|
|
|
|
```mermaid
|
|
flowchart TD
|
|
scan_start[Start Scan] -->|Success| log_entry[Log Result]
|
|
scan_start -.->|Timeout| retry_queue[Retry Queue]
|
|
|
|
```
|
|
|
|
## 6. Sequence Diagrams
|
|
|
|
For showing interactions over time.
|
|
|
|
* **Rule:** Always enable `autonumber` to make referencing steps in conversation easier.
|
|
* **Rule:** Define `participant` or `actor` aliases at the top for clarity.
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
autonumber
|
|
actor U as User
|
|
participant A as API
|
|
participant D as Database
|
|
|
|
U->>A: Request Data
|
|
A->>D: Query ID
|
|
D-->>A: Return Payload
|
|
|
|
```
|
|
|
|
## 7. Subgraphs (Grouping)
|
|
|
|
Use subgraphs to cluster related components (e.g., separating "Cloud" from "On-Prem").
|
|
|
|
* **Rule:** Indent subgraph content by **4 spaces**.
|
|
* **Rule:** Give subgraphs descriptive IDs.
|
|
* **Rule:** Label the subgraph clearly using the `subgraph ID [Label]` syntax.
|
|
|
|
```mermaid
|
|
flowchart LR
|
|
subgraph aws [AWS Cloud]
|
|
lb[Load Balancer] --> web[Web Server]
|
|
end
|
|
subgraph on_prem [Office]
|
|
user[Laptop] --> lb
|
|
end
|
|
|
|
```
|
|
|
|
## 8. Styling (Classes)
|
|
|
|
Do not use inline styles (e.g., `style A fill:#f9f`). It creates "spaghetti code."
|
|
|
|
* **Rule:** Use `classDef` at the bottom of the file to define themes.
|
|
* **Rule:** Apply classes using the `:::` operator.
|
|
* **Standard Classes:**
|
|
* `classDef failure fill:#f88,stroke:#333;`
|
|
* `classDef success fill:#8f8,stroke:#333;`
|
|
|
|
|
|
|
|
**Example:**
|
|
|
|
```mermaid
|
|
flowchart TD
|
|
build[Build Code] --> test{Tests Pass?}
|
|
test -- No --> alert[Alert Team]:::failure
|
|
test -- Yes --> deploy[Deploy]:::success
|
|
|
|
classDef failure fill:#ffcccc,stroke:#ff0000;
|
|
classDef success fill:#ccffcc,stroke:#00ff00;
|
|
|
|
```
|
|
|
|
## 9. Linting & Formatting
|
|
|
|
* **Indentation:** Use 4 spaces for nested elements.
|
|
* **Spacing:** Put spaces around arrow connectors for readability (`A --> B`, not `A-->B`).
|
|
* **Comments:** Use `%%` for comments to explain complex logic.
|
|
|
|
## 10. Quick Cheat Sheet
|
|
|
|
| Type | Syntax | Output Shape |
|
|
| --- | --- | --- |
|
|
| Process | `id[Text]` | Rectangle |
|
|
| Decision | `id{Text}` | Diamond |
|
|
| Database | `id[(Text)]` | Cylinder |
|
|
| Terminal | `id([Text])` | Rounded Pill |
|
|
| Subroutine | `id[[Text]]` | Double Border |
|
|
| Comment | `%% Text` | Invisible |
|