Theming

SCSS modules + design tokens. No Tailwind, no CSS-in-JS, no second CSS system. Build-time only, zero runtime.

As of 2026-08. Stable API — semver from here (Upgrading).

Every colour is a semantic token. A raw hex in any component or stylesheet is a lint failure and fails x verify's lint step.

Source of truth: packages/ui/src/tokens/_colors.scss. tokens.ts is a hand-maintained typed mirror for consumers that cannot read CSS — charts, <canvas>, OG images, transactional mail — and tokens.test.ts fails the build if the two disagree. Values on this page are transcribed from those files; when they differ, the files win.

Colour roles

Named by role, not by value: --color-bg, never --blue-500. Stored as space-separated RGB channels so rgb(var(--color-accent) / 0.5) composites without a second token.

24 roles, in the order COLOR_ROLES declares them. A component that needs a 25th is asking for a design decision, not a variable.

The six-name tone vocabulary components expose — neutral, accent, success, warning, danger, info — is $tones in _colors.scss, mirroring TONES in components/variants.ts; variants.test.ts fails on drift.

The 1.1.0 contrast retune

As of 2026-08 seven channels moved, because eight pairings failed WCAG AA. The worst was line on surface-raised in dark at 1.16:1 — an input border nobody can see.

Anything still carrying the old numbers is stale — including any copy of the palette outside packages/ui/src/tokens/. There is no gate that finds one, which is exactly how the /_x dashboard shipped the 1.16:1 border of its own.

Other token scales

Every scale is a SCSS map in packages/ui/src/tokens/, emitted as a custom property by theme.scss — the only stylesheet that emits any — and read back through the function in the third column below. t.tracking(wide), never a hand-written var(--tracking-wide) — the property name is spelled in one file, and a scale with no function is one every author has to spell for themselves.

Most scales carry a typed mirror in tokens.ts as well, for consumers that cannot read CSS. Two do not, and the table says which; tokens.test.ts fails the build on drift in the ones that do.

Breakpoints and computed lengths

Every length, breakpoint and fluid size comes from @ultimat3/ui/tokens. An app that needs max-width does not write its own mixin.

A rung is quoted or bare — '2xl' and 2xl are the same rung. Prefer a container query (t.container, t.container-query) to all three mixins: reach for the viewport only when the layout depends on it.

Each refusal is a Sass @error — the stylesheet does not compile — in the same shape as every other error: code, cause, fix:.

Layout mixins

A flex row or column is @include t.row(…) / @include t.column(…), never a hand-written display: flex block. Defined in packages/ui/src/tokens/_mixins.scss; every gap default is a spacing token.

Measured on one downstream app, As of 2026-10: 691 hand-written display: flex blocks restated these two mixins across 211 stylesheet modules. No guard refuses a hand-written flex block yet — row and column are the convention, not a build error.

Note the naming: font size is --text-*, weight is --weight-*, line height is --leading-*, tracking is --tracking-* — not --font-size-*.

Defined once per theme

Light in :root, dark behind the media query, and both mirrored under html[data-theme] so an explicit user choice always beats the OS. _colors.scss's emit mixin writes all four blocks from the same two maps, so a role cannot be defined in one block and forgotten in another.

:root                                { color-scheme: light; /* $light */ }
@media (prefers-color-scheme: dark)  { :root { color-scheme: dark; /* $dark */ } }
html[data-theme='dark']              { color-scheme: dark;  /* $dark  */ }
html[data-theme='light']             { color-scheme: light; /* $light */ }

color-scheme rides along, so form controls, scrollbars, and the UA's own ::selection follow the theme without a second declaration.

Consuming tokens

Channels, not #rrggbb, so any opacity is rgb(var(--token) / a). Inside @ultimat3/ui the wrapper is t.role('<name>', $alpha).

/* apps/web/app/nav/toolbar.module.scss */
.toolbar {
  background: rgb(var(--color-bg) / 0.8);
  backdrop-filter: blur(12px);
  color: rgb(var(--color-fg));
  border-bottom: 1px solid rgb(var(--color-line));
}

.toolbar__action {
  background: rgb(var(--color-accent));
  color: rgb(var(--color-accent-fg));

  &:hover { background: rgb(var(--color-accent-strong)); }
  &[disabled] { color: rgb(var(--color-fg-muted) / 0.6); }
}

Text on a filled surface takes that surface's -fg role — accent-fg on accent, danger-fg on danger. Hardcoding accent-fg for every tone is the bug IconButton shipped with before 1.1.0: a danger icon button wore accent's on-colour.

No dark: variants, no @media in a component. A component is bg + fg + line; the theme flip happens above it.

From TypeScript

For anything that cannot read a custom property — a chart, a <canvas>, an OG image, an email:

import { color, colorRgb, colorVar } from '@ultimat3/ui';

colorVar('accent');            // 'var(--color-accent)'      — the channel list
color('accent', 0.5);          // 'rgb(var(--color-accent) / 0.5)'
colorRgb('dark', 'accent');    // 'rgb(96 170 240)'          — resolved, no indirection

An unknown role throws X_TOKEN_UNKNOWN naming every role that exists.

Brand overrides — defineTheme()

The one seam for restyling. Not a forked stylesheet, not an SCSS @use ... with () override — there is no second path.

Declare it once, in apps/web/shared/theme.ts, as a named export brand. The framework does the rest (As of 2026-10):

// apps/web/shared/theme.ts
import { defineTheme } from '@ultimat3/ui';

export const brand = defineTheme({ preset: 'scifi' });

One file, one reader: packages/cli/src/theme-brand.ts. The /_x dev dashboard is framework chrome, not an app document, and keeps the shipped palette. No JavaScript is added: the brand is CSS, and the theme toggle and dark mode work as before — the brand answers html[data-theme] and prefers-color-scheme at every level theme.scss does, so the boot script and ThemeToggle flip between the brand's two palettes. A save to theme.ts is applied on the next x dev.

The demo app (dummy/social-media-clone) ships the scifi preset this way; examples/dummy keeps the default palette.

import { brandStyleTag, defineTheme } from '@ultimat3/ui';

const brand = defineTheme({
  colors: { light: { accent: '31 110 178' }, dark: { accent: '96 170 240' } },
  radius: { md: '0.375rem' },
  font: { sans: 'Inter, system-ui, sans-serif' },
});

brand.css;                  // the four CSS blocks, as a string
brandStyleTag(brand);       // '<style>…</style>' — exactly what the framework inlines

Returns a frozen { css: string }. It emits :root, html[data-theme='light'], the prefers-color-scheme: dark block and html[data-theme='dark'] — radius and font ride :root only. Output is ordered by the canonical scale arrays rather than by your object, so re-rendering the same input is byte-identical. Empty input gives css: '', which the framework emits nothing for.

Values are validated, never escaped

The output lands in a <style> element, so a value that could close it is refused rather than sanitised.

Resolution and first paint

Order: explicit localStorage choice → theme.defaultMode, where 'system' (the default) means the OS preference and 'dark' or 'light' is the app's own opinion. Applied by a blocking inline <head> script, before first paint and before the render-blocking stylesheet, so there is no flash of the wrong theme.

The boot writes the script; the app writes nothing (As of 20.2.0). x dev, the container and x build's static export all inline themeScript({ fallback }) from @ultimat3/render with theme.defaultMode from app.config.ts as the fallback, and the served processes admit its sha256 to script-src from the same string — packages/cli/src/theme-boot.ts. An app that wants to open dark sets theme: { defaultMode: 'dark' } and is done. The storage key is ultimate.theme on both sides: the boot reads it, ThemeToggle writes it, and a test pins the two literals equal. Before this release neither of the framework's two theme scripts was inlined by anything, both fell back to light, and they disagreed on the key.

@ultimat3/ui's own inline script (THEME_INLINE_SCRIPT, themeInlineScriptTag, themeInlineScriptHash, themeInlineScriptCspSource) is gone: an app that still inlined it by hand deletes that code — the boot's script already runs first.

On the client, resolveTheme() reads the same order back: stored choice, then the data-theme the boot stamped (ThemeEnv.current()), then defaultTheme(env) — the app's own defaultMode as the boot stamped it in data-theme-default (ThemeEnv.appDefault()), and the OS only when that is 'system' or absent — so with defaultMode: 'dark' on a light-OS machine the first toggle flips to light instead of writing the dark already on screen.

Where tokens live

shared/ is importable by site/, app/, and api/. site/ importing from app/ stays a build error — see Project layout. The /_x dev dashboard reads its six channels from colorTokens at render time rather than keeping a copy → Admin dashboard.

Derived surfaces

The manifest is generated. Hand-editing a colour there drifts from the tokens and fails x verify's manifest step.

Accessibility

:focus-visible {
  outline: var(--stroke-thick) solid rgb(var(--color-accent));
  outline-offset: var(--stroke-thick);
}

::selection {
  background: rgb(var(--color-accent) / 0.25);
  color: rgb(var(--color-fg-strong));
}

@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
    scroll-behavior: auto !important;
  }
}

What contrast is actually gated

contrast.test.ts measures every pairing below in both themes, over the four surfaces (bg, bg-soft, surface, surface-raised) and the four status tones. A failure reports the measured ratio, not just a boolean.

shadow is not contrast-gated.

The global guard collapses motion to 0.01ms !important on *. Substituting a cross-fade for a movement therefore needs the component's own prefers-reduced-motion block, !important, on a selector more specific than * — otherwise the feedback is gone rather than calmed. The rule and the rest of the motion vocabulary: Interface rules.

Rules

• Semantic tokens everywhere. A raw hex — or an rgb()/hsl() called with numbers — in any .scss this package ships is a failing test, packages/ui/src/tokens/tokens.test.ts, on x verify's unit step. Not lint: biome ignores .scss, and the rule said "lint" while nothing read it. Two files are exempt, because a literal is supposed to live in them: tokens/_colors.scss and tokens/_shadow.scss. In an app the same rule is guards/raw-colour.ts.
• Each token defined once per theme, by the emit mixin: :root, the media query, and both data-theme mirrors.
• html[data-theme] always beats prefers-color-scheme.
• Theme applied before first paint by a blocking inline script.
• 24 colour roles. Adding one is a design-system change, reviewed as one, and it lands in _colors.scss and tokens.ts in the same commit.
• Text on a filled surface uses that surface's -fg role, never accent-fg by default.
• Restyle through defineTheme(). A forked stylesheet is the wrong answer to every brand question.
• Components never contain a media query for theme. They read tokens.
• Contrast verified in light and dark; a token pair that passes in one theme only is a failure.
• Colours are themed; numbers, dates, and money are localized → I18n, Money, Timezones and dates.

Component-by-component props and the token vocabulary each one accepts: UI components. What a screen has to do with those tokens — motion, focus, contrast, the four loading states: Interface rules.