Create Mermaid diagrams following project conventions: domain-based organization, filename prefixes by diagram type, and software engineering best practices. Trigger: When creating diagrams, flowcharts, sequence diagrams, ER diagrams, or any visual documentation in Mermaid.
.mmd files under docs/diagrams/| Skill | Purpose | Path |
|---|---|---|
project-docs | File organization, docs/diagrams/ structure, naming conventions | ../project-docs/SKILL.md |
corporate-colors | Catppuccin palette for optional color coding |
../corporate-colors/SKILL.mdDiagrams live in docs/diagrams/, organized by software domain (not diagram type):
docs/diagrams/
├── auth/
│ ├── flow-login.mmd
│ ├── seq-oauth-google.mmd
│ └── er-users.mmd
├── payments/
│ ├── flow-checkout.mmd
│ └── state-payment-lifecycle.mmd
├── booking/
│ └── flow-reservation.mmd
└── architecture/ # Cross-cutting, system-level diagrams
├── c4-system-context.mmd
└── deployment-gcp.mmd
Why by domain? When working on a feature, you want everything related in one place. The diagram type is encoded in the filename prefix so you can still filter across domains.
User authentication, login, OAuth → auth/
Payment processing, Flow.cl, billing → payments/
Reservations, scheduling, availability → booking/
Push notifications, emails, alerts → notifications/
Pet profiles, caretaker profiles → profiles/
System-level, deployment, infra, C4 → architecture/
Format: {type-prefix}-{descriptive-name}.mmd
| Prefix | Diagram type |
|---|---|
flow- | Flowchart / process flow |
seq- | Sequence diagram |
er- | Entity-relationship |
class- | Class diagram |
state- | State diagram |
c4- | C4 model diagram |
gantt- | Gantt chart |
Every diagram MUST start with two comment lines:
%% Short description in Spanish
%% Dominio: {domain} | Tipo: {type}
✅ userOpen[Usuario abre la app]
❌ A[Usuario abre la app]
validatePayment[Validar pago] --> processCharge[Procesar cobro]
| Arrow | Meaning |
|---|---|
--> | Normal flow |
-.-> | Optional / async |
==> | Critical path |
--x | Error / failure |
Use subgraphs to separate: mobile, API, external services, databases. See assets/example-subgraphs.mmd.
Use Catppuccin Latte colors from corporate-colors skill. See assets/example-styles.mmd.
Reference examples for each diagram type in assets/:
| File | Type | Shows |
|---|---|---|
example-flow.mmd | Flowchart | User journey with decisions |
example-seq.mmd | Sequence | API interaction with Flow.cl |
example-er.mmd | ER | Core data model |
example-state.mmd | State | Booking lifecycle |
example-subgraphs.mmd | Flowchart | Bounded contexts |
example-styles.mmd | Flowchart | Catppuccin color coding |
# Create a new diagram domain directory
mkdir -p docs/diagrams/{domain}
# Preview (requires: npm install -g @mermaid-js/mermaid-cli)
mmdc -i docs/diagrams/{domain}/{diagram}.mmd -o docs/diagrams/{domain}/{diagram}.svg
# Batch render all diagrams to SVG
find docs/diagrams -name '*.mmd' -exec sh -c 'mmdc -i "$1" -o "${1%.mmd}.svg"' _ {} \;
# Validate syntax (dry run)
mmdc -i docs/diagrams/{domain}/{diagram}.mmd -o /dev/null
docs/diagrams/{domain}/{prefix}-{name}.mmdmmdc or GitHub/IDE preview