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
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-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-sm / shadow-md / shadow-lg
Generic Tailwind elevation scale. Shadows are off by default — only floating UI (dropdowns, popovers, the pinned sticky bar) opts in. No use-case-specific shadow tokens; the generic scale stays cleanly re-themeable for white-label builds.
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.