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.
The figmaMapping
function integrates Figma with the codebase by identifying design tokens in the designs and processing them through the designTokenMapper
function.
Each token is mapped to the design system, transforming it into a format compatible with the codebase. If no mapping is defined for a token, returning undefined
keeps the original token unchanged.
import { figmaMapping } from "@builder.io/dev-tools/figma";
figmaMapping({
designTokenMapper(token: string) {
// Mapping logic here
return transformedToken || undefined;
}
});
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-', '')})`;
}
return undefined;
}
})
figmaMapping({
designTokenMapper(token: string) {
// CSS Custom Properties
return `var(--${token})`;
// 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)",
// Spacing
"spacing-2": "var(--space-2)",
"spacing-4": "var(--space-4)",
"spacing-8": "var(--space-8)",
// Breakpoints
"breakpoint-tablet": "768px",
"breakpoint-desktop": "1024px",
};
// Customize the token based on the type and return as css variables
if (token.startsWith('font-size')) {
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.