Your design tokens stop at the web boundary

In every multi-platform design system, there comes a point where the pipeline effectively ends, leading to a reliance on a single source of truth for values used across various platforms. Initially, this works well with colours and spacing stored in a JSON file, which is then transformed into a stylesheet containing custom properties.

However, when other platforms like iOS need the same values, the process often involves manually typing the numbers into the respective codebase. This approach is not inherently flawed, as the engineer making these changes is merely following a reasonable decision-making process given the lack of other mechanisms. The real issue arises when a value changes in the web pipeline but has no direct connection to the corresponding code in other platforms.

Without a build step that flags discrepancies or a review process that highlights changes, the two files remain unrelated, and divergences can occur without anyone noticing. To prevent such issues, a true single source of truth must ensure that every platform derives its values from this source through a build step. This build step should generate files that are visible, committable, and diffable, so any changes to the values are immediately apparent.

The Design Tokens Community Group (DTCG) format offers a standard way to write tokens in a JSON structure with typed values and nested groups. While the specific format may not be crucial, the existence of a single source of truth is essential. The real value lies in the layer built on top of this structure, which distinguishes between primitives and semantics.

Primitives are the basic values, while semantics define how these primitives are used within the design system. The key to a durable design system is ensuring that tokens are semantic, meaning that the token name alone can indicate its purpose. For example, color.primary should clearly indicate its role as the primary action colour, rather than being just another blue shade.

This semantic layer allows for easier updates when redesigns occur, as changing the primary colour only requires modifying the semantic token, not dozens of individual instances across multiple platforms. When generating values for non-web platforms, transforming and formatting the tokens becomes a straightforward process. Style Dictionary's model provides transforms to adapt values for specific platforms like Swift, Kotlin, or Dart, and formats to generate output files in the appropriate syntax for each platform.

For instance, web platforms may use CSS custom properties, while iOS platforms use Swift enums or structures. The critical aspect is to ensure that the generated native code does not force developers to branch their views based on colour schemes, as this negates the benefits of a single source of truth. Finally, the most overlooked step is making tokens adoptable on their own.

This means designing the system in a way that tokens can be used independently of any platform-specific implementation, allowing developers to adopt tokens without needing to understand or generate platform-specific code. By following these principles, design systems can maintain consistency across platforms and evolve gracefully through redesigns.