Tokens

Brand — plum

Plum is the brand 10% — used sparingly on filled CTAs, focus rings, selected states. primary is the saturated plum for filled buttons and the focus ring. primary-container is the only sanctioned soft brand surface — for selected radio cards, brand-themed pills, active-but-not-CTA backgrounds. Pair bg-primary with text-on-primary; pair bg-primary-container with text-on-primary-container. Brand colours are full-opacity only — alpha-modulated utilities (bg-primary/10, text-primary/40, etc.) are forbidden everywhere.

The -hover token is consumed internally by koala-btn for filled-button hover states — don’t reach for it directly in markup.

Surfaces

Four container levels — page → sidebar / banded → inset row → card. The brand is intentionally surface-rich in the warm range; hierarchy is rendered with hairlines and tone shifts rather than shadows. Light mode pivots around warm cream (#F7F3EC); dark mode around midnight (#131418).

On-surface — ink

Slate-neutral text ramp. Four steps from headings down to placeholders. Dark-mode on-surface is warm cream by design — the warm heading on midnight is the brand’s signature pairing and ties the two modes together.

Inverse surface

The dark fill in light mode that flips to a light fill in dark mode. One semantic role covers tooltips, snackbars, dark-style secondary buttons, and high-contrast banded sections. Pair bg-inverse-surface with text-on-inverse-surface.

Canvas

Forced-white surface for content whose contrast budget is set outside the design system — quiet zones around generated QR codes, printed document previews, embedded code samples with locked-foreground ink. Identical in light and dark mode by design. Reach for bg-canvas only when the foreground is fixed; for everything else, use the surface tokens above.

Outlines

Containers separate via borders, not shadows. outline is the visible border on cards, inputs, and section dividers. outline-variant is the lighter hairline used for table row separators and inset row dividers.

Status

Five warm-aligned status families: success (sage), danger (warm red), warning (amber), info (marine), neutral. Each is a four-token bundle: the saturated accent (success) paired with on-success for the filled-fill foreground, plus the soft surface (success-container) paired with on-success-container. Use the bundle through koala-badge and the equivalent component helpers — never raw Tailwind palette classes.

Type scale

Tailwind defaults — not redeclared. Strict usage rules: 16px (default) for primary content (body, names, descriptions, timestamps, links), text-sm for <dt> labels, secondary metadata, and table headers, text-xs only for tiny badges. Never shrink primary content. Display headings (text-3xl and up) take tracking-tight (≈ -0.025em).

Font weights

Plus Jakarta Sans for everything. Tailwind defaults — only font-medium, font-semibold, and font-bold appear in normal use. Headings are font-semibold, sentence case.

Eyebrow

The single sanctioned uppercase style. 11px / 600 / 0.16em letter-spacing, coloured text-on-surface-muted. Used for category labels above section headings, navigation group titles, and contextual badges that label content. Never on headings, body, badges, or anywhere else. Apply via <span class="koala-eyebrow">.

Radius

A single 5px radius for every UI surface. Buttons, badges, inputs, cards, modals, side trays, dropdowns, switches, segmented controls — every shape shares the same corner. Every Tailwind radius utility (rounded-sm, rounded-md, rounded-lg, rounded-xl, rounded-2xl) resolves to 5px. The only exception is rounded-full, reserved for genuinely circular elements: avatars, spinners, icon-in-circle containers, notification dots. Segmented controls and pills render with the standard 5px corner — not rounded-full.

Shadows

Never on containers. Reserved for floating UI: dropdowns, autocomplete panels, popovers, tooltips, modals on desktop. Containers (cards, page sections, settings panels) separate via border-outline.

Shadows are opt-in. Static containers never shadow — only floating UI (dropdowns, popovers, the pinned sticky bar) applies an elevation utility. The system uses the generic shadow-sm / shadow-md / shadow-lg scale with no use-case-specific shadow tokens, so the elevation scale stays cleanly re-themeable for white-label builds.

Motion

One duration token plus the project’s two easing curves. Used in @layer components rules and Alpine x-transition. Never write raw 0.2s ease-out in new code. See /motion for the full reference. Hover the box to preview.

Z-index

Stacking is named, not numeric. Reach for the role token, not z-50. Modals and side trays share the same stacking level deliberately — they never coexist.

Focus

Focus rings are brand colour (plum), 2px solid, no offset. Validation-error focus swaps in a rose ring (--ring-color-focus-error). Values are tokenised so every component picks the same look. See /focus for the full reference. Click into a field to preview.