mermaid-diagrams

When to Use

• Creating any visual diagram for the project
• Documenting flows, sequences, data models, or architecture
• Adding .mmd files under docs/diagrams/

---

Dependencies

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.md

---

File Placement

Diagrams 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.

Choosing the Domain Subdirectory

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/

---

Filename Convention

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

---

Critical Patterns

1. Title Comments (mandatory)

Every diagram MUST start with two comment lines:

%% Short description in Spanish
%% Dominio: {domain} | Tipo: {type}

2. Node IDs: Descriptive English camelCase

✅  userOpen[Usuario abre la app]
❌  A[Usuario abre la app]

3. Labels in Spanish, IDs in English

validatePayment[Validar pago] --> processCharge[Procesar cobro]

4. Arrow Styles

Arrow	Meaning
-->	Normal flow
-.->	Optional / async
==>	Critical path
--x	Error / failure

5. Subgraphs for System Boundaries

Use subgraphs to separate: mobile, API, external services, databases. See assets/example-subgraphs.mmd.

6. Keep Diagrams Focused

• One diagram = one concept
• Flowcharts: max ~15 nodes, split if larger
• Sequence diagrams: max ~6 participants, split by interaction boundary

7. Color Coding (optional)

Use Catppuccin Latte colors from corporate-colors skill. See assets/example-styles.mmd.

---

Examples

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

---

Commands

# 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

---

Checklist

• File at docs/diagrams/{domain}/{prefix}-{name}.mmd
• Title comment on lines 1-2
• Descriptive English camelCase node IDs
• Spanish labels
• Consistent arrow styles
• Subgraphs for system boundaries
• Focused (not overloaded)
• Renders correctly with mmdc or GitHub/IDE preview