Platform-Specific Tokens

Platform-specific tokens are design values that exist only on certain platforms or have different values across platforms to accommodate platform-specific requirements, conventions, or capabilities. While cross-platform tokens maintain identical values everywhere, platform-specific tokens acknowledge that some design decisions must vary to optimize user experience on each platform.

What Are Platform-Specific Tokens

Platform-specific tokens address requirements unique to individual platforms. These tokens might define iOS-specific safe area insets, Android-specific elevation values, or web-specific hover states. They complement universal tokens by handling cases where one-size-fits-all values would compromise platform-appropriate design.

Some platform-specific tokens share names but have different values. A minimum touch target size token might be 44 points on iOS (matching Apple’s Human Interface Guidelines) and 48 density-independent pixels on Android (matching Material Design guidelines). The semantic meaning is identical, but platform conventions dictate different values.

Other platform-specific tokens exist on only one platform. Web platforms support hover states that touch-primary mobile platforms cannot trigger. Shadow implementations differ enough between web CSS box-shadow, iOS CALayer shadows, and Android elevation that separate token definitions may serve better than forced abstraction.

How Platform-Specific Tokens Work

Token systems accommodate platform-specific values through various mechanisms. Style Dictionary and similar tools support platform filters that include or exclude tokens based on target platform. Tokens can specify which platforms they apply to through metadata or file organization.

File-based organization separates universal and platform-specific tokens. A tokens/core directory might contain universal definitions while tokens/ios, tokens/android, and tokens/web directories hold platform-specific additions or overrides. Build configurations combine appropriate files for each platform output.

tokens/
  core/
    colors.json     # Universal color tokens
    spacing.json    # Universal spacing tokens
  ios/
    sizing.json     # iOS-specific size values
  android/
    elevation.json  # Android-specific elevation values
  web/
    hover.json      # Web-specific hover state tokens

Override mechanisms allow platform-specific values to replace universal defaults. A token defined in core files might be redefined in platform files with platform-appropriate values. Build order determines precedence, typically with platform files overriding core definitions.

Documentation must clearly indicate which tokens are universal versus platform-specific. Design tools and developer documentation should show token availability per platform, preventing confusion when tokens appear in designs but are unavailable on certain platforms.

Key Considerations

• Clear naming distinguishes universal from platform-specific tokens
• Override precedence rules must be well-documented and consistent
• Platform-specific tokens increase maintenance burden proportionally
• Design tool integration may not visualize platform variations
• Testing must verify platform-specific tokens apply correctly
• Consumer documentation needs platform-scoped token references

Common Questions

When should tokens have platform-specific values versus universal values?

Platform conventions and guidelines provide primary guidance. When platform design guidelines specify values, platform-specific tokens respect those specifications. iOS Human Interface Guidelines recommend 44-point touch targets; Material Design specifies 48dp. Platform-specific tokens honor these standards.

Technical platform differences also warrant platform-specific tokens. CSS shadows, iOS shadows, and Android elevation use fundamentally different models. Attempting to abstract these into universal tokens often produces suboptimal results on all platforms. Platform-specific tokens allow each platform to use its native approach effectively.

User expectation differences justify some platform-specific variations. iOS users expect certain spacing and typography rhythms that differ from Android conventions. Platform-specific tokens enable platform-appropriate implementations while maintaining brand consistency at a higher level.

Universal tokens remain appropriate when brand requirements override platform conventions. A brand’s primary color should typically be consistent across platforms. Core spacing rhythms might stay consistent to maintain visual identity. The decision balances brand consistency against platform optimization.

How do design tools handle platform-specific tokens?

Design tools increasingly support token variants and modes that can represent platform differences. Figma’s variables feature allows defining different values for different modes, which can represent platforms. Designers can switch between iOS and Android modes to see platform-appropriate values.

Plugins extend design tool capabilities for platform-specific tokens. Tokens Studio for Figma supports multiple token sets that can represent platform variations. Designers work with the appropriate token set for their target platform.

Design review processes should verify platform-specific considerations. When designs target multiple platforms, reviews should examine each platform’s token application. Handoff documentation should explicitly note platform-specific values and any expected differences.

Some organizations maintain separate design files per platform when differences are substantial. This approach ensures designers think platform-natively but increases maintenance burden and risks divergence. Clear source-of-truth definitions for shared elements mitigate divergence risks.

How do teams prevent platform-specific token proliferation?

Governance processes evaluate whether proposed platform-specific tokens are truly necessary. Before creating platform-specific tokens, teams should verify that universal tokens genuinely cannot serve the need. Many apparent platform requirements can be addressed through implementation approaches rather than token variations.

Regular audits identify platform-specific tokens that could be consolidated. As understanding matures, patterns emerge showing where platform variations add value versus complexity. Consolidation opportunities reduce maintenance burden.

Abstraction layers sometimes eliminate apparent platform-specific needs. Rather than platform-specific shadow tokens, teams might define semantic shadow levels that platform implementations interpret appropriately. The token system defines “elevation-low” while platforms determine specific rendering approaches.

Documentation should explain the rationale for each platform-specific token. This documentation helps future maintainers understand whether tokens remain necessary or might be consolidated as platform capabilities evolve.

Summary

Platform-specific tokens acknowledge that optimal design sometimes requires different values across platforms while maintaining design system unity at the semantic level. Success requires clear organization distinguishing universal from platform-specific tokens, governance preventing unnecessary proliferation, and documentation helping designers and developers understand platform-specific availability and rationale.