@wandelbots/design-tokens
v3.0.0
Published
Wandelbots Nova design tokens (DTCG sources + generated CSS / JS outputs).
Keywords
Readme
@wandelbots/design-tokens
Single source of truth for Wandelbots Nova design tokens. Generates CSS custom properties and typed JS exports from DTCG-format token sources.
The package is deliberately framework-agnostic — it ships values, not components. The MUI 7 theme built on top of these tokens lives in @wandelbots/mui.
Tokens are owned by the design department. Values, names, and hierarchy come from Figma — don't invent, rename, or locally override a token. Missing one? Request it from the design department.
Token architecture
Token files are generated from data/variables.json (raw Figma export) by scripts/transform-variables.ts. Each Figma variable collection becomes its own <collection>.tokens.json file in DTCG format. The collection names, hierarchy, and aliasing structure are defined in Figma — this repo does not impose a layering convention.
Collections with multiple Figma modes additionally emit tokens/themes/<theme>.tokens.json containing that mode's values — see Themes.
Do not hand-edit files in tokens/. To change token values or structure, update them in Figma and re-export.
All token files use the DTCG format with $value, $type, and $description.
Filtering unused tokens
Tokens with $description: "no use" are excluded from all build outputs (CSS variables, JS exports). They remain in the DTCG source files for documentation/completeness but are not shipped to consumers. This keeps the public API surface intentional — only tokens actively used in the design system are exported.
To mark a token as unused, set its description to "no use" in Figma. To re-include it later, change the description to something meaningful.
Build outputs
| Output | Import path | Usage |
| --------------------- | ------------------------------------------ | ---------------------------------- |
| CSS custom properties | @wandelbots/design-tokens/css | @import in global CSS |
| JS/TS constants | @wandelbots/design-tokens | Direct value access in JS/TS |
| Theme overrides (JS) | @wandelbots/design-tokens/themes | Non-default theme values in JS/TS |
Using MUI? The theme lives in @wandelbots/mui — createNovaMuiTheme().
Themes
The zero gravity collection is themed — it has multiple modes in Figma. Dark is the
default theme: its values are what you get from the plain @wandelbots/design-tokens import
and from :root in the CSS output. It is not duplicated as a separate theme.
Additional modes are emitted as overrides. Currently only simulation is published
(Light exists in Figma but is not exported yet).
Only themed collections are overridden. --wb-colors-*, --wb-spacing-*, --wb-radius-*,
--wb-font-* and --wb-breakpoints-* are single-mode and stay constant across themes.
CSS
Themes are scoped by a data-wb-theme attribute, so they can be applied to the whole document
or to any subtree:
<body> <!-- dark (default) -->
<div data-wb-theme="simulation"> <!-- simulation overrides apply here -->
...
</div>
</body>document.documentElement.dataset.wbTheme = "simulation"
delete document.documentElement.dataset.wbTheme // back to darkJS
import { simulation } from "@wandelbots/design-tokens/themes"
simulation.ZeroGravityActionDisabled // literal value, not a var() referenceTheme objects contain only the tokens that a theme overrides, with fully resolved literal values. Fall back to the default export for anything not present in a theme.
Adding a theme
Add the Figma mode name to THEME_MODES in scripts/transform-variables.ts and rebuild. For
example, publishing Light is Light: "light".
Quick start
# Build all outputs (transform + compile)
pnpm build
# Transform only (raw Figma → DTCG)
pnpm build:tokens
# Compile only (DTCG → dist/)
pnpm build:styles
# Run tests
pnpm testUsage examples
CSS
@import "@wandelbots/design-tokens/css";
.card {
background: var(--wb-zero-gravity-background-paper-elevation-8);
border: 1px solid var(--wb-zero-gravity-divider);
border-radius: var(--wb-radius-md);
}Figma sync
Token values come from Figma via the WB Tokens Export plugin (see figma-export).
- Open the Figma file → run the plugin → click Export Tokens
- The plugin pushes
data/variables.jsonto a PR on GitHub - CI (
.github/workflows/tokens-sync.yml) auto-transforms and validates the PR
To transform locally after updating data/variables.json:
pnpm build:tokens # raw → tokens/*.tokens.json
pnpm build:styles # tokens → dist/CSS variable naming
All CSS custom properties use the --wb- prefix, followed by the Figma collection name.
Prefer the semantic Zero Gravity tokens (--wb-zero-gravity-*) over the raw palette
primitives (--wb-colors-*); reach for --wb-colors-* only when no suitable Zero Gravity
token exists.
--wb-zero-gravity-background-default— semantic background color--wb-zero-gravity-primary-main— semantic primary/brand color--wb-colors-blue-500— raw palette primitive--wb-spacing-2— 16px spacing unit--wb-radius-sm— 10px border radius (used for buttons)