PlantUML Notes, Legends, and Annotations

Notes, Legends, and Annotations in PlantUML

Notes and annotations transform a basic diagram into a self-documenting artifact. They provide context that the structural elements alone cannot convey.

Floating Notes

note "This is a floating note" as N1

Floating notes are not attached to any element. Use them for general diagram-level observations.

Linked Notes (Sequence Diagrams)

Alice -> Bob: Request
note left of Alice
  Alice sends the initial
  request with auth token
end note

note right of Bob
  Bob validates the token
  before processing
end note

note over Alice, Bob
  This exchange happens
  over HTTPS
end note

Left/Right: Place notes beside a participant. Over: Span a note across multiple participants to annotate an entire interaction.

Linked Notes (Class Diagrams)

class User {
  +name: String
}

note right of User
  Represents both regular
  users and admin users.
  See UserRole enum.
end note

note "Shared between\nall diagram types" as N2
User .. N2

Headers and Footers

header Last updated: 2024-03-15
footer Page %page% of %lastpage%

title System Architecture Overview
caption Figure 1: Production deployment topology

Headers, footers, titles, and captions add professional metadata. The %page% variable is useful for multi-page PDF exports.

Legends

legend right
  | Color | Meaning |
  |<#LightBlue>| Frontend |
  |<#LightGreen>| Backend |
  |<#LightYellow>| Database |
endlegend

Legends explain color coding and symbols. Place them with legend left, legend right, or legend center.

Conditional Formatting with Stereotypes

class Service <<critical>> {
  +process(): void
}

class Helper <<utility>> {
  +format(): String
}

skinparam class {
  BackgroundColor<<critical>> #FFCDD2
  BackgroundColor<<utility>> #E8F5E9
}

Stereotypes combined with skinparam let you create a visual vocabulary. Mark critical services in red, utilities in green, deprecated components in gray.