T02: Nodes and Shapes

2.2.1 Why Nodes Matter

In a flowchart, nodes represent states, actions, decisions, or system components. If edges define flow, nodes define meaning.

Well-designed nodes:

• Improve readability

• Convey semantic intent

• Reduce ambiguity

• Make architecture self-explanatory

In Mermaid, nodes are defined by combining:

NodeID[Label]

The bracket style determines the shape.

---

2.2.2 Basic Node Structure

Minimum syntax:

Here:

• A → internal identifier

• [Start] → visible text

If you omit the label:

Mermaid automatically creates rectangular nodes named A and B.

However, explicit labels are recommended for production diagrams.

---

2.2.3 Standard Rectangle Node

Default shape:

[Text]

Example:

Use this for:

• Processes

• System components

• Standard steps

---

2.2.4 Rounded Rectangle

Syntax:

(Text)

Example:

Rounded nodes are commonly used for:

• Start/End states

• Entry/Exit points

---

2.2.5 Circle Node

Syntax:

((Text))

Example:

Often used for:

• Start markers

• Terminal points

• Event triggers

---

2.2.6 Diamond (Decision Node)

Syntax:

{Text}

Example:

Decision nodes:

• Represent branching logic

• Require labeled outgoing edges

• Are critical in workflow modeling

---

2.2.7 Subroutine Node

Syntax:

[[Text]]

Example:

Use subroutine nodes to represent:

• Reusable modules

• External systems

• Encapsulated processes

---

2.2.8 Advanced Shape Variants

Mermaid also supports extended shapes.

Parallelogram (Input/Output)

[/Text/]

Example:

---

Asymmetric Shape

>Text]

Example:

---

2.2.9 Combining Shapes in a Workflow

Let’s build a realistic example.

Scenario: Order Processing

Observe:

• Circle → Start/End

• Parallelogram → Input

• Rectangle → Process

• Diamond → Decision

• Subroutine → External module

This creates semantic clarity.

---

2.2.10 Multi-Line Labels

To improve readability, use <br> for line breaks:

Useful for:

• Long descriptions

• Detailed process steps

---

2.2.11 Explicit Node ID with Custom Text

You can define ID separately from label:

Best practice:

• Keep IDs short

• Keep labels descriptive

Example:

AuthService[Authentication Service]

Instead of:

A[Authentication Service]

This improves maintainability.

---

2.2.12 Reusing Nodes

Mermaid automatically reuses nodes if IDs match.

Example:

Creates bidirectional reference.

Important:

• Reusing IDs unintentionally can break diagrams.

---

2.2.13 Node Styling (Preview)

Basic styling:

This changes:

• Background color

• Border

• Thickness

Full styling is covered in advanced sections, but understanding node customization starts here.

---

2.2.14 Refactoring Example (Hands-On)

Start with a basic diagram:

Now improve clarity using shapes:

Notice the improvement in semantic clarity.

---

2.2.15 Common Beginner Mistakes

1. Mixing up brackets

2. Forgetting to label decision branches

3. Overusing shapes unnecessarily

4. Using single-letter IDs in large diagrams

Poor practice:

A --> B --> C

Better:

User --> API --> Database

---

2.2.16 Design Guidelines

For professional diagrams:

• Use circle for start/end

• Use diamond strictly for decisions

• Use rectangle for processes

• Use subroutine for external modules

• Avoid excessive shape variation

• Maintain naming consistency

Think semantically, not visually.

---

2.2.17 Practice Exercise

Build a Registration Flow with:

• Start node

• User input node

• Validation process

• Decision node

• Success and Failure paths

• End node

Constraints:

• Use at least four different shapes

• Add labeled branches

• Ensure clarity without styling

---

2.2.18 Key Takeaways

Nodes define structure and meaning in flowcharts.

Mastering:

• Node identifiers

• Shape syntax

• Semantic usage

• Proper labeling

is essential for building maintainable and professional Mermaid diagrams.

In the next topic, we will explore Links and Direction, and how connections influence structural layout and readability.