Join us for our biggest AI launch event on 10/31

Announcing Visual Copilot - Figma to production in half the time

Builder.io logo
Contact Sales
Platform
Developers
Contact Sales

Blog

Home

Resources

Blog

Forum

Github

Login

Signup

×

Visual CMS

Drag-and-drop visual editor and headless CMS for any tech stack

Theme Studio for Shopify

Build and optimize your Shopify-hosted storefront, no coding required

Resources

Blog

Get StartedLogin

in beta

for developers

Rather than relying on the Builder Figma Plugin’s visual interface, you can manage mappings programmatically, directly integrated into your codebase.

By using the CLI, you can can keep mappings consistent and up-to-date as designs evolve for better control and flexibility when mapping components from Figma to code.

To get the most out of this article, be sure:

  • You have a Figma design ready with relevant components to be mapped.
  • You’re using the Builder Figma Plugin.
  • Your application is connected to Builder Devtools and running locally.
  • Devtools is connected to the same Builder Space as your codebase.

For setup details, visit Importing Figma Designs.

If you've been using the Builder Figma plugin to automatically map your components, you can migrate to the improved workflow that uses the command line to map components with the instructions in this section.

If you've never used the Builder Figma plugin for mapping components in your project, skip to the next section.

To update an existing project that already uses component mapping with the Builder Figma Plugin:

1. In package.json, update the Builder Devtools dependency to ^1.1.0.

npm i @builder.io/dev-tools@1.1.0 --save

2. Start the mapping integration process.

npx builder.io figma migrate

3. Follow the command line instructions.

1. In package.json, update the Builder Devtools dependency to ^1.1.0.

npm i @builder.io/dev-tools@1.1.0 --save

2. In Figma, select the component you want to map.

3. Press Cmd + L, which is available in the Figma context menu under Copy/Paste as > Copy link to selection.

4. At the command line, run the command to start the mapping process. Replace the placeholder <URL> with the link you copied in Figma within quotes.

npx builder.io figma add "https://figma.com..."

6. In the prompt that opens in Figma, grant access to the Builder CLI by clicking the Allow access button.

7. Back at the command line, when you are prompted, select the local component you want to map. Type the name to filter, if you have a lot of components.

8. Inspect the suggested mapper function and request any changes. For example, "Provide a better default value for the subtitle". Press Enter for Devtools to generate another mapper function with your recommendations.

9. When you are satisfied with the suggestion, respond to the prompt question of "How does the mapping look?" with "good".

10. At the prompt for where to save the new mappings, specify the location you'd like.

11. Open your new mapper file and edit your mapper() function if needed.

Publishing your Figma mappings doesn’t update your repo but pushes the updated mappings into your Builder space. This ensures that the mappings are applied the next time someone generates code in the Figma plugin. 

To publish a new mapping:

  1. Run npx builder.io figma publish. Note that if you have any properties missing in a mapping function for a component, the CLI returns an error alerting you. In this case, make sure that you check that the types in the mapper file against the types in the component and provide all needed types.
  2. When prompted to publish found mappings, choose Publish or Cancel.

To confirm that your mappings were published, run npm run dev in your project, go to the Builder Figma plugin Design System tab, and expand the component to find the new mapping. If it doesn't show up immediately, be sure to refresh by closing and re-opening the plugin.

To create your own mapper file for mapping design tokens:

1. Name your mapper file with the naming convention of myComponent.mapper.tsx, where myComponent is the name of your component.

2. Import figmaMapping:

import { figmaMapping } from "@builder.io/dev-tools/figma";

3. Add a figmaMapping() function using designTokenMapper() to pass in your token, as in the following example that shows the designMapper() function to map blue to brand blue:

// import figmaMapping so Devtools can map components
import { figmaMapping } from "@builder.io/dev-tools/figma";

figmaMapping({
  designTokenMapper(token) {
   // if blue in Figma, return brand blue
   if (token === 'blue') {
       return 'var(--brand-blue, #18B4F4)'
   }
   // leave anything else the same
   return undefined
  }
});

4. Publish:

npx builder.io figma publish

For more advanced use cases and additional mapping functions, visit Component Mapping Functions.

The following commands are available for managing your mappings. Run these commands from the root of your project.

Start the auto-mapping command line workflow, which this document covers in detail, for the Figma component:

npx builder.io figma add <URL>

Pushes the updated mappings to your Builder Space so that the mappings are applied the next time a team mate generates code in the Figma plugin. 

Publish your Figma mappings to Builder:

npx builder.io figma publish

Migrate your existing Figma mappings into your local project. This command fetches Figma mappings, lists them for you, and prompts you for a location in your project to save the mappings.

This command creates any folders you specify in the path that don't exist and a new file for each mapping. For example, if you specify /src/mappings the CLI creates a mappings directory within src and a file for any existing mappings, for example, if you had a footer mapping, the CLI would create Footer.mapper.tsx:

npx builder.io figma migrate

Note that mapping files must be mapper.tsx files, but that they can be anywhere in your repo. These files contain the code responsible for translating Figma components to code components in your app. You can also have multiple mappings on a single component.

Use this command for troubleshooting login issues between Figma and Builder. It should not be necessary under normal circumstances but can resolve issues where authentication has failed.

Re-authenticate with Figma and Builder:

npx builder.io figma auth

Each mapping file contains default mappings for the respective component. For example, a Footer.mapper.tsx file could have these features:

// import figmaMapping so Devtools can map components
import { figmaMapping } from "@builder.io/dev-tools/figma";
import Footer from "@components/Layout/Footer";

// provide figmaMapping() with the Builder component key
// in mapper(), the code is the same as in the Figma plugin
figmaMapping({
  componentKey: "d8fccf9e902602249fa68217953daab094570bba",
  mapper(figma) {
    return <Footer></Footer>;
  },
});

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

Was this article helpful?

Product

Visual CMS

Theme Studio for Shopify

Sign up

Login

Featured Integrations

React

Angular

Next.js

Gatsby

Get In Touch

Chat With Us

Twitter

Linkedin

Careers

© 2020 Builder.io, Inc.

Security

Privacy Policy

Terms of Service

Newsletter

Get the latest from Builder.io

By submitting, you agree to our Privacy Policy

Product

Platform Overview

Integrations

What's New

Open Source

Builder

Builder

Mitosis

Mitosis

Qwik

Qwik

Partytown

Partytown

Popular Guides

From Design to Code Guide

Composable Commerce Guide

Headless CMS Guide

Headless Commerce Guide

Composable DXP Guide

Design to Code

Resources

Blog

Knowledge Base

Community Forum

Partners

Templates

Success Stories

Showcase

Resource Center

Frameworks

React

React

Next

Next.js

Qwik

Qwik

Gatsby

Gatsby

Angular

Angular

Vue

Vue

Svelte

Svelte

Remix logo

Remix

Nuxt

Nuxt

Hydrogen

Hydrogen

See All

© 2024 Builder.io, Inc.

Security

Privacy Policy

SaaS Terms

Security & Compliance

Cookie Preferences