T03: Annotations and Styling

4.3.1 Why Annotations and Styling Matter

A class diagram that is structurally correct but visually unclear is difficult to interpret.

Annotations and styling help:

• Highlight critical classes

• Clarify domain roles

• Add explanatory notes

• Improve readability

• Emphasize architectural boundaries

In Mermaid, annotations and styling allow you to enhance presentation without changing structural semantics.

Structure defines correctness. Styling improves communication.

---

4.3.2 Adding Notes to Class Diagrams

You can attach notes to classes for explanation.

Basic syntax:

note for ClassName "Text"

---

Example 1 — Simple Note

Notes are useful for:

• Domain explanation

• Constraints

• Business rules

• Clarifying assumptions

---

4.3.3 Multi-Line Notes

For more detailed documentation:

Keep notes concise. Avoid embedding large paragraphs.

---

4.3.4 Stereotypes

Stereotypes indicate special roles.

Syntax:

<<stereotype>>

Example:

classDiagram
    class User <<Entity>>
    class UserService <<Service>>
    class UserRepository <<Repository>>

Common stereotypes:

• <<Entity>>

• <<Service>>

• <<Controller>>

• <<Repository>>

• <<DTO>>

Stereotypes communicate architectural intent.

---

4.3.5 Styling Classes

You can style classes using the classDef and class keywords.

Basic syntax:

classDef styleName fill:#color,stroke:#color,stroke-width:2px
class ClassName styleName

---

Example 2 — Styling Critical Classes

This visually highlights the Payment class.

---

4.3.6 Styling Multiple Classes

classDiagram
    class User
    class Order
    class Payment

    classDef entity fill:#e6f2ff,stroke:#003366
    class User,Order entity

You can assign styles to multiple classes at once.

---

4.3.7 Styling by Architectural Layer

Example: Layered Architecture

This visually separates:

• Controller layer

• Service layer

• Repository layer

• Domain entity

Styling supports architectural storytelling.

---

4.3.8 Styling Relationships

Mermaid allows limited relationship styling using linkStyle.

Example:

classDiagram
    class A
    class B

    A --> B
    linkStyle 0 stroke:#ff0000,stroke-width:2px

linkStyle 0 refers to the first relationship declared.

Use relationship styling sparingly.

---

4.3.9 Full Example — Styled E-Commerce Model

classDiagram
    class Customer {
        int customerId
        string name
    }

    class Order {
        int orderId
        float totalAmount
    }

    class Payment {
        int paymentId
        string status
    }

    Customer "1" --> "0..*" Order : places
    Order "1" --> "1" Payment : paidBy

    classDef entity fill:#e6f2ff,stroke:#003366
    classDef critical fill:#ffe6e6,stroke:#990000,stroke-width:2px

    class Customer,Order entity
    class Payment critical

Interpretation:

• Entities styled uniformly

• Payment emphasized as critical domain component

This improves visual hierarchy.

---

4.3.10 Organizing Large Diagrams

In large systems:

• Group related classes visually

• Use consistent color coding

• Apply stereotypes for clarity

• Avoid excessive decoration

Bad styling practice:

• Too many colors

• Inconsistent themes

• Highlighting everything

Good styling practice:

• Minimal color palette

• Meaningful highlighting

• Clear legend (if needed)

---

4.3.11 Using Comments in Class Diagrams

Comments are not rendered but help maintainability.

Syntax:

%% This is a comment

Example:

Useful for collaborative diagram editing.

---

4.3.12 Refactoring Example (Hands-On)

Start simple:

Now enhance:

classDiagram
    class User <<Entity>> {
        int userId
        string email
    }

    class Order <<Entity>> {
        int orderId
        float totalAmount
    }

    User "1" --> "0..*" Order : places

    classDef entity fill:#e6f2ff,stroke:#003366
    class User,Order entity

Observe:

• Stereotypes added

• Multiplicity added

• Styling applied

• Readability improved

---

4.3.13 Common Mistakes

1. Over-styling diagrams

2. Using too many color variations

3. Styling before defining correct structure

4. Ignoring accessibility (low contrast colors)

5. Forgetting consistency across diagrams

Remember:

Structure first. Styling second.

---

4.3.14 Hands-On Exercise

Design a Banking Domain Model with:

Classes:

• Bank

• Account

• Transaction

• Customer

• Loan

Requirements:

• Use stereotypes for Entity and Service

• Apply at least two different class styles

• Highlight one critical class

• Add at least one explanatory note

Keep design clean and professional.

---

4.3.15 Best Practices

• Use styling to emphasize domain importance

• Maintain consistent color conventions

• Keep annotations concise

• Use stereotypes to indicate architecture layer

• Avoid clutter

Think of styling as:

Visual hierarchy layered over structural correctness.

---

4.3.16 Key Takeaways

Annotations and styling:

• Improve clarity

• Highlight importance

• Communicate architecture layers

• Enhance maintainability

However:

They do not replace correct modeling.

A well-structured diagram with minimal styling is better than a visually impressive but semantically incorrect one.

With this, you have completed the core foundations of Class Diagrams.

In the next chapter, we move into State Diagrams, where system state transitions become the primary modeling focus.