Design System — Token Reference
Source of truth: src/app.css
Last updated: 2026-03-27
All UI values must come from these tokens unless listed under Intentional Raw Values.
Spacing
4px grid. Token name = multiplier (--sp-3 = 3 × 4px = 12px).
| Token |
Value |
Use for |
--sp-0 |
0px |
Explicit zero |
--sp-px |
1px |
Borders, hairlines |
--sp-0.5 |
2px |
Micro-nudge (margin-top on meta text) |
--sp-1 |
4px |
Tight gap, field label gap, small padding |
--sp-1.5 |
6px |
Badge gap, icon gap, footer gap |
--sp-2 |
8px |
Compact gap, button group gap, inner padding |
--sp-3 |
12px |
Standard gap, row padding, list item gap |
--sp-4 |
16px |
Card padding (mobile), section margin, tab margin |
--sp-5 |
20px |
Card padding (desktop), module gap, sidebar gap |
--sp-6 |
24px |
Large padding, overlay padding, page container |
--sp-7 |
28px |
Primary card padding, section group margin |
--sp-8 |
32px |
Page top padding, empty state, desktop grid gap |
--sp-10 |
40px |
Large elements (avatar width), empty list padding |
--sp-12 |
48px |
Empty state padding, large spacing |
--sp-16 |
64px |
Reserved |
--sp-20 |
80px |
Page bottom padding (scroll clearance) |
Semantic spacing aliases
| Token |
Resolves to |
Use for |
--section-gap |
--sp-7 (28px) |
Gap between major page sections |
--card-pad |
--sp-5 (20px) |
Default module/card padding |
--card-pad-primary |
--sp-7 (28px) |
Hero/primary module padding |
--card-pad-secondary |
--sp-4 (16px) |
Compact card padding |
--row-gap |
--sp-3 (12px) |
Gap between list rows |
--module-gap |
--sp-5 (20px) |
Gap between dashboard modules |
--row-pad-y |
14px |
Vertical padding inside data rows (off-grid, intentional) |
--row-pad-x |
--sp-4 (16px) |
Horizontal padding inside data rows |
--inner-gap |
--sp-3 (12px) |
Gap between items within a row |
Mobile overrides (≤768px)
| Token |
Desktop |
Mobile |
--card-pad |
20px |
16px |
--card-pad-primary |
28px |
20px |
--row-pad-y |
14px |
16px |
--section-gap |
28px |
20px |
Radius
| Token |
Value |
Use for |
--radius-xs |
4px |
Tiny pills, skeleton placeholders, kbd hints |
--radius-sm |
6px |
Badges, chips, nav links, danger buttons |
--radius-md |
8px |
Buttons, inputs, tabs, entry rows, icon containers |
--radius |
12px |
Cards, modals, panels, main containers |
--radius-lg |
16px |
Hero cards, action cards, pill chips, ImmichPicker modal |
--radius-full |
9999px |
Circles, toggles, avatars |
Elevation (Shadows)
Light and dark mode have separate values. Dark mode uses higher opacity.
| Token |
Light |
Use for |
--shadow-xs |
0 1px 2px rgba(0,0,0,0.03) |
Row hover, active tabs, inner elements |
--shadow-sm |
0 1px 3px rgba(0,0,0,0.04), 0 4px 12px rgba(0,0,0,0.04) |
Secondary cards, inputs, budget tables |
--shadow-md |
0 2px 6px rgba(0,0,0,0.04), 0 8px 24px rgba(0,0,0,0.06) |
Standard card elevation (default .module) |
--shadow-lg |
0 4px 12px rgba(0,0,0,0.06), 0 16px 40px rgba(0,0,0,0.1) |
Hero cards, primary modules, dropdowns |
--shadow-xl |
0 8px 24px rgba(0,0,0,0.08), 0 24px 60px rgba(0,0,0,0.15) |
Modals, overlay panels |
Legacy aliases: --card-shadow → --shadow-md, --card-shadow-sm → --shadow-sm
Colors
Surfaces (3-layer depth)
| Token |
Light |
Dark |
Layer |
--canvas |
#F5F6F8 |
#09090b |
Page background — everything sits on this |
--surface |
#FFFFFF |
#0f0f12 |
Sidebars, panels, slide-out sheets |
--surface-secondary |
#FAFAFB |
#111114 |
Input backgrounds, secondary panels |
--card |
#FFFFFF |
#161619 |
Content containers, elevated with shadow |
--card-secondary |
#FAFAFB |
#111114 |
Secondary cards, button backgrounds |
--card-hover |
#f0f0f3 |
#1c1c20 |
Row hover, interactive feedback |
Borders
| Token |
Light |
Dark |
--border |
rgba(0,0,0,0.06) |
rgba(255,255,255,0.06) |
--border-strong |
rgba(0,0,0,0.1) |
rgba(255,255,255,0.1) |
Text hierarchy
| Token |
Light |
Dark |
Use for |
--text-1 |
#1a1a1f |
#fafafa |
Headings, names, amounts — read first |
--text-2 |
#4a4a55 |
#a1a1aa |
Body text, descriptions — read second |
--text-3 |
#6b6b76 |
#71717a |
Labels, metadata, captions — supporting |
--text-4 |
#b4b4bd |
#3f3f46 |
Placeholders, disabled, timestamps — background |
Accent (indigo / blue)
| Token |
Light |
Dark |
Use for |
--accent |
#4F46E5 |
#3b82f6 |
Primary actions, links, active states |
--accent-bg |
#EEF2FF |
rgba(59,130,246,0.1) |
Icon wells, strong highlight backgrounds |
--accent-dim |
rgba(79,70,229,0.06) |
rgba(59,130,246,0.08) |
Subtle hover, selection backgrounds, focus rings |
--accent-border |
rgba(79,70,229,0.10) |
rgba(59,130,246,0.12) |
Accent-tinted borders |
--accent-focus |
rgba(79,70,229,0.12) |
rgba(59,130,246,0.15) |
Active states, selection bars |
Semantic colors
| Token |
Light |
Dark |
Use for |
--success |
#16A34A |
#22c55e |
Positive values, income, completed |
--success-bg |
#F0FDF4 |
rgba(34,197,94,0.1) |
Icon wells |
--success-dim |
rgba(34,197,94,0.08) |
rgba(34,197,94,0.08) |
Badge backgrounds |
--error |
#DC2626 |
#ef4444 |
Errors, issues, delete actions |
--error-bg |
#FEF2F2 |
rgba(239,68,68,0.1) |
Icon wells |
--error-dim |
rgba(239,68,68,0.08) |
rgba(239,68,68,0.08) |
Badge backgrounds |
--warning |
#d97706 |
#f59e0b |
Warnings, pending states |
--warning-bg |
rgba(245,158,11,0.08) |
rgba(245,158,11,0.1) |
Badge backgrounds |
Overlay
| Token |
Light |
Dark |
Use for |
--overlay |
rgba(0,0,0,0.3) |
rgba(0,0,0,0.6) |
Modal backdrop, reading pane overlay |
--overlay-strong |
rgba(0,0,0,0.5) |
rgba(0,0,0,0.75) |
Heavy overlays |
--nav-bg |
rgba(255,255,255,0.9) |
rgba(15,15,18,0.9) |
Navbar blur background |
Typography
| Token |
Desktop |
Mobile (≤768px) |
Use for |
--text-xs |
11px |
12px |
Badges, pills, tiny counters |
--text-sm |
13px |
15px |
Labels, meta, captions, button text |
--text-base |
14px |
16px |
Body text, list items, inputs |
--text-md |
15px |
17px |
Card titles, important rows (16px+ avoids iOS zoom) |
--text-lg |
17px |
18px |
Section headers, modal titles |
--text-xl |
22px |
22px |
Page titles |
--text-2xl |
28px |
26px |
Hero headings |
--text-3xl |
36px |
32px |
Large hero numbers |
Line heights
| Token |
Value |
Use for |
--leading-tight |
1.2 |
Headings, hero numbers |
--leading-snug |
1.35 |
Card titles, compact text |
--leading-normal |
1.5 |
Body text |
--leading-relaxed |
1.65 |
Article content |
--leading-loose |
1.8 |
Long-form reading |
Fonts
| Token |
Value |
--font |
'Inter', -apple-system, system-ui, sans-serif |
--mono |
'JetBrains Mono', ui-monospace, monospace |
Global Component Classes
Defined in app.css, usable in any component without local <style> duplication.
| Class |
Description |
.module |
Card container (bg, border, shadow, padding) |
.module.primary |
Hero card (more padding + elevation) |
.module.flush |
No padding (for flush content) |
.module-header |
Flex header row (title left, action right) |
.module-title |
Uppercase label |
.module-action |
Accent link → "View all →" |
.data-row |
Standard list item with hover + zebra striping |
.badge + .error/.success/.warning/.accent/.muted |
Semantic status badges |
.tab-bar + .tab + .tab-badge |
Pill-style tab navigation |
.section-label |
Uppercase group header |
.btn-primary / .btn-primary.full |
Primary action buttons |
.btn-secondary |
Secondary action buttons |
.btn-icon |
Square icon button (36×36) |
.input |
Standard text input |
.skeleton |
Shimmer loading placeholder |
.page / .page-header / .page-title / .page-greeting |
Page-level layout |
.app-surface |
Centered max-width container |
Intentional Raw Values
These values exist outside the token system by design. Do not convert them.
Non-scale spacing
Values that don't land on the 4px grid. Used for optical tuning where grid steps are too coarse.
| Value |
Where |
Why |
1px |
margin-top on meta text, feed separators |
Sub-pixel nudge for vertical alignment |
3px |
Badge padding-y, kbd padding |
Optical centering within small elements |
5px |
Pill padding-y, chip padding |
Between sp-1 (4px) and sp-1.5 (6px), tuned per element |
7px |
View-btn padding-y, sidebar gap |
Between sp-1.5 (6px) and sp-2 (8px) |
9px |
Nav item padding-y, suggestion row padding-y |
Between sp-2 (8px) and 10px |
10px |
Input padding-y, dropdown padding, various gaps |
Common "comfortable touch" size, between sp-2 and sp-3 |
11px |
Entry row padding-y, toggle btn padding-bottom |
Asymmetric optical alignment |
13px |
FAB action padding-y, list row padding |
Between sp-3 (12px) and 14px |
14px |
Button padding-x, row padding-x, modal gap, field row gap |
Most common off-grid value. Used as standard horizontal rhythm for interactive elements. Also --row-pad-y for data rows. |
15px |
Transaction row padding-y |
Between sp-3.5 and sp-4, tuned for readability |
18px |
Detail header margin-bottom, AI guide padding-top |
Between sp-4 (16px) and sp-5 (20px) |
22px |
Trip stats padding-x, modal body padding |
Between sp-5 (20px) and sp-6 (24px) |
Non-scale border-radius
| Value |
Where |
Why |
9px |
Status segment control inner radius |
Between radius-md (8px) and radius (12px) |
10px |
Event cards, photo thumbnails, notes, modals, unscheduled items, food rows |
Heavily used "soft card" radius. Between radius-md (8px) and radius (12px). |
14px |
CommandPalette box, toggle track |
Large interactive controls |
20px |
Bottom sheet top corners |
Extra-round for sheet feel |
50% |
Circular elements (cover nav dots, meal-number, image-delete) |
True circle, differs from radius-full on non-square elements |
Data visualization colors
These are visual category identifiers, not semantic UI colors. They must remain consistent within their visualization set, independent of theme.
Fitness macros:
| Color |
Hex |
Use |
| Protein |
#8B5CF6 |
Purple macro bar |
| Carbs |
#F59E0B |
Amber macro bar |
| Fat |
#3B82F6 |
Blue macro bar |
Fitness meal weights:
| Color |
Background |
Text |
Meaning |
| Heavy |
rgba(239,68,68,0.1) |
#DC2626 |
High-calorie meal |
| Moderate |
rgba(245,158,11,0.1) |
#B45309 |
Medium-calorie meal |
| Light |
rgba(34,197,94,0.1) |
#15803D |
Low-calorie meal |
Trip categories:
| Color |
Background |
Text |
Category |
| Hotel |
rgba(168,85,247,0.1) |
#a855f7 |
Lodging |
| Restaurant |
rgba(249,115,22,0.1) |
#f97316 |
Food & dining |
| Hike |
rgba(34,197,94,0.15) |
#16a34a |
Outdoor activity |
| Logistics |
rgba(161,161,170,0.1) |
--text-3 |
Transport, other |
Other:
| Color |
Hex |
Use |
| Favorite star |
#F59E0B |
Star icon fill (reader, fitness) |
| AI badge |
rgba(59,130,246,0.1) / #3B82F6 |
AI-logged entry indicator |
| Transfer pill |
rgba(59,130,246,0.1) / #3b82f6 |
Budget transfer indicator |
Glass & overlay effects
Applied to elements layered over images. Not theme-switchable because they depend on photo content, not UI surface.
| Value |
Where |
rgba(0,0,0,0.7)..0.1 |
Cover image gradient (trips) |
rgba(255,255,255,0.15) |
Cover nav button background |
rgba(255,255,255,0.3) |
Cover nav button hover |
rgba(0,0,0,0.3) / rgba(0,0,0,0.5) |
Cover share button / hover |
rgba(0,0,0,0.35) |
Modal overlays (trips), detail overlay (inventory) |
rgba(0,0,0,0.5) |
Image delete button, search saving overlay |
Directional panel shadows
Non-standard shadow directions for slide-in panels and bottom sheets. Cannot use elevation tokens.
| Value |
Where |
0 -8px 32px rgba(0,0,0,0.12) |
FAB bottom sheet (fitness, trips) |
-12px 0 40px rgba(0,0,0,0.12) |
Detail slide-in sheet (inventory) |
-6px 0 28px rgba(0,0,0,0.08) |
Reading pane (reader) |
-8px 0 32px rgba(0,0,0,0.1) |
Edit sheet (trips) |
8px 0 24px rgba(0,0,0,0.08) |
Mobile sidebar (reader) |
Accent-tinted FAB shadows
Colored shadows for floating action buttons. Not in the elevation scale because they use accent color, not black.
| Value |
Where |
0 8px 24px rgba(79,70,229,0.3) |
FAB resting (fitness) |
0 12px 32px rgba(79,70,229,0.4) |
FAB hover (fitness) |
0 6px 20px rgba(79,70,229,0.3) |
FAB resting (trips) |
0 8px 28px rgba(79,70,229,0.4) |
FAB hover (trips) |
Near-match shadows
Shadows that are close to tokens but intentionally differ in blur radius or opacity.
| Value |
Nearest token |
Diff |
0 2px 6px rgba(0,0,0,0.05) |
--shadow-xs |
Larger blur, higher opacity |
0 1px 2px rgba(0,0,0,0.04) |
--shadow-xs |
Opacity 0.04 vs 0.03 |
0 1px 4px rgba(0,0,0,0.04) |
--shadow-xs |
Larger blur |
0 1px 4px rgba(0,0,0,0.08) |
--shadow-xs |
Larger blur + opacity |
0 16px 48px rgba(0,0,0,0.15) |
--shadow-xl |
Single layer vs dual |
0 1px 3px rgba(0,0,0,0.06) |
--shadow-xs |
Higher opacity |
0 8px 24px rgba(0,0,0,0.12) |
--shadow-md |
Higher opacity |
0 20px 60px rgba(0,0,0,0.15) |
--shadow-xl |
Single layer |
0 20px 60px rgba(0,0,0,0.2) |
--shadow-xl |
Single layer, higher opacity |
0 1px 3px rgba(0,0,0,0.15) |
--shadow-sm |
Toggle thumb, much higher opacity |
d3e250e361