Theming

All components read CSS variables defined in resources/css/ui.css. Re-theming never requires editing component markup — you change tokens only. Light and dark themes, plus admin and customer surfaces, are all expressed as token layers that cascade via standard CSS specificity.

How re-theming works

Existing themes store bare HSL channels ("H S% L%"). Each semantic mapping also accepts a full-color override such as --primary-color: oklch(...), so teams can migrate to perceptually uniform OKLCH without breaking an existing HSL theme. Tailwind opacity modifiers such as bg-primary/90 continue to use the same semantic utility.

To swap your brand color, open resources/css/ui.css and change the --primary channel values in both :root (light) and .dark:

/* resources/css/ui.css — change --primary for light + dark */

:root {
    /* Default: inverse primary — the text colour is the fill */
    --primary: 225 9% 17%;
    --primary-foreground: 0 0% 100%;

    /* Example: swap to indigo */
    /* --primary: 243 75% 59%; */
    /* --primary-foreground: 210 40% 98%; */
}

.dark {
    /* Default dark: inverse again — near-white fill, near-black text */
    --primary: 180 7% 97%;
    --primary-foreground: 210 11% 4%;

    /* Example: swap to indigo (lighter for dark bg) */
    /* --primary: 243 75% 75%; */
    /* --primary-foreground: 222.2 47.4% 11.2%; */
}

Token layers

ui.css is structured as five explicit layers that cascade in order:

Token reference

The tokens below are the real custom properties defined in ui.css. Tailwind utilities are derived automatically: e.g. --primary → bg-primary / text-primary / border-primary.

Dark mode without a script

The theme script (<x-ui.theme-script />) sets .dark from the stored choice and needs script-src 'self' or a nonce. A page that runs no script at all, for example an OAuth sign-in or consent page served with default-src 'none'; style-src 'self', sets data-theme="system" on <html> instead. The tokens in ui.css and in every generated theme then follow the operating system's colour scheme through prefers-color-scheme.

<!DOCTYPE html>
<html lang="en" data-theme="system">
    <head>
        <meta name="color-scheme" content="light dark">
        @vite('resources/css/app.css')
    </head>
    <body class="bg-background text-foreground">…</body>
</html>

Using surfaces

Surfaces let you scope a completely different token set to a subtree without touching the global theme. Add the data-surface attribute to any wrapper element.

{{-- Admin surface: override --primary / --ring here for a separate admin palette --}}
<div data-surface="admin">
    <brok:sidebar />
    <brok:data-table />
</div>

{{-- Customer surface: same default accent; retune it independently of admin --}}
<div data-surface="customer">
    <brok:hero />
    <brok:pricing-card />
</div>

Surface overrides apply to the entire subtree — all descendant components automatically pick up the correct --primary, --radius, and other tokens without any changes to component markup. Admin blocks must pin to the admin surface; this is enforced by the block test suite.

Density and component metrics

Control heights, horizontal padding, field gaps, card padding, dialog padding, and section rhythm are semantic tokens. Set data-density="compact" or data-density="comfortable" on any subtree to change its density without editing individual components.

<main data-density="compact">
    <brok:button>Compact action</brok:button>
    <brok:input placeholder="Compact input" />
</main>

<section data-density="comfortable">
    <brok:button>Comfortable action</brok:button>
</section>

The five physical control tiers sit on the 8px grid: 24, 32, 40, 48, and 56px. Component APIs expose semantic sm / md / lg sizes; the normal md control resolves to the 40px tier. Density remaps those semantic sizes to the fixed tiers instead of inventing new heights.

OKLCH overrides

Prefer OKLCH for new brand palettes. Keep values inside the sRGB gamut unless you also provide a wider-gamut enhancement, and verify foreground/background pairs in both light and dark modes.

:root {
    /* Full-color values override the legacy HSL channel fallback. */
    --primary-color: oklch(0.637 0.237 25.331);
    --primary-foreground-color: oklch(0.985 0 0);
}

@media (color-gamut: p3) {
    :root {
        /* Optional wider-gamut enhancement after testing clipping. */
        --primary-color: oklch(0.637 0.26 25.331);
    }
}

Custom theme example

To build a green-primary, fully rounded theme, override only the tokens you need. Every other value inherits from the defaults.

/* resources/css/ui.css — custom brand theme */

:root {
    /* Brand: forest green */
    --primary: 142 71% 45%;
    --primary-foreground: 0 0% 100%;

    /* Rounder corners (default is 1rem) */
    --radius: 1.5rem;

    /* Warmer muted tones */
    --muted: 120 10% 94%;
    --muted-foreground: 120 6% 45%;
}

.dark {
    --primary: 142 65% 55%;
    --primary-foreground: 142 10% 10%;
}