Tokens
How the Tokens tab works (system tokens, Breakdance mappings, and custom tokens)
What are tokens in BreakColorUI?
In BreakColorUI, tokens are simply CSS custom properties (variables) that represent design decisions: color steps, font sizes, spacing values, layout sizes, and more. You configure them once and reuse them everywhere via var(--...).
Two layers of tokens
- • System tokens (BreakColorUI): generated from Colors / Typography / Spacing / Theme.
- • Integration tokens (Breakdance): semantic variables that map Breakdance concepts to your system tokens.
Where is the Tokens tab?
Open any project in the Dashboard. In the top tabs you'll see Tokens next to Colors, Typography, Spacing, Theme, and Export.
Important: Tokens tab does not replace the other tabs
The Tokens tab is mainly for mapping and extending the system. The base token generation still comes from Colors, Typography, Spacing, and Theme.
Collections inside Tokens
The Tokens tab is organized in two always-available collections:
BreakColorUI (system)
Lists the generated system tokens (typography, spacing, section spacing, border radius). You can also create custom system tokens (extra entries) when you need more tokens than the default scale.
Breakdance (integration)
Lets you configure Breakdance semantic tokens (global colors) and see the font-size mappings that connect Breakdance to your typography tokens.
Label vs CSS Var view
Use the toggle at the top-right of the Tokens panel to switch between human-friendly Labels and the actual CSS variable names. Copy buttons always copy the CSS variable name.
Breakdance: Global colors (semantic mapping)
Breakdance expects semantic global variables like “Headings color” or “Brand color”. BreakColorUI exposes these as --bde-* tokens and lets you map each one to a color step from your palettes.
Text & headings
Example: --bde-headings-color and --bde-body-text-color usually map to neutral steps 12/11.
Brand & links
Example: --bde-brand-primary-color and --bde-links-color often map to brand step 9.
Per-theme values
Each semantic token can have a Light and Dark value, so your mapping stays correct in both themes.
/* Breakdance semantic tokens (values usually reference your color tokens) */
html:root {
--bde-headings-color: var(--hcl-neutral-12);
--bde-body-text-color: var(--hcl-neutral-11);
--bde-background-color: var(--hcl-neutral-1);
--bde-brand-primary-color: var(--hcl-brand-9);
--bde-brand-primary-color-hover: var(--hcl-brand-10);
--bde-links-color: var(--hcl-brand-9);
--bde-links-color-hover: var(--hcl-brand-10);
}Best practice: keep semantic tokens as var() references
Instead of setting semantic tokens to raw HEX values, map them to your system color variables (e.g. var(--hcl-brand-9)). This keeps everything consistent and theme-friendly.
Breakdance: Font sizes (linked mapping)
BreakColorUI links Breakdance font-size variables to your typography tokens. You typically don't edit these in the Tokens tab — they are references to the typography scale.
html:root {
--bde-h1-font-size: var(--hfs-h1);
--bde-h2-font-size: var(--hfs-h2);
--bde-h3-font-size: var(--hfs-h3);
--bde-h4-font-size: var(--hfs-h4);
--bde-h5-font-size: var(--hfs-h5);
--bde-h6-font-size: var(--hfs-h6);
--bde-body-font-size: var(--hfs-text-m);
}BreakColorUI: System tokens (read-only lists)
The BreakColorUI collection lists the core tokens you already configured in other tabs. It shows min/max values (in px) and lets you quickly copy the corresponding CSS variable name.
Typography sizes
Headings (H0–H6) and text sizes (L/M/S) are derived from your Typography settings.
Spacing sizes
Component spacing (--hsp-*) and section spacing (--hss-*) are derived from your Spacing settings.
Border radius
Radius tokens (--hrd-*) follow the preset you selected in Theme.
Not a second source of truth
If you want to change a base token, do it in the original tab (Typography/Spacing/Theme).
Adding custom tokens
The Tokens tab lets you create two kinds of custom tokens:
1) Custom color tokens (Breakdance → Global colors)
- • Use case: create extra semantic variables for your project (e.g. “Card background”).
- • CSS variable name: generated from the label (spaces → dashes), e.g. “Card background” becomes
--card-background. - • Values: you can set both Light and Dark values (recommended: reference
--hcl-*tokens).
html:root {
--card-background: var(--hcl-neutral-2);
}
/* In dark mode (Full System exports), the referenced --hcl-neutral-* values change automatically */2) Custom system tokens (BreakColorUI → additional tokens)
- • Use case: extend typography/spacing/section spacing/border radius beyond the default set (add more tokens when needed).
- • Naming: BreakColorUI creates a safe, unique token name for you (so you don’t accidentally overwrite existing variables).
- • Export: fluid tokens are exported as
clamp()values from your min/max px.
html:root {
/* Custom Component Spacing */
--hsp-3xs: clamp(0.5rem, 0.42rem + 0.25vw, 0.625rem);
}How tokens affect Export
Everything configured in the Tokens tab is included when you export CSS (see Export & Integration).
What gets exported from the Tokens tab
- • Breakdance semantic variables:
--bde-*values (from Global colors mapping). - • Custom color tokens: any extra tokens you added inside Global colors.
- • Custom system tokens: extra sizes for headings/text/spacing/section spacing/border radius.
Troubleshooting
My custom token name looks different than my label
Custom color token variable names are generated from the label (lowercase, spaces become dashes, special characters removed). Rename the label to update the generated CSS variable name.
I don’t see my token in my project
Tokens become available on your site only after you export and paste the CSS into your project (e.g. Breakdance Global CSS). If you change tokens, re-export.