UI usage guide
When to reach for each element — so the Portal reads as one considered product, not a pile of similar-looking parts. Every example below is built from the real koala-* helpers, so this guide can't drift from the components it documents.
Type roles
Six jobs, one typeface (Plus Jakarta Sans) plus system mono. Each role is one helper class — apply it, get the whole role. Size and weight signal hierarchy, never colour alone.
Page title
When a heading gets a divider
A divider marks a structural seam between a header band and a body. Use it only when the card genuinely has those two zones — that's what koala-card-header-label renders.
koala-card — title, figure and sparkline are one composition.Caps vs sentence case
Two different things, not two styles of the same thing. Caps (koala-eyebrow) is a label for a region; sentence case (koala-section-title) is an actual title.
Card body…
Cards
Every card is a koala-card — a surface-container with a 1px outline and a 5px corner. They differ by how the title relates to the body.
Header band + divider + structured body.
Tabs
Tabs switch between sections of one object (a case: General, Enquiries, Docs, Tasks…). They never navigate the whole app — that's the sidebar's job. The active tab is a plum pill; the row is flush so the active pill's left edge lines up with the content below.
Buttons
One primary action per view. Everything else is secondary or quieter. Destructive actions are outlined, never filled, until the moment of confirmation.
Status badges
Six warm-aligned families, each carrying a fixed meaning. Pick by meaning, not by colour you fancy — and keep one status vocabulary per object type.
Avatars
Initials on a coloured chip — never gradient fills or AI faces. koala-avatar derives a stable colour from the name, so a person keeps the same colour across the app.
rounded-full is correct here.Form controls
koala-field generates the label, the surface-recessed input and its validation in one tag. koala-switch is for instant on/off. Focus is a 2px plum ring, no offset.
Surfaces & nesting
Depth is built from surface roles and borders, not shadows. Adjacent surfaces always differ by one role, and nesting caps at two levels: page → container → recessed.
Colour
Plum is the only brand accent. There is no secondary brand colour. Everything non-plum is either neutral ink/surface or a semantic status colour.
Spacing & shape
A 4px spacing base, and a single 5px corner on every UI surface — buttons, inputs, cards, badges, dropdowns. The full circle is reserved for genuinely round things.
Icons
Lucide, outlined, 1.5 stroke-width, round caps, drawn in currentColor via <koala-icon>. Set colour on the element, never an icon-colour prop. See the full set on the Icons page.
Empty states
A muted icon, a one-line headline, a sentence of warm guidance, and (if there's an action) a single button. koala-empty-state centres and sizes it for you.
No notes yet
Add a note to keep the team in the loop on this quote.
Pages in context
The rules above, composed into real screens from the same helpers. Numbered markers map every part back to its rule.
1 — List page
A collection you scan and filter. Page title + one primary action, a toolbar, then a single table card.
Transactions1
| Client3 | Reference | Status | Fee | Completion |
|---|---|---|---|---|
 Susan Batchelor | P-YCJFQH4 | Active5 | £1,740.00 | 14 Aug 20266 |
 Matthew Daughtrey | S-KOISYZ | Active | £2,257.00 | 22 Jul 2026 |
 Gillian Kinnear | S-HGXISI | Complete | £1,492.80 | 2 Jun 2026 |
koala-th (uppercase label role); rows are koala-tr.koala-mono-id.2 — Detail / view page
A single object opened up. Object title with a descriptor and status, object tabs, then a main column of section cards beside a sidebar panel of meta.
Susan Batchelor1
Susan Batchelorkoala-tabs) switch sections of this one record — never app-level nav.3 — Settings page
Configuration grouped into stacked section cards, with a nav rail. Each card states what it does, then the controls, then one save.
Settings1
koala-field) in a recessed surface, label above.Voice
Copy is part of the brand: warm, plain, human — like a helpful colleague, not a system notice. UK English, sentence case, action verbs.