CONCEPT Cited by 1 source
Design-token cross-platform theming¶
Design-token cross-platform theming is the approach of defining styling variables (colours, font sizes, border widths, spacing, etc.) once as platform-agnostic tokens and letting a build step resolve them to platform-appropriate values: CSS variables on web, native style primitives on iOS/Android.
The canonical implementation in the React Native +
cross-platform-UI world is StyleX. Zalando's
ZDS tokens package
(@zds/tokens/tokens.stylex) is its production case.
Why tokens, not platform-specific styles¶
Writing styles directly per platform (hex colours in Swift, hex colours in Kotlin, hex colours in CSS) guarantees drift:
- Design changes have to happen in three places.
- Designers can't see all three at once, so inconsistency accumulates silently.
- Cross-platform parity is not enforceable.
Tokens invert this:
- One source of truth — the token registry. A colour change happens in one place.
- Platform-appropriate resolution at build time.
- Theming and dark mode fall out for free (tokens can have light/dark variants).
- Cross-platform parity is guaranteed by construction.
How StyleX implements it¶
StyleX tokens are typed, module-scoped variables:
import { tokens } from "@zds/tokens/tokens.stylex";
const styles = css.create({
primaryStyle: {
backgroundColor: tokens.colorBackgroundDefault,
borderWidth: tokens.borderWidthS,
borderColor: tokens.colorBorderSecondary,
},
});
The StyleX build step rewrites these references:
- Web: to CSS custom properties in a compiled static CSS
file.
tokens.colorBackgroundDefaultbecomesvar(--color-background-default). - Native: to the platform-native value (RGBA, points, etc.) resolved at build/runtime against the current theme.
Pair with cross-platform UI substrate¶
Tokens on their own aren't enough — you also need a cross-platform UI substrate that consumes them. Zalando pairs ZDS tokens with react-strict-dom for the UI elements and Metro's platform-specific file resolution for the per-platform escape hatches. All three together form the cross-platform UI stack.
Seen in¶
- sources/2025-10-02-zalando-accelerating-mobile-app-development-with-rendering-engine-and-react-native —
canonical wiki first source. Zalando's ZDS tokens are shown
in use in a
BaseMessage/DefaultMessagecomponent; tokens resolve to platform-appropriate values across web + iOS + Android.