Skip to content

Tokens ​

A theme is CSS variables in three layers. registry/ code reads the semantic and component layers only, through Tailwind utilities.

LayerPrefixWritten byRead by
Raw--h-raw-*Theme generatorSemantic layer only
Semantic--h-*Theme generatorComponents, blocks, layouts
Component--h-<component>-*Component authorThat component

Knobs ​

A theme is fully described by one knob file. @heart-ui/theme exports generateTheme(knobs): string, which returns tokens.css.

json
{
  "name": "default",
  "primary": "oklch(0.55 0.2 260)",
  "neutral": { "hue": 260, "chroma": 0.02 },
  "radius": 0.5,
  "density": "default",
  "font": { "sans": "Inter, system-ui, sans-serif", "mono": "ui-monospace, monospace" },
  "shadow": "soft"
}
KnobTypeValues
primaryCSS colorAny; converted to OKLCH
neutralhue 0-360, chroma 0-0.04Tints the gray scale
radiusnumber, rem0 to 1
densityenumcompact, default, comfortable
fonttwo font stackssans, mono
shadowenumnone, soft, crisp

Raw layer ​

Six scales of 11 steps: neutral, primary, success, warning, danger, info. Variable form: --h-raw-<scale>-<step>.

Step50100200300400500600700800900950
Lightness.985.968.929.869.704.554.446.372.279.208.129
Chroma factor.08.15.30.50.8011.90.75.60.45

Each step is oklch(lightness, base chroma x factor, hue), clamped to the sRGB gamut. primary takes hue and chroma from the knob. Status scales use fixed hues (success 150, warning 75, danger 25, info 235) at chroma 0.17. neutral uses the knob's hue and chroma.

Semantic layer ​

Colors. Each row is --h-<name>; values name a raw step.

NameLightDarkUse
backgroundwhiteneutral-950Page
surfacewhiteneutral-900Cards, panels
surface-raisedwhiteneutral-800Popovers, menus, dialogs
surface-sunkenneutral-100neutral-950Wells, table headers
mutedneutral-100neutral-800Neutral fills, hover
muted-hoverneutral-200neutral-700Hovered neutral fills
muted-activeneutral-300neutral-600Pressed neutral fills
foregroundneutral-900neutral-50Body text
muted-foregroundneutral-600neutral-300Secondary text
subtle-foregroundneutral-500neutral-400Placeholders, hints
disabled-foregroundneutral-400neutral-600Disabled text
borderneutral-200neutral-800Dividers, card edges
border-controlneutral-500neutral-500Input and checkbox edges
ringprimary-500primary-500Focus ring
overlayblack at 50%black at 70%Scrim behind dialogs
primaryprimary-600primary-400Primary actions
primary-hoverprimary-700primary-300
primary-activeprimary-800primary-200
primary-foregroundwhiteneutral-950Text on primary
primary-subtleprimary-50primary-950Tinted fills, selected rows
primary-subtle-foregroundprimary-700primary-300Text on primary-subtle
linkprimary-700primary-300Inline links

Each status (success, warning, danger, info) gets four tokens with the same step mapping as primary: <s> (600 / 400), <s>-foreground (white / neutral-950), <s>-subtle (50 / 950), <s>-subtle-foreground (700 / 300). danger also has danger-hover (700 / 300) and danger-active (800 / 200), the same steps as primary's.

Charts use chart-1 to chart-6: primary-500, then the info, success, warning, danger, and neutral 500 steps (400 in dark mode).

Contrast: the generator checks every foreground against its background. Text pairs must reach 4.5:1 and border-control and ring must reach 3:1 against background and surface. A failing token moves one step at a time toward more contrast until it passes. When the foreground is already at the end of its scale, the background moves instead, and primary takes primary-hover, primary-active and ring with it so they stay distinct. The default theme needs no moves.

Shape, size, and motion:

TokenValue
radius-sm, radius-md, radius-lgknob x 0.5, x 1, x 1.5
radius-full9999px
control-sm, control-md, control-lgcompact 1.75 / 2 / 2.25 rem; default 2 / 2.25 / 2.5 rem; comfortable 2.25 / 2.5 / 2.75 rem
control-px-sm, -md, -lg0.5 / 0.75 / 1 rem, scaled 0.875 compact, 1.125 comfortable
gap-sm, gap-md, gap-lg0.5 / 1 / 1.5 rem, scaled as above
shadow-sm, shadow-md, shadow-lgBy shadow knob; all none when the knob is none
font-sans, font-monoFrom the knob
ring-width, ring-offset2px, 2px
duration-fast, -normal, -slow100 / 200 / 300 ms; 0 ms under prefers-reduced-motion
easecubic-bezier(0.2, 0, 0, 1)

Layout:

TokenValue
content-max80rem
content-narrow48rem
sidebar-width, sidebar-width-collapsed16rem, 3.5rem
topbar-height3.5rem
page-px1rem; 1.5rem from 768 px
section-gap1.5rem
z-sticky, z-overlay, z-modal, z-popover, z-toast, z-tooltip10, 40, 50, 60, 70, 80

Component layer ​

A component declares a token only when a theme has a reason to diverge from the semantic value, and it always falls back to a semantic token:

css
border-radius: var(--h-button-radius, var(--h-radius-md));

List every component token in the "Tokens" section of that component's Markdown page.

Dark mode ​

tokens.css defines light values on :root and dark values on .dark, [data-theme="dark"]. Nothing in registry/ uses Tailwind's dark: variant; a color that must differ in dark mode is a missing token.

Tailwind mapping ​

theme.css is static and ships with init. It maps tokens to Tailwind's theme so utilities resolve to variables:

css
@import "tailwindcss";
@import "./tokens.css";

@theme inline {
  --color-background: var(--h-background);
  --color-primary: var(--h-primary);
  --color-primary-foreground: var(--h-primary-foreground);
  --radius-md: var(--h-radius-md);
  --shadow-md: var(--h-shadow-md);
  --font-sans: var(--h-font-sans);
  --spacing-control-md: var(--h-control-md);
  /* one line per semantic token */
}

Resulting utilities: bg-background, bg-surface, text-foreground, text-muted-foreground, bg-primary, text-primary-foreground, border-border, ring-ring, rounded-md, shadow-md, h-control-md, px-control-px-md, gap-gap-md. Confirm the exact @theme namespaces against the Tailwind CSS v4 docs before writing theme.css.

Lint rule ​

@heart-ui/eslint-plugin rule no-raw-values fails on any of these inside registry/:

  • Hex, rgb(), hsl(), oklch(), or named colors.
  • Tailwind palette classes (bg-blue-500, text-gray-700).
  • Arbitrary-value classes (w-[13px], bg-[#fff]).
  • --h-raw-* references.
  • The dark: variant.

Spacing utilities from Tailwind's numeric scale (p-4, gap-2) are allowed for layout inside an item. Control height, control padding, and radius must use the token utilities.