Dark Mode

Built-in dark mode with FOUC prevention and regression tests.

Setup

1. Include ThemeScript before your content to prevent FOUC:

@layout.Base(layout.DefaultPageProps()) {
    @layout.ThemeScript("")
    {@content}
}

2. Add the @custom-variant directive in your CSS:

@import "tailwindcss";
@custom-variant dark (&:where(.dark, .dark *));

3. Optionally add a ThemeToggle:

@layout.ThemeToggle("Toggle theme", "")

How It Works

• ThemeScript runs before first paint, reads localStorage, and adds the .dark class to <html>.
• color-scheme: light on :root, color-scheme: dark on .dark — native form controls render correctly in both modes.
• ThemeToggle syncs across all instances on the page via querySelectorAll.

Color Convention

Every neutral and semantic color class has a dark: variant — enforced by regression tests (TestDarkModeCompliance, TestDarkModeSemanticColors).

LocalStorage Guard

ThemeScript and ThemeToggle both wrap localStorage access in try/catch to handle Safari private mode (QuotaExceededError).