Creating Custom Tokens

Prerequisites: You should be familiar with Design Tokens before reading this guide.

The built-in token types cover colors, spacing, radii, typography, borders, shadows, font weights, durations, and breakpoints. If you need a token for a type they don’t cover (e.g. EdgeInsetsGeometry, Gradient, or an app-specific value object), you can create one by extending MixToken<T> and providing a reference class.

Step 1: Define the Token Class

Extend MixToken<T> with your value type and implement the call() method to return a reference wrapper:


/// Token for EdgeInsetsGeometry values
class EdgeInsetsGeometryToken extends MixToken<EdgeInsetsGeometry> {
  const EdgeInsetsGeometryToken(super.name);
 
  @override
  EdgeInsetsGeometryRef call() => EdgeInsetsGeometryRef(Prop.token(this));
}

Step 2: Define the Reference Class

The reference class wraps a Prop so the token value can participate in Mix’s resolution and merging system:


/// Reference class — wraps the Prop so it can be used in styles
class EdgeInsetsGeometryRef extends Prop<EdgeInsetsGeometry> {
  EdgeInsetsGeometryRef(Prop<EdgeInsetsGeometry> prop) : super.fromProp(prop);
}

Step 3: Provide and Use the Token

Custom tokens use the generic tokens map in MixScope (instead of the typed maps like colors or spaces):


final $contentPadding = EdgeInsetsGeometryToken('padding.content');
final $cardPadding = EdgeInsetsGeometryToken('padding.card');
 
MixScope(
  tokens: {
    $contentPadding: EdgeInsets.all(16),
    $cardPadding: EdgeInsets.symmetric(horizontal: 24, vertical: 16),
  },
  child: MyApp(),
);

Reference the token in a style via .create() and .merge():


final style = BoxStyler()
    .color(Colors.red)
    .size(100, 100)
    .merge(.create(padding: $contentPadding()));

When to Use Custom Tokens

Custom tokens are useful when:

Your design system uses value types not covered by the built-in set (e.g. Gradient, ShapeBorder)
You want to share app-specific configuration values (e.g. a custom animation config object) through the token system
A third-party package exposes value types you want to theme consistently

For standard styling needs, prefer the built-in token types.