PlantUML Colors and Themes: A Practical Styling Guide

PlantUML colors can clarify roles, boundaries, and states without turning a diagram into a poster. The fastest approach is to begin with a built-in theme, then add only the semantic colors your diagram needs. This guide shows that workflow with examples you can paste into a renderer.

If you are still choosing a diagram type, browse the PlantUML examples hub. The styling techniques below work especially well with authentication flows; see the PlantUML sequence diagram guide.

Key Takeaways

• Use !theme for a coherent baseline and local color syntax for meaningful exceptions.
• Prefer CSS-like <style> rules for new reusable styling; PlantUML marks skinparam as deprecated, although it remains supported for compatibility.
• Treat color as a secondary signal. Labels, line styles, and shapes must still communicate the diagram in grayscale.
• Test contrast in the actual PNG, SVG, or page background where the diagram will appear.

Before You Begin

What you need:

• A PlantUML renderer or online editor
• A small diagram that already renders correctly
• Permission to use your product or documentation color palette
• About 20 minutes
• Difficulty: Beginner

Keep styling separate from modeling. First make the relationships correct; then change appearance. PlantUML's color documentation accepts named colors and hexadecimal values, while its theme documentation describes reusable themes.

To compare a theme or palette against the actual rendered output, open the OnUML editor, choose PlantUML mode, and paste one of the examples below.

Step 1: Preview the Available Colors

By the end of this step, you will have a renderer-generated color reference rather than an unreliable list copied from elsewhere.

Open the OnUML editor, choose PlantUML mode, and paste the following source:

@startuml
colors
@enduml

To find colors near a particular hue, provide a search term:

@startuml
colors chocolate
@enduml

The output is the verification: if a named color appears in the OnUML preview, the current renderer recognizes it.

Step 2: Apply Color to Individual Elements

By the end of this step, colors will represent business meaning rather than decoration.

@startuml
actor Customer #DCEBFF
participant "Web App" as Web #E8F5E9
participant "Identity Service" as IdP #FFF3CD
database "User Store" as DB #F3E5F5

Customer -> Web: Submit credentials
Web -> IdP: Verify identity
IdP -> DB: Read account
DB --> IdP: Account record
IdP --> Web: Authentication result
Web --> Customer: Show signed-in state
@enduml

Hex values are useful when a design system defines exact tokens. Named colors are easier to read in small examples. Do not encode success, warning, or failure by color alone: retain explicit message labels and participant names.

The same technique works in class diagrams:

@startuml
class Order #E8F5E9
class Payment #FFF3CD
class PaymentFailure #FDECEC

Order --> Payment : requests
Payment ..> PaymentFailure : may create
@enduml

Step 3: Start with a Built-In Theme

By the end of this step, typography, lines, and surfaces will share a coherent baseline.

@startuml
!theme spacelab

actor Customer
participant "Checkout API" as API
database Orders

Customer -> API: Place order
API -> Orders: Save order
Orders --> API: Order ID
API --> Customer: Confirmation
@enduml

Run this helper diagram in OnUML to list the themes available to the current renderer:

@startuml
help themes
@enduml

The official theme gallery is useful for comparison, but verify the chosen theme in the OnUML preview. Local paths such as ./themes are not available to the web editor, so use a built-in theme or place custom rules directly in a <style> block.

Step 4: Create Reusable CSS-Like Styles

By the end of this step, your source will define reusable rules for diagram element types.

@startuml
<style>
root {
  BackgroundColor #FFFFFF
  FontColor #172033
  LineColor #52627A
  FontName Inter
}
actor {
  BackgroundColor #DCEBFF
  LineColor #2457A7
}
participant {
  BackgroundColor #E8F5E9
  LineColor #2F6B3C
}
arrow {
  LineColor #52627A
  FontColor #172033
}
</style>

actor Customer
participant API
Customer -> API: Request
API --> Customer: Response
@enduml

PlantUML describes this CSS-like system in its style documentation. The precise selectors available can vary by diagram family and version, so render a small fixture before migrating a large style library.

Older projects frequently use skinparam:

@startuml
skinparam backgroundColor #FFFFFF
skinparam sequenceArrowColor #52627A
skinparam sequenceParticipantBackgroundColor #E8F5E9
Alice -> Bob: Compatible legacy styling
@enduml

The skinparam documentation marks the mechanism as deprecated and points toward CSS-like styling. That does not mean existing diagrams stop working; it means new shared styling should favor <style> where the target version supports it.

Step 5: Build an Accessible Palette

By the end of this step, the diagram will remain understandable when colors are hard to distinguish.

Use a small palette with explicit jobs:

PlantUML supports automatic foreground selection with a form such as #?light:dark, as documented on the color page. It can help choose between two candidates, but it is not a WCAG certification. Export the diagram, test its contrast against the real background, and check it in grayscale.

Step 6: Keep Styling Reusable in OnUML

By the end of this step, diagrams will share a maintainable set of visual rules.

Keep shared <style> rules in a source snippet that you can paste into related OnUML diagrams. After changing the snippet, preview representative sequence and class diagrams before applying it everywhere. Prefer built-in themes and inline styles over local or moving remote theme files that the web renderer cannot reproduce reliably.

For spacing, direction, and containers, styling is only half the problem. Continue with the PlantUML layout guide.

Common Mistakes to Avoid

Using too many colors. A large palette makes readers decode decoration before meaning. Limit colors to a few named roles.

Overriding every theme property. If most properties are replaced, the theme no longer provides value. Either keep the theme as a base or maintain one explicit style file.

Treating automatic text color as an accessibility test. It chooses between candidates; it does not evaluate every label, border, and export context.

Letting styling hide model errors. A beautiful arrow can still express the wrong dependency. Review semantics before presentation.

What Success Looks Like

A successful styled diagram renders with the same semantic palette across sequence and class examples, remains legible in grayscale, and requires only a theme or shared style update to change brand presentation. Its labels still explain every state without color.

Frequently Asked Questions

Can I use hex colors in PlantUML?

Yes. PlantUML accepts hexadecimal colors in many element declarations and style properties. Test the exact syntax in the diagram type and version you deploy.

Are PlantUML themes built in?

PlantUML distributes built-in themes, and help themes lists those available to the current OnUML renderer.

Should I replace every skinparam rule now?

Not necessarily. Existing diagrams can keep compatible rules, while new shared styling can move toward <style>. Migrate incrementally and compare rendered output.

Official Sources

• PlantUML colors
• PlantUML themes
• PlantUML theme gallery
• PlantUML CSS-like styles
• PlantUML skinparam

You now have a repeatable styling workflow: choose a baseline theme, add semantic colors, validate accessibility, and centralize reusable rules. Use the PlantUML examples hub to apply the system to more diagram types, then refine composition with the PlantUML layout guide.