Multi-platform design systems: what's different about native

A team that has a functioning web design system and wants to extend it to iOS and Android usually starts with tokens. Export the color and spacing values, import them into the native platform tools, align the values. This solves maybe 20% of the problem and leaves the other 80% largely unexamined.

The hard parts of a multi-platform design system have almost nothing to do with token values. They're structural: the interaction patterns, the navigation paradigms, the accessibility model, the component rendering behavior, and the documentation itself all need different answers per platform. Treating a cross-platform design system as primarily a token synchronization problem will produce a system that looks consistent and behaves inconsistently. Users notice even when they can't articulate why.

Where platforms genuinely diverge

iOS and Android have their own platform conventions. Users who are native to those platforms have expectations built from years of OS-level interaction: how menus open, how navigation stacks, how sheets present, how selection works in a list. These expectations are not the same as web expectations, and they're not the same across iOS and Android.

A bottom sheet that slides up to reveal options is correct on iOS. The same pattern on Android is a bottom sheet but with different animation easing, different gesture affordance for dismissal, and different relationship to the back button. The design system component that handles this cannot be a single component with platform-specific values swapped in. It has to account for the behavioral differences.

The web design system team's instinct is to define components at the interaction level ("a bottom sheet is a bottom sheet") and then let platform implementations handle the differences. This works until the interaction models diverge enough that there's no meaningful shared definition. A date picker on web is a popover with a calendar grid. On iOS it's a scroll wheel. On Android it's a modal with a month view. The shared thing is the concept of selecting a date, not any element of the implementation.

The documentation surface area problem

Web documentation talks about props and variants and CSS custom properties. Native documentation has to talk about SwiftUI modifiers, UIKit delegate patterns, Jetpack Compose parameters, and sometimes three different ways to achieve the same visual output depending on which version of the OS you're targeting.

A shared documentation site that covers all three platforms produces documentation that is accurate for each platform but comprehensible to fewer people. A web engineer reading the iOS documentation will likely misunderstand it, and vice versa. Separate documentation that's platform-specific is more useful but harder to maintain and provides no shared context for cross-platform design decisions.

The setup that works: shared documentation for design intent, platform-specific documentation for implementation. A component page starts with the design rationale (when to use this, what it should communicate, the interaction behavior at a conceptual level) and then branches into platform-specific usage sections. The design intent is written once. The implementation guidance is written separately per platform and maintained by someone with platform expertise.

This requires more people than a web-only system. Native platform expertise is specialized and different from web expertise. A design systems team that is entirely web-focused will produce native documentation that is incorrect in specific, hard-to-catch ways. The kind of incorrect that a platform-native engineer immediately recognizes and immediately stops trusting.

What tokens can and can't unify

Tokens work for values that are genuinely platform-agnostic: a color defined as --color-text-primary: #1a1a1a should be the same value in iOS and Android and web. Typography values (font size, line height) can be shared where the platforms use similar units.

Tokens don't work for things that differ structurally between platforms. Spacing on iOS and Android is often specified in points or density-independent pixels, not CSS pixels. These convert to different physical sizes depending on screen density, and the mapping isn't always 1:1 with web values. A --spacing-sm: 8px in CSS doesn't automatically translate to 8pt in UIKit in a way that produces visually consistent results across devices.

Animation tokens (duration and easing values) are particularly fraught. The platforms have different default motion behaviors and different motion guidelines. Apple's Human Interface Guidelines and Material Design have different and sometimes conflicting positions on animation physics. Sharing animation tokens across platforms can produce motion that feels wrong on both simultaneously. Not wrong enough to obviously violate platform conventions, but off in a way that native users notice.

The component naming question

Component naming across platforms is where conceptual integrity gets tested. The web design system calls something a "chip." iOS calls the same pattern a "tag" in some Apple documentation and "token" in others. Android's Material Design calls it a "chip" but with different behavior rules.

Aligning on a single canonical name across platforms is worth doing. It enables cross-platform conversations without constant translation. But aligning the name while preserving the platform-appropriate behavior is the only version of this that actually works. A "chip" that means the same thing at the naming level but renders and behaves correctly per platform is the goal.

The platforms where naming disagreements cause the most damage are the ones where the design systems team tries to unify behavior, not just names. "Chip on iOS should work like chip on web because they're the same component" is a statement that's going to run into a wall when iOS users encounter web-style interaction patterns on native hardware.

Governance across three platforms

Platform teams are often organized separately. The iOS engineers are on a different team than the web engineers. The Android engineers may be on a different team still, or co-located with iOS engineers on a mobile team that has its own relationship to design.

A design systems team that operates on web is sometimes positioned as owning the design system "platform" with native implementations as downstream ports. This creates friction: the native teams know their platforms in ways the web-focused design systems team doesn't, and their feedback about what's implementable or appropriate on their platform gets filtered through a team that doesn't always have the context to evaluate it.

The version that works is a federated model with a shared design system identity: each platform has implementation ownership with engineers who specialize in that platform, and there's a shared design layer that covers visual language, component naming, and design intent. The shared layer is owned by someone, usually the design systems design lead, and the implementations are owned by people with platform expertise.

The native implementation of the design system that nobody trusts is usually the one that was built by web engineers trying to translate, rather than native engineers building with the platform in mind.