design_tokens_builder: A Dart repository from simpleclub

A package for generating a Flutter ThemeData from an exported design token json that is used e.g. in this Figma plugin. It rather aims to create a Flutter Theme based on Material 3 than creating a lot of custom widgets for each token.

Features

Right now, we support generating/parsing the following:

ColorScheme
TextStyle
- Font family mapping (from Figma font name to Flutter name)
- Font weight
- Line height
- Font size
- Letter spacing
- Text decoration
Theme extension
- Borders
- Border radii
- Box Shadows
- Colors
- Dimensions (also with px)
- Font families
- Font weights
- Line height (only %)
- Numbers
- Opacity (also with %)
- Edge insets
- Text cases
- Text decorations
- Text styles
Exposing theming and extensions via a BuildContext extension

Getting started

Add a .json file containing the tokens describing your app design.
Add a tokenbuilder.yaml configuration file (see example project) in your lib directory
1. Add the path leading to the json to the configuration file
2. Map Figma font names to Flutter font family names in the configuration file
Add this builder to build.yaml

targets:
  $default:
    builders:
      design_tokens_builder:design_tokens_builder:
        enabled: true

Usage

Before you can use the tokens, you have to start the build runner by executing flutter pub run build_runner build. After that, just make sure to use one of the GeneratedTokenSet for the selected Brightness in your ThemeWidget.

return Theme(
  data: GeneratedTokenSet.general.data.dark,
  child: Container(),
);

By listening to Brightness changes, you could then easily switch between themes. You could also easily change the token set.

This package also exposes the generated theme extensions by building a BuildContext extension. You can use the shortcut like this context.yourExtension. We also provide shortcuts for theme-related properties like context.colorScheme and context.textTheme.

Additional information

Multi-theming and dark and light mode

The package can generate themes based on multiple token sets in your token data json. Every set will be available through a GeneratedTokenSet. This enum contains all set pairs and ThemeData for light and dark themes. To specify the brightness of your set, use Light/Dark as a suffix in design tokens (e.g. yourSetLight, yourSetDark). You also might have a global or core set with universal tokens that do not change based on the selected brightness. In that case, make sure to call this set global. It will be recognized by the builder and ignored when creating GeneratedTokenSets.

Generation of Flutter `ThemeData`

The package allows for the straightforward generation of Flutter's ThemeData. To do so, you have to have a certain structure for your design tokens. Since this is a system token related to Material 3 the tokens used to generate Flutter's ThemeData should always start with sys. If you then e.g. want to set the primary color in Flutter's ColorScheme you have to add a token called sys.primary with type color to your json file containing all of your tokens. primary is the name of ColorSchemes primary field. Remember to write the field names in camel case so the package can recognize them correctly. For text styles, it works similarly. Here also use sys as the leading part of your token. To better organize the tokens in Token Studio, we decided to split the text style naming. So if you want to generate displaySmall text style, just use a sys.display.small token of type typography.

Generation of theme extensions

Theme extensions are a great way of providing custom parameters that are not defined in ThemeData defined. You can create a new extension using a different prefix than sys for your tokens. Based on that name and the type of the tokens inside that token group an extension will get generated and added to the ThemeData. So a custom set of colors called custom in your token json with the type color will generate a class CustomColors which extends ThemeExtension<CustomColors>.

Example token json:

{
  "light": {
    // <- Token set
    "sys": {
      // <- Token group sys - Used for Flutter ThemeData
      "primary": {
        // <- Token for primary color in ColorScheme
        "value": "#0000FF",
        "type": "color"
      },
      "background": {
        "value": "#FFFFFF",
        "type": "color"
      },
      "onBackground": {
        "value": "#000000",
        "type": "color"
      }
      …
    }
  },
  "$themes": [],
  "$metadata": {
    "tokenSetOrder": [
      "light"
    ]
  }
}

Using math and aliases in your tokens

Using math operations and aliases in your tokens is supported by the package.

Tokens Studio for Figma feature parity

Please also see Tokens Studio for figma documentation .

Expand table

Group	Parsable	Exposed via Extension
Sizing	✅	✅
Spacing	✅	✅
Color	✅	✅
Border radius	✅	✅
Border width	✅	✅
Box shadow	✅	✅
Opacity	✅	✅
Font family	✅	✅
Font weight	✅	✅
Font size	✅	✅
Line height	✅	✅
Letter spacing	✅	✅
Paragraph spacing	✅	✅
Text case	✅	✅
Text decoration	✅	✅
Typography compositions	✅	✅
Assets	❌	❌
Composition	❌	❌
Dimension	✅	✅
Border	✅	✅

Flutter theming

The following table shows which themes the package can generate.

Expand table

Properties	Supported
`colorScheme`	✅
`iconTheme`	❌
`textTheme`	✅
`appBarTheme`	❌
`badgeTheme`	❌
`bannerTheme`	❌
`bottomAppBarTheme`	❌
`bottomNavigationBarTheme`	❌
`bottomSheetTheme`	❌
`buttonBarTheme`	❌
`buttonTheme`	❌
`cardTheme`	❌
`checkboxTheme`	❌
`chipTheme`	❌
`dataTableTheme`	❌
`datePickerTheme`	❌
`dialogTheme`	❌
`dividerTheme`	❌
`drawerTheme`	❌
`dropdownMenuTheme`	❌
`elevatedButtonTheme`	❌
`expansionTileTheme`	❌
`filledButtonTheme`	❌
`floatingActionButtonTheme`	❌
`iconButtonTheme`	❌
`listTileTheme`	❌
`menuBarTheme`	❌
`menuButtonTheme`	❌
`menuTheme`	❌
`navigationBarTheme`	❌
`navigationDrawerTheme`	❌
`navigationRailTheme`	❌
`outlinedButtonTheme`	❌
`popupMenuTheme`	❌
`progressIndicatorTheme`	❌
`radioTheme`	❌
`searchBarTheme`	❌
`searchViewTheme`	❌
`segmentedButtonTheme`	❌
`sliderTheme`	❌
`snackBarTheme`	❌
`switchTheme`	❌
`tabBarTheme`	❌
`textButtonTheme`	❌
`textSelectionTheme`	❌
`timePickerTheme`	❌
`toggleButtonsTheme`	❌
`tooltipTheme`	❌

Future capabilities

We want to extend the package also to be able to generate/parse more material themes like ButtonTheme etc.

Let us know if you miss something by creating an issue or by actively contributing!

Contributing

With this open-source repository, we want to create a tool that helps Flutter integrate with more tools to streamline and simplify the design handoff experience by utilizing Flutter's API. Since this is not only a problem we face, we want to share and collaborate on this software to give back to the community. Any contributions are more than welcome!

See our contributing guide for more information.

simpleclub/design_tokens_builder