Design system overview

The platform’s design system is a dual-target token graph: the web’s apps/svelte-web/src/routes/layout.css is the source of truth for every color, type, spacing, radius, and shadow token, defined in OKLCH for both light and dark modes. The native mobile palette is derived from those same OKLCH values and committed into each native app as generated token files (Tokens.swift / Tokens.kt, light + dark), read via @Environment(\.tokens) (iOS) / LocalTokens.current (Android). Inter is the body font on both sides.

Token flow

flowchart LR
    LayoutCss["apps/svelte-web/src/routes/layout.css<br/>:root + .dark OKLCH"]
    Tailwind["Tailwind v4 @theme inline<br/>web utility classes"]
    NativeTokens["Generated native tokens<br/>Tokens.swift / Tokens.kt (light + dark)"]

    LayoutCss --> Tailwind
    LayoutCss --> NativeTokens

Edits land in layout.css. The native token files are regenerated from those OKLCH values and committed into each app. Tailwind v4’s @theme inline block at the bottom of layout.css exposes every CSS variable as a Tailwind theme key automatically.

What lives where

Subject	Page	Generation
Colors (67 light + 67 dark), typography, spacing, radius, shadows	Tokens	Auto-generated every build from layout.css.
Web bits-ui-wrapped primitives + native mobile primitive libraries	Components	Hand-authored catalog organized by tier.
Design intent — property-first philosophy, status taxonomy, dark mode strategy, a11y floor	Principles	Hand-authored synthesis of the team’s design intent.

For framework-specific patterns (form actions, kebab-case filenames, icon library rules) see Conventions → Web and Conventions → Mobile (Native).

Enforcement

Two codified review agents sit alongside the docs:

• .claude/agents/design-review.md — runs a token-anchored visual inspection (color resolution vs. layout.css, spacing scale, typography hierarchy, status badge colors, both light + dark themes, WCAG 2.1 AA keyboard / contrast / labels) on Playwright-renderable surfaces.
• .claude/skills/mobile-ui-audit/SKILL.md — flags native mobile UI violations across the SwiftUI + Compose apps: hardcoded Color literals outside the generated token files (must read @Environment(\.tokens) / LocalTokens.current), static palette refs that bypass dark-mode switching, raw Material3 buttons instead of PrimaryButton / SecondaryButton, hardcoded user-facing strings instead of the i18n lookup, and Origin-header / Bearer-auth regressions.

Both are invoked manually from Claude Code (@design-review / @mobile-ui-audit) — there is no CI hook today.

Adding a new token

1. Define the OKLCH value in both :root and .dark blocks of apps/svelte-web/src/routes/layout.css.
2. (If the token should be available on native mobile) regenerate the committed native token files (Tokens.swift / Tokens.kt, light + dark) from the new OKLCH values.
3. Run bun --filter @repo/docs build — the regenerated /design/tokens/ page picks up the new row automatically.