Figma foundations

The Figma integration is optional. fetch reads a published Figma library and writes the foundations (colors, typography, effects, icons, logos) as tokens, CSS, and Sass. The foundation pages of the documentation app show them.

Credentials

Set the Figma file ID and a personal access token in .env. If you entered them during init, they are already there.

HANDOFF_FIGMA_PROJECT_ID=figma-file-id
HANDOFF_DEV_ACCESS_TOKEN=figma-personal-access-token

The token needs the file_content:read and library_content:read scopes.

These names are the defaults of integrations.figma. Set the block only to use different variable names, to commit the file ID, or to change the file per profile. The access token accepts only an environment reference:

import { defineConfig, fromEnv } from 'handoff-app'

export default defineConfig({
  integrations: {
    figma: {
      projectId: fromEnv('HANDOFF_FIGMA_PROJECT_ID', { default: null }),
      accessToken: fromEnv('HANDOFF_DEV_ACCESS_TOKEN', { default: null }),
    },
  },
})

Fetch

npm run fetch

• If a value is empty, fetch asks for it in the terminal and can save it to .env, or to .env.<profile> when a profile is selected.
• Without a terminal, for example in CI, fetch stops with an error that names the missing variable.
• After a design change, publish the Figma library again, then run fetch again.

Output

fetch writes to exported/ (exportsOutputDirectory, or HANDOFF_OUTPUT_DIR):

Commit exported/ so local builds and CI builds use the same inputs. To check that a fetch worked, look for exported/tokens.json; an empty foundation page does not prove it.

Token transformers

Handoff always runs the CSS, Sass, and Sass types transformers from handoff-core. Add more, or change the output directory of a core one, with pipeline.transformers:

import { CoreTransformers, defineConfig } from 'handoff-app'

export default defineConfig({
  pipeline: {
    transformers: [
      { transformer: CoreTransformers.StyleDictionaryTransformer, outDir: 'sd', format: 'json' },
    ],
  },
})

Scaffold catalog items from Figma

npx handoff-app scaffold

Creates catalog item stubs for the components in the fetched Figma data. The command asks which components to create and how.

Publish foundations

publish tokens and publish assets run the Figma pipeline before the upload, so the credentials must be available. See Publish and checkout.