Theming

Change the base theme's tokens, or add a theme of your own.

Updated
On this page

A theme is a set of token values. Components read the tokens and never a fixed colour, so restyling the whole UI is changing a few custom properties. Nothing is compiled per theme.

Tokens

The canvas and each fill show three steps: -light, the base and -dark, as in primary-light and primary-dark. The swatches read the live tokens, so they follow light or dark.

Page

canvas

ink

Aa
Aa
Aa

The page and its default text.

card

ink

Aa

Above the page and opaque: cards, dropdowns, modals, toasts.

well

ink

Aa

A recess drawn over the surface: code, table headers and tracks.

hover

ink

Aa

The hover and selected fill, drawn as ink.

muted

text only

Aa

Quiet text: hints, captions, descriptions.

Brand

primary

primary-contrast

Aa
Aa
Aa

The default button and badge.

secondary

secondary-contrast

Aa
Aa
Aa

The quiet fill that steps back from primary.

accent

accent-contrast

Aa
Aa
Aa

A second brand color for highlights.

Status

destructive

destructive-contrast

Aa
Aa
Aa

The destructive variant of buttons, badges and alerts.

success

success-contrast

Aa
Aa
Aa

The success variant of badges and alerts.

warning

warning-contrast

Aa
Aa
Aa

The warning variant of badges and alerts.

info

info-contrast

Aa
Aa
Aa

The info variant of badges and alerts.

Brand scales

Each brand color also brings a 50 to 950 scale, as bg-primary-200 or text-accent-700. The color sits at the step nearest its lightness, or the step a theme's shades field names, and the rest spread between a near-white and a near-black.

Each fill also has a -text color for when the fill is the text, as in an alert or a link. It is the fill until a theme sets a better one.

Shape

Every border is ink at one of three strengths (0 to 1), so it follows the theme. The same strengths are the -soft, -medium and -hard variant of any color (ink, primary, secondary, accent, destructive, success, warning, info), so bg-primary-soft, border-ink-hard and ring-accent-medium follow the theme too:

  • --strength-soft (0.05): rules inside a surface, such as separators and table rows.
  • --strength-medium (0.1): cards, menus and alerts.
  • --strength-hard (0.25): controls, such as inputs, outline buttons and switches.

The results are --border-color-soft, --border-color and --border-color-hard, with border-ink-soft, border-ink-medium and border-ink-hard as the matching utilities.

Shadows take their color from --shadow-color (black, so a dark theme never glows) at --shadow-strength (1, where 0 is flat). --radius-full shapes pills and dots, and --tint-strength sets how strongly an alert washes its color.

Five tokens set states:

  • --hover-strength (0.1): how far ink tints a hovered button or row.
  • --well-strength (0.04, 0.4 on dark): how dark a recess is.
  • --disabled-opacity (0.5): a disabled control's opacity.
  • --backdrop-strength (0.5): how dark a modal dims the page.
  • --track-strength (0.2): how faint a progress track or spinner ring is.

border

Every line: borders, dividers, field outlines. Never a fill.

ring

The focus ring.

radius

The base corner radius. Smaller parts use a little less of it.

shadow-soft

The lift of cards, inputs and the selected tab.

shadow

Dropdown panels.

shadow-hard

Modals and toasts.

Colour values are HSL channels without the hsl(): --primary: 221 83% 53%. Pick each contrast color to read clearly on its fill.

Loading the stylesheet

The addon ships its CSS prebuilt as ui.min.css, with a readable ui.css beside it: the tokens, the base, the elements and the size scale, with no utilities. Link the minified file, then your own file after it:

{var $ui = p('@ui')->file('ui.min.css')}
{var $site = p('assets')->file('site.css')}

<link
	rel="stylesheet"
	href="{$ui->url()}"
>
<link
	rel="stylesheet"
	href="{$site->url()}"
>

A component's root is one class. Everything inside it, its parts, looks and open or selected states, has no specificity, so a plain rule in the later file wins with no !important and no longer selector. Only a root's own :hover, :focus-visible and disabled rules carry weight, and the component variables avoid them. Set a token to change the whole UI, or write a rule for one element:

:root {
	--primary: 221 83% 53%;
	--radius: 0.25rem;
}

.card {
	gap: 1rem;
}

.card > header {
	padding: 0 2rem;
}

The dark values and a rule that targets :root are covered below. A build with UnoCSS can do the same and more.

Changing the base theme

With UnoCSS, the preset writes the tokens first and the component CSS after them. A site's own rules go after both, in the same ui layer, so they win without raising specificity. Put them in a CSS file and add it to the site's UnoCSS config as a preflight:

import { readFileSync } from 'node:fs';
import { defineConfig } from 'unocss';
import ui from '../../phlat/addons/ui/assets/preset.mjs';

export default defineConfig({
	presets: [ui()],
	preflights: [
		{
			layer: 'ui',
			getCSS: () => readFileSync(new URL('./theme.css', import.meta.url), 'utf8'),
		},
	],
});

Then set the tokens to change in theme.css:

:root {
	--primary: 221 83% 53%;
	--primary-contrast: 0 0% 98%;
	--ring: 221 83% 53%;
	--radius: 0.25rem;
}

A :root rule also reaches dark: the preset's system dark rule has the same weight and comes first, so the later rule wins and the token is the same in both schemes. To give dark its own value, write it for [data-theme=dark] and, inside prefers-color-scheme: dark, for :root:not([data-theme=light]), which outweighs :root:

[data-theme=dark] {
	--primary: 217 91% 70%;
}

@media (prefers-color-scheme: dark) {
	:root:not([data-theme=light]) {
		--primary: 217 91% 70%;
	}
}

To restyle one component, write a plain rule for it, such as .button { height: 3rem; }, or change its text size, since it is measured in em. Put a class of the region in front to change it only there: .release-list .button { font-size: 1.125rem; } makes every button inside .release-list larger and leaves the rest alone. The overview covers size, colour and looks.

Adding a theme

A theme is a selector that sets every token, picked by a data-theme attribute. Set all of them: a token left out falls through to the light or dark value beneath it. Add color-scheme so native controls and scrollbars match, and avoid the names light and dark, which the preset already uses.

:root[data-theme=forest],
[data-theme=forest] {
	--canvas: 60 20% 98%;
	--ink: 150 20% 8%;
	--muted: 150 8% 40%;
	--card: 0 0% 100%;
	--strength-medium: 0.15;
	--primary: 152 55% 26%;
	--primary-contrast: 60 20% 98%;
	--destructive: 0 72% 45%;
	--destructive-contrast: 0 0% 98%;
	--ring: 152 55% 26%;
	--radius: 0.75rem;
	color-scheme: light;
}

The selector has two parts for a reason. :root[data-theme=forest] is what <html data-theme="forest"> matches, and its extra weight keeps it ahead of the preset's system dark rule wherever the file loads. On any other element [data-theme=forest] is enough.

Using a theme

Set the attribute on <html> to theme the page, from wherever the site keeps the choice:

<html
	lang="en"
	data-theme="{$theme}"
>

Without the attribute the page follows the system, light or dark.

On any other element the attribute themes just that region. Tokens inherit, but only the body paints a background, so give the region its own:

<section
	data-theme="forest"
	class="bg-canvas text-ink p-6 rounded-lg"
>
	{ui button, title: 'Save' /}
</section>

Components inside read the region's tokens, so the same button is forest green here and the base theme everywhere else.