Skip to content
docspp

Theming

Diagrams follow the site’s light and dark mode. To restyle them, override tokens: CSS variables that start with --docspp-. Nothing in the renderer uses a colour that is not a token.

Pick a palette to see the same diagram restyled. The snippet under each is the only CSS involved.

Scenario

The shopper pays. We write the payment down first, charge the card second, and tell the rest of the system last, so a crash never loses money.

HTTP request / responseData accessPersistent channel (websocket, gRPC)Queue / brokerDashed: planned
Loading diagram…
IRecord itbefore any money moves
1
Web app→Payments APIPOST /payments

The request carries an idempotency key, so a retry cannot charge twice.

2
Payments API→Ledger databaseINSERT payment (pending)
IICharge the card
3
Payments API→Stripecreate payment intent
4
Stripeauthorise card

This is the only step we do not control, and the slowest one.

5
Stripe→Payments APIsucceeded
IIIFinish
6
Payments API→Ledger databasemark paid
7
Payments API→RabbitMQpayment.succeeded
8
Payments API→Web app201 Created
9
RabbitMQ→Receipt mailerpayment.succeededplanned

Receipts are planned. Today the shopper only sees the on-screen confirmation.

src/styles/custom.css
/* Nothing to write. The defaults follow the site theme. */

Where to put the CSS

Section titled “Where to put the CSS”

Override tokens under .docspp in src/styles/custom.css (the file the starter already loads). To style only some diagrams, scope the rule to a wrapper:

.my-team-docs .docspp {
  --docspp-accent: #7a4ec4;
}
<div class="my-team-docs">
  <Diagram name="checkout" />
</div>

For dark mode, add a second rule. The site sets data-theme on the page, and the renderer follows it:

.docspp {
  --docspp-accent: #7a4ec4;
}
:root[data-theme='dark'] .docspp {
  --docspp-accent: #b79bf0;
}

Tokens

Section titled “Tokens”

Surfaces and text

Section titled “Surfaces and text”
Token Used for
--docspp-bg The canvas and frame background.
--docspp-surface Cards, buttons, panels.
--docspp-surface-2 Table headers, phase bands, hover states.
--docspp-zone The fill of top-level groups.
--docspp-ink Primary text and the default line colour.
--docspp-muted Secondary text and data lines.
--docspp-line Borders and hairlines.
--docspp-tile The tile behind coloured brand logos.
--docspp-shadow The shadow under cards and panels.

Accent and status

Section titled “Accent and status”
Token Used for
--docspp-accent Highlights, the active step, packets, requests.
--docspp-accent-soft Soft accent backgrounds, such as a selected step.
--docspp-tunnel The tunnel edge kind.
--docspp-ok, --docspp-ok-soft Responses and success.
--docspp-warn, --docspp-warn-soft Events, planned and legacy tags.
--docspp-bad, --docspp-bad-soft Errors.

Behaviour

Section titled “Behaviour”
Token Meaning
--docspp-dim How faded unrelated items get while a reader focuses a box or a scenario plays. 0.5 by default; 1 turns fading off.

Fonts

Section titled “Fonts”
Token Meaning
--docspp-sans Text. Defaults to IBM Plex Sans, then the system font.
--docspp-mono Subtitles, step labels, the interfaces table. Defaults to IBM Plex Mono.

The starter loads IBM Plex through @fontsource/ibm-plex-sans and @fontsource/ibm-plex-mono. Change the fonts by loading your own and setting these two tokens.

Colour families

Section titled “Colour families”

Each family has two tokens: the accent and a tinted background. See colours.

Matching your site

Section titled “Matching your site”

If your docs site already has a palette, map the tokens to it once, and diagrams follow when you change it:

.docspp {
  --docspp-accent: var(--sl-color-accent);
  --docspp-ink: var(--sl-color-white);
  --docspp-surface: var(--sl-color-black);
}

The full list of defaults is at the top of packages/react/src/styles.css in the repository.

Found a mistake? Open an issue.Every diagram here is a YAML file drawn by docspp. MIT license.