Theming

Ragnar uses a three-layer token architecture controlled through HTML data attributes. Themes, modes, spacing scale, and border radius are all swappable at runtime — set them imperatively or with the RagnarProvider.

Overview

Ragnar's theming system is built on CSS custom properties with three distinct layers:

  1. Primitives — 20 color palettes (19 with shades 50–950, plus mono with an extra 0 for pure white), named like --color-blazeorange-500. Plus radius, sizing, spacing, viewport, and font-size scales.
  2. Modes — Light, dim, and dark mode mappings. Activated via data-mode.
  3. Themes — Accent color and font pairings layered on top of mode tokens. Activated via data-theme.

Data Attributes

All theming is controlled through four HTML data attributes. The RagnarProvider writes these for you, but you can also set them by hand:

Themes

Two themes ship out of the box. Each defines an accent color, font pairing, and surface treatment. Use createTheme to make your own with minimal token overrides.

industrial-retro

The default. Geist type and a blazeorange accent for confident, modern surfaces.

minimal

Restrained, near-monochrome surfaces with a single accent. Ideal for content-heavy apps.

Modes

Ragnar supports three light levels: light, dim, and dark. Each maps the same semantic token names to different primitive values, so components don't need to change at all when you switch.

Spacing Scale

data-spacing adjusts the base spacing unit:

  • compact — Denser layouts, tighter padding.
  • standard — Default spacing (recommended).
  • wide — More breathing room, larger touch targets.

Border Radius

data-curves controls the global border radius scale:

  • sharp — Fully squared off.
  • slight — Subtle rounding. Default.
  • sweeping — Friendly, large rounding.

RagnarProvider

RagnarProvider is the recommended way to manage these attributes. It writes them to <html>on every change, lazy-loads the theme's fonts, persists choices to localStorage, and optionally follows the OS prefers-color-scheme.

Custom Themes

Use createTheme to override only the tokens you care about — the rest fall through from the base theme you extend. Custom themes are registered with the provider and selected by name like any built-in theme.