Design tokens have become the lingua franca of modern design systems. But when you’re operating across three platforms—web, iOS, and Android—with distributed teams spanning four time zones, synchronization becomes a non-trivial engineering challenge.
Our journey began when we realized that our Figma variables, CSS custom properties, and Swift color assets had drifted so far apart that the same “primary blue” rendered as three visibly different hues across platforms. The cognitive load on designers and engineers was unsustainable.
We built a pipeline that starts with a single source of truth: a JSON token file maintained in a dedicated repository. Every merge to main triggers a CI job that transforms these tokens into platform-specific outputs—CSS custom properties for web, a Swift package for iOS, and an XML resource file for Android.
The transformation layer is where the real complexity lives. Color spaces differ across platforms. A token like `spacing.lg` might map to `rem` on web but `points` on iOS. We wrote custom transformers using Style Dictionary that handle these conversions deterministically.
Versioning was another challenge we underestimated. When a token changes, all three platforms need to adopt the update—but not necessarily simultaneously. We introduced semantic versioning for our token packages, with breaking changes requiring explicit opt-in from each platform team.
After six months of iteration, our token count grew from 200 to over 4,000. Performance of the build pipeline became critical. We implemented incremental builds that only regenerate outputs for changed token categories, reducing build times from 45 seconds to under 3 seconds.
The cultural shift was arguably harder than the technical one. Designers needed to think in tokens rather than raw values. Engineers needed to resist the temptation to hardcode. We invested heavily in documentation, onboarding sessions, and linting rules that flag direct value usage.
Looking back, the investment has paid dividends. Design reviews are faster because everyone speaks the same language. Platform parity issues dropped by 90%. And our design system team—once seen as a bottleneck—is now viewed as an enabler.
