Semantic Tokens
Role-based tokens for surfaces, text, borders, status, tones, code and the tenant accent, in light and dark modes, plus the theming API.
Components use semantic roles, never the raw palette (status colours excepted). A role is a CSS custom property in @unflowio/tokens/css with a light value and a [data-theme='dark'] value, and a Tailwind utility that reads it at runtime.
Surfaces
| Variable | Utility | Light | Role |
|---|---|---|---|
--bg-page | bg-page | grey-100 | App canvas |
--bg-surface | bg-surface | grey-50 | Cards, inputs, table rows |
--bg-surface-raised | bg-surface-raised | #ffffff | Modals, raised cards |
--bg-muted | bg-muted | grey-100 | Hover rows, table header |
--bg-subtle | bg-subtle | grey-200 | Selected list item, switch track |
--bg-inverse | bg-inverse | black | Tooltip, bulk bar, dark snackbar |
--bg-inverse-hover | bg-inverse-hover | grey-700 | Hover on inverse surfaces, solid grey tag |
--bg-strong | bg-strong | grey-300 | Pressed or hovered subtle surfaces |
--bg-highlight | bg-highlight | yellow-200 | Search match highlight |
--bg-selected-row | bg-selected-row | accent 10% | Selected rows |
--overlay-backdrop | bg-backdrop | rgb(20 20 26 / 0.5) | Modal backdrop |
Text
| Variable | Utility | Light | Role |
|---|---|---|---|
--fg-primary | text-fg | black | Body text |
--fg-secondary | text-fg-secondary | grey-700 | Secondary labels |
--fg-muted | text-fg-muted | grey-600 | Hints, descriptions |
--fg-subtle | text-fg-subtle | grey-600 | Table secondary text, totals |
--fg-placeholder | placeholder:text-fg-placeholder | grey-600 | Placeholders |
--fg-on-inverse | text-on-inverse | white | Text on bg-inverse |
--fg-link | text-link | accent text | Links |
--fg-link-hover | text-link-hover | accent 600 step | Hovered links |
--fg-disabled | text-disabled, bg-disabled | grey-400 | Disabled text and checked disabled controls |
--fg-icon | text-icon | grey-400 | Decorative icons inside fields |
Every text role except --fg-disabled and --fg-icon reaches 4.5:1 on every surface in both modes; a unit test enforces it.
Borders and focus
| Variable | Utility | Light | Role |
|---|---|---|---|
--border-default | border-border | grey-300 | Default border |
--border-muted | border-border-muted | grey-200 | Dividers |
--border-focus | border-focus, ring-focus | --fg-primary (black in light mode) | Focused field border |
--focus-ring | shadow-focus | accent 35% | Focus ring on every interactive component |
Status
Each status has a family of roles. Fills keep their value in dark mode so white labels stay readable; the indicator, soft surfaces, borders and text switch to the matching dark steps.
| Variable | Utility | Use |
|---|---|---|
--error, --success, --warning, --info | text-error, border-error, … | Indicator colour: icons, field borders, text on a neutral surface |
--{status}-fill | bg-error-fill, … | Solid fills with a white label: destructive button, solid tag, status badge |
--{status}-fill-hover | hover:bg-error-fill-hover, … | Hover on a solid fill |
--{status}-soft | bg-error-soft, … | Soft surfaces: alerts, snackbars, secondary tags |
--{status}-soft-hover | hover:bg-error-soft-hover, … | Hover on a soft surface |
--{status}-border | border-error-border, … | Border around a soft surface |
--{status}-text | text-error-text, … | Text on a soft surface |
Tones
Categorical hues for tags and other labels that carry no status: cyan, teal, violet, indigo, pink and fuschia. Each has --tone-{hue}-soft, --tone-{hue}-soft-hover, --tone-{hue}-border and --tone-{hue}-text (bg-tone-teal-soft, text-tone-teal-text, …), with dark-mode values.
Code
Code blocks stay dark in both modes.
| Variable | Utility | Role |
|---|---|---|
--code-background | bg-code | Code block body |
--code-foreground | text-code-fg | Plain code text |
--code-header-background | bg-code-header | Header row (language, copy button) |
--code-header-foreground | text-code-header-fg | Header text |
--code-border | border-code-border | Block border |
--code-token-* | — | Syntax colours: comment, keyword, string, string-expression, constant, function, parameter, punctuation, link. These are the names Shiki's css-variables theme reads |
Accent
A tenant sets one variable, --uf-accent (default purple #c056ff). Everything else is derived from it in CSS:
| Variable | Utility | Derivation |
|---|---|---|
--accent-primary | bg-primary | OKLCH lightness − 0.09 (the 600 step: #c056ff → #a334e0) |
--accent-primary-hover | hover:bg-primary-hover | OKLCH lightness − 0.15 |
--uf-accent-fg | text-primary-fg | White or #14141a, whichever reaches 4.5:1 on the 600 step |
--accent-soft | bg-accent-soft | 10% accent on the surface |
--accent-border | border-accent-border | 35% accent on the surface |
--accent-text | text-accent-text | OKLCH lightness 0.42 (0.8 in dark mode) |
Browsers without relative colour syntax get a color-mix approximation.
Checked checkboxes, radios, switches, sliders and progress bars use --control-active (bg-control-active), which is neutral (--bg-inverse) by default. Set --control-active: var(--accent-primary) and --control-active-fg: var(--uf-accent-fg) to make them follow the accent.
Font
--uf-font-sans (default 'Manrope', system-ui, sans-serif) backs the font-sans utility. A tenant can override it, like the accent.
Dark mode
Set data-theme="dark" on <html> (or on any element, for a dark subtree). Every semantic role above has a dark value, so components need no extra classes; the accent derivations are recomputed for the dark surfaces.
<html data-theme="dark">On the client, applyTenantTheme({ accent, mode: 'dark' }) sets the attribute for you (see below).
Theming API
@unflowio/utils sets the accent inputs:
import { applyTenantTheme, tenantThemeStyle } from '@unflowio/utils';
// Server: render the variables on <html> so there is no flash.
<html style={tenantThemeStyle({ accent: '#0f7c96', fontFamily: "'IBM Plex Sans', sans-serif" })} />;
// Client: change the theme at runtime (on <html> by default, or on any element).
applyTenantTheme({ accent: '#a6e22e', mode: 'dark' });tenantThemeStyle computes --uf-accent-fg with accentForeground(accent) unless you pass accentForeground. On an element other than <html>, applyTenantTheme also sets data-uf-theme, so the accent shades are derived for that subtree.
In TypeScript
semanticTokens (from @unflowio/tokens) mirrors the stylesheet: light, dark, derived and derivedRelativeColor, keyed by variable name. It is generated from tokens.css. Read live values with var(--name); never copy them into styles.