Design System
Defined in frontend/DESIGN.md and wired into Tailwind: a Material Design 3–style token system with an indigo primary, tonal surface elevation, Inter for text, JetBrains Mono for data.
Principles
- Tokens, not values. Components never use raw hex or arbitrary pixel sizes — they use semantic classes (
bg-surface-container-low,text-on-surface-variant,p-stack-md). - Tonal elevation. Depth comes from progressively tinted surface containers, not box shadows.
- Every color has an "on-" partner. Text on
primaryison-primary; never pair tokens across roles. - Mono for machine data. IDs, tool names, costs, and code render in JetBrains Mono (
font-mono-sm).
Color tokens (light theme)
Core roles
| Token | Hex | Used for |
|---|---|---|
primary | #3525cd | CTAs, active nav, links, key accents |
on-primary | #ffffff | text/icons on primary |
primary-container | #4f46e5 | hover state for primary buttons |
secondary | #006c49 | success states, positive helpers |
secondary-container | #6cf8bb | success chips/badges backgrounds |
tertiary | #684000 | warning-ish accents (quality, in-progress) |
error | #ba1a1a | errors, failed counts, destructive hints |
error-container | #ffdad6 | error panels/banners backgrounds |
Surfaces (elevation ladder)
| Token | Hex | Typical use |
|---|---|---|
background / surface | #f9f9ff | page background |
surface-container-lowest | #ffffff | cards, panels |
surface-container-low | #f0f3ff | hover fills, subtle wells |
surface-container | #e7eefe | icon chips, active nav fill |
surface-container-high | #e2e8f8 | avatar fill, deeper wells |
surface-container-highest | #dce2f3 | progress-bar tracks |
on-surface | #151c27 | primary text |
on-surface-variant | #464555 | secondary text |
outline | #777587 | tertiary text, placeholder icons |
outline-variant | #c7c4d8 | borders, dividers |
The rule of thumb visible throughout the components: card = surface-container-lowest + border-outline-variant; hover = one step up the ladder.
Typography
| Token class | Font | Size / line | Weight | Use |
|---|---|---|---|---|
display | Inter | 36 / 44 | 600 | dashboard hero numbers |
headline-lg | Inter | 24 / 32 | 600 | page titles |
headline-md | Inter | 18 / 26 | 600 | card/section titles |
body-lg | Inter | 16 / 24 | 400 | prominent body |
body-md | Inter | 14 / 20 | 400 | default body |
label-md | Inter | 12 / 16 | 500 | labels, meta, badges |
mono-sm | JetBrains Mono | 12 / 18 | 400 | IDs, tools, costs |
Applied as paired classes in the codebase, e.g. font-headline-md text-headline-md. Fonts load via Google Fonts <link>s in app/layout.tsx, alongside Material Symbols Outlined for icons (<span className="material-symbols-outlined">dashboard</span>; active nav uses fontVariationSettings: "'FILL' 1").
Spacing & layout
An 8px-based scale exposed as semantic utilities used everywhere in the components:
| Class family | Examples in use |
|---|---|
stack-* (vertical rhythm) | space-y-stack-md, p-stack-lg, mb-stack-sm, gap-stack-md |
gutter | page padding md:p-gutter, grid gap-gutter |
| fixed chrome | sidebar w-sidebar-width (260px), topbar height 64px (h-16), content offset md:ml-[260px] pt-20 |
| container | max-w-container-max centered main column |
Radii: cards rounded-xl, inputs/buttons rounded-md/rounded-lg, chips rounded-full.
Recurring patterns (copy these)
<section className="rounded-xl border border-outline-variant
bg-surface-container-lowest p-stack-md">
...
</section>Tone semantics
Used consistently by RecentActivity and the stat cards:
| Tone | Tokens | Means |
|---|---|---|
success | secondary family | completed work, healthy runs |
primary | primary family | informational, in-product entities |
warning | tertiary family | needs attention, quality metrics |
error | error family | failures |
neutral | surface/outline family | counts without judgment |
Dark mode
The root layout pins className="light" on <html> — a dark palette is not implemented in the app (the docs site you are reading has one; the product does not). Roadmap item.
Related pages
- Components — the tokens in action
frontend/DESIGN.md— the source token file (colors, typography, radii as YAML)