Thinking About Token Architecture: My Journey Toward Context-Aware Design Systems

I've been wrestling with a token architecture challenge lately, and I think I might have found an approach that could change how we think about platform-specific design systems. Let me walk you through my thinking process and the solution I'm exploring.

The Challenge That Started It All

While tinkering on a "multi-platform" design system, I kept running into the same frustrating pattern. I'd set up what seemed like a clean token hierarchy—primitives, semantic, component tokens—and everything looked great. Then came the reality check: iOS needs different spacing increments, Android follows Material Design principles, and web has its own conventions.

Suddenly my elegant system became a sprawling matrix. Do I create separate token sets for each platform? Do I sacrifice platform conventions for consistency? Neither option felt right, and I started wondering if there was a better way to approach this entirely.

What I'm Thinking: Context-Aware Semantic Tokens

Here's the core idea I'm exploring: What if semantic tokens could be smart enough to know their context and adapt accordingly?

Instead of managing separate platform-specific token files, I'm experimenting with semantic tokens that can resolve to different values based on where they're being used. The structure I'm considering looks like this:

How I'm Approaching Context Resolution

The breakthrough moment came when I realized semantic tokens don't have to be static. They should be decision trees:

{
  "button-primary-background": {
    "web": "{platform.web.accent-primary}",
    "ios": "{platform.ios.system-blue}",
    "android": "{platform.android.primary-container}",
    "default": "{primitives.color.blue-500}"
  }
}

This way, products just reference button-primary-background and automatically get the right value for their platform. I'm essentially abstracting away platform complexity while preserving platform-appropriate behavior.

Edge Cases I'm Discovering

As I've been thinking through this approach, I've identified several scenarios where the simple context-aware pattern might not be enough:

Brand Requirements vs. Platform Conventions

I'm realizing that sometimes brand requirements need to override platform conventions entirely. For example, what happens when a fintech app needs specific colors for regulatory compliance, regardless of platform?

My current thinking is to allow product-level overrides:

{
  "button-primary-background": {
    "all-platforms": "{brand.fintech.regulatory-blue}"
  }
}

Accessibility Considerations

I'm also considering how accessibility requirements might conflict with platform defaults. Should I build accessibility context into semantic tokens themselves?

{
  "text-on-surface": {
    "web": "{platform.web.on-surface}",
    "web-high-contrast": "{platform.web.on-surface-high-contrast}",
    "ios": "{platform.ios.label}",
    "android": "{platform.android.on-surface}"
  }
}

Component-Specific Platform Behavior

Some components might need fundamentally different behavior per platform. I'm thinking about data visualizations that need different opacity values on iOS versus Android due to different background systems.

Progressive Enhancement Scenarios

For web, I'm considering how to handle modern CSS features that need fallbacks:

{
  "modal-backdrop": {
    "web-modern": "rgba(0,0,0,0.4) backdrop-blur(8px)",
    "web-fallback": "rgba(0,0,0,0.6)",
    "ios": "{platform.ios.system-background-secondary}",
    "android": "{platform.android.scrim}"
  }
}

Multi-Theme Complexity

The most complex scenario I'm grappling with is how different platforms handle theming. iOS dark mode behaves differently than Android's dark theme, and both are different from web dark mode.

My Implementation Strategy

I'm thinking about this as a gradual evolution rather than a complete overhaul:

Phase 1: Start with primitives and platform layers. I want to map out genuine platform differences first—not just what's possible, but what's actually necessary.

Phase 2: Build the semantic layer with simple context resolution. I'm planning to start with the most common use cases and add complexity only when needed.

Phase 3: Connect products to semantic tokens. I'm committed to resisting the urge to add overrides until I encounter real edge cases.

Phase 4: Add escape hatches for the edge cases I've identified, but keep them as exceptions.

What I'm Learning About Tooling

This approach requires build tooling that can handle context resolution. I'm evaluating whether existing tools like Style Dictionary can support this pattern, or if I need to build custom tooling that can:

• Resolve context-aware tokens at build time

• Handle fallback chains when contexts aren't defined

• Validate platform token references

• Generate platform-specific outputs while maintaining semantic references

Why I Think This Could Work

What excites me about this approach is how it serves different stakeholders:

Product teams get clean, platform-agnostic tokens that automatically do the right thing.

Platform teams maintain a single source of truth for their conventions.

System maintainers get meaningful abstractions that reduce implementation errors while providing flexibility.

Brand teams get consistency across platforms while respecting platform conventions.

Questions I'm Still Exploring

I'm still working through some fundamental questions:

• How do I handle the complexity of nested contexts (platform + theme + accessibility)?

• What's the right balance between automatic context resolution and explicit overrides?

• How do I ensure this approach scales as the system grows?

• What happens when platform conventions change—how do I propagate those changes efficiently?

Where I'm Headed Next

I should plan some time to prototype this approach with a small subset of tokens to validate the concept. I want to see how it feels to actually build with these context-aware semantics before committing to the full architecture.

The goal isn't to eliminate platform differences—it's to manage them intelligently. I'm hoping this context-aware semantic layer can give us both consistency and contextual appropriateness.

If this works, it could represent a shift from rigid token hierarchies toward more intelligent, adaptive design systems. The tokens would understand their environment and make appropriate decisions automatically.

My Current Thinking

I'm convinced that the future of design systems is more semantic and context-aware. By building tokens that understand their environment, we can create systems that are both consistent and contextually appropriate.

This feels like a significant step toward design systems that don't force us to choose between consistency and platform appropriateness. Instead, they give us both.

I'm excited to continue exploring this approach and see where it leads. The early signs are promising, and I think this could be a meaningful contribution to how we think about scalable design systems.