Map design system tokens

For developers

Enterprise plans

Deprecated

Builder.io is transitioning from manual component mapping to Component indexing, which automatically discovers and maps your design system components.

To migrate away from component mapping, visit the Component mapping migration guide.

Design system tokens are essential for maintaining consistency between the design and codebase. The Builder Plugin maps the tokens from the Figma design to the codebase using a mapping function.

Setup

To implement token mapping, ensure the correct setup so that Builder recognizes it.

The token mapping file should be placed in the mappings directory at the project root using the filename as in this example.

<PROJECT ROOT>/mappings/design-tokens.mapper.tsx

How token mapping works

The figmaMapping() function integrates Figma with your codebase by identifying design tokens, transforming them, and mapping them through the designTokenMapper() function.

Each token aligns with your design system, ensuring consistency and compatibility. If no mapping exists for a token, returning undefined preserves the original token.

/* <PROJECT ROOT>/mappings/design-tokens.mapper.tsx */ import { figmaMapping } from "@builder.io/dev-tools/figma"; figmaMapping({ designTokenMapper(token: string) { // Map token with design system return transformedToken || undefined; } });

How Figma token transformation works

Figma uses different naming conventions for design tokens and variables. While Figma token names follow a hierarchical structure, the Builder Figma plugin automatically transforms the tokens coming from Figma before passing them to the designTokenMapper() function.

These transformations replace all / characters with - and convert spaces into - to maintain consistency. This process aligns Figma tokens with your design system naming conventions.

Examples of token name transformation

Figma token	Transformed token with Builder
`red 100`	`red-100`
`light/gray/gray-400`	`light-gray-gray-400`
`Data viz palette/charts-blue-2-300`	`data-viz-palette-charts-blue-2-300`

For more information, see Guide to variables in Figma and Apply variables to designs.

Mapping options

The designTokenMapper provides flexibility in translating design tokens into your codebase.

You can customize the mapping function to fit your specific needs, whether working with LESS, SCSS, or CSS variables or adding custom logic for more advanced and complex use cases.

This section outlines various approaches to customize the function based on your project's requirements.

Map by categories

figmaMapping({ designTokenMapper(token: string) { // Colors if (token.startsWith("color-")) { return `var(--${token})`; } // Typography if (token.startsWith("font-")) { return `var(--text-${token.replace("font-", "")})`; } // Spacing if (token.startsWith("spacing-")) { return `var(--space-${token.replace("spacing-", "")})`; } // (Dark Mode/text-secondary) → var(--dark-mode-text-secondary)) if (token.startsWith("dark-mode")) { return `var(--${token})`; } return undefined; }, });

Map by CSS variables

figmaMapping({ designTokenMapper(token: string) { // CSS Custom Properties return `var(--${token})`; // Uncomment the following lines if you need SCSS or Less variable mappings: // SCSS Variables // return `$${token}`; // Less Variables // return `@${token}`; } });

Custom token mapping

The designTokenMapper function handles dynamic tokens by applying custom logic for specific scenarios.

For instance, a predefined tokenMap object covers various design token categories such as colors, typography, spacing, and breakpoints. Additionally, tokens with prefixes like font size are programmatically converted into matching CSS variables for enhanced use cases.

import { figmaMapping } from "@builder.io/dev-tools/figma"; figmaMapping({ designTokenMapper(token) { const tokenMap: Record<string, string> = { // Colors "primary-100": "var(--color-primary-light)", "primary-500": "var(--color-primary-main)", "primary-900": "var(--color-primary-dark)", "neutral-100": "var(--color-gray-100)", "neutral-500": "var(--color-gray-500)", "neutral-900": "var(--color-gray-900)", // Typography "font-size-sm": "var(--text-sm)", "font-size-md": "var(--text-base)", "font-size-lg": "var(--text-lg)", "font-size-xl": "var(--text-xl)", "font-size-2xl": "var(--text-2xl)", // Spacing "spacing-2": "var(--space-2)", "spacing-4": "var(--space-4)", "spacing-8": "var(--space-8)", "spacing-16": "var(--space-16)", // Breakpoints "breakpoint-mobile": "480px", "breakpoint-tablet": "768px", "breakpoint-desktop": "1024px", "breakpoint-large": "1440px", }; // Customize the token based on the type and return as a CSS variable if (token.startsWith('font-size') || token.startsWith('spacing')) { return `var(--${token})`; } return tokenMap[token] ?? undefined; }, });

Integrating design tokens in Builder

If you’re using Design Tokens in Builder, the plugin automatically maps tokens from CSS as long as the variable names match. It is optional to use Design Tokens when using the Builder Figma Plugin mapping feature.

If your design system uses different naming conventions, you can customize the token mapping function to translate Figma tokens into your codebase format.

For more details on defining and registering design tokens, visit Design Tokens.

What's next

Certain parts of this workflow use AI, for more information, visit How Builder Uses AI.

Was this article helpful?