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: dark navy */
    --primary: 222.2 47.4% 11.2%;
    --primary-foreground: 210 40% 98%;

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

.dark {
    /* Default dark: near-white */
    --primary: 210 40% 98%;
    --primary-foreground: 222.2 47.4% 11.2%;

    /* 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.

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: blue primary, 0.375rem radius --}}
<div data-surface="admin">
    <x-ui.sidebar />
    <x-ui.data-table />
</div>

{{-- Customer surface: orange primary, 0.5rem radius --}}
<div data-surface="customer">
    <x-ui.hero />
    <x-ui.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">
    <x-ui.button>Compact action</x-ui.button>
    <x-ui.input placeholder="Compact input" />
</main>

<section data-density="comfortable">
    <x-ui.button>Comfortable action</x-ui.button>
</section>

The five physical control tiers are 32, 36, 40, 44, and 48px. Component APIs expose semantic sm / md / lg sizes; the normal md control resolves to a 44px-friendly target. Density remaps those semantic sizes to the fixed tiers instead of inventing new heights.

Layout grammar

Build screens from constrained layout primitives. Their props map to literal, discoverable classes and unknown values fall back safely, so feature code never needs arbitrary pixel gaps.

<x-ui.section space="lg" surface="muted">
    <x-ui.container size="lg">
        <x-ui.stack gap="lg">
            <x-ui.prose :centered="false">
                <h2>Workspace activity</h2>
                <p>Readable copy wraps safely, including long translated strings and URLs.</p>
            </x-ui.prose>

            <x-ui.grid cols="3" gap="md">
                <x-ui.surface>…</x-ui.surface>
                <x-ui.surface>…</x-ui.surface>
                <x-ui.surface>…</x-ui.surface>
            </x-ui.grid>

            <x-ui.cluster gap="sm" justify="end">
                <x-ui.button variant="outline">Cancel</x-ui.button>
                <x-ui.button>Save</x-ui.button>
            </x-ui.cluster>
        </x-ui.stack>
    </x-ui.container>
</x-ui.section>

Use stack for flow, cluster for wrapping inline groups, grid for columns, container and section for page rhythm, surface for panels, prose for readable text, and bleed scroll="true" for intentionally wide tables or code.

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 */
    --radius: 0.75rem;

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

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