Getting Started with a Package

This guide will teach you how to get Figmage running to generate a standalone design package.

At the end of this guide, you will have a finished Flutter package that contains all your Tokens as Dart code.

📱 Add to your App Instead Figmage also supports adding tokens directly to your existing Flutter app.

Prerequisites

Before you start, we assume that you have a few things ready.

Figma Credentials

You’ll need your Figma file ID and a personal access token. See the Obtaining Figma Credentials guide for instructions.

Design Tokens

You’ll need at least some design tokens in your Figma file. See the Design Tokens reference for instructions.

Flutter App

An existing Flutter app where you want to use the design tokens package.

Install Figmage CLI

First, install the Figmage CLI by running:

dart pub global activate figmage

Create your Tokens Package

Next, decide where you want the generated package to live. You can create the package anywhere on your machine, use a monorepo, check it into your version control system separately, or even publish it to pub.dev.

1. Decide on a name and location for your package. Make sure to follow the Dart package naming conventions when choosing a name.

2. Create a directory with that name for your package to live in. Let’s say you want to call your package design_tokens, you would run the following command:

   mkdir design_tokens

3. Create a figmage.yaml file in the root of your package directory. While this is not strictly necessary, it is recommended to have a figmage.yaml file in the root of your package directory. This file will contain the configuration for Figmage.

   touch design_tokens/figmage.yaml

   Your package directory should now look like this:

   • Directorydesign_tokens

     • figmage.yaml

Configure Figmage

1. Open the figmage.yaml file you created earlier and add your Figma file ID:

   figmage.yaml

   fileId: "YOUR_FIGMA_FILE_ID"

   If you don’t have your file ID yet, see the Obtaining Figma Credentials guide.

2. Optionally, configure additional settings as needed:

   # Additional configuration options
   colors:
     generate: true
   typography:
     generate: true
     useGoogleFonts: true
   numbers:
     generate: true
   spacers:
     generate: true

3. For more detailed configuration, see the Configuration Options reference.

Run Figmage

From your package directory, run:

figmage forge -t YOUR_FIGMA_PERSONAL_ACCESS_TOKEN

If you don’t have your personal access token yet, see the Obtaining Figma Credentials guide.

Figmage will fetch your Tokens from Figma and generate the Dart code for your package. Pay attention to the output in your terminal. Unless you are running Figmage with an Enterprise Figma account, you will see an error message:

✗ Failed to fetch variables: Unauthorized. Make sure you have a valid access token that can access the file and that you are a Figma Enterprise team member. (0.7s)
✓ Found ... styles (3.0s)
✓ Generated package at ... with ... files (0.1s)
...

This is expected and does not affect the generation of your Style-based Tokens. Take a look at the Figma Account Requirements for more information.

Structure After Generation

If everything went well, you should now have a Dart package in your package directory that contains all your Tokens as Dart code.

Your package should look something like this:

• Directorydesign_tokens/

  • Directorylib/

    • Directorysrc/

      • colors.dart
      • typography.dart
      • …
    • design_tokens.dart
  • figmage.yaml
  • pubspec.yaml

Go ahead and open one of the files in the src directory to see your Tokens as Dart code. You will notice that Figmage generated a class for each of your top-level Token collections.

So if your Tokens were structured like this in Figma:

semantic
├── surface
│   ├── primary
│   └── secondary
└── onSurface
    ├── primary
    └── secondary

You will see a Dart class like this in your colors.dart file:

design_tokens/lib/src/colors.dart

// ...
class ColorsSemantic extends ThemeExtension<ColorsSemantic> {
  const ColorsSemantic({
    required this.surfacePrimary,
    required this.surfaceSecondary,
    required this.onSurfacePrimary,
    required this.onSurfaceSecondary,
  });

  // ...
}

Tip

If you have many top-level collections in Figma, you will see a lot of classes in this Dart file.

This might complicate the usage of your tokens in your Flutter app, so we recommend you to limit yourself to a few top-level collections and use nested structures for more detailed Tokens. A good start is grouping your collections by their type, like primitive, semantic, and component.

Update Dependencies

Now add your Tokens package as a dependency to your Flutter app.

1. Open the pubspec.yaml file of your Flutter app and add the following line to the dependencies section:

   pubspec.yaml

   dependencies:
     design_tokens:
       path: relative/path/to/your/design_tokens/

   If you decided to give your package a different name, make sure to replace design_tokens with the name you chose.

2. Run flutter pub get:

   flutter pub get

Using Tokens in your App

1. Add the generated Tokens to your app’s Theme

   Figmage generates ThemeExtension classes, which you will need to add to your app’s ThemeData to use them.

   lib/main.dart

   import 'package:design_tokens/design_tokens.dart';
   // ...
   @override
   Widget build(BuildContext context) {
     return MaterialApp(
       theme: ThemeData(
         // ...
         extensions: [
           ColorsSemantic.standard(), // or .light() if you have modes
           TypographySemantic.standard(),
         ],
       ),
       // Add dark theme if you have it
       darkTheme: ThemeData(
         // ...
         extensions: [
           ColorsSemantic.dark(), // Only if you have a dark mode
           TypographySemantic.standard(),
         ],
       ),
       themeMode: ThemeMode.system,
       home: MyHomePage(),
     );
   }

2. Use your Tokens in your widgets:

   lib/example_button.dart

   import 'package:design_tokens/design_tokens.dart';
   import 'package:flutter/material.dart';
   
   class ExampleButton extends StatelessWidget {
     @override
     Widget build(BuildContext context) {
       return ElevatedButton(
         style: ElevatedButton.styleFrom(
           backgroundColor: context.colorsSemantic.surfacePrimary,
           foregroundColor: context.colorsSemantic.onSurfacePrimary,
           textStyle: context.typographySemantic.headline1,
         ),
         onPressed: () {},
         child: Text('Click me!'),
       );
     }
   }

Updating Tokens

Whenever your Tokens change in Figma, you can run Figmage again in the same package directory to automatically update your package with the latest changes:

figmage forge -t YOUR_FIGMA_PERSONAL_ACCESS_TOKEN

What’s Next?

Configuration Options Explore all configuration options to customize your token generation.

Star the Repository Show your support by starring the Figmage repository on GitHub.