Tokens

A token is a named value: a color, a shadow, a size. Components and products use the name, never the value, so a value can change in one place and every screen follows in both modes. This page is the reference for every token. The rules for choosing between tokens belong to the foundation that owns each group, linked from each section below.

Principles

• One source. Every token in tokens.json is written once there. foundation.css is generated from it, and nothing else defines a token value.
• Names say the role, not the color. attention, not pink; layer-canvas, not white. A token keeps its name when its value changes, and the dark value lives under the same name.
• Use the role token before the palette. Reach for palette-* only where no role fits; see Color.
• A value used three times becomes a token. A one-off value can stay inline, as an ink step or an oklch() literal; on its third use, add a token.

Where tokens live

An app that uses Tailwind imports @botiverse/raft-ui/styles.css. A page without Tailwind imports @botiverse/raft-ui/foundation.css and reads the custom properties: var(--layer-canvas).

How foundation.css is generated

packages/ui/scripts/build-tokens.mjs reads tokens.json and writes foundation.css. Never edit foundation.css by hand.

vp run @botiverse/raft-ui#build:tokens          # write src/foundation.css
node packages/ui/scripts/build-tokens.mjs --check   # exit 1 if it is out of date

• Change a value in tokens.json, run build:tokens, and commit both files. A test (foundation.generated.test.ts) fails when foundation.css doesn't match tokens.json.
• A token's path becomes its property name: {layer.canvas} is --layer-canvas. $root names the group itself: {foreground.$root} is --foreground. A reference ("{palette.cyan.800}") becomes var(--palette-cyan-800).
• The format has no field for modes, so tokens.json adds an extension, build.botiverse.raft:

The generated file has, in order:

1. the palette, on :where(:root);
2. light mode, on :where(:root) and .light;
3. dark mode, on .dark;
4. dark mode again under @media (prefers-color-scheme: dark) for a root without .light or .dark, so the page has the right colors before the app sets a class;
5. the aliases declared in every mode, then the deprecated names.

A .light element inside a dark page is a light island, for a preview or a portal; the dark: variant in styles.css follows the nearest mode class. See Dark mode.

Token grammar

Names are built from a few parts, so a name you haven't seen tells you what it is for.

Neutral roles. The role is one of four:

• foreground-*: text and icons;
• layer-*: a surface, in the order things stack (frame, sidebar, canvas, card, popover);
• line-*: a line;
• fill-*: a fill laid into or over a surface.

The purpose says where the token is used: frame, sidebar, canvas, card, popover, code, hud, on-frame, on-hud, link, field. Intensity runs from the bare name down to -muted, then -hint for text, and from -hairline through -seam to -strong for lines.

Color roles. The family is one of brand, attention, info, success, warning, danger or inactive. The slot says which shade:

Opacity. Every layer token is opaque except layer-backdrop, the scrim. fill-muted and fill-strong are opaque. fill-pressed, fill-frame-pressed and sticker-pressed are translucent: they are overlays laid on top of a control (Pressed overlays).

Utilities. A Tailwind utility is the property's prefix and the token name: bg-layer-card, text-foreground-muted, border-line-strong. Shadows are named apart: shadow-float for elevation-float, shadow-sticker for elevation-sticker, shadow-focus for focus-ring. The numbered palette steps are only custom properties, not utilities; the bare bg-palette-yellow and its siblings are the exception.

Token groups

Each block below is generated from tokens.json and shows the light and dark values.

Palette

The raw colors the roles point at. The rules for using them directly are in Color.

Text and icons

foreground and its tiers, and the text colors for the frame and the HUD. Usage and contrast: Color, Typography.

Surfaces

Usage: Color.

Fills

Usage: Color and Pressed overlays.

Lines

Usage and widths: Color, Shape.

Ink steps

Translucent steps of ink that lines, secondary text and overlays are made from. Use the role tokens; reach for an ink step only for a one-off wash.

Color roles

What each color means: Meanings of color.

Statuses

Task statuses and presence lights: Statuses.

Stickers

Usage: Stickers.

Shadows and the focus ring

Usage: Elevation, Accessibility.

Metrics

The type metrics a field and a card title share with the parts laid out beside them. Usage: Typography.

Tokens defined in styles.css

These are Tailwind theme values in styles.css, not entries in tokens.json, so they have no generated table.

Deprecated names

Earlier names are kept as aliases until raft-ui 1.0, in the deprecated group of tokens.json. Each one points at the token to use instead, so old code keeps working while it moves.

The renames follow a few patterns:

primary-*                  ->  brand-*
accent-*                   ->  attention-*
color-brutal-{color}-{n}   ->  palette-{color}-{n}   (purple -> lavender)
secondary-{n}              ->  palette-stone-{n}
layer-panel                ->  layer-canvas
layer-canvas-muted         ->  layer-sidebar
layer-inset                ->  fill-muted
layer-hud-foreground       ->  foreground-on-hud
foreground-strong          ->  foreground
foreground-icon            ->  foreground-muted
foreground-placeholder     ->  foreground-hint
line                       ->  line-seam
line-muted                 ->  line-hairline
theme-shadow-float/lg/xl   ->  elevation-float       (utility: shadow-float)
theme-shadow-sticker       ->  elevation-sticker     (utility: shadow-sticker)
theme-focus-ring           ->  focus-ring            (utility: shadow-focus)
theme-shadow-xs/sm/md      ->  none: controls cast no shadow, drop the class

The codemod

raft-ui ships a codemod that rewrites the old names in Tailwind utilities (bg-…, hover:border-…/50) and in CSS custom properties (var(--…)):

node node_modules/@botiverse/raft-ui/codemods/token-names.mjs <dir-or-file>... [--dry]

• It rewrites .ts, .tsx, .js, .jsx, .mjs, .cjs, .css and .html files, and skips node_modules, dist and build. --dry lists the files it would change.
• It renames references and leaves declarations alone, so running it twice is safe.
• Review the result by hand. A guard that forbade an old name (a lint rule, a test, an allowlist) now forbids the new one, and a pattern built from parts, such as a regular expression over class names, keeps the old name.
• The docs never use a deprecated name: scripts/check-docs.mjs fails a page that does.

Changing a token

• Add or change a value only in tokens.json, then regenerate foundation.css in the same change.
• Give a new token a name that follows the grammar above, and add its utility to styles.css if components need one.
• Rename a token by keeping the old name in the deprecated group, pointing at the new one, and adding the rename to the codemod. Remove aliases only in a major version.
• When a text, surface or tint value changes, recheck the contrast guarantees in Color for both modes.
• Update the foundation page that owns the token in the same pull request (Authoring).

Related

• Color: what each color token is for, and the contrast it guarantees.
• Typography: the type styles and the metric tokens.
• Elevation: shadows and the focus ring.
• Dark mode: what changes between the modes.