Design tokens

A token is a named color or shadow with a job, like --text-muted or --surface-secondary. It has two layers: the stylesheet gives each token a light and a dark value, and a component reads the token by name. Components never touch the raw value.

Two tokens, from value to use

/* packages/ui/src/styles/globals.css */
:root,
[data-theme="light"] {
  --text-muted: #6D7284;
  --primary: #0038FF;
}
[data-theme="dark"] {
  --text-muted: #868CA3;
  --primary: #4D7AFF;
}

// What a component writes
<p className="text-[12px] text-[var(--text-muted)]">Intros this year</p>
<div className="h-full rounded-full bg-[var(--primary)]" />

data-theme="dark" on <html> swaps every value at once, so the same class is right in both themes. There is no palette underneath (no --blue-500): each value is written straight into the role that uses it, so one role can change without moving another.

Bridge writes bg-[var(--surface-secondary)] instead of a short class like bg-surface-secondary. The class reads the token on the element itself, so a data-theme="light" area inside a dark page (the handbook’s previews) gets its own values. It is also how Bridge OS has always written tokens, so code moves between the app and the package unchanged.

The package’s Tailwind theme holds only what never changes with the theme: the Mulish font and the entrance and exit animations (animate-fade-in, animate-scale-in and others).

A token is named for its job, never its color. Tokens that belong together share a start, and the part after it says the variation.

Colors also have display names from Bridge’s Figma palette, such as Royal, Charcoal and Slate 15. Use them when people talk about colors, in reviews and specs. Code always uses the token: --primary, never a class named after Royal. The reference below shows both.

Look-alikes

All 64 tokens, read from packages/ui/src/styles/globals.css on every build. Each swatch is drawn on its theme’s own page color, so see-through values look as they do in use.

Rare. Most new colors turn out to be an existing token at an opacity.

1. Check whether an existing token does the job. A paler blue is bg-[var(--primary)]/8; a softer strip is bg-[var(--surface-secondary)]/60; a quieter text is the next text step.
2. Name it for its job, following the patterns above. Add a light value under :root and a dark value under [data-theme="dark"] in packages/ui/src/styles/globals.css, under the right comment heading. A token without a dark value fails the build.
3. If it is text or sits behind text, add the pair to the contrast checks (lib/tokens-core.ts) and make it pass 4.5:1 in both themes.
4. If its value is a new Figma color, give it its display name in lib/palette.ts.
5. Record it in DESIGN.md → Color if it adds a new kind of role, and note it in the package’s CHANGELOG.md.
6. Rebuild. This page reads the stylesheet, so the token shows up in the reference under its heading.

A token in the stylesheet

/* packages/ui/src/styles/globals.css */
:root,
[data-theme="light"] {
  /* Text */
  --text-muted: #6D7284;
}
[data-theme="dark"] {
  /* Text */
  --text-muted: #868CA3;
}

Hard-coded colors are the most common way a screen breaks in dark mode and drifts from the system in light.

• No hex, rgb() or Tailwind palette colors (bg-white, text-black, bg-gray-100) in components.
• No dark: patches in app code. If something looks wrong in dark mode, fix the token.
• Never fill a button with --primary or --error; use the -solid tokens.
• Shadows come from --shadow-*. Never write a box-shadow with its own color.
• --shadow-card and --shadow-dropdown are older shadows, still used by a few tooltips and hover cards. Anything new that floats uses --shadow-menu, --shadow-dialog or --shadow-drawer.

Which color to use for which job, and the contrast of every pair, are on Color. How the theme switch works is on Theming.