Using Mermaid for requirements and specification documentation

Requirements documentation is where good intentions go to die. Word docs and spreadsheets age fast, testers build against stale specs, and developers rediscover ambiguities after weeks of coding. Mermaid won't solve every problem, but it can keep behavioral requirements visible and unambiguous by embedding them as diagrams that live alongside your code.

The problem with text-only specs

Traditional requirements docs suffer from several issues:

• Static — a flowchart buried in a Word doc gets overlooked
• Silent drift — the behavior changes in code; the spec doesn't
• Jargon gaps — developers, testers, and product talk past each other
• Hard to review — stakeholders don't read 50 pages

Diagrams alone don't fix these, but they make requirements visible.

How Mermaid fits requirements workflows

Mermaid is lightweight enough to live in version control (Git diffs are readable), but visual enough to force specificity. Use it for three core requirement types.

1. User flows and happy paths

When you need to specify "what happens when the user does X," sequence diagrams excel:

sequenceDiagram
    actor User
    participant Web as Web App
    participant API as Backend API
    participant DB as Database
    
    User->>Web: Click "Checkout"
    Web->>API: POST /orders (items, address)
    API->>DB: INSERT order (status: pending)
    API->>API: Generate invoice PDF
    API-->>Web: 200 OK {order_id, invoice_url}
    Web->>User: Show confirmation + print button
    Note over User: Order is live in system

This is testable: testers write test cases that trace this path. Developers use it as an acceptance criterion. QA verifies each arrow.

2. Error handling and edge cases

Flowcharts are best for branching logic:

flowchart TD
    A[User submits form] --> B{Fields valid?}
    B -->|No| C[Show field errors]
    C --> A
    B -->|Yes| D[Submit to backend]
    D --> E{Server response?}
    E -->|200 OK| F[Save to DB]
    F --> G[Show success]
    E -->|4xx error| H[Show user-friendly message]
    E -->|5xx error| I[Log to Sentry, show retry button]
    H --> A
    I --> A

This forces you to answer: "What do we do if the database is down? If the user hits submit twice? If validation is slow?"

3. State-driven behavior

When a feature has clear states (e.g., an order: pending → processing → shipped → delivered), state diagrams make it explicit:

stateDiagram-v2
    [*] --> Pending: Order created
    Pending --> Processing: Payment confirmed
    Processing --> Shipped: Warehouse notified
    Shipped --> Delivered: Carrier event received
    Shipped --> Returned: Customer initiates return
    Returned --> Refunded: Items inspected
    Refunded --> [*]
    
    Processing --> Cancelled: Cancel requested
    Pending --> Cancelled: Cancel requested
    Cancelled --> [*]

This is your source of truth for state transitions. Any code that doesn't follow this diagram is a bug.

Best practices for requirement diagrams

1. One diagram per requirement, or one per user story.

A single 50-node flowchart is a requirements doc, not a diagram. Keep each diagram to 6–12 nodes if possible. If it gets bigger, split it.

2. Label edges with the decision or condition.

flowchart TD
    A{Is user logged in?}
    A -->|Yes| B[Show dashboard]
    A -->|No| C[Show login]

The edge label is the requirement. Be specific: "Yes" is too vague. "User has valid session token" is better.

3. Embed in your README or docs alongside code.

## Order checkout flow

When a user submits an order:

[embedded diagram]

### Implementation notes
- See `api/orders.ts` for the POST endpoint
- Payment processing uses Stripe (lib/stripe.ts)
- Inventory updates are async via SQS

Link the diagram to the code. Now when someone reviews a PR, they see both.

4. Version diagrams with your code.

Store requirement diagrams in version control, in the same folder as the feature code:

features/
  checkout/
    checkout.md          <- requirements
    checkout.ts          <- implementation
    checkout.test.ts     <- tests

Git diffs will show if behavior changed. Code review catches spec drift.

5. Review diagrams in PR-level requirements.

Before code review, ask: "Does this code match the diagram?" If the diagram is outdated, update it in the same PR.

Example: Payment refund requirements

Here's what a complete requirement spec looks like, combining flowchart, state diagram, and prose:

Story: As a customer, I want to request a refund so I can recover my money if the order doesn't arrive.

Behavior:

flowchart TD
    A[Order delivered] --> B[Customer views order]
    B --> C{Customer clicks refund?}
    C -->|No| D[Order closed]
    C -->|Yes| E{Days since delivery?}
    E -->|≤ 30 days| F[Refund approved]
    E -->|> 30 days| G[Refund denied - expired]
    F --> H[Process refund to original payment method]
    H --> I[Notify customer]
    G --> I

State changes:

stateDiagram-v2
    Delivered --> RefundRequested: Customer submits
    RefundRequested --> RefundApproved: Within 30 days
    RefundRequested --> RefundDenied: After 30 days
    RefundApproved --> Refunding: Stripe processes
    Refunding --> Refunded: Funds arrive in 3–5 days
    RefundDenied --> Closed: No further action

Acceptance criteria:

• Refund button disabled after 30 days from delivery date
• Approved refunds show in system within 1 hour
• Customer receives email with refund status and ETA
• Stripe webhook updates refund status in real time

Now testers, developers, and product managers are all looking at the same picture.

Tooling integration

MermaidCreator: Use the visual editor to draft requirement diagrams with product stakeholders. Export as Mermaid, commit to Git.

CI/CD: Mermaid diagrams render in GitHub, so requirement diagrams show up in PRs automatically (if you use .md or .mmd files).

Markdown: Embed diagrams in your wiki, Markdown docs, or static site. They're future-proof — no tool vendor lock-in.

FAQ

Q: Isn't this just more documentation to maintain? A: Yes, but it's a lightweight format that lives in Git. If the code changes and the diagram doesn't, Git diff reveals the drift. That's better than a stale Word doc.

Q: Should every requirement be a diagram? A: No. Use diagrams for behavioral specs — flows, state machines, interactions. Use prose for non-functional requirements (performance, security, accessibility).

Q: What if the requirement is still fuzzy? A: That's a feature. Trying to diagram something reveals that it's not clear. Nail down the ambiguity before coding.

Q: Can we generate code from these diagrams? A: Not reliably. Mermaid is a spec tool, not a code-generation tool. Use the diagram as a test spec and a code review checklist instead.

Ready to bring diagrams into your requirements process? Start with a sequence diagram for your next user story and see how it clarifies the discussion.