Foundations
The design guidelines behind the system — the principles, standards and best practices for building consistent, accessible HealthMetrics interfaces.
Explore the foundations
The building blocks every interface composes from — each with its own reference page.
Grid
The responsive 12–8–4 column system.
Colour
Semantic tokens, AA in both themes.
Background
The canvas layer — muted cream light, deep navy dark.
Typography
The nine-step Inter type scale.
Icons
Material Symbols + the HMS icon set.
Motion
Durations, easing and when to animate.
Radius
One base token drives the corner ramp.
Shadow
The six-step elevation ramp.
Spacing
An 8px rhythm on the 4px scale.
Principles
What every HealthMetrics interface should be.
Accessible
Every pattern meets WCAG 2.2 AA. Colour is never the only signal, targets are comfortable, and focus is always visible.
Consistent
One token contract and one component set, so the same control looks and behaves the same in every product.
Branded
The HMS brand is expressed through tokens, not one-off styling — teal leads, coral accents, navy for AI and dark surfaces.
Efficient
Sensible defaults and composable components let teams build quickly without re-deciding the basics.
Standards
The measurable rules the system holds itself to.
| Standard | Rule |
|---|---|
| Contrast | All foreground/background pairings pass WCAG 2.2 AA in both light and dark themes. |
| Colour | Use semantic tokens (--primary, --destructive, --muted-foreground …) — never hardcoded hex. Coral is a decorative accent, never the destructive red or the primary action. |
| Spacing | An 8px base grid. Compose with the Tailwind spacing scale; avoid arbitrary pixel values. |
| Radius | A single --radius (8px) drives the sm/md/lg/xl ramp so corners stay consistent. |
| Typography | Inter across the interface; Material Symbols Rounded for icons. Set weight and size from the scale, not ad hoc. |
| Theming | Light and dark are first-class. Style with tokens and both themes are covered automatically — never assume a background colour. |
Best practices
Practical guidance when composing screens.
Do
- Use semantic tokens so light/dark and rebrands flow through automatically.
- Lead each view with a single primary action; support it with secondary/outline/ghost.
- Pair every input with a
<Label>and expose status beyond colour alone. - Reuse a component before building a new one; extend via props, not forks.
Don't
- Hardcode hex values or arbitrary pixel spacing.
- Use the brand coral as a destructive colour or a primary CTA.
- Rely on colour as the only way to convey meaning.
- Reserve the AI palette (stream cyan, navy) for non-AI decoration.
See the brand page for logo and palette specifics, and the full token reference in Storybook → Design Tokens.