nathan
417501dbd1
- Add Frank v6 core personality and base commands - Install 7 reasoning skills (CRAFT, CoT, ToT, RAG, Markdown, Mermaid, Advanced Reasoning) - Install 5 specialties (DevOps, ITIL, Data Analysis, Prompt Engineering, SCCM) - Update copilot-instructions.md with v6 integration guide - Add comprehensive architecture documentation - Migrate style.mermaid.instructions.md from instructions/ to skills/ - Remove deprecated .github/instructions/ files (migrated to skills/) - Remove obsolete create-commit.msg.prompt.md
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 |
|