Qiri · Design system

Design system

One token set across every surface, the foundations documented, and the real components published as live libraries. The pharmacist console, patient app, demo, outreach tool and marketing site all draw from a single source of truth for colour, type, spacing, radius, elevation and motion — so every surface is unmistakably Qiri.

Design principles

Everything below serves a handful of convictions. Qiri is vertical software in a regulated clinical setting, read by a burnt-out pharmacist at 500 scripts a day and by a patient collecting a sensitive medication. The design has a job to do for both, and these are the rules it holds to.

Clinical safety as a visual language Flagship

The console exists to end the 90% override reflex; every visual decision on a safety screen serves that. This is the severity grammar, rendered live from the same tokens the console ships: each verdict is a locked triplet of colour, glyph and copy, with its accessibility decision and clinical sign-off attached.

The verdict grammar

One verdict banner per screen. The verdict and its one-line because-clause are one unit: the headline states the decision, the line under it states why. The longer clinical explanation can follow below, but a verdict never sits alone with its reason floating elsewhere in muted text. And the brand owns the call: it is BLOCKED BY QIRI, never QIRI BLOCKS; keeping Qiri's name on the decision is what earns trust in the block instead of a reflex override.

Drug-interaction severity

"Interaction" is a reserved word: it means a drug interaction and nothing else (any other event is an Activity). Interaction rows rank four tiers; severity colour follows the clinical-reference convention pharmacists already know from Micromedex and Lexicomp, and every tier is a quiet chip, never a filled red block. Danger is deliberately calm: alarm is what trained the 90% override reflex.

The four-beat verdict arc

One token set

The canonical tokens live in design-system/qiri-tokens.css. Each product stylesheet carries a synced @qiri-tokens block; changing a token there and running node design-system/sync-tokens.mjs propagates it to every surface. The block also carries the designed dark counterpart (:root[data-theme="dark"]), inert until a surface opts in. Product-specific tokens (clinical-domain colours, marketing layout) live outside the shared block and are free to differ. One named exception: the light-mode accent-wash knobs (--wash-cover / --wash-band) are hand-declared per app, not synced.

Typography

Three families, each with a clear job. Playfair Display carries the warm, human voice in headlines; Plus Jakarta Sans does the reading and every control; JetBrains Mono is reserved for machine data. The mono diet is a rule, not a preference — mono means "a machine produced this exact value" (an ID, a code, a quantity), never prose.

Type scale

Line-heights: --lh-display 1.05 · --lh-heading 1.15 · --lh-body 1.55 · --lh-tight 1.1.

The scale, seen

The same ladder rendered at size, in its real family and weight, so a step is chosen by eye rather than by arithmetic.

Colour & accessibility

Qiri runs a deliberate warm / clinical split: warm sand tones for patient-facing, human moments; cool charcoal for clinical chrome. Semantic colour (success / warning / danger / info) is separate from the brand accent and always carries meaning, never decoration.

Brand palette — Pantone source of truth

The brand colours are anchored to specific Pantone TCX chips. These sRGB values are the exact source of truth — do not nudge them; where a hue must shift for legibility, add a derived text token rather than moving the base.

Every status hue whose base is only large/UI-safe now carries a derived text token at the same hue, AA for normal-size text; fills, borders and large text keep the base. On light: --color-accent-text #3A68A0 (info and accent; 5.73:1 on white), --color-danger-text #A23D30 (5.28:1 on the danger wash), --color-success-text #32775B (4.64:1), --color-warning-text #965A0C (4.85:1; a deep amber), plus the console severity pair --color-aero-text #B94B3C (4.60:1) and --color-amber-text #965A0C (5.06:1 on its wash; it converged with the warning text token when both moved to true amber, 2026-07-15). Each has a dark counterpart that lifts or converges as the dark grounds require. This extends the derived-text pattern to every status: status text is AA-normal (Jon, 2026-07-14), superseding for text the earlier chips-are-UI AA-large position (recorded in the verdict table, David 2026-07-12); fills and large chrome keep the base. Pumice Stone (--color-stone) and Castle Wall (--color-castle) are reserved warm neutrals: tokenised but intentionally unused, earmarked for Counter terminal surfaces and dividers; decorative and UI use only, never small text on light backgrounds.

The tokens, live

These chips render from this page's own synced @qiri-tokens block, so they cannot drift from what ships. Click any chip to copy its value.

Clinical-domain accents

Five hues (console-only, outside the shared block) tag clinical categories on the review surface, so a pharmacist reads the domain at a glance. Their per-domain mapping is owned by the console.

Contrast (WCAG)

Qiri is read at kiosk standing distance, so contrast is a requirement. Key pairs, measured:

Accent wash on the light ground

Light-mode page grounds across the console, outreach, and the marketing site carry a soft Alaskan Blue cast: a low-alpha radial of --color-accent-soft over the existing ground, so the three surfaces read as one product. The wash lives on the page ground, never on title blocks or cards. Its strength sits in two knobs, --wash-cover and --wash-band, and dark mode zeroes both in one declaration: Carbon already carries its own accent treatment, and a blue wash over it reads as a smudge. One deliberate exception to the one-token-set rule: the two wash variables are declared by hand in each app's stylesheet, not synced from qiri-tokens.css, so check each app when tuning them.

Dark theme

The dark theme is designed, not inverted: the same Pantone anchors, recast. Carbon (19-4012 TCX) becomes the card ground, Snow White (11-0602 TCX) becomes the ink, and Alaskan Blue (15-4225 TCX) takes the accent seat, because Regatta reads only 3.07:1 on Carbon (UI and large text only). The status hues are lifted for the dark grounds, where the deep light bases sink (the light danger reads 1.77:1 on Carbon, illegible); their washes keep the deep light hues at raised alpha, so chips stay tinted rather than chalky. Where a lifted base already clears AA as normal text, the derived text token converges with it: --color-accent-text and --color-danger-text equal their bases on dark, and stay defined so product CSS resolves unchanged.

The dark block ships inside every surface's synced @qiri-tokens block but is strictly opt-in: it activates only when a surface sets data-theme="dark" on the root element. This docs site adopts it (following prefers-color-scheme, with the toggle in the nav as the override; use it to read this table on the grounds it describes). The patient app ships its warm dark counterpart through the same generated token module, and the pharmacist console now ships light and dark too, driven by the same tokens through a System / Light / Dark control in Settings › Appearance. On dark, elevation inverts: a shadow barely reads on near-black, so height is carried by the lightening surface ladder plus subtle cream-based borders, and the verdict grammar (blocked, held, cleared) plus status chips stay calm and AA-legible, recomputed on the dark grounds below. The Counter is deliberately light-locked, keeping its warm rail even when the console is dark.

Focus, proven

Keyboard focus draws a 2px solid accent ring with a 2px offset (the console's global :focus-visible rule; mouse clicks stay quiet, and an alpha wash is banned as a focus indicator because it is invisible). This page ships the same rule site-wide: Tab through these to see it.

Elevation

A three-step ladder of soft shadows — floating surfaces on cream, not hard outlines. Pick by how far the surface sits above the page; don't stack levels.

Spacing

One 4px rhythm everywhere: --space-N is N × 4px. Compose gaps and padding from the scale; never invent an off-scale pixel value. (Outreach still re-declares --space-5..8 locally — a tracked follow-up, not a second scale.)

Radius

Round increases with prominence — and fully interactive pills are the house shape for buttons: every shipped button (console and patient) wears --radius-pill, which is why a squared-off button reads instantly as off-brand.

Motion

Motion is calm and purposeful. Entrances decelerate; state changes are quick and even. Everything honours prefers-reduced-motion — the signature aura falls back to a static state, never a jarring stop.

The console verdict moment Live

The one place console motion carries clinical weight is when a verdict lands and when a script leaves the queue. Both halves shipped 2026-07-13: the landing entrances in fc81d54, the queue-exit choreography in 3c6cc1a (the signed row leaves, the counts move only after it has gone, the toast enters last; the sequencing is kept under Reduce Motion because order is information). It uses only the shared tier above, and its first rule is a prohibition.

Signature aura & motion Patient

The patient app's rarest asset: a brand mark that is quietly alive. Where the console is calm chrome, the patient surface breathes. It is tuned for someone collecting sensitive medication, so every motion is slow, low-contrast and warm: presence, not a spinner; delight, not confetti. All of it is driven by one motion source of truth (lib/motion.ts) and honours the OS "Reduce Motion" setting everywhere.

The state-colour language

A soft radial wash carries the screen's emotional state. Content sits centred and unboxed inside it, so the colour dissolves into the cream canvas rather than living in a card. This is the app's ambient background (StateBloom / AmbientBloom).

The arrival

The aura mark (LivingAuraOrb) always breathes gently in place. On a fresh "medication ready" event it performs a one-time arrival: the glow blooms up on a soft breath of light, three concentric rings ripple outward in sequence, and a single success haptic lands. It plays once per event, then settles back into the calm breathing state on later visits. The timings below are the whole signature tier.

See it breathe

This is not a video: the orb below is rendered live by this page from the same numbers as the table above (breath 4200 ms half-cycle at a ~7%/3.5% swell, bloom 780 ms, halo 1100 ms staggered 60/300/540, ring growth 1.7×/2.0×/2.3×). The arrival plays once when it first scrolls into view; replay it as often as you like. With Reduce Motion on, it renders fully static, exactly as the app does.

Reduce Motion is a contract

The signature moment is the first thing to yield when the patient has asked for less motion. Never a jarring stop: a graceful, static fallback.

The exception, live: HoldToConfirm asks for a deliberate 1200 ms press before an irreversible act fires; a danger tint fills behind the label as visual feedback (a JS timer decides completion, the fill is purely feedback). Releasing early rewinds in 160 ms. Try it, and note the fill still animates under Reduce Motion, because it is information.

The pieces

Iconography

One line-icon language: Lucide-style, drawn on a 24×24 frame with stroke-width: 2, round caps, and colour inherited from the text (currentColor). No icon fonts, no pasted raw SVG.

Logo & brand mark

The Qiri mark is a single glyph: a blue aura orb with a white "reasoning drop" inside it, the shape that carries the idea of a system that thinks. It has three sanctioned forms and a short list of rules, all of them living in real code (patient-app/src/components/brand.tsx) so the brand is applied identically everywhere.

Voice & terminology

Qiri's rarest design asset: opinionated, clinically-motivated content rules. They're safety-driven and specific — the same kind of guideline Stripe and Shopify are known for, in a regulated clinical setting.

Glossary: say / avoid

The words the product actually uses, and the near-misses that creep in. Australian pharmacy first: these match PBS, AHPRA and patient expectations, not US software habits.

The counselling register, worked

The most differentiated voice rule, shown rather than stated: the same three moments written in clinic-speak and in Qiri's patient register. Sensitive items get an extra layer: notifications and lock screens never name the medicine; the name appears only inside the app.

Patterns

Foundations and atoms answer "what does a control look like"; patterns answer "how do we build the screen". These are the house recipes for the three things every console surface does: take input, list records, and handle the moments when there's nothing, something's loading, or something went wrong. Each recipe is realised in real components, so the rule and the code never drift.

Forms & validation

Every form is built from TextField and its siblings. A field is always labelled, help sits on one line under it, and validation shows in place rather than in a popup. Confirmation is reserved for the actions that deserve it.

Data & tables

The scripts queue, records, patients and transactions are all the same surface: a DataTable, optionally paired with a Pager, a row Menu, and an EmptyState for when the list is empty. Build a list from these, not a bespoke table.

Empty, loading & error states

Three distinct moments, three distinct tones. Each is deliberately designed: a blank region or a lone spinner is never the answer.

The queue & filtering

The console's spine is a queue the pharmacist works down. Filtering narrows what is already on screen; it never becomes the only path to an item.

The sign-off, end to end

The whole clinical loop in one recipe: what the pharmacist sees, presses and hears back, from opening a script to the row leaving the queue.

Screen scaffolds Patient

Where the console has pattern recipes, the patient app has two screen scaffolds: templates that assemble the primitives into a whole screen, so every detail and onboarding step lands identically without each screen re-solving the layout. They are the reason the header, footer and journey feel the same everywhere.

Kiosk conformance floor Phase 2 gate

"Kiosk-ready by default" is a principle above; this is the floor that makes it auditable. Phase 2 puts Qiri on a standalone touchscreen used at standing distance, with no keyboard, no hover, gloved and older hands, and intermittent connectivity. Every kiosk-bound surface must clear this floor; the console notes say what already conforms today and what is desktop-only.

Published component libraries Live

The real Qiri components — the ones the apps actually ship — are published as live design-system libraries. Design work builds directly with them, so every screen produced is on-brand and maps one-to-one onto shippable code. React DOM and React Native can't share one bundle, so each runtime has its own library.

Component gallery Live

Every published component, rendered. These are static previews of the real components in the two libraries above, so you can see the whole system at a glance without leaving this page. Open a library to build with them live.

Two temperatures, componentwise

"One brand at two temperatures" proven per component: the same concept from each library, side by side. The grammar never changes (pill buttons, one primary per view, tinted status, errors that teach); the temperature does (cool charcoal density for the clinic, warm full-width calm for the patient).

Pharmacist console 51 components · 50 shown (ConsoleProvider is the context provider — it has a library card but nothing visual to preview)

Patient app 25 components

What's covered

The libraries carry the components that render standalone today. A few surfaces sit outside them by design.

Changelog

What has shipped, most recent first. The design system is built in the open alongside the product, so every entry here maps to real components and live surfaces.

Contributing

The design system has no separate component library to maintain: it is pointed straight at the app's own source, so the way you change a component is to change the app. A short map of how it fits together, and how a change lands.