Token Resolution

CalibrateDS extracts Figma Variables and Styles, normalizes them, and generates CSS Custom Properties that power your component styling.

How it works

When you run ptb generate-tokens, the CLI traverses your DesignSystemModel and writes a CSS file for each token collection. Figma variable names are transformed into --ptb-* prefixed CSS custom properties using the collection and token name.

A Figma variable like colors / brand / 900 becomes:

:root {
  --ptb-colors-brand-900: #103D1A;
}

Spacing, radius, and typography tokens follow the same convention:

:root {
  --ptb-spacing-large: 24px;
  --ptb-radius-md: 8px;
}

Dimension values are rounded to at most 3 decimal places, preserving sub-pixel values like 0.5px while eliminating floating-point noise like 16.000000000000004px.

Alias Tokens

If a Figma variable references another variable (an alias), PTB resolves the full chain and emits a var() reference:

:root {
  --ptb-colors-primary: var(--ptb-colors-brand-900);
}

PTB follows alias chains up to 10 hops deep. Circular alias chains are detected and skipped, with a count reported in the token generation metrics.

Token Bindings in Component Context

When AI implements a component (or you build it manually), PTB passes resolvedBindings in the ComponentContext. Each binding includes:

• cssVar — the CSS custom property the component is directly bound to in Figma (use this in component stylesheets)
• cssValue — the actual resolved CSS value (hex color, px dimension, etc.)
• canonicalCssVar — the terminal token's CSS variable, after following the full alias chain

Instead of telling the AI to use a literal hex code like #103D1A, the context instructs it to use the semantic CSS variable:

fill: var(--ptb-colors-brand-900, #103D1A)

The fallback is the concrete resolved value — so your components render correctly even before the token CSS file is loaded, and the browser always has a valid value to fall back to.

Unresolvable tokens

If a token cannot be resolved (broken alias chain, missing variable), cssValue is an empty string. PTB emits the variable reference alone — it will never fabricate a fallback or produce a self-referential var(--x, --x). ptb doctor tokens flags unresolvable tokens during health checks.

Gap and Padding Values

For layout properties (gap, padding), PTB always prefers the raw numeric rawValue over the Figma token name. This ensures the generated CSS contains valid values like 16px, not the internal Figma variable path like spacing/large.

Naming Convention

The naming.tokenCase option in ptb.config.json controls how the token name segment is cased within the --ptb-* prefix. The default is camelCase:

/* camelCase (default) */
--ptb-colorsBrand900

/* kebab-case */
--ptb-colors-brand-900

If a token is unresolved or missing from your Figma variables, ptb doctor tokens will flag it during health checks to prevent hardcoded values from slipping through.

Next Steps

Ready to fetch your data? Choose your workflow: Direct API or Plugin Export.