State Diagrams

What are State Diagrams?

Marmaid's State diagrams are used to describe the behavior of systems by representing states and transitions between them. They are particularly useful in software development, engineering, and process modeling. Each state represents a condition, and transitions show how one state changes to another.

Purpose

State diagrams provide:

• A clear visualization of system behavior.

• Easy identification of states and transitions.

• Simplified modeling of finite state machines.

Mermaid supports state diagrams with flexible syntax, allowing users to create dynamic and visually engaging models.

---

Creating Your First State Diagram

1. Open the Code IDE and click Apps and Agents.

2. Select Mermaid. Paradime will automatically start a new Mermaid project.

3. In the terminal that appears, use the arrow keys to select "State Diagram."

4. A new state.mmd file will be created in your editor with this starter template:

---
title: Simple sample
---
stateDiagram-v2
    [*] --> Still
    Still --> [*]
    Still --> Moving
    Moving --> Still
    Moving --> Crash
    Crash --> [*]

1. Click the eye icon (👁️) to preview your diagram.

2. Modify the .mmd file as needed.

---

Diagram Syntax Guide

States

Define states using either a simple ID or a descriptive label:

stateDiagram-v2
    state "This is a state description" as s2
    s2: Another description

Transitions

Transitions represent the movement between states using -->:

stateDiagram-v2
    s1 --> s2: Transition Label

Start and End States

Indicate start and end states with [ * ]:

stateDiagram-v2
    [*] --> s1
    s1 --> [*]

Composite States

Define states with internal sub-states:

stateDiagram-v2
    [*] --> Composite
    state Composite {
        [*] --> SubState1
        SubState1 --> SubState2
        SubState2 --> [*]
    }

Conditional Paths

Model choices or forks using <<choice>>:

stateDiagram-v2
    state choice <<choice>>
    s1 --> choice
    choice --> s2: Yes
    choice --> s3: No

---

Advanced Features

Concurrency

Represent concurrent states:

stateDiagram-v2
    [*] --> Active
    state Active {
        [*] --> SubState1
        --
        [*] --> SubState2
    }

Notes

Add notes for clarity:

stateDiagram-v2
    State1: A state with a note
    note right of State1: This is additional information.
    State1 --> State2

Styling States

Use classDef to define styles and apply them to states:

stateDiagram
    classDef highlighted fill:#f96,stroke:#333;
    State1 --> State2
    class State1 highlighted

---

Data Team Examples

Workflow Example

stateDiagram-v2
    [*] --> DataPreparation
    DataPreparation --> Analysis
    Analysis --> Visualization
    Visualization --> [*]

System State Example

stateDiagram-v2
    [*] --> Idle
    Idle --> Active
    Active --> Error
    Error --> Idle
    Error --> [*]

---

Best Practices

1. Plan Transitions: Clearly define all state transitions.

2. Use Descriptive Labels: Label states and transitions for clarity.

3. Group Related States: Use composite states for better organization.

4. Add Notes: Include notes to explain complex transitions.

5. Iterate: Continuously refine your diagram for accuracy.

---

Troubleshooting and Tips

Common Issues

• Unlinked States: Ensure all states are connected with transitions.

• Overlapping Elements: Adjust layout using composite states or direction settings.

Modular Design

Divide complex diagrams into smaller sections for readability.

---

Additional Resources

For more details, visit the official Mermaid documentation.