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.

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-md, rounded-md, rounded-md, rounded-md, rounded-md) resolves to 5px. The only exception is rounded-full, reserved for genuinely circular elements: avatars, spinners, icon-in-circle containers, notification dots, toggle thumbs. Pills and "rounded-full" segmented controls are not used — segmented controls render as rectangles with the standard 5px corner.

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.

Dark-mode halo. A black drop has no contrast against midnight, so the rare surface that legitimately uses a shadow in dark mode pairs shadow-lg with dark:shadow-halo. The halo projects a faint right-edge glow tinted with --color-outline, visually extending the border rather than adding a new drop. Currently used only on the Portal sidebar.

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.