Book a call

WritingFoundations & tokensPart 6 of 6 in Tokens in practice

Cross-platform design systems: web, iOS and Android from one source

Three platforms, three teams, three blues. How to share decisions instead of code: one token source for every platform, components built natively with the same names, and a simple test for what to share and what to adapt.

On this pageThe problem with three separate systems
  1. The problem with three separate systems
  2. One source of decisions, every platform
  3. Share, adapt or keep separate
  4. Organising the team and the docs
  5. Where to start
  6. The short version
  7. Frequently asked questions
  8. Further reading

The short answer

A cross-platform design system shares decisions, not code. Write tokens once in a shared format and generate them for every platform (CSS variables, Swift, Kotlin, Figma variables) with a build tool such as Style Dictionary. Build components natively on each platform, with the same names, props and tokens. Then decide, component by component, what to share (brand, foundations, words, component purposes), what to adapt to platform conventions (navigation, date pickers, switches, text sizes) and what to keep separate (things that only exist on one platform). The test: would a regular user of this platform be surprised by how it behaves? If yes, adapt.

  • People expect an iPhone app to feel like an iPhone app, while still recognising your brand.
  • Each extra platform adds roughly the same component effort again; tokens are the part that scales for free.
  • Keep one set of names and one documentation page per component, with platform tabs.

The problem with three separate systems

Most companies end up with a web system, then an iOS one built by the iOS team, then an Android one. Each starts from the same brand guidelines and drifts within a year: three blues, three button heights, three ways to show an error.

An illustration: one brand, three blues

The situation

Web, iOS and Android teams each maintain their own colours and components from a shared brand PDF.

What goes wrong

A brand refresh means three projects. A contrast fix lands on web and Android but not iOS. Support screenshots look like three different companies.

What a shared source changes

One set of token files generates colours, type and spacing for all three. The refresh is one change, reviewed once, released everywhere.

One source of decisions, every platform

Token filesColour, type, spacing, radius, motion, in the DTCG format
→
BuildA pipeline such as Style Dictionary transforms names and units
→
OutputsCSS variables · Swift · Kotlin / Compose · Figma variables
→
ComponentsBuilt natively on each platform; same names, props and tokens
Tokens are written once and generated for each platform. Components are built per platform. Tokens are the part of a design system that works everywhere, which is why they come first.
// one token…
{ "color": { "action": { "primary": { "bg": { "$type": "color", "$value": "{color.brand.600}" } } } } }

// …generated for each platform
--color-action-primary-bg: #4736fe;                          /* CSS */
static let colorActionPrimaryBg = Color(hex: 0x4736FE)        // Swift
val ColorActionPrimaryBg = Color(0xFF4736FE)                  // Kotlin

Units change too: spacing in rem on the web becomes points on iOS and dp on Android; type sizes may map to Dynamic Type styles on iOS. The build tool handles the conversion, so designers and engineers still talk about space.4 on every platform.

Share, adapt or keep separate

Decide to…UsuallyExamples
ShareBrand, foundations, content, component names and purposesColours, voice, "primary button", error message formulas, icon meanings
AdaptThings where the platform has strong conventionsNavigation (tab bar vs drawer), date and time pickers, switches, sheets, text sizes, haptics, back behaviour
Keep separateThings that only exist on one platformWidgets, watch faces, desktop keyboard shortcuts, hover-only interactions
The three choices for every component and pattern. Practitioner view Apple's Human Interface Guidelines and Google's Material Design describe different navigation, controls and text sizes; respect both.
THE TEST

Would a regular user be surprised?

If an iPhone user would be surprised by how something behaves, adapt it to iOS. If not, share it. A custom date picker that ignores the platform's own usually fails this test.

WHAT STAYS THE SAME

Purpose, name and tokens

Even an adapted component keeps the same name, the same purpose, the same props where possible and the same tokens. "Primary button" means the same thing everywhere.

Organising the team and the docs

  • One component, one page: a single documentation page per component with tabs for web, iOS and Android, so the shared purpose and guidance sit above the platform details.
  • Platform specialists in the core team: at least one engineer per platform. Without one, that platform's version lags and teams build their own.
  • Same names, mapped props: where platforms differ (onClick vs a SwiftUI action), document the mapping once.
  • Coordinated releases: token changes ship to every platform in the same release, even if components follow at different speeds.
  • Platform-specific sizes as component tokens: a button's height can map to each platform's guidelines through a component token. See component tokens.

Where to start

  1. Move tokens into one source

    Collect each platform's colours, type and spacing, agree the names, and generate all three from one set of files. This alone removes most visible drift.

  2. Align names and purposes

    Make a table of every component on every platform. Same purpose, same name; note where behaviour should differ.

  3. Decide share, adapt or separate

    Component by component, starting with the ten used most.

  4. Bring docs together

    One page per component with platform tabs, so the guidance is written once.

Each extra platform adds roughly the same component effort again. Budget for it; see component complexity.

In practice

At CARS24, a new palette in OKLCH and a four-layer token system carried the rebrand across India, the UAE and Australia. Read the case study.

The short version

  • Share decisions, not code: one token source generated for every platform.
  • Build components natively, with the same names, props and tokens.
  • Share brand and purpose; adapt to platform conventions; keep platform-only things separate.
  • One documentation page per component, with platform tabs.
  • Put a specialist for each platform in the core team.

Frequently asked questions

Can one design system cover web, iOS and Android?

Yes, by sharing tokens, names and guidance from one source while building components natively on each platform and adapting where platform conventions differ.

How do you share design tokens across platforms?

Keep tokens in a shared format such as DTCG JSON and use a build tool like Style Dictionary to generate CSS variables, Swift, Kotlin and Figma variables from the same files.

Should mobile apps follow the brand or the platform?

Both: brand in colour, type, voice and imagery; platform in navigation, controls and behaviour people already know.

Should we use a cross-platform framework instead?

Frameworks like React Native or Flutter can share component code. The same principles still apply: shared tokens, and adapting where people expect platform behaviour.

Further reading