Theme System === Compass ships a runtime theming engine that lets users switch between preset palettes, create custom themes through the AI agent, and edit those themes incrementally. Every theme defines light and dark color maps, typography, spacing tokens, and shadow scales. Switching themes triggers an animated circle-reveal transition from the click origin. This document explains how the pieces fit together, what problems the architecture solves, and where to look when something breaks. How themes work --- A theme is a `ThemeDefinition` object (defined in `src/lib/theme/types.ts`) containing: - **32 color keys** for both light and dark modes (background, foreground, primary, sidebar variants, chart colors, etc.) - all in oklch() format - **fonts** (sans, serif, mono) as CSS font-family strings, plus an optional list of Google Font names to load at runtime - **tokens** for border radius, spacing, letter tracking, and shadow geometry - **shadow scales** (2xs through 2xl) for both light and dark, since some themes use colored or offset shadows - **preview colors** (primary, background, foreground) used by the theme card swatches in settings When a theme is applied, `applyTheme()` in `src/lib/theme/apply.ts` builds a `