/// getting-started

Colors

PDS spends colour like a budget, not a palette. Most of the interface is black, white, and gray; colour is reserved for the handful of moments that carry meaning. Restraint is what makes those moments read.

The colour budget

A PDS surface aims for roughly this split, measured by area:

~70%

Black / canvas

The ground the interface sits on. In dark mode it is near-black; in light mode, near-white. It is the default, and it does most of the work.

~29%

White & gray

Text, hairlines, ghost fills, and controls — the entire structural vocabulary, drawn in monochrome. This is where the system lives.

<1%

Colour

The accent signal and the status tones combined. If colour is creeping past a percent of the screen, something is miscategorised.

Accent is not a status

Two colour roles exist and they never overlap. The accent is the single reserved signal — it marks focus rings, the one live number, and the selected item, and it changes with data-accent. The status tones carry meaning about state, and they are fixed. Keeping them separate is what lets a green accent coexist with a red “failed” badge without the two ever being confused.

The rule

The accent is never a button fill and never a status. Status is never encoded in colour alone — a badge always carries a text label or icon, so it survives colour-blindness and grayscale.

The status tones

Five tones cover every state. They appear as Badge, Callout, and Banner tints and as StatusDot fills — each a tinted background with an AA-readable foreground, in both themes. The tone prop selects one; there is no color prop by design.

Tone	Example	Use for
`success`	Deployed	A completed, healthy, or passing state.
`warning`	Quota 90%	Degraded, nearing a limit, or needs attention.
`danger`	Failed	Failed, blocked, or destructive.
`info`	In review	Neutral information — distinct from the accent.
`neutral`	Idle	Inert, off, or unremarkable status.

Note that info and neutral are distinct: info is a coloured, attention-worthy note; neutral is inert gray. Do not use info as a stand-in for the accent.

Environment colours

A third, narrow colour role marks which environment a surface belongs to, set via data-env and read through the single --pds-color-env token. It is intentionally loud — you should never wonder whether you are about to run a command against production.

dev
staging
prod

Env	Reads as
`dev`	Slate — low-stakes local and preview builds.
`staging`	Amber — pre-production; look before you leap.
`prod`	Red — production; every action is real.