Design Tokens

Human’s design system is built on W3C Design Tokens Community Group (DTCG) format JSON files that compile to CSS custom properties, Swift constants, Kotlin objects, and C macros.

Token Architecture

design-tokens/
  base.tokens.json         — primitive color scales, spacing, radii
  semantic.tokens.json     — theme-aware aliases (dark, light, high-contrast)
  typography.tokens.json   — font families, sizes, weights, tracking
  motion.tokens.json       — durations, easings, micro-physics presets
  glass.tokens.json        — Liquid Glass tiers (subtle, standard, prominent)
  components.tokens.json   — component-level overrides
  opacity.tokens.json      — opacity scale
  elevation.tokens.json    — z-index layers and shadows
  breakpoints.tokens.json  — responsive breakpoints

Color Tokens

Dark Theme

Token	CSS Variable	Usage
`dark.bg`	`--hu-bg`	Page background
`dark.bg-surface`	`--hu-bg-surface`	Card/panel surfaces
`dark.bg-elevated`	`--hu-bg-elevated`	Modals, popovers
`dark.text`	`--hu-text`	Primary body text
`dark.text-muted`	`--hu-text-muted`	Secondary text
`dark.text-faint`	`--hu-text-faint`	Placeholder, hint text
`dark.accent`	`--hu-accent`	Primary accent (Fidelity green)
`dark.accent-secondary`	`--hu-accent-secondary`	Secondary accent (amber)
`dark.accent-tertiary`	`--hu-accent-tertiary`	Tertiary accent (indigo)
`dark.success`	`--hu-success`	Success states
`dark.warning`	`--hu-warning`	Warning states
`dark.error`	`--hu-error`	Error states
`dark.info`	`--hu-info`	Informational states
`dark.border`	`--hu-border`	Default borders
`dark.border-subtle`	`--hu-border-subtle`	Subtle dividers

Light Theme

Light theme tokens mirror dark theme with adjusted values for white backgrounds. Access via the same CSS variables — they swap automatically based on prefers-color-scheme or explicit theme class.

High Contrast Theme

High contrast tokens maximize luminance ratios for users with low vision. All text/background pairs exceed 7:1 contrast ratio (WCAG AAA).

Spacing Tokens

Token	Value	CSS Variable
`space.2xs`	`0.25rem` (4px)	`--hu-space-2xs`
`space.xs`	`0.5rem` (8px)	`--hu-space-xs`
`space.sm`	`0.75rem` (12px)	`--hu-space-sm`
`space.md`	`1rem` (16px)	`--hu-space-md`
`space.lg`	`1.5rem` (24px)	`--hu-space-lg`
`space.xl`	`2rem` (32px)	`--hu-space-xl`
`space.2xl`	`3rem` (48px)	`--hu-space-2xl`
`space.3xl`	`4rem` (64px)	`--hu-space-3xl`

Radius Tokens

Token	Value	CSS Variable
`radius.xs`	`4px`	`--hu-radius-xs`
`radius.sm`	`6px`	`--hu-radius-sm`
`radius.md`	`8px`	`--hu-radius-md`
`radius.lg`	`12px`	`--hu-radius-lg`
`radius.xl`	`16px`	`--hu-radius-xl`
`radius.full`	`9999px`	`--hu-radius-full`

Elevation Tokens

Z-index layers are explicitly ordered to prevent stacking conflicts:

Token	Value	Usage
`z.base`	`0`	Default content
`z.raised`	`100`	Sticky headers, raised cards
`z.dropdown`	`1000`	Dropdowns, select menus
`z.sticky`	`1100`	Sticky nav, toolbars
`z.overlay`	`1200`	Overlays, backdrops
`z.modal`	`1300`	Modal dialogs
`z.popover`	`1400`	Popovers, tooltips
`z.toast`	`1500`	Toast notifications
`z.max`	`9999`	Absolute top layer

Build Pipeline

Generate all platform outputs:

cd design-tokens && npx tsx build.ts

Outputs:

ui/src/styles/_tokens.css — CSS custom properties
website/src/styles/_tokens.css — Website CSS custom properties
apps/shared/.../DesignTokens.swift — Swift Color/CGFloat constants
apps/android/.../DesignTokens.kt — Kotlin Color/Dp constants
include/human/design_tokens.h — C preprocessor macros (256-color + truecolor)
docs/design-tokens-reference.json — Machine-readable reference for docs