Getting Started

This guide will teach you how to get Figmage running and set you up for success.

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

What you need

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

Figma Design File

You should have a Figma file that represents your Design System, or just a simple app design. In both cases, you should have at least a few Tokens defined in your file.

Figma Account

In most cases, you will only need an account that can access the file you want to sync with your project. However, if you are using Variables in Figma, you might need a paid plan. Find out more here.

Install Figmage

First, you need to install the Figmage CLI. You can do this by running the following command in your terminal:

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 in your terminal:

   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

Tell Figmage where to find your Tokens

Now that you have your package set up, you need to tell Figmage where to find your Tokens in Figma.

1. Get your Figma file’s ID. You can find the ID of your Figma file in the URL when you have the file open in your browser. It looks something like this:

   https://www.figma.com/design/<<your-file-id>>/...

   An easy way to obtain the link from the Figma app is to click the Share button in the top right corner of the app and select the Copy link option.

2. Add the Figma file ID to your figmage.yaml file. Open the file you created earlier and add the following content:

   figmage.yaml

    fileId: <<your-file-id>>

3. Obtain a Personal Access Token from Figma.

   You can generate a Personal Access Token in the Figma app by going to your account settings and selecting the Generate new token option. Make sure to copy the token to a safe place, as you will not be able to see it again.

   Caution

   To prevent accidental leaks, Figmage does not allow adding your Personal Access Token directly to the figmage.yaml file. You have to pass it as input every time you run Figmage. You can store your access token in an environment variable or a secret manager and use it from there.

Run Figmage ✨

Now that you have everything set up, you can run Figmage to generate your Tokens package.

1. Navigate to your package directory in your terminal.

   cd design_tokens

2. Run Figmage with the following command:

   figmage forge -t <<your-personal-access-token>>

   Replace <<your-personal-access-token>> with the Personal Access Token you obtained earlier.

3. Let Figmage do its magic.

   Figmage will now 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.

Inspect the generated package

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.

✅ Using your Tokens in your Flutter app

Now that you have your Tokens as Dart code, you can use them in your Flutter app.

1. Add your Tokens package as a dependency to your Flutter app.

   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. 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.

   For example, this is how you would add the generated ColorsSemantic and TypographySemantic to your app’s ThemeData:

   lib/main.dart

    import 'package:design_tokens/design_tokens.dart';
   // ...
   @override
   Widget build(BuildContext context) {
     return MaterialApp(
       theme: ThemeData(
         // ...
         extensions: [
           ColorsSemantic.standard(),
           TypographySemantic.standard(),
         ],
       ),
       home: MyHomePage(),
     );
   }

   If your Tokens were generated from Variables, you will get multiple contructors, one for each mode. Let’s say you have a dark and a light mode, you would use them like this:

   lib/main.dart

    import 'package:design_tokens/design_tokens.dart';
   // ...
   @override
   Widget build(BuildContext context) {
     return MaterialApp(
       theme: ThemeData(
           // ...
           extensions: [
               ColorsSemantic.light(),
               TypographySemantic.standard(),
           ],
       ),
       darkTheme: ThemeData(
           // ...
           extensions: <ThemeExtension<dynamic>>[
               ColorsSemantic.dark(),
               TypographySemantic.standard(),
           ],
       ),
       themeMode: isLightTheme ? ThemeMode.light : ThemeMode.dark,
       home: MyHomePage(),
     );
   }

3. Use your Tokens in your app

   You are ready to use your tokens wherever you want!

   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!'),
       );
     }
   }

That’s it! You now have your Tokens as Dart code in your Flutter app. 🎉

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

What’s next?

Customize your Experience Learn how to configure Figmage to your needs.

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