Why the current Design Tokens implementation is not complete

[tilucasoli]

Summary

The current Design Tokens implementation is functional for several common paths, but it is not complete yet.
The main gap is that token references and token resolution are mixed in ways that can look like concrete values but are just sentinel values relying on noSuchMethod.

Problem statement

The Design Tokens feature should allow any value to become tokenizable while preserving type safety and predictable resolution behavior.
Today, sentinel values and final resolution exist only inside Mix—tokens resolve correctly when used within Mix’s styling flow. If a user uses tokens in plain Flutter widgets (e.g. by following suggested call methods from the documentation), resolution may not happen there and the API may not behave as expected, leading to confusion and integration risks.

What is working today

• Token definitions via MixToken<T> and specialized token types are available.
• Tokens can be provided through MixScope.
• Tokens can be resolved from BuildContext.
• MixToken<T> extensions use the call() method that applies a sentinel value first, then resolution happens later in the style pipeline. This flow only works for predefined types (e.g. those handled in getReferenceValue: Color, double, Radius, Shadow, BoxShadow, TextStyle, Breakpoint, BorderSide, FontWeight, Duration, List<Shadow>, List<BoxShadow>). Custom or other T are not given proper ref types and do not get the same sentinel-then-resolve behavior.
• Style APIs can carry token references and resolve them later in many Mix-managed flows—for those predefined types.

Why the implementation is not complete

1. The goal is broader than what is currently covered

The goal of Design Tokens is to make any kind of value tokenizable, not only a fixed subset of value types.
Resolution via BuildContext works well in the current code. The limitation is that the call() method on MixToken (which returns ref/sentinel values for the style pipeline) only works for known built-in token types; custom or other value types do not get the same treatment.

class EdgeInsetsToken extends MixToken<EdgeInsetsGeometryMix> {
  const EdgeInsetsToken(super.name);
}

final $contentPadding = EdgeInsetsToken('padding.content');

// Inside of the Widget
@override
Widget build(BuildContext context) {
   return MixScope(
   tokens: {$contentPadding: EdgeInsetsGeometryMix.all(16)},
   child: Box(
         style: BoxStyler().padding($contentPadding.call()) // it doesn't work
      ),
   );
}

2. Resolution depends on BuildContext, but styles are often created in places where it is not available

Any token can be resolved using BuildContext, but styles are frequently declared in places where BuildContext is not available yet (for example, static style declarations, shared constants, or builder-independent layers).

final $contentPadding = EdgeInsetsToken('padding.content');

// Shared style declared outside widget build.
final buttonStyle = BoxStyler()
    // Cannot use `$contentPadding.resolve(context)` here because there is no BuildContext.
    // Forcing to use .call(), but it throws an error
    .padding($contentPadding())

3. MixToken.call() can suggest a final value when it is actually a temporary reference

Some classes extending MixToken expose call() returning a Ref-like value. This is useful internally, but the API can give the impression that the returned object is already the final concrete value.
In reality, it is a temporary placeholder that must be resolved later.

This becomes problematic in two common scenarios:

• Flutter widget APIs that expect immediate concrete values may receive unresolved references and fail to resolve them.
• User operations like copyWith or value transformations can run on unresolved placeholders, causing invalid behavior or runtime errors.

const $title = TextStyleToken('typography.title');

void unsafeUsageOutsideMix(BuildContext context) {
  final styleRef = $title(); // Looks like TextStyle, but is a token reference.

  // This can throw at runtime because token refs use noSuchMethod until resolved.
  final changed = styleRef.copyWith(fontSize: 20);

  // Same risk for plain Flutter usage paths outside Mix resolution boundaries.
  Text('Hello', style: changed);
}

Impact

• API clarity risk: Developers may incorrectly assume token references are concrete values.
• Integration risk: Tokenized values passed outside Mix resolution boundaries may break.
• Composition risk: Value-level operations (copyWith, arithmetic, merges) can behave incorrectly before resolution.

useToken(...) as a possible solution (and its problems)

One possible solution is an API like:

useToken<T>(MixToken<T> token, Style Function(T value) builder)

Upside: It gives a clear, ergonomic way to build styles from resolved token values (e.g. “when this token is X, apply this style”), which can simplify token-aware styling.

final $primary = ColorToken('color.primary')

final style = 
   BoxStyler()
      .useToken($primary, BoxStyler.color)

Problems: If implemented on top of ContextVariant, it can alter the order of style application and not respect the override order. To be safe, resolution would need to happen inline at the same declaration position (order-preserving), not as a variant layer with different merge timing—which may constrain or complicate the implementation.

final $primary = ColorToken('color.primary')

// The final color will be the color on the token because the ContextVariants are applied after the normal methods
final style = 
   BoxStyler()
      .useToken($primary, BoxStyler.color)
      .color(Colors.red)