Foundation
Design tokens — color, typography, spacing, radius, shadow, size.
Design tokens are the single source of truth for every visual decision in the Brik ecosystem — color, type, spacing, radius, shadow, motion. A token gives a value a name and a purpose. Components never reference raw values; they reference tokens. This means a component built once works correctly across every Brik client without touching its code.
Token source of truth lives in Figma. This site documents what's available and how to use it. To add a new token, edit Figma first — don't add it to CSS directly.
Tokens load via a two-tier cascade — BDS canon first (@brikdesigns/bds/tokens.css), client brand override second (theme-{client}.css). Architecture, full import order, and the <html> switch table: The Cascade.
Token types: primitives vs semantic
| Type | Purpose | Example | Used in |
|---|---|---|---|
| Primitive | Raw scale value — the number or color itself | --color-poppy-light: #e35335 | Never in components |
| Semantic | Purpose-bound alias pointing to a primitive | --background-brand-primary: var(--color-poppy-light) | Components, always |
Primitives define the palette. Semantics define the intent. Components only know intent.
/* ✅ Correct — semantic, works across all themes */
.bds-button { background: var(--background-brand-primary); }
/* ❌ Wrong — hardcoded, breaks in every non-default theme */
.bds-button { background: #e35335; }
/* ❌ Wrong — primitive, breaks the abstraction */
.bds-button { background: var(--color-poppy-light); }Naming convention
--[category]-[role]-[variant]| Category | Pattern | Examples |
|---|---|---|
| Background | --background-{role} | --background-brand-primary, --background-primary-hover, --background-info |
| Text | --text-{role} | --text-primary, --text-brand-primary, --text-info |
| Surface | --surface-{role} | --surface-primary, --surface-secondary, --surface-info |
| Border | --border-{role} | --border-primary, --border-brand-primary, --border-info |
| Page | --page-{role} | --page-primary, --page-secondary |
| Font family | --font-family-{role} | --font-family-heading, --font-family-body, --font-family-label |
| Typography | --{style}-{size} | --heading-lg, --body-md, --label-sm |
| Spacing | --padding-{size}, --gap-{size} | --padding-lg, --gap-md |
| Border radius | --border-radius-{size} | --border-radius-sm, --border-radius-md |
| Shadow | --shadow-{size} | --shadow-sm, --shadow-lg |
| Scale step | --{category}-{index} | --space-400, --font-size-700, --color-grayscale-dark |
Full vocabulary rules — title vs heading, label family, axes, no-unclassed-wrappers — in Build Standards.
Figma variable collections → CSS output
Figma organises variables into named collections. Each collection has modes. Style Dictionary flattens the active mode of each collection into figma-tokens.css.
| Figma collection | Active mode | What it generates |
|---|---|---|
primitives | value | Raw scale: --color-poppy-*, --space-*, --font-size-*, --border-radius-*, --shadow-blur-* |
color | light / dark | Semantic roles: --background-*, --text-*, --surface-*, --border-*, --page-* |
typography | default | Composite tokens: --heading-lg, --body-md, --label-sm, --font-family-* |
spacing | default | --padding-*, --gap-* |
border-radius | soft | --border-radius-sm/md/lg |
border-width | default | --border-width-sm/md/lg |
elevation | subtle | --shadow-sm/md/lg/xl, --blur-radius-* |
breakpoint | default | --breakpoint-web/tablet/mobile |
Light vs dark mode: figma-tokens.css uses the light mode of the color collection. figma-tokens-dark.css uses the dark mode. Both files use identical variable names — consuming projects import dark after light, and the browser applies whichever matches [data-theme="dark"].
Browse the token categories
417 tokens across all collections. Each page below explains one primitive group: what tokens exist, what they mean semantically, and the rules for using them outside their category (don't).
Color
Semantic color roles + interaction states + status + the primitive palettes.
Typography
Font families, the type scale, weights, line heights, and the semantic role rule.
Spacing
The 4-point grid, semantic padding and gap tokens, the primitive space scale.
Size
Container sizes, breakpoints, hero constraints, and the element-size scale.
Border radius
Corner rounding from sharp (0) to pill (999) to fully circular.
Border width
Line thickness for borders, dividers, and outlines.
Shadow
Elevation tokens — composed semantic shadows + primitive blur/spread scales.
Build Standards
Naming, slot vocabulary, composition layers, HTML semantics, and prop axes.
Theming
A client brand is a single CSS file (~12–27 token overrides) that redefines semantic tokens. Components never change. See Theming for the four-layer cascade, Client Themes for the override matrix and minimal template, and Atmospheres for the visual character layer.
Validate with Client Sim: Switch to Client Sim in the Storybook toolbar. It assigns Georgia / Verdana / Courier New to heading / body / label families — any component using the wrong --font-family-* token becomes immediately visible.
Adding a new token
Always start in Figma — never in CSS.
- Add the variable to the correct collection in the Figma Foundations file
- Connect Claude with the Figma dev plugin (provide channel ID)
- Run the sync:
bun scripts/pull-variables.js <channel> > /tmp/vars.json && node scripts/sync-figma-mcp.js /tmp/vars.json --build - Verify the token appears in
tokens/figma-tokens.css - Add it to the consuming project's
src/lib/tokens.tsexport map
Exception: tokens that aren't ready for Figma yet go in tokens/gap-fills.css with a TODO: promote to Figma comment.
What NOT to do
/* ❌ Never use a primitive in a component */
.card { color: var(--color-grayscale-darkest); }
/* ✅ Use the semantic alias */
.card { color: var(--text-primary); }
/* ❌ Never hardcode a value */
.button { background: #e35335; }
/* ✅ Use the semantic token */
.button { background: var(--background-brand-primary); }
/* ❌ Never edit figma-tokens.css manually */
/* ✅ Edit in Figma → run sync → regenerates automatically */
/* ❌ Never skip the TypeScript layer in consuming projects */
style={{ color: 'var(--text-primary)' }}
/* ✅ Import from the token map */
import { color } from '@/lib/tokens';
style={{ color: color.text.primary }}
/* ❌ Never hand-author dark-mode overrides */
[data-theme="dark"] { --background-primary: #111; }
/* ✅ Dark mode ships generated from Figma — bundled into @brikdesigns/bds/tokens.css */
@import '@brikdesigns/bds/tokens.css';Page Structure
The HTML skeleton and BEM section pattern for Brik pages in Astro and Next.js — from page shell to inner slot anatomy.
Token Anatomy
The six disambiguated concepts that describe every BDS token — Anatomy, Tier, Library, Layer, Mode, Tenet — and the four-tier abstraction stack every token belongs to.