Colours and families

A node’s family sets the stripe along the top of its card and the tint of its icon tile. There are seven: blue, amber, violet, green, teal, red and slate. Kinds choose a family for you, so every database is green and every service is blue without any work.

Loading diagram…

Choosing a family

nodes:
  ledger: { kind: service, family: violet, title: Ledger }

family on a node wins over the kind’s. Groups, kinds and custom kinds accept family too:

kinds:
  ledger: { icon: lucide:book-open, family: amber }

groups:
  billing: { label: Billing, family: amber }

Use a family to mean something, and keep it consistent: for instance, amber for anything that touches money. A diagram where every box is a different colour says nothing.

The families

Family	Default for	Light accent	Dark accent
`blue`	Services, gateways, workers, containers, functions	`#2358c4`	`#7ba6ff`
`green`	Databases, caches, storage	`#23744a`	`#74d39b`
`amber`	Queues	`#a85a06`	`#f2a759`
`violet`	Agents, networks, virtual machines	`#6a43bd`	`#b9a0f5`
`teal`	Auth and monitoring	`#0a6f8f`	`#55bcdb`
`slate`	Clients, users, external systems	`#566275`	`#9aa5b5`
`red`	Nothing by default. For things that need attention.	`#a8372d`	`#e8837a`

Recolouring a family

Each family is two tokens: --docspp-<family> for the accent and --docspp-<family>-bg for the tinted background. Override both, and every node of that family follows.

Default
Services in orange

Everything in one picture. Letters on the edges match the interfaces table underneath.

Scenario

HTTP request / responseData accessPersistent channel (websocket, gRPC)Queue / brokerDashed: planned

Loading diagram…

Key	From → To	Kind	Auth	What travels
A	Shopper browser → CDN	http	—	HTTPS
B	CDN → API gateway	http	—	—
C	API gateway → Keycloak	data	client credentials	signing keys
D	API gateway → catalog-service	http	—	/products
E	API gateway → cart-service	http	—	/cart
F	API gateway → order-service	http	—	/orders
G	catalog-service → Redis	data	—	cache
H	catalog-service → PostgreSQL	data	—	—
I	cart-service → Redis	data	—	—
J	order-service → PostgreSQL	data	—	—
K	order-service → Stripe	channel	API key	payment intent
L	order-service → RabbitMQ	queue	—	order.created
M	RabbitMQ → notification-worker	queue	—	—

Everything in one picture. Letters on the edges match the interfaces table underneath.

Scenario

HTTP request / responseData accessPersistent channel (websocket, gRPC)Queue / brokerDashed: planned

Loading diagram…

Key	From → To	Kind	Auth	What travels
A	Shopper browser → CDN	http	—	HTTPS
B	CDN → API gateway	http	—	—
C	API gateway → Keycloak	data	client credentials	signing keys
D	API gateway → catalog-service	http	—	/products
E	API gateway → cart-service	http	—	/cart
F	API gateway → order-service	http	—	/orders
G	catalog-service → Redis	data	—	cache
H	catalog-service → PostgreSQL	data	—	—
I	cart-service → Redis	data	—	—
J	order-service → PostgreSQL	data	—	—
K	order-service → Stripe	channel	API key	payment intent
L	order-service → RabbitMQ	queue	—	order.created
M	RabbitMQ → notification-worker	queue	—	—

.docspp {
  --docspp-blue: #c2410c;
  --docspp-blue-bg: #ffedd5;
}
:root[data-theme='dark'] .docspp {
  --docspp-blue: #fb923c;
  --docspp-blue-bg: #3b1d0a;
}

Pick a darker accent for light mode and a lighter one for dark mode, so the stripe and icon keep enough contrast on both backgrounds. The -bg token should be a very light tint in light mode and a very dark one in dark mode.

Status is not a family

A node’s status (planned, legacy, optional) is drawn with a dashed outline and a tag, whatever its family. The colours for warnings and errors come from the status tokens (--docspp-warn, --docspp-bad), not from a family. See theming.