Design Tokens

Introduction

Design tokens are the core of any design system. They are the smallest pieces of a design system that define the visual properties of a UI. These properties can include colors, typography, spacing, and more. Design tokens are used to maintain consistency across an application and make it easier to update the design system. As Mix is a solution for styling and is used for building design systems, it also supports design tokens.

Getting Started

Mix has built-in support for design tokens. It naturally integrates with five types of them: color, textStyle, space, radius, and breakpoint. These tokens are used to define the visual properties in key-value pairs, where the key is the token name and the value is the actual value of the token.

final primary = ColorToken('primary');
 
final docTheme = MixThemeData(
  colors: {
    primary: Colors.lightBlue,
  },
  textStyles: {...},
  radii: {...},
  spaces: {...},
);

MixTheme and MixThemeData

In the same way we use Theme and ThemeData in Flutter, Mix has MixTheme and MixThemeData. MixTheme is a widget that wraps the application and provides the design tokens to all its child widgets.

MixTheme(
  data: docTheme,
  child: ...
);

MixThemeData

MixThemeData is a class that defines the values for the design tokens that will be used throughout the application. It has five properties related to Design Tokens: colors, textStyles, spaces, radii, and breakpoints. Each property is a map that contains the tokens and their values.

Also, MixThemeData has an additional property called defaultOrderOfModifiers, which is used to override the default order of modifiers. Therefore, if you prefer to use a different order of modifiers, you can set it in the defaultOrderOfModifiers instead of using the orderOfModifiers property in each StyledWidget. To set your own order of modifiers, you just need to pass a list of types that extends WidgetModifierSpec. For instance:

final overrideOrderTheme = MixThemeData(
  defaultOrderOfModifiers: [
    SizedBoxModifierSpec,
    ClipRectModifierSpec,
    TransformModifierSpec,
  ],
);

Applying design tokens

After defining the design tokens, you can use them in your application to style your widgets. All attributes that accept a token as a value have a ref method that allows you to access the token value. For instance:

$box.color.ref(ColorToken)
 
$text.style.ref(TextStyleToken)
 
$box.borderRadius.ref(RadiusToken)
 
$box.padding.all.ref(SpaceToken) // You can replace `all` with any other padding property

In a real example:

Box(
  style: Style(
    $box.color.ref(primary),
    $box.height(100),
    $box.width(100),
  ),
);

Mix's tokens are also flexible enough to be used in Flutter's widgets, you just need to use the resolve method to get the token value.

Container(
  height: 200,
  width: 200,
  color: primary.resolve(context),
)

Next Steps

Now that you know how design tokens work in Mix, you can start defining your own tokens and using them in your application. For a step-by-step tutorial on how to theme your app with Mix, check the Theming guide.

Widget Modifiers Animations