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 (Human green) | | dark.accent-secondary | --hu-accent-secondary | Secondary accent (amber) | | dark.accent-tertiary | --hu-accent-tertiary | Tertiary accent (steel blue) | | 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