Get started
Colour themes
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 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.
Plotwork
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=violetnode db database "Orders DB"node events queue "Events" tone=orangenode done service "Confirmed" tone=green icon=status:successnode failed service "Payment failed" tone=red
shopper -> api : "places order"api -> idp : "checks token" role=identityapi -> db : "writes" role=dataapi -> events : "emits" role=asyncapi -> paidpaid -> done : "yes"paid -> failed : "no"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.
Plotwork
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=violetnode db database "Orders DB"node events queue "Events" tone=orangenode done service "Confirmed" tone=green icon=status:successnode failed service "Payment failed" tone=red
shopper -> api : "places order"api -> idp : "checks token" role=identityapi -> db : "writes" role=dataapi -> events : "emits" role=asyncapi -> paidpaid -> done : "yes"paid -> failed : "no"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.
Plotwork
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=violetnode db database "Orders DB"node events queue "Events" tone=orangenode done service "Confirmed" tone=green icon=status:successnode failed service "Payment failed" tone=red
shopper -> api : "places order"api -> idp : "checks token" role=identityapi -> db : "writes" role=dataapi -> events : "emits" role=asyncapi -> paidpaid -> done : "yes"paid -> failed : "no"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.
Plotwork
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=violetnode db database "Orders DB"node events queue "Events" tone=orangenode done service "Confirmed" tone=green icon=status:successnode failed service "Payment failed" tone=red
shopper -> api : "places order"api -> idp : "checks token" role=identityapi -> db : "writes" role=dataapi -> events : "emits" role=asyncapi -> paidpaid -> done : "yes"paid -> failed : "no"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.
Plotwork
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=violetnode db database "Orders DB"node events queue "Events" tone=orangenode done service "Confirmed" tone=green icon=status:successnode failed service "Payment failed" tone=red
shopper -> api : "places order"api -> idp : "checks token" role=identityapi -> db : "writes" role=dataapi -> events : "emits" role=asyncapi -> paidpaid -> done : "yes"paid -> failed : "no"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.
Plotwork
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=violetnode db database "Orders DB"node events queue "Events" tone=orangenode done service "Confirmed" tone=green icon=status:successnode failed service "Payment failed" tone=red
shopper -> api : "places order"api -> idp : "checks token" role=identityapi -> db : "writes" role=dataapi -> events : "emits" role=asyncapi -> paidpaid -> done : "yes"paid -> failed : "no"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).
Plotwork
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=violetnode db database "Orders DB"node events queue "Events" tone=orangenode done service "Confirmed" tone=green icon=status:successnode failed service "Payment failed" tone=red
shopper -> api : "places order"api -> idp : "checks token" role=identityapi -> db : "writes" role=dataapi -> events : "emits" role=asyncapi -> paidpaid -> done : "yes"paid -> failed : "no"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, 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 | The header line and its options |
| Brand themes | An organisation's own colours, which win over theme= |
| Repository settings | defaults.theme for every diagram in a repository |
| Language reference | Every option, tone and diagnostic code |