Theme System - Design Tokens & Dark Mode

A complete design token system for Astro sites. Control colors, typography, spacing, and dark mode from a single JSON file. Zero flash of unstyled content, even with view transitions.

Explore Theming

Theme System - Design Tokens & Dark Mode

About This Service

Design tokens that work across every component

The Theme System lets you control your entire site's visual identity from theme.json. Define light and dark color palettes, typography scales, and spacing - every shared component automatically adapts to your tokens via CSS custom properties.

Dark mode switching is built with zero FOUC (flash of unstyled content), even when using Astro's view transitions. The solution uses an inline head script, astro:before-swap listeners, and transition-duration guards to prevent any visible flash during page navigation.

Each token maps to a Tailwind utility class, so you write bg-primary, text-body, border-border - and the actual colors come from your theme.json. Swap the entire palette by editing one file.

JSON-based design tokens

Define all colors, fonts, and spacing in theme.json. CSS custom properties are generated at build time and consumed by Tailwind utilities. One file controls the entire visual system.

Zero-FOUC dark mode

Dark mode that works correctly with Astro view transitions. Inline head script + before-swap listener + transition guards eliminate any visible flash during theme switches or page navigation.

Per-site customization

In a monorepo, each site has its own theme.json. Shared components read tokens dynamically, so the same component renders differently on each site without code changes.

Tailwind integration

Tokens map directly to Tailwind utility classes. Use bg-primary, text-heading, border-border in your templates - the actual values come from your theme configuration.

Battle-Tested

Battle-tested across real agency deployments.

Lifetime Updates

Every template update is yours forever.

Top Lighthouse Performance

Fastest sites in your market, out of the box.

Technical Specifications

Token FormatJSON → CSS custom properties

Dark ModeZero-FOUC with view transitions

TailwindFull utility class mapping

FontsGoogle Fonts + local fallbacks

Per-Site OverrideMonorepo-ready

CompatibilityAll Wumty templates

Included with All Kits

The Theme System is a core part of every Wumty template. It's included with Starter, Single Site, Studio, and Agency kits.

Frequently Asked Questions

Common questions about the Theme System.

How do I change my site's color palette?

Edit theme.json. Change the hex values under colors.light and colors.dark, rebuild, and every component updates automatically. No need to touch any component code.

Does dark mode work with Astro view transitions?

Yes. The Theme System includes a three-part solution (inline head script, astro:before-swap listener, and transition-duration guards) that eliminates FOUC even during client-side navigation.

Can I add custom design tokens?

Yes. Add new keys to theme.json, extend the Tailwind config to reference them as CSS custom properties, and use them as utility classes in your templates.

What if I don't want dark mode?

Set default_theme to 'light' and theme_switcher to false in your config. The dark palette still exists in theme.json but won't be activated.

Works With Every Kit

The Theme System is included with the free Starter Kit, Single Site, Studio, and Agency Kit. Pair it with the SEO Toolkit for automatic meta tag generation and the Performance Toolkit for 100/100 Lighthouse scores. See all options on the pricing page.

Token Reference

The theme.json file follows a structured format that maps directly to CSS custom properties and Tailwind utility classes. Here is the top-level structure:

colors.light - Defines the light mode palette: primary, secondary, background, foreground, heading, body, border, and muted values. Each key becomes a CSS custom property (e.g., --color-primary) and a Tailwind utility (e.g., bg-primary, text-primary).
colors.dark - Defines the dark mode palette using the same keys. When dark mode is active, these values replace the light tokens via CSS custom properties scoped to the .dark class on the root element.
fonts - Specifies heading and body font families with Google Fonts integration. The build pipeline generates preconnect hints and font-display: swap declarations automatically from these values.
spacing - Controls global spacing scales used by layout components. Values map to Tailwind spacing utilities, ensuring consistent padding and margins across shared components.

To customize your site’s visual identity, edit the hex values and font names in theme.json and rebuild. Every shared component adapts automatically - no component code changes needed.

How Dark Mode Works

Dark mode in Astro with view transitions is notoriously difficult to implement without a visible flash of the wrong theme. The Theme System solves this with a three-part approach:

1. Inline head script. A small <script is:inline> block in the document <head> reads the user’s stored preference (or system setting) and applies the .dark class to <html> before the browser paints. Because this script runs synchronously before first paint, the correct theme is always visible from the first frame.

2. Before-swap listener. When Astro’s view transitions navigate between pages, the astro:before-swap event fires before the new document replaces the old one. The Theme System injects the correct theme class into e.newDocument.documentElement during this event, ensuring the incoming page has the right theme applied before it becomes visible.

3. Transition-duration guards. A CSS rule sets transition-duration: 0s !important on all elements under a .theme-swapping class. This prevents CSS transitions from animating during theme changes or page swaps, eliminating the visual flicker that occurs when background colors, text colors, and borders all transition simultaneously.

Back to products