docs: document and highlight ContextToken

[tilucasoli]

Summary

ContextToken<T> shipped in mix 2.1.0 (btwld/mix#938) but was completely undocumented — zero mentions anywhere in this repo, despite the docs already covering every other token type (ColorToken, RadiusToken, SpaceToken, BreakpointToken, …).

This PR closes that gap.

Changes

guides/design-token.mdx — new "Context Tokens" section

Placed after Theme Switching (its natural neighbor, since the canonical use case is deriving from Theme.of(context)). Covers:

• Zero-config, context-derived resolution — no MixScope required
• Fluent-chain ordering parity with other tokens (primary() behaves like any value in the chain)
• MixScope override behavior — the resolver is a context-derived default a scope can override
• ⚠️ Resolver-identity equality caveat → declare context tokens as top-level / static finals
• A comparison table: scope tokens vs. ContextToken

tutorials/creating-custom-tokens.mdx — cross-link

Added an info callout so authors with a BuildContext-derived value reach for the built-in ContextToken instead of hand-rolling a custom token.

Accuracy

All examples are grounded in the actual 2.1.0 API (packages/mix/lib/src/theme/tokens/mix_token.dart) and mirror the behavior asserted in context_token_integration_test.dart (chain ordering, scope override, resolver-identity equality). No new preview blocks were added — the section is copy + code samples only.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
mix-docs	Ready	Preview, Comment	Jun 26, 2026 5:30pm

[Copilot]

Pull request overview

Adds first-class documentation for ContextToken<T> so Mix docs cover context-derived token resolution (e.g., bridging Material Theme.of(context)), plus a cross-link from the custom-token tutorial to steer readers toward the built-in type when appropriate.

Changes:

• Add a new “Context Tokens” section to the Design Tokens guide, including usage examples, scope override behavior, and an equality caveat.
• Update the Design Tokens page description to mention BuildContext-derived tokens.
• Add an info callout to the “Creating Custom Tokens” tutorial linking to ContextToken.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
src/content/documentation/mix/guides/design-token.mdx	Adds Context Tokens section and updates frontmatter description to include BuildContext-derived tokens.
src/content/documentation/mix/tutorials/creating-custom-tokens.mdx	Adds a callout directing readers to use ContextToken for BuildContext-derived values instead of custom tokens.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[leoafarias]

I’d make two wording corrections before publishing. The implementation supports the main ContextToken claims here: no MixScope is required, scope overrides work, chain order is preserved, and equality is resolver-identity based. The remaining risk is that the docs imply ContextToken works for arbitrary BuildContext-derived value types, while ContextToken.call() only has token-reference support for Mix’s supported token value set.

[tilucasoli]

Addressed the review feedback in 17774f71:

• Qualified ContextToken scope to Mix's built-in token value types in design-token.mdx (including the comparison table).
• Softened the custom-tokens callout to "you may not need a custom token" and documented .resolve(context) / custom-token paths for unsupported types.

Resolved the open threads — ready for another look when you have a moment.

[leoafarias]

LGTM