Foundations
The visual primitives every Koala component composes from. Read this once; the rest of the system follows from these rules.
Principles
Warm, restrained, editorial
Plum is the 10%. The other 90% is cream, slate, and white space.
Borders, not shadows
Containers use hairline borders. Shadows are reserved for floating UI.
Sentence case throughout
No uppercase headings. The eyebrow style is the one sanctioned exception.
No inline glyph separators
No middot, bullet, pipe, or en-dash inside UI text. Stack or use a wider gap.
Every colour is a token
No alpha syntax. No raw hex. If a new soft brand surface is needed, tokenise it.
Pair container with on-container
bg-primary-container pairs with text-on-primary-container. Always.
Mobile first
Components collapse to phone width before they bloom on desktop.
Shared components first
If a koala-* helper exists, use it. Don't reach for raw markup.
Colour
Brand — plum
Surface ladder
Ink ladder
Status families
Typography
Families
Type scale
Save quote
Eyebrow
Section headerThe single sanctioned uppercase style. 11px / 600 weight / 0.16em tracking. Used to mark section starts and table-of-contents-style labels. Never on body text.
Weights
Radius
One radius for everything. Every rounded-* utility resolves to 5px.
Segmented controls and pills render with the standard 5px corner — not rounded-full.
Motion
Spacing
4px grid. gap-1 = 4px, gap-12 = 48px.
Focus & elevation
Cards never shadow. Floating UI (dropdowns, popovers, modals) does.
Layering & elevation
z-index ladder
z-base
0
Page flow
z-raised
10
Hover lifts, focus rings
z-sticky
20
Sticky headers, breadcrumb banner
z-dropdown
30
Dropdown panels, autocomplete results
z-navbar
35
Top navigation chrome
z-modal-backdrop
40
Scrim behind modals & trays
z-modal
50
Modal dialogs
z-side-tray
50
Off-canvas trays (same plane as modal)
z-toast
60
Notification toasts (always on top)
Scrim & shadows
color-scrim
Modal / tray backdrop. Light: 50% ink on transparent. Dark: 75% black on transparent.
shadow-resting / shadow-raised / shadow-floating / shadow-overlay
Component-independent elevation scale. Shadows are off by default; floating UI opts in by depth, not by element name, so white-label themes can change the shadow language globally.
color-outline / color-outline-variant
Hairline borders. Outline is the strong divider (card edges); outline-variant is the soft inner rule (rows, nested cards).
color-inverse-surface / color-on-inverse-surface
High-contrast inverse surface for the secondary filled button variant and stat-pill emphasis.
Dark mode
Single toggle in the top header. Adds .dark to <html>, persists to localStorage, fires a View Transition circle-reveal animation.
Every token flips automatically — surfaces, ink, status families, brand. No dark: partner classes needed on most utilities; the token does the work.
Page widths
Three container scales for centred page content.
max-w-3xl
768px
max-w-5xl
1024px
max-w-7xl
1280px
Mobile: px-4. Tablet: sm:px-6. Desktop: lg:px-8.