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.
Motion
Spacing
4px grid. gap-1 = 4px, gap-12 = 48px.
Focus & elevation
Cards never shadow. Floating UI (dropdowns, popovers, modals) does.
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.