# Colour themes

> Page: https://docs.plotwork.dev/colour-themes. Index of every page: https://docs.plotwork.dev/llms.txt

Draw a diagram in another palette by writing `theme=` on its header. Every kind takes it, every theme holds a light and a dark scheme, and the colours keep their meaning in all of them.

## TL;DR

| Question | Answer |
|---|---|
| How do I choose one? | Write `theme=<name>` on the header line, such as `flow "Checkout" theme=ocean`. In the portal's editor, choose it from the Look menu over the canvas. |
| Which themes are there? | `plotwork`, `slate`, `ocean`, `forest`, `sunset`, `mono`, `contrast`. `plotwork` is the default. |
| Does it change light and dark? | No. Light, dark, or one picture that follows the reader (`auto`) is chosen where the picture is drawn. A theme holds both schemes. |
| Do the colours keep their meaning? | Yes. Red is an error, green success and amber a warning in every theme, and line roles keep their colours' roles. |
| Is the text readable? | Every text colour reaches 4.5:1 on every background it is drawn on, in every theme and both schemes, and 7:1 in `contrast`. A test checks each pair. |
| Can a repository set one for every diagram? | Yes: `defaults.theme` in `plotwork.config.json`. A header's own `theme=` wins. The light or dark picture is `defaults.scheme`. |
| What about my organisation's brand? | Where a [brand theme](https://docs.plotwork.dev/brand-themes.md) applies, the brand wins and `theme=` is not used. |

## 1. The themes

| Name | Title | Looks like |
|---|---|---|
| `plotwork` | Plotwork | The default: warm grays with clear, even tones. |
| `slate` | Slate | Cool blue-gray surfaces and calm, slightly muted tones. |
| `ocean` | Ocean | Navy ink and sea-tinted frames, with deep blues and teals. |
| `forest` | Forest | Sage frames and earthy tones: pine, moss, rust, and ochre. |
| `sunset` | Sunset | Warm stone frames with coral, plum, and dusk blue. |
| `mono` | Mono | Pure grays with muted tones, for print and quiet documents. Status colours stay. |
| `contrast` | High contrast | Black and white with strong tones and borders: text at 7:1 or more (WCAG AAA). |

A name that is not one of these is error E136, and its hint names the closest theme and lists them all. `theme=dark` is refused with a note: dark is a scheme, not a colour theme.

## 2. What a theme changes

A theme sets the same roles the default does: the card and group surfaces, the borders, the primary and secondary ink, the line colour, and the eight tones. So a diagram never has to change to change its theme.

| Kept in every theme | Why |
|---|---|
| Tone meanings | Blue, violet, aqua and orange tell parts apart; green, amber and red are success, warning and error. |
| Line roles | `role=data` is drawn in the blue tone, `identity` in violet, `async` in orange and dotted, `private` in aqua. |
| Sizes and layout | A theme changes colours only, so every box keeps the room its text needs. |
| Official cloud icons | AWS, Azure and Google Cloud icons are drawn as each vendor publishes them, on their light tile. |

## 3. Gallery

The same diagram in each theme. Switch the docs between light and dark to see both schemes.

### Plotwork

The default: warm grays with clear, even tones.

**Diagram source**

```diagram
flow "Checkout in Plotwork" direction=right theme=plotwork desc="A shopper pays through an orders API that checks a token, writes a database, and emits an event."

node shopper person "Shopper"
group app "Application" tone=blue {
  node api service "Orders API"
  node paid decision "Paid?"
}
node idp identity "Identity" tone=violet
node db database "Orders DB"
node events queue "Events" tone=orange
node done service "Confirmed" tone=green icon=status:success
node failed service "Payment failed" tone=red

shopper -> api : "places order"
api -> idp : "checks token" role=identity
api -> db : "writes" role=data
api -> events : "emits" role=async
api -> paid
paid -> done : "yes"
paid -> failed : "no"
```

*Picture: Checkout in Plotwork: 8 nodes, 7 connections. A shopper pays through an orders API that checks a token, writes a database, and emits an event.*

**Text description**

**Nodes:**

- Shopper, person
- Identity, identity
- Orders DB, database
- Events, queue
- Confirmed, service
- Payment failed, service
- Group: Application
  - Orders API, service
  - Paid?, decision

**Connections:**

- Shopper to Orders API: places order
- Orders API to Identity (identity line): checks token
- Orders API to Orders DB (stored data line): writes
- Orders API to Events (asynchronous line): emits
- Orders API to Paid?
- Paid? to Confirmed: yes
- Paid? to Payment failed: no

### Slate

Cool blue-gray surfaces and calm, slightly muted tones.

**Diagram source**

```diagram
flow "Checkout in Slate" direction=right theme=slate desc="A shopper pays through an orders API that checks a token, writes a database, and emits an event."

node shopper person "Shopper"
group app "Application" tone=blue {
  node api service "Orders API"
  node paid decision "Paid?"
}
node idp identity "Identity" tone=violet
node db database "Orders DB"
node events queue "Events" tone=orange
node done service "Confirmed" tone=green icon=status:success
node failed service "Payment failed" tone=red

shopper -> api : "places order"
api -> idp : "checks token" role=identity
api -> db : "writes" role=data
api -> events : "emits" role=async
api -> paid
paid -> done : "yes"
paid -> failed : "no"
```

*Picture: Checkout in Slate: 8 nodes, 7 connections. A shopper pays through an orders API that checks a token, writes a database, and emits an event.*

**Text description**

**Nodes:**

- Shopper, person
- Identity, identity
- Orders DB, database
- Events, queue
- Confirmed, service
- Payment failed, service
- Group: Application
  - Orders API, service
  - Paid?, decision

**Connections:**

- Shopper to Orders API: places order
- Orders API to Identity (identity line): checks token
- Orders API to Orders DB (stored data line): writes
- Orders API to Events (asynchronous line): emits
- Orders API to Paid?
- Paid? to Confirmed: yes
- Paid? to Payment failed: no

### Ocean

Navy ink and sea-tinted frames, with deep blues and teals.

**Diagram source**

```diagram
flow "Checkout in Ocean" direction=right theme=ocean desc="A shopper pays through an orders API that checks a token, writes a database, and emits an event."

node shopper person "Shopper"
group app "Application" tone=blue {
  node api service "Orders API"
  node paid decision "Paid?"
}
node idp identity "Identity" tone=violet
node db database "Orders DB"
node events queue "Events" tone=orange
node done service "Confirmed" tone=green icon=status:success
node failed service "Payment failed" tone=red

shopper -> api : "places order"
api -> idp : "checks token" role=identity
api -> db : "writes" role=data
api -> events : "emits" role=async
api -> paid
paid -> done : "yes"
paid -> failed : "no"
```

*Picture: Checkout in Ocean: 8 nodes, 7 connections. A shopper pays through an orders API that checks a token, writes a database, and emits an event.*

**Text description**

**Nodes:**

- Shopper, person
- Identity, identity
- Orders DB, database
- Events, queue
- Confirmed, service
- Payment failed, service
- Group: Application
  - Orders API, service
  - Paid?, decision

**Connections:**

- Shopper to Orders API: places order
- Orders API to Identity (identity line): checks token
- Orders API to Orders DB (stored data line): writes
- Orders API to Events (asynchronous line): emits
- Orders API to Paid?
- Paid? to Confirmed: yes
- Paid? to Payment failed: no

### Forest

Sage frames and earthy tones: pine, moss, rust, and ochre.

**Diagram source**

```diagram
flow "Checkout in Forest" direction=right theme=forest desc="A shopper pays through an orders API that checks a token, writes a database, and emits an event."

node shopper person "Shopper"
group app "Application" tone=blue {
  node api service "Orders API"
  node paid decision "Paid?"
}
node idp identity "Identity" tone=violet
node db database "Orders DB"
node events queue "Events" tone=orange
node done service "Confirmed" tone=green icon=status:success
node failed service "Payment failed" tone=red

shopper -> api : "places order"
api -> idp : "checks token" role=identity
api -> db : "writes" role=data
api -> events : "emits" role=async
api -> paid
paid -> done : "yes"
paid -> failed : "no"
```

*Picture: Checkout in Forest: 8 nodes, 7 connections. A shopper pays through an orders API that checks a token, writes a database, and emits an event.*

**Text description**

**Nodes:**

- Shopper, person
- Identity, identity
- Orders DB, database
- Events, queue
- Confirmed, service
- Payment failed, service
- Group: Application
  - Orders API, service
  - Paid?, decision

**Connections:**

- Shopper to Orders API: places order
- Orders API to Identity (identity line): checks token
- Orders API to Orders DB (stored data line): writes
- Orders API to Events (asynchronous line): emits
- Orders API to Paid?
- Paid? to Confirmed: yes
- Paid? to Payment failed: no

### Sunset

Warm stone frames with coral, plum, and dusk blue.

**Diagram source**

```diagram
flow "Checkout in Sunset" direction=right theme=sunset desc="A shopper pays through an orders API that checks a token, writes a database, and emits an event."

node shopper person "Shopper"
group app "Application" tone=blue {
  node api service "Orders API"
  node paid decision "Paid?"
}
node idp identity "Identity" tone=violet
node db database "Orders DB"
node events queue "Events" tone=orange
node done service "Confirmed" tone=green icon=status:success
node failed service "Payment failed" tone=red

shopper -> api : "places order"
api -> idp : "checks token" role=identity
api -> db : "writes" role=data
api -> events : "emits" role=async
api -> paid
paid -> done : "yes"
paid -> failed : "no"
```

*Picture: Checkout in Sunset: 8 nodes, 7 connections. A shopper pays through an orders API that checks a token, writes a database, and emits an event.*

**Text description**

**Nodes:**

- Shopper, person
- Identity, identity
- Orders DB, database
- Events, queue
- Confirmed, service
- Payment failed, service
- Group: Application
  - Orders API, service
  - Paid?, decision

**Connections:**

- Shopper to Orders API: places order
- Orders API to Identity (identity line): checks token
- Orders API to Orders DB (stored data line): writes
- Orders API to Events (asynchronous line): emits
- Orders API to Paid?
- Paid? to Confirmed: yes
- Paid? to Payment failed: no

### Mono

Pure grays with muted tones, for print and quiet documents. Status colours stay.

**Diagram source**

```diagram
flow "Checkout in Mono" direction=right theme=mono desc="A shopper pays through an orders API that checks a token, writes a database, and emits an event."

node shopper person "Shopper"
group app "Application" tone=blue {
  node api service "Orders API"
  node paid decision "Paid?"
}
node idp identity "Identity" tone=violet
node db database "Orders DB"
node events queue "Events" tone=orange
node done service "Confirmed" tone=green icon=status:success
node failed service "Payment failed" tone=red

shopper -> api : "places order"
api -> idp : "checks token" role=identity
api -> db : "writes" role=data
api -> events : "emits" role=async
api -> paid
paid -> done : "yes"
paid -> failed : "no"
```

*Picture: Checkout in Mono: 8 nodes, 7 connections. A shopper pays through an orders API that checks a token, writes a database, and emits an event.*

**Text description**

**Nodes:**

- Shopper, person
- Identity, identity
- Orders DB, database
- Events, queue
- Confirmed, service
- Payment failed, service
- Group: Application
  - Orders API, service
  - Paid?, decision

**Connections:**

- Shopper to Orders API: places order
- Orders API to Identity (identity line): checks token
- Orders API to Orders DB (stored data line): writes
- Orders API to Events (asynchronous line): emits
- Orders API to Paid?
- Paid? to Confirmed: yes
- Paid? to Payment failed: no

### High contrast

Black and white with strong tones and borders: text at 7:1 or more (WCAG AAA).

**Diagram source**

```diagram
flow "Checkout in High contrast" direction=right theme=contrast desc="A shopper pays through an orders API that checks a token, writes a database, and emits an event."

node shopper person "Shopper"
group app "Application" tone=blue {
  node api service "Orders API"
  node paid decision "Paid?"
}
node idp identity "Identity" tone=violet
node db database "Orders DB"
node events queue "Events" tone=orange
node done service "Confirmed" tone=green icon=status:success
node failed service "Payment failed" tone=red

shopper -> api : "places order"
api -> idp : "checks token" role=identity
api -> db : "writes" role=data
api -> events : "emits" role=async
api -> paid
paid -> done : "yes"
paid -> failed : "no"
```

*Picture: Checkout in High contrast: 8 nodes, 7 connections. A shopper pays through an orders API that checks a token, writes a database, and emits an event.*

**Text description**

**Nodes:**

- Shopper, person
- Identity, identity
- Orders DB, database
- Events, queue
- Confirmed, service
- Payment failed, service
- Group: Application
  - Orders API, service
  - Paid?, decision

**Connections:**

- Shopper to Orders API: places order
- Orders API to Identity (identity line): checks token
- Orders API to Orders DB (stored data line): writes
- Orders API to Events (asynchronous line): emits
- Orders API to Paid?
- Paid? to Confirmed: yes
- Paid? to Payment failed: no

## 4. Themes and brands

An organisation on Pro can set a [brand theme](https://docs.plotwork.dev/brand-themes.md), which the hosted service uses for every diagram it draws for that organisation. The brand wins over `theme=`: the organisation's look stays the same whoever wrote the diagram. The source keeps its `theme=`, so the diagram drawn by the local server, the command line or the GitHub Action, where no brand applies, keeps its theme.

## See also

| Doc | Why |
|---|---|
| [Writing diagrams](https://docs.plotwork.dev/writing-diagrams.md) | The header line and its options |
| [Brand themes](https://docs.plotwork.dev/brand-themes.md) | An organisation's own colours, which win over `theme=` |
| [Repository settings](https://docs.plotwork.dev/repository-settings.md) | `defaults.theme` for every diagram in a repository |
| [Language reference](https://docs.plotwork.dev/reference/language.md) | Every option, tone and diagnostic code |