For Developers

This section will walk you through integrating Handoff into your existing developer toolchain.

Developer Quick Start

You can quickly fetch tokens from a Figma project. You'll need the following

  • A Figma file with one published Handoff component
  • A figma developer token
  • Node 16+

To see all the CLI options avaliable to you type `handoff-app help` or view the CLI Reference page

Install and Fetch Tokens

Start by installing the handoff CLI.

Install Handoff, and fetch tokens
1npm install -g handoff-app
2mkdir handoff-project
3cd handoff-project
4handoff-app fetch

Handoff will ask for a developer key. You can generate this key by logging in to Figma.

Provide your developer key
1Starting Handoff Figma data pipeline. Checking for environment and config.
2
3Figma developer access token not found. You can supply it as an environment
4variable or .env file at DEV_ACCESS_TOKEN. Use these instructions to generate
5them https://help.figma.com/hc/en-us/articles/8085703771159-Manage-personal-access-tokens
6
7Figma Developer Key: {Enter your Development Key}

Handoff will ask for the Figma File ID you want to get.

Provide your File ID
1Figma project id not found. You can supply it as an environment variable or .env
2file at FIGMA_PROJECT_ID. You can find this by looking at the url of your Figma
3file. If the url is https://www.figma.com/file/IGYfyraLDa0BpVXkxHY2tE/Starter-%5BV2%5D
4your id would be IGYfyraLDa0BpVXkxHY2tE
5
6Figma Project Id: {Enter your File Id}

Handoff will ask if you want to save these secrets to a local env. If you do make sure you don't commit them to your repo, since they contain important Figma secrets.

Do you want to store these creds
1You supplied at least one required variable. We can write these variables to a local env
2file for you to make it easier to run the pipeline in the future.
3
4Write environment variables to .env file? (y/n):

If everything is correct, you will see the following

Fetch Output
1An .env file was created in the root of your project. Since these are sensitive
2variables, please do not commit this file.
3
4Starting Figma data extraction.
5Alert exported: 11
6Button exported: 45
7...
8Icons exported: 24
9Logo exported: 2
10Preview template styles built
11Figma pipeline complete: 8 requests

You should see a folder created called exported in the root of your directory. This folder contains all of the exported tokens, along with the transformations and integration tools. You can now integrate these artifacts into your project.

View Documentation

Handoff will generate a static documentation website with all the tokens. You can launch that by running -

Start documentation website locally
1handoff-app start
2- event compiled client and server successfully in 112 ms (18 modules)
3- wait compiling...
4- event compiled client and server successfully in 74 ms (18 modules)
5> Ready on http://localhost:3000

If you point a browser to http://localhost:3000 you'll see this -

Sample documentation site

This site is fully customizable. Our documentation on customization will help you customize your site.

Exported Artifacts

TODO: Overview of exported artifacts

Transformers

TODO: Explanation of transofrmers and link to transformer docs

What's Next

Once you have the CLI up and running, you can do a couple of things -

  • Start integrating tokens into your project
  • Map tokens to your existing Sass Project
  • Integrate Handoff with your existing javascript build tooling
  • Customize and Publish the Handoff generated documentation to the web