Map design system tokens

for developers

Design system tokens are an essential part of maintaining consistency between your design and code. The Builder Figma Plugin helps you map these tokens from your Figma design to your codebase using a mapping function.

How token mapping works

The token mapping function is called for each design token the plugin finds in your Figma design. In this way, you can transform the token names from Figma into the format you use in your codebase.

Token mapping function example

Consider a scenario where your design system uses different naming conventions in Figma and in your codebase. Here’s a practical example of a token mapping function:

function Mapper(designToken: string) {
  
  // Convert Figma token names to your codebase format
  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',
  };
  
  // Return the corresponding token or keep the token unchanged
  return tokenMap[designToken] || designToken;
}

Using the token mapping function

The token mapping function provides flexibility in how design tokens are translated to your codebase. This section outlines various approaches to customize the function based on your project's specific requirements.

Whether you're working with Less, SCSS, or CSS variables, or need to keep certain tokens unchanged, the following examples demonstrate how to adapt the function to your needs.

Less variables

To map tokens to Less variables, you could use:

return '@'+ designToken;

SCSS variables

For SCSS variables, you might use:

return '$' + designToken;

CSS variables

To map to CSS custom properties:

return `var(--${designToken})`;

No change

If you want to keep the token unchanged, return false.

return false;

Customizing token mapping

You can customize the token mapping function to fit your specific needs. For example, you could add logic to handle different types of tokens depending on their unique requirements, or to transform token names in more complex ways.

The goal of this function is to make sure that the design tokens from your Figma designs are correctly translated into the format you use in your codebase so you can maintain consistency across your design system.

Here's an example of a token mapping function that demonstrates techniques for customization:

function Mapper(designToken: string) {
  const tokenMap: Record<string, string> = {
    'primary-100': 'var(--color-primary-light)',
    'primary-500': 'var(--color-primary-main)',
    'primary-900': 'var(--color-primary-dark)',
    'font-size-sm': 'var(--text-sm)',
    // Additional mappings...
  };

  // Customize the token based on type and return it
  if (designToken.startsWith('font-size')) {
    return `var(--${designToken})`;
  }
  
  return tokenMap[designToken] || designToken;
}

This function showcases a more comprehensive approach to token mapping. It includes a predefined tokenMap object that covers various design token categories such as colors, typography, spacing, and breakpoints.

The function checks if the input designToken exists in this map and returns the corresponding value if found. If the token isn't in the map, it returns false, indicating that the token should remain unchanged.

Integrating design tokens in Builder

If you’re using design tokens in Builder, the plugin automatically maps tokens from as long as the CSS variable names match. This way your design system remains consistent across your application without manual adjustments.

However, using Builder design tokens is optional when using the Builder Figma Plugin mapping feature. If your design system uses different naming conventions, you can customize the token mapping function to accurately translate Figma tokens into your codebase format.

This flexibility means you can adapt the mapping process to your specific needs, ensuring your design system stays cohesive and easy to manage.

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?