Tokens

Every design primitive in the system: brand colours, status colours, surfaces, borders, body text, type scale, radius, shadows, motion, z-index, and focus. Each section that varies between light and dark mode shows both side by side.

Source of truth: DESIGN.md is the editable file; running task tokens regenerates tokens.css. Swatches read CSS variables — they can't drift.

Brand

Two single-value tokens — that’s the entire brand palette. No numbered shades, no -soft/-strong/-subtle variants. primary is the green for filled buttons, focus rings, and active accents. secondary is the deep blue-grey for headings, links, body emphasis, and dark fills. Brand colours are full-opacity only — alpha-modulated utilities (bg-primary/10, text-secondary/40, etc.) are forbidden. For tints, soft backgrounds, and hover states, reach for the gray scale or a semantic surface token (bg-surface-muted).

Light

#5E9268

Dark

#5a8563

primary

--color-primary

Light

#213745

Dark

#213745

secondary

--color-secondary

Status

Each status has three tokens: -bg (filled background), -fg (text), and -accent (prominent solid). Use these in place of raw Tailwind palettes when UI represents a status.

success

Light

bg #ECFDF5 · fg #047857 · accent #10B981

success

Dark

bg #022C22 · fg #6EE7B7 · accent #10B981

--color-success-bg · --color-success-fg · --color-success-accent

danger

Light

bg #FEF2F2 · fg #B91C1C · accent #EF4444

danger

Dark

bg #450A0A · fg #FCA5A5 · accent #EF4444

--color-danger-bg · --color-danger-fg · --color-danger-accent

warning

Light

bg #FFFBEB · fg #92400E · accent #F59E0B

warning

Dark

bg #451A03 · fg #FCD34D · accent #F59E0B

--color-warning-bg · --color-warning-fg · --color-warning-accent

info

Light

bg #EFF6FF · fg #1D4ED8 · accent #3B82F6

info

Dark

bg #172554 · fg #93C5FD · accent #3B82F6

--color-info-bg · --color-info-fg · --color-info-accent

neutral

Light

bg #F9FAFB · fg #374151 · accent #6B7280

neutral

Dark

bg #1F2937 · fg #D1D5DB · accent #9CA3AF

--color-neutral-bg · --color-neutral-fg · --color-neutral-accent

Surfaces

Container backgrounds. The page background is the brand's warm cream (#FAF8F4). Use these instead of hardcoded bg-white dark:bg-gray-700.

Light

#FFFFFF

Dark

#374151

surface

Cards, side trays, modals

--color-surface

Light

#FAF8F4

Dark

#101828

surface-page

Page background

--color-surface-page

Light

#F3F4F6

Dark

#1F2937

surface-muted

Nested/quieter blocks

--color-surface-muted

Light

#E5E7EB

Dark

#374151

surface-strong

Slightly darker than -muted (e.g. avatar fill)

--color-surface-strong

Borders

Containers separate via borders, not shadows.

Light

#E5E7EB

Dark

#374151

border-default

Cards, dividers, table rows

--color-border-default

Light

#F3F4F6

Dark

#1F2937

border-subtle

Quiet separators inside dense sections

--color-border-subtle

Body text

Default text colour and the muted variant for metadata.

The quick brown fox jumps over the lazy dog. Used for primary content.

Light #101828

The quick brown fox jumps over the lazy dog. Used for primary content.

Dark #F3F4F6

body

--color-body

The quick brown fox jumps over the lazy dog. Used for primary content.

Light #6B7280

The quick brown fox jumps over the lazy dog. Used for primary content.

Dark #9CA3AF

body-subtle

--color-body-subtle

Type scale

Tailwind defaults. Strict usage rules: 16px (default) for primary content, text-sm for labels and metadata, text-xs only for tiny badges. Never shrink primary content.

text-xs (12px)

The quick brown fox

Tiny badges only

text-sm (14px)

The quick brown fox

Labels, metadata, table headers

text-base (16px)

The quick brown fox

Primary content (default)

text-lg (18px)

The quick brown fox

Subheadings, standout text

text-xl (20px)

The quick brown fox

Card titles, section headings

text-2xl (24px)

The quick brown fox

Page headings (compact)

text-3xl (30px)

The quick brown fox

Page headings (full)

text-4xl (36px)

The quick brown fox

Marketing / hero only

Font weights

Plus Jakarta Sans loaded at 400/500/600/700.

font-normal (400)

The quick brown fox

Body copy

font-medium (500)

The quick brown fox

Form labels, nav items

font-semibold (600)

The quick brown fox

Section headings, card titles

font-bold (700)

The quick brown fox

Page headings, table headers

Radius

rounded-lg, rounded-xl, and rounded-2xl all resolve to 0.375rem. Pills (rounded-full) are the only round shape.

rounded-lg

0.375rem

rounded-xl

0.375rem

rounded-2xl

0.375rem

rounded-full

9999px

Shadows

Never on containers. Reserved for floating UI: dropdowns, autocomplete panels, popovers, modals on desktop.

shadow-xs

Subtle separators

shadow-sm

Lifted action chips

shadow-md

Tooltips, toasts

shadow-lg

Dropdowns, modals

Motion

Three perceptual tiers plus the project's two easing curves. Hover the boxes to preview.

Hover me

--motion-fast

0.15s · Hover, fade-in

Hover me

--motion-default

0.25s · Tab underlines, accordion

Hover me

--motion-slow

0.3s · Side tray, modal show/hide

Hover me

--motion-deliberate

0.5s · Page transitions

--easing-default: ease-out · --easing-emphasis: cubic-bezier(0.1, 0.5, 0.1, 1)

Z-index

Stacking is named, not numeric. Reach for the role token, not z-50.

Token	Value	Role
--z-base	0	Default flow
--z-raised	10	Stat tile hover, sticky table headers
--z-sticky	20	Sticky page headers, sub-nav bars
--z-dropdown	30	Autocomplete panels, action menus
--z-modal-backdrop	40	Modal/side-tray backdrop
--z-modal	50	Modals
--z-side-tray	50	Side tray content (modals and trays never coexist)
--z-toast	60	Notifications, toasts

Focus

Focus rings are brand colour, 2px solid, no offset. Click into a field to preview.

Light · --ring-color-focus

Dark · --ring-color-focus

--ring-color-focus · --ring-color-focus-error · --ring-width-focus: 2px · --ring-offset-focus: 0px

Edit DESIGN.md to change tokens; run task tokens to regenerate tokens.css. The narrative around each token (rules, do's and don'ts) lives only in DESIGN.md.