Skip to main content

Token reference

Every name lives on :root in light-tokens.css; dark-tokens.css repeats the 68 that change in the dark. The Tailwind column is what tailwind.css / styles.css add: a colour listed as bg-x is also text-x, border-x, ring-x, fill-x and takes opacity modifiers (bg-x/10); a text-* size carries its line height; --spacing is the unit every spacing utility multiplies. A token marked deprecated stays in the contract but no component reads it, and zui theme check warns (inert-override) when a theme sets it. Sections follow the groups of tokens.json.

Sections​

Contract version​

the token contract this file implements. A theme may set the same name to its own version; zui theme diff prints both

TokenLightDarkDescriptionTailwind
--zui-theme-version"2.0.0"Version of the token contract (semver, quoted); a theme file may set its own.

Core primitives​

TokenLightDarkDescriptionTailwind
--background#ffffff#0a0a0aThe page surface.bg-background
--foreground#0a0a0a#fafafaBody text on --background.text-foreground

Border & input​

TokenLightDarkDescriptionTailwind
--border#e4e4e7#a1a1aaDefault border and divider colour.bg-border
--input#e4e4e7#27272aBorder of form controls.bg-input
--input-unsaved#fffbeb#1a1808Background of a field with unsaved changes.bg-input-unsaved
--ring#27272a#d4d4d8Keyboard focus ring.bg-ring

Primary​

--<hue>-text is the hue as small text on --background (and on the hue's 10% tint), AA-safe where the surface colour itself is not.

TokenLightDarkDescriptionTailwind
--primary#2563ebBrand surface: primary buttons, active states, links.bg-primary
--primary-foreground#ffffffText on --primary.text-primary-foreground
--primary-text#1d4ed8#60a5faPrimary-coloured text on --background.text-primary-text
--primary-border#bed0f9#12254eBorder of a primary-tinted callout or outline: ~30% --primary over --background.bg-primary-border
--primary-glowrgba(37, 99, 235, 0.3)rgba(37, 99, 235, 0.4)Translucent primary halo (AI button, glow effects).bg-primary-glow

Secondary​

TokenLightDarkDescriptionTailwind
--secondary#f4f4f5#27272aSecondary button surface.bg-secondary
--secondary-foreground#18181b#fafafaText on --secondary.text-secondary-foreground

Danger​

TokenLightDarkDescriptionTailwind
--danger#dc2626Danger surface: danger buttons, error borders.bg-danger
--danger-foreground#ffffffText on --danger.text-danger-foreground
--danger-text#b91c1c#f87171Danger-coloured text on --background (error messages).text-danger-text
--danger-border#f5bebe#491212Border of a danger-tinted callout or outline: ~30% --danger over --background.bg-danger-border

Muted​

TokenLightDarkDescriptionTailwind
--muted#f4f4f5#27272aQuiet surface: table headers, skeletons, disabled fills.bg-muted
--muted-foreground#65656d#a1a1aaSecondary text: descriptions, placeholders, captions.text-muted-foreground

Accent​

TokenLightDarkDescriptionTailwind
--accent#f4f4f5#27272aHover / active row and option surface.bg-accent
--accent-foreground#18181b#fafafaText on --accent.text-accent-foreground
--accent-glowrgba(244, 244, 245, 0.5)rgba(39, 39, 42, 0.7)Translucent accent halo.bg-accent-glow

Popover​

TokenLightDarkDescriptionTailwind
--popover#ffffff#18181bFloating surface: menus, listbox options, tooltips.bg-popover
--popover-foreground#0a0a0a#fafafaText on --popover.text-popover-foreground

Card​

TokenLightDarkDescriptionTailwind
--card#ffffff#18181bRaised content surface.bg-card
--card-foreground#0a0a0a#fafafaText on --card.text-card-foreground

Success​

TokenLightDarkDescriptionTailwind
--success#15803dSuccess surface: badges, toasts, progress.bg-success
--success-foreground#ffffffText on --success.text-success-foreground
--success-text#166534#4ade80Success-coloured text on --background.text-success-text
--success-border#b9d9c5#0d2d19Border of a success-tinted callout or outline: ~30% --success over --background.bg-success-border

Warning​

--warning-foreground sits on a warning surface, --warning-text is warning-coloured text on --background

TokenLightDarkDescriptionTailwind
--warning#b45309Warning surface.bg-warning
--warning-foreground#ffffffText on --warning.text-warning-foreground
--warning-text#92400e#fbbf24Warning-coloured text on --background (required markers, hints).text-warning-text
--warning-border#e9cbb5#3d200aBorder of a warning-tinted callout or outline: ~30% --warning over --background.bg-warning-border

Info​

TokenLightDarkDescriptionTailwind
--info#f9fafb#1f2937Informational callout surface.bg-info
--info-foreground#0a0a0a#fafafaText on --info.text-info-foreground
--info-textvar(--info-foreground)Info-coloured text on --background; --info is a near-neutral surface, so this follows --info-foreground.text-info-text
--info-border#e4e4e7#27272aBorder of an informational callout.bg-info-border

Categorical data-visualization palette for @zuilib/charts​

Slots are assigned to series in fixed declaration order and never cycled — the order is CVD-validated (adjacent-pair ΔE ≥ 8 in both modes). Marks are non-text graphics held to WCAG 1.4.11 (3:1), not 4.5:1; light slots 3–5 sit below 3:1 by design and rely on tooltips, the interactive legend and a paired table view. Scatter/bubble charts use at most slots 1–3 together (the all-pairs-validated subset). A theme overriding any slot must re-validate the full order.

TokenLightDarkDescriptionTailwind
--chart-1#2563eb#3b82f6Series slot 1 — the brand blue; harmonizes with --primary.bg-chart-1
--chart-2#eb6834#d95926Series slot 2 — orange.bg-chart-2
--chart-3#1baf7a#199e70Series slot 3 — aqua.bg-chart-3
--chart-4#eda100#c98500Series slot 4 — yellow.bg-chart-4
--chart-5#e87ba4#d55181Series slot 5 — magenta.bg-chart-5
--chart-6#008300#3fa33fSeries slot 6 — green.bg-chart-6
--chart-7#4a3aa7#9085e9Series slot 7 — violet.bg-chart-7
--chart-8#e34948#e66767Series slot 8 — red.bg-chart-8
TokenLightDarkDescriptionTailwind
--sidebar#f4f4f5#18181bSidebar surface. Deprecated: No component reads the sidebar tokens; kept for compatibility.bg-sidebar
--sidebar-foreground#18181b#fafafaText on --sidebar. Deprecated: No component reads the sidebar tokens; kept for compatibility.text-sidebar-foreground
--sidebar-primary#2563ebSidebar primary surface. Deprecated: No component reads the sidebar tokens; kept for compatibility.bg-sidebar-primary
--sidebar-primary-foreground#ffffffText on --sidebar-primary. Deprecated: No component reads the sidebar tokens; kept for compatibility.text-sidebar-primary-foreground
--sidebar-accent#e4e4e7#27272aSidebar hover / active item surface. Deprecated: No component reads the sidebar tokens; kept for compatibility.bg-sidebar-accent
--sidebar-accent-foreground#18181b#fafafaText on --sidebar-accent. Deprecated: No component reads the sidebar tokens; kept for compatibility.text-sidebar-accent-foreground
--sidebar-border#e4e4e7#27272aSidebar border. Deprecated: No component reads the sidebar tokens; kept for compatibility.bg-sidebar-border
--sidebar-ring#2563ebSidebar focus ring. Deprecated: No component reads the sidebar tokens; kept for compatibility.bg-sidebar-ring

Gradients​

TokenLightDarkDescriptionTailwind
--gradient-primarylinear-gradient(135deg, #3b82f6 0%, #2563eb 100%)Primary sweep. Deprecated: No component reads the gradient tokens; kept for compatibility.bg-gradient-primary
--gradient-subtlelinear-gradient(180deg, #ffffff 0%, #f4f4f5 100%)linear-gradient(180deg, #0a0a0a 0%, #18181b 100%)Background to muted fade. Deprecated: No component reads the gradient tokens; kept for compatibility.bg-gradient-subtle
--gradient-cardlinear-gradient(135deg, rgba(59, 130, 246, 0.05) 0%, rgba(37, 99, 235, 0.05) 100%)linear-gradient(135deg, rgba(59, 130, 246, 0.1) 0%, rgba(37, 99, 235, 0.1) 100%)Faint primary tint for cards. Deprecated: No component reads the gradient tokens; kept for compatibility.bg-gradient-card
--gradient-herolinear-gradient(135deg, #3b82f6 0%, #8b5cf6 50%, #ec4899 100%)Blue to violet to pink hero sweep. Deprecated: No component reads the gradient tokens; kept for compatibility.bg-gradient-hero

Shadows​

the --shadow-1 … --shadow-4 scale from barely-there to overlay, plus the semantic aliases

TokenLightDarkDescriptionTailwind
--shadow-10 1px 2px 0 rgba(0, 0, 0, 0.05)0 1px 2px 0 rgba(0, 0, 0, 0.3)Barely-there lift.shadow-1
--shadow-20 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -1px rgba(0, 0, 0, 0.06)0 4px 6px -1px rgba(0, 0, 0, 0.5), 0 2px 4px -1px rgba(0, 0, 0, 0.3)Switch thumb, small floating parts.shadow-2
--shadow-30 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -2px rgba(0, 0, 0, 0.05)0 10px 15px -3px rgba(0, 0, 0, 0.5), 0 4px 6px -2px rgba(0, 0, 0, 0.3)Popovers: Select and Combobox options.shadow-3
--shadow-40 20px 25px -5px rgba(0, 0, 0, 0.1), 0 10px 10px -5px rgba(0, 0, 0, 0.04)0 20px 25px -5px rgba(0, 0, 0, 0.7), 0 10px 10px -5px rgba(0, 0, 0, 0.4)Dialogs and drawers.shadow-4
--shadow-card0 1px 3px 0 rgba(0, 0, 0, 0.1), 0 1px 2px 0 rgba(0, 0, 0, 0.06)0 1px 3px 0 rgba(0, 0, 0, 0.5), 0 1px 2px 0 rgba(0, 0, 0, 0.3)Card resting shadow: between --shadow-1 and --shadow-2, its own value.shadow-card
--shadow-glow0 0 20px rgba(59, 130, 246, 0.4)0 0 20px rgba(59, 130, 246, 0.5)Primary halo. Deprecated: No component reads --shadow-glow; kept for compatibility.shadow-glow

Shape​

--radius is the one knob: every step below derives from it, and the Tailwind utilities (rounded-sm, rounded-md, rounded-lg, ...) carry the same derivation inside the utility (.rounded-lg { border-radius: calc(var(--radius) + 4px) }, see theme.css), resolved at the element, so --radius on :root or on any subtree (.panel { --radius: 0 }) reshapes everything inside it. The --radius-* steps are for plain CSS; the utilities do not read them, so overriding one step on :root changes plain-CSS uses only.

TokenLightDarkDescriptionTailwind
--radius0.5remThe one shape knob: 0 squares everything, 999px makes pills.rounded, rounded-sm, rounded-md, rounded-lg, rounded-xl, rounded-2xl, rounded-3xl
--radius-smcalc(var(--radius) - 2px)Checkbox, small chips.
--radius-mdvar(--radius)Controls: Button, Input, Select.
--radius-lgcalc(var(--radius) + 4px)Cards, popovers.
--radius-xlcalc(var(--radius) + 8px)Dialogs, drawers.
--radius-2xlcalc(var(--radius) + 16px)
--radius-3xlcalc(var(--radius) + 24px)
--radius-full9999pxTrue circles (avatars, radio dots, switch tracks) and pill-shaped controls (Badge shape="pill", chips). Never themed.
--radius-buttonvar(--radius)Button corners. Follows the --radius knob by default; 9999px gives pill buttons and 0 sharp ones without reshaping cards or inputs.rounded-button

Type​

TokenLightDarkDescriptionTailwind
--font-sansui-sans-serif, system-ui, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"Body and UI face; also font-sans and the preflight body font.font-sans
--font-monoui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospaceCode face; font-mono.font-mono

Type scale​

size and line height per text-* step

TokenLightDarkDescriptionTailwind
--text-xs0.75remtext-xs size.text-xs
--text-xs-line-heightcalc(1 / 0.75)text-xs line height.
--text-sm0.875remtext-sm size: control text, labels.text-sm
--text-sm-line-heightcalc(1.25 / 0.875)text-sm line height.
--text-base1remtext-base size: body.text-base
--text-base-line-height1.5text-base line height.
--text-lg1.125remtext-lg size.text-lg
--text-lg-line-heightcalc(1.75 / 1.125)text-lg line height.
--text-xl1.25remtext-xl size.text-xl
--text-xl-line-heightcalc(1.75 / 1.25)text-xl line height.
--text-2xl1.5remtext-2xl size: Heading h2.text-2xl
--text-2xl-line-heightcalc(2 / 1.5)text-2xl line height.
--text-3xl1.875remtext-3xl size: Heading h1.text-3xl
--text-3xl-line-heightcalc(2.25 / 1.875)text-3xl line height.

Font weights​

TokenLightDarkDescriptionTailwind
--font-weight-normal400font-normal.font-normal
--font-weight-medium500font-medium: labels, buttons.font-medium
--font-weight-semibold600font-semibold: headings.font-semibold
--font-weight-bold700font-bold.font-bold

Spacing​

the unit Tailwind's scale multiplies (p-4 = 4 × this). Padding, gaps and margins inside the components all derive from it.

TokenLightDarkDescriptionTailwind
--spacing0.25remThe spacing unit; every p-* / gap-* / m-* utility is a multiple of it.p-4, gap-2, … (multiples)

Control density​

the box every sized control (Button, Input, NativeSelect, Select, Combobox, Textarea) is built on. Fields share the heights with Button; Button has its own, wider, horizontal padding.

TokenLightDarkDescriptionTailwind
--control-height-sm2remHeight of a size="sm" control.
--control-height-md2.5remHeight of a size="md" control (the default).
--control-height-lg3remHeight of a size="lg" control.
--control-padding-x-sm0.75remHorizontal padding of a sm field.
--control-padding-x-md1remHorizontal padding of a md field.
--control-padding-x-lg1remHorizontal padding of a lg field.

Button​

its own, wider, horizontal padding on the shared control heights (its corner shape is --radius-button)

TokenLightDarkDescriptionTailwind
--button-padding-x-sm0.75remHorizontal padding of a sm Button.
--button-padding-x-md1remHorizontal padding of a md Button.
--button-padding-x-lg1.5remHorizontal padding of a lg Button.

Card padding​

multiples of --spacing

TokenLightDarkDescriptionTailwind
--card-padding-smcalc(var(--spacing) * 4)Card padding="sm".
--card-padding-mdcalc(var(--spacing) * 6)Card padding="md" (the default).
--card-padding-lgcalc(var(--spacing) * 8)Card padding="lg".

Table cell padding​

multiples of --spacing

TokenLightDarkDescriptionTailwind
--table-cell-padding-x-smcalc(var(--spacing) * 2)Table size="sm" cell horizontal padding.
--table-cell-padding-y-smcalc(var(--spacing) * 1.5)Table size="sm" cell vertical padding.
--table-cell-padding-x-mdcalc(var(--spacing) * 3)Table size="md" cell horizontal padding.
--table-cell-padding-y-mdcalc(var(--spacing) * 2.5)Table size="md" cell vertical padding.

Drawer panel extent​

width for side="start" / "end", height for top / bottom. Deliberately --drawer-size-*, not --drawer-width-*: which axis is measured depends on side

TokenLightDarkDescriptionTailwind
--drawer-size-sm20remDrawer size="sm" panel extent.
--drawer-size-md28remDrawer size="md" panel extent.
--drawer-size-lg40remDrawer size="lg" panel extent.

Container width caps and gutter​

TokenLightDarkDescriptionTailwind
--container-width-sm40remContainer size="sm" max-width.
--container-width-md48remContainer size="md" max-width.
--container-width-lg64remContainer size="lg" max-width.
--container-width-xl80remContainer size="xl" max-width.
--container-width-2xl96remContainer size="2xl" max-width.
--container-paddingcalc(var(--spacing) * 4)Container horizontal gutter.

Dialog panel width caps and padding​

TokenLightDarkDescriptionTailwind
--dialog-width-sm24remDialog size="sm" max-width.
--dialog-width-md32remDialog size="md" max-width (the default).
--dialog-width-lg42remDialog size="lg" max-width.
--dialog-width-xl56remDialog size="xl" max-width.
--dialog-paddingcalc(var(--spacing) * 6)Dialog panel padding (header, body and footer).

Anchored panels​

(Select, Combobox)

TokenLightDarkDescriptionTailwind
--anchor-max-heightcalc(var(--spacing) * 60)Max height of an anchored Select / Combobox panel before it scrolls.

Slider​

the track and thumb parts of the native range input. The colours follow --primary / --muted / --ring; the component sets the sizes per size

TokenLightDarkDescriptionTailwind
--slider-thumb-size1remSlider thumb diameter when no size sets it.
--slider-track-height0.375remSlider track height when no size sets it.
--slider-fillvar(--primary)Filled portion of the Slider track.
--slider-trackvar(--muted)Empty portion of the Slider track.
--slider-thumbvar(--primary)Slider thumb.
--slider-thumb-ringvar(--ring)Keyboard focus ring around the Slider thumb.

Tooltip​

TokenLightDarkDescriptionTailwind
--tooltipvar(--foreground)Tooltip bubble and arrow colour (inverted: --foreground, with --background text).

Avatar​

TokenLightDarkDescriptionTailwind
--avatar-ringvar(--background)Colour that separates an Avatar from what it overlaps (group ring, status cut-out); set it to the surface the avatar sits on.

Motion​

--ease-standard is the default for every transition, --ease-decelerate is what the .animate-* enter/exit classes use

TokenLightDarkDescriptionTailwind
--duration-fast150msColour transitions; the default transition-* duration.transition-* (default duration)
--duration-normal200msMovement; the .animate-* enter / exit classes.
--duration-slow300msLarge panels (Drawer, Dialog).

Easing curves​

TokenLightDarkDescriptionTailwind
--ease-standardcubic-bezier(0.4, 0, 0.2, 1)Default timing function of every transition.ease-standard, transition-* (default easing)
--ease-deceleratecubic-bezier(0, 0, 0.2, 1)Decelerate: entrances and exits.ease-decelerate

Animations​

the animation shorthand behind each .animate-* class (animations.css) and, with Tailwind, the animate-* utility of the same name. Keyframes are in keyframes.css.

TokenLightDarkDescriptionTailwind
--animate-fade-infade-in var(--duration-normal) var(--ease-decelerate)animate-fade-in
--animate-fade-outfade-out var(--duration-normal) var(--ease-decelerate)animate-fade-out
--animate-slide-in-from-topslide-in-from-top var(--duration-normal) var(--ease-decelerate)animate-slide-in-from-top
--animate-slide-in-from-bottomslide-in-from-bottom var(--duration-normal) var(--ease-decelerate)animate-slide-in-from-bottom
--animate-slide-in-from-startslide-in-from-start var(--duration-normal) var(--ease-decelerate)animate-slide-in-from-start
--animate-slide-in-from-endslide-in-from-end var(--duration-normal) var(--ease-decelerate)animate-slide-in-from-end
--animate-scale-inscale-in var(--duration-normal) var(--ease-decelerate)animate-scale-in
--animate-scale-outscale-out var(--duration-normal) var(--ease-decelerate)animate-scale-out
--animate-spinzui-spin 1s linear infiniteLoops; keyframes are zui- prefixed so Tailwind's own spin is never emitted alongside.animate-spin
--animate-pulsezui-pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infiniteanimate-pulse
--animate-bouncezui-bounce 1s ease-in-out infiniteanimate-bounce
--animate-shakeshake 0.5s ease-in-outanimate-shake
--animate-skeleton-waveskeleton-wave 1.6s linear infiniteThe Skeleton wave sheen.animate-skeleton-wave
--animate-progress-indeterminateprogress-indeterminate 1.5s var(--ease-standard) infiniteThe Progress bar without a value.animate-progress-indeterminate

Text editor code blocks​

(@zuilib/text-editor .zui-code): one colour per syntax role, light and dark. --zui-code-operator and --zui-code-punctuation are currentColor so they follow the block's text colour.

TokenLightDarkDescriptionTailwind
--zui-code-comment#6e7781#8b949e
--zui-code-string#0a3069#a5d6ff
--zui-code-number#0550ae#79c0ff
--zui-code-keyword#cf222e#ff7b72
--zui-code-builtin#6639ba#d2a8ff
--zui-code-type#953800#ffa657
--zui-code-function#8250df#d2a8ff
--zui-code-property#0550ae#79c0ff
--zui-code-variable#953800#ffa657
--zui-code-constant#0550ae#79c0ff
--zui-code-operatorcurrentColor
--zui-code-punctuationcurrentColor
--zui-code-tag#116329#7ee787
--zui-code-attr#0550ae#79c0ff
--zui-code-regex#0a3069#a5d6ff
--zui-code-meta#6639ba#d2a8ff
--zui-code-inserted#116329#7ee787Diff: added line text.
--zui-code-inserted-background#dafbe1rgba(63, 185, 80, 0.15)Diff: added line background.
--zui-code-deleted#82071e#ffa198Diff: removed line text.
--zui-code-deleted-background#ffebe9rgba(248, 81, 73, 0.15)Diff: removed line background.

Text editor table rails​

(@zuilib/text-editor .zui-table-rail): the row / column handles beside a table.

TokenLightDarkDescriptionTailwind
--zui-table-rail-accentvar(--primary)Hovered handle and insert marker.
--zui-table-rail-accent-foregroundvar(--primary-foreground)Icon on --zui-table-rail-accent.
--zui-table-rail-dangervar(--danger)Remove handle.
--zui-table-rail-danger-foregroundvar(--danger-foreground)Icon on --zui-table-rail-danger.