Foundations

Color

One brand color, one pop, and three signals. Every role has a light and a dark value, and every text pairing passes WCAG AA.

#Principles

Roles, not hexComponents read --color-surface, never #ffffff. Raw values live only in tokens/.

Color is a signalTeal is yours and fine, or actionable. Amber is look at this. Red is down or wrong. Everything else is paper and ink.

Violet is rareThe pop marks what is new or current. One or two places per screen. Never status.

#The palette

Left half of each chip is light, right half is dark. Hex values are read from tokens/colors.json.

bg --color-bg Light #f7f5f0 Dark #111517 page background (paper)

surface --color-surface Light #ffffff Dark #191f22 cards, sidebar, inputs

sunken --color-sunken Light #efece4 Dark #0e1214 insets, tracks, hover fills

ink --color-ink Light #0f1419 Dark #f1eee7 primary text

muted --color-muted Light #5c5750 Dark #a39d94 secondary text, labels

line --color-line Light #e4e0d8 Dark #2a3236 card borders, dividers

line-strong --color-line-strong Light #cfc9bd Dark #3a444a inputs, secondary buttons

accent --color-accent Light #1f6b5c Dark #5cbca4 primary actions, positive change, brand. The one brand color.

accent-strong --color-accent-strong Light #175245 Dark #7fd0ba hover state of accent

accent-soft --color-accent-soft Light #e2efe9 Dark #1b2d29 tinted backgrounds, active nav

on-accent --color-on-accent Light #ffffff Dark #06201a text on an accent fill

pop --color-pop Light #5a45d6 Dark #a99cff the extra pop — marks what is new or current (latest week, a fresh insight). Sparingly: one or two places per screen, never for status.

pop-soft --color-pop-soft Light #ece9fb Dark #25214a tinted background for pop

on-pop --color-on-pop Light #ffffff Dark #100c33 text on a solid pop fill

warn --color-warn Light #9a4507 Dark #e8ad62 needs attention, the weekly action

warn-soft --color-warn-soft Light #faeddb Dark #332a1a tinted background for warn

danger --color-danger Light #9b2c2c Dark #ee9a94 decreases, destructive actions

danger-soft --color-danger-soft Light #f8e4e2 Dark #3a2321 tinted background for danger

overlay --color-overlay Light rgba(15, 20, 25, 0.42) Dark rgba(0, 0, 0, 0.6) modal and handoff backdrop

focus --color-focus Light #1f6b5c Dark #7fd0ba 2px keyboard focus ring, every interactive element

#Which color for what

Need	Role	Example
Page background	`bg`	The paper behind everything
Cards, sidebar, inputs	`surface` with a `line` border	Card, tile, field
Wells and tracks	`sunken`	Inset, rank bar track, hover fill
Text and numbers	`ink`, secondary `muted`	Headlines, labels
Primary action, ready, positive change	`accent`; hover `accent-strong`; tint `accent-soft`	● Connected
The latest, the new	`pop`, tint `pop-soft`	Latest
Needs a look, the weekly action	`warn`, tint `warn-soft`	Waiting for first report
Decreases, failures, destructive	`danger`, tint `danger-soft`	Failed
Keyboard focus	`focus`	2px ring on every interactive element
Modal backdrop	`overlay`	Handoff

The four signals side by side

Ready Needs a look Failed Latest

Code

<div class="btn-row">
  <span class="pill pill-accent">Ready</span>
  <span class="pill pill-warn">Needs a look</span>
  <span class="pill pill-danger">Failed</span>
  <span class="pill pill-pop">Latest</span>
</div>

Do

Use accent for one primary action per view
Pair every signal color with words or an arrow
Test in grayscale and in both themes

Don’t

Use accent as a theme color or for nav chrome
Use violet for status, or in more than two places
Add a new color. Propose a role in tokens/ first
Use gradients, glows, or decorative color

#Light and dark

Dark is not an afterthought. Every role has a dark value. Dark follows the OS by default and can be forced with data-theme="dark" or "light" on <html> (Settings → Appearance). Any element can opt into dark with data-theme="dark"; that is how the specimens on this site are previewed.

A new dark value has to be added in both dark blocks of the tokens (the prefers-color-scheme block and the [data-theme='dark'] block). Email previews are the exception: real email is light in both themes, so they read the --color-mail-* tokens.

#Contrast

Every text pairing the product uses meets WCAG AA (4.5:1 or better) in both themes. Check any new pairing before you add it.

Pairing	Light		Dark
`ink` on `bg` Body text on the page	Aa	17.0:1	Aa	15.8:1
`ink` on `surface` Text and numbers on cards	Aa	18.5:1	Aa	14.4:1
`muted` on `surface` Secondary text on cards	Aa	7.2:1	Aa	6.2:1
`muted` on `bg` Secondary text on the page	Aa	6.6:1	Aa	6.8:1
`muted` on `sunken` Labels inside an inset	Aa	6.1:1	Aa	7.0:1
`accent` on `surface` Links, positive change	Aa	6.3:1	Aa	7.3:1
`accent` on `bg` Links on the page	Aa	5.8:1	Aa	8.0:1
`accent` on `accent-soft` Active nav item, ready pill	Aa	5.4:1	Aa	6.3:1
`accent-strong` on `surface` Hovered link	Aa	9.0:1	Aa	9.2:1
`on-accent` on `accent` Primary button label	Aa	6.3:1	Aa	7.5:1
`on-accent` on `accent-strong` Primary button label, hovered	Aa	9.0:1	Aa	9.5:1
`warn` on `surface` Attention text	Aa	6.5:1	Aa	8.4:1
`warn` on `warn-soft` Weekly action band, waiting pill	Aa	5.6:1	Aa	7.1:1
`danger` on `surface` Decreases, errors	Aa	7.5:1	Aa	7.7:1
`danger` on `danger-soft` Destructive hover, failed pill	Aa	6.2:1	Aa	6.7:1
`pop` on `surface` “Latest” text	Aa	6.4:1	Aa	7.1:1
`pop` on `pop-soft` Latest pill	Aa	5.4:1	Aa	6.4:1
`on-pop` on `pop` Text on a solid pop fill	Aa	6.4:1	Aa	7.9:1

Computed from tokens/colors.json when the site is built. The build fails if any pairing drops below 4.5:1.