for developers
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.
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 shown in the example.
<PROJECT ROOT>/mappings/design-tokens.mapper.tsxThe 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;
}
});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.
| Figma token | Transformed token with Builder |
|---|---|
|
|
|
|
|
|
For more information, see Guide to variables in Figma and Apply variables to designs.
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.
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;
},
});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}`;
}
});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;
},
});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.
Certain parts of this workflow use AI, for more information, visit How Builder Uses AI.
