UnflowUI
Tokens

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

VariableUtilityLightRole
--bg-pagebg-pagegrey-100App canvas
--bg-surfacebg-surfacegrey-50Cards, inputs, table rows
--bg-surface-raisedbg-surface-raised#ffffffModals, raised cards
--bg-mutedbg-mutedgrey-100Hover rows, table header
--bg-subtlebg-subtlegrey-200Selected list item, switch track
--bg-inversebg-inverseblackTooltip, bulk bar, dark snackbar
--bg-inverse-hoverbg-inverse-hovergrey-700Hover on inverse surfaces, solid grey tag
--bg-strongbg-stronggrey-300Pressed or hovered subtle surfaces
--bg-highlightbg-highlightyellow-200Search match highlight
--bg-selected-rowbg-selected-rowaccent 10%Selected rows
--overlay-backdropbg-backdroprgb(20 20 26 / 0.5)Modal backdrop

Text

VariableUtilityLightRole
--fg-primarytext-fgblackBody text
--fg-secondarytext-fg-secondarygrey-700Secondary labels
--fg-mutedtext-fg-mutedgrey-600Hints, descriptions
--fg-subtletext-fg-subtlegrey-600Table secondary text, totals
--fg-placeholderplaceholder:text-fg-placeholdergrey-600Placeholders
--fg-on-inversetext-on-inversewhiteText on bg-inverse
--fg-linktext-linkaccent textLinks
--fg-link-hovertext-link-hoveraccent 600 stepHovered links
--fg-disabledtext-disabled, bg-disabledgrey-400Disabled text and checked disabled controls
--fg-icontext-icongrey-400Decorative 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

VariableUtilityLightRole
--border-defaultborder-bordergrey-300Default border
--border-mutedborder-border-mutedgrey-200Dividers
--border-focusborder-focus, ring-focus--fg-primary (black in light mode)Focused field border
--focus-ringshadow-focusaccent 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.

VariableUtilityUse
--error, --success, --warning, --infotext-error, border-error, …Indicator colour: icons, field borders, text on a neutral surface
--{status}-fillbg-error-fill, …Solid fills with a white label: destructive button, solid tag, status badge
--{status}-fill-hoverhover:bg-error-fill-hover, …Hover on a solid fill
--{status}-softbg-error-soft, …Soft surfaces: alerts, snackbars, secondary tags
--{status}-soft-hoverhover:bg-error-soft-hover, …Hover on a soft surface
--{status}-borderborder-error-border, …Border around a soft surface
--{status}-texttext-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.

VariableUtilityRole
--code-backgroundbg-codeCode block body
--code-foregroundtext-code-fgPlain code text
--code-header-backgroundbg-code-headerHeader row (language, copy button)
--code-header-foregroundtext-code-header-fgHeader text
--code-borderborder-code-borderBlock 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:

VariableUtilityDerivation
--accent-primarybg-primaryOKLCH lightness − 0.09 (the 600 step: #c056ff → #a334e0)
--accent-primary-hoverhover:bg-primary-hoverOKLCH lightness − 0.15
--uf-accent-fgtext-primary-fgWhite or #14141a, whichever reaches 4.5:1 on the 600 step
--accent-softbg-accent-soft10% accent on the surface
--accent-borderborder-accent-border35% accent on the surface
--accent-texttext-accent-textOKLCH 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.