Agnostik
Loading...

Reference

Theme System

How CSS tokens, custom variants, and runtime preferences work together.

Overview

Theme System

The theme system controls everything visual that changes at runtime — color mode, accent color, font size, layout density, motion, accessibility filters, and more. It has three layers that work together:

  1. CSS — theme.css and controls.css define tokens, custom variants, and mode-specific overrides using plain CSS and Tailwind v4 directives. No JavaScript involved.
  2. React — ThemeProvider in root.tsx reads persisted preferences, syncs them to <html> attributes and classes, and exposes them via useTheme().
  3. Storage — preferences are persisted to cookies (SSR-readable) and/or localStorage (client-only), so they survive page loads and hard reloads without flash.

The key idea: the CSS reacts to the HTML element's state. ThemeProvider doesn't apply styles — it sets attributes and classes on <html>. The CSS does the rest.