Design tokens are named design decisions, such as a colour, a spacing step or a type size, stored once as data and then used by your design files, your iOS code and your Android code. On mobile, they stop the same brand blue from drifting into three slightly different blues across Figma, Swift and Kotlin. This guide explains how to structure tokens, which format to choose, how to get them into both platforms, and where they stop helping.
TL;DR
- A design token is a named value (for example
color.action.default) that replaces a hard-coded one like#0055FF. One source feeds design, iOS and Android. - Use three tiers: primitive, semantic and component. Semantic tokens do most of the work for theming and dark mode.
- Store tokens in the W3C Design Tokens format, which reached its first stable version in October 2025, and generate platform code with a build tool.
- Tokens do not fix accessibility by themselves. You still need platform overrides for system settings such as high contrast and dynamic colour.
- Start small: colour, spacing and typography first, with clear naming, before you try to tokenise everything.
Table of Contents
- What design tokens are, and why mobile teams need them
- Tokens vs variables: what is the difference?
- The three-tier structure that keeps tokens manageable
- Choosing a format: the W3C standard
- Getting tokens into iOS and Android
- Theming and dark mode with tokens
- What tokens do not solve
- Our view: start small, treat tokens as a product
- Common mistakes to avoid
- Planning a token system for your app
- How we can help
- FAQ
- Sources
What design tokens are, and why mobile teams need them
A token pairs a raw value with a meaningful name. Instead of telling a developer to use #0D99FF, you tell them to use primary-blue, and that name stays connected to the value wherever it lives. Tokens typically cover colours, typography, spacing, border radii, sizing and elevation.
Mobile makes the case for tokens stronger than the web does, for three reasons.
- Two codebases, at least. Most mobile products ship on iOS and Android, often with a web companion. Each has its own way of declaring colours and sizes. Without a shared source, a brand colour change means editing several files by hand, and somebody misses one.
- Frequent theming. Dark mode is expected on both platforms. Tokens let you swap values per mode without touching components.
- Long product lives. Apps are updated for years. Rebrands, new sub-brands and white-label versions are far cheaper when the values live in one place.
The Figma Learn guide on tokens lists the same benefits for design systems generally: a single source of truth between design and code, easier management as the system scales, and less repeated work.
Tokens vs variables: what is the difference?
People use the two words interchangeably, which causes confusion. The distinction is useful.
- A token is the decision. It is a platform-agnostic name and value that lives in your source of truth, for example
color.surface.default. - A variable is how a tool or language stores that decision. Figma has Variables, the web has CSS custom properties, Android has XML resources or Compose theme values, and iOS has colour assets or Swift constants.
In practice, a token becomes a variable in each environment. The Penpot team puts it well: tokens are the abstract language of design, while CSS variables are one way to implement them in the browser. Mobile is the same: your token is the idea, and a Swift constant or an Android resource is its local expression.
In Figma, Variables are the feature used to implement tokens. Unlike older Styles, they support aliasing, scoping and modes such as light and dark, so a change to a base value flows through without you updating individual elements. That is why we treat Figma Variables as the design-side home of the token set, not as the token system itself.
The three-tier structure that keeps tokens manageable
Most mature systems use three layers. The names vary, but the logic is the same.
| Tier | What it holds | Example | Who should use it |
|---|---|---|---|
| Primitive | Raw values | blue-600: #0055FF | Only other tokens |
| Semantic | Intent | color-action-default → blue-600 | Designers and developers, daily |
| Component | Element-specific | button-bg → color-action-default | Component libraries |
The tier definitions and the advice on theming point the same way: semantic tokens are the main lever for dark and light mode, while component tokens are best kept out of the global library to avoid tight coupling.
Why semantic tokens matter most
If a button uses blue-600 directly, a dark theme means finding every button. If it uses color-action-default, you remap that one token in dark mode. Figma's own writing on the subject argues that decoupling the visual property from its intent lets teams change themes, support multiple brands or adjust accessibility settings globally without touching component code.
Naming: decide early
Poor naming at the start tends to make a system harder to maintain, not easier. A few rules we find work:
- Name by role, not appearance.
color-text-muted, notcolor-grey-light-text. - Keep one pattern: category, property, variant, state. For example
color-action-default-pressed. - Avoid platform words in token names.
spacing-mdtravels;androidPadding16does not. - Write the rule down and keep it where designers and developers both read it.
Choosing a format: the W3C standard
Until recently, every tool had its own token file shape. In October 2025 the W3C Design Tokens Community Group published the first stable version of a vendor-neutral format. It is JSON-based and uses $type, $value and $description keys, so the same file can move between design tools and development workflows.
The file is plain, structured JSON, the same family of data that a JSON-LD schema tool outputs for websites, which is part of why it is easy to validate, diff and review in code.
A minimal token file in this format looks like this:
{
"color": {
"blue": {
"600": { "$type": "color", "$value": "#0055FF" }
},
"action": {
"default": {
"$type": "color",
"$value": "{color.blue.600}",
"$description": "Primary interactive elements"
}
}
}
}
The curly-brace reference is an alias. It is how a semantic token points at a primitive. Standardising on this input format means you can swap tools later without rebuilding the library, which is the sensible way to avoid lock-in.
Getting tokens into iOS and Android
A token file does nothing until it becomes code. The usual route is a build step that reads the JSON and writes native files.
Style Dictionary is the most widely used build tool for this. It parses your tokens and exports them to platforms including iOS, Android and CSS, and it is forward-compatible with the Design Tokens Community Group spec. A typical run produces:
- iOS: Swift constants, or Objective-C headers if you maintain older code.
- Android: XML colour and dimension resources, or Kotlin files for Jetpack Compose.
- Web: CSS custom properties, if you have a web companion.
A walkthrough of a Style Dictionary v4 and DTCG pipeline describes the same outcome: one JSON source transformed into platform-specific assets, which prevents visual drift between platforms.
A sensible pipeline
- Design tokens as Variables in Figma, using the three tiers.
- Export to the DTCG JSON format and commit the file to a repository.
- Build with Style Dictionary in CI, so every change to the file regenerates the iOS and Android output.
- Review the generated diff in a pull request. Designers can read a diff of colour values.
- Publish the generated files as a package or shared module that each app consumes.
The weak point is almost always step 3. Without an automated pipeline, teams fall back on manual syncing and the errors that come with it. Developer buy-in matters as much as the tooling: treat the tokens as a product, and give developers interactive documentation, such as a Storybook page, so they can see and use what exists.
The colour format trap
This one catches experienced teams. Android XML colours use #AARRGGBB, with alpha first, while the web convention is #RRGGBBAA. Share one token source across Android and web without a proper transform and semi-transparent colours come out wrong. Test any token with transparency on a real device early. Overlays, scrims and disabled states are where it shows up first.
Theming and dark mode with tokens
Dark mode is the clearest payoff. Define a light and a dark mode for your semantic colour tokens in Figma, and map them to the matching platform mechanism: asset catalogue appearances on iOS, night resource qualifiers or a dark colour scheme in Compose on Android.
Two habits help:
- Never hard-code a primitive in a component. If a screen references
blue-600, it will not change with the theme. - Test contrast in both modes. A token that passes in light mode may fail in dark. Our article on designing for user preference and dark mode covers the design side in more detail.
What tokens do not solve
Tokens give you consistency. They do not make an app accessible or native-feeling by themselves. Mobile teams still need adaptive themes that follow system-wide settings, and they often need a layer of platform-specific overrides, such as dynamic colour on Android or high-contrast modes on iOS, that sit outside the cross-platform token set.
That is a design decision, not a tooling one. Let the platform win where users expect it to: system fonts that scale with Dynamic Type, touch targets that follow each platform's guidance, and colours that respect the user's settings. Our guide to app accessibility goes through what to check, and the iOS app design guide covers platform conventions you should not tokenise away.
Our view: start small, treat tokens as a product
We have built more than 300 apps, and the pattern is consistent. Teams that struggle with tokens rarely struggle with the technology. They struggle with scope and ownership.
Here is what we recommend.
- Do not aim for all or nothing. Start with colour, spacing and type. Add radii, shadows and motion once the first three are stable.
- Get the hierarchy right before the tooling. A clean three-tier structure on a spreadsheet beats a sophisticated pipeline fed by messy names.
- Give the token set an owner. One designer and one developer who review changes together. Without that, the file decays.
- Pick the format for the long term. The DTCG standard means your tokens outlive any one design tool.
- Decide per project. A single-platform MVP may not need a pipeline at all. A multi-brand retail app or a charity app with several campaign themes almost certainly does. We are technology-agnostic, so we recommend the approach that fits the project, whether that is native, cross-platform or web.
Tokens are one part of a wider design system. If you are weighing how much to invest, our 90-day plan for a mobile design system shows how to phase the work, and our overview of multi-platform development tools helps you choose the stack the tokens will feed.
— Paul
Common mistakes to avoid
| Mistake | What happens | Fix |
|---|---|---|
| Naming by appearance | grey-light becomes dark in dark mode | Name by role |
| Component tokens in the global library | Tight coupling, hard to change | Keep them with the component |
| Manual sync between design and code | Drift, missed updates | Automate with a build step |
| Ignoring alpha channel order | Wrong transparency on Android | Use platform transforms and test on devices |
| Tokenising everything at once | Slow rollout, little adoption | Begin with colour, spacing, type |
| Treating tokens as accessibility | Missed system settings | Add platform overrides and test |
Planning a token system for your app
If you are commissioning an app, tokens should be part of the design brief from the start, not a retrofit. Ask your agency or team these questions:
- Will the app share a brand with a website or other apps?
- Does it need dark mode, high contrast or multiple brand themes?
- Who will maintain the design files and the code after launch?
- Which platforms are in scope now, and which might follow?
The answers decide whether you need a light-touch token set or a full pipeline. Our brand strategies for mobile apps article is a good companion for the brand side of that conversation.
How we can help
Our process runs through Discover, Design, Develop and Deploy. Token structure belongs in Discover and Design, so that what we build in Develop is consistent on every platform from the first release. If you already have an app and suspect it has drifted, our Mobile App Clinics are a way to get an expert review. If you have a new project in mind, tell us about your business app.
FAQ
Are design tokens the same as a design system?
No. Tokens are one layer of a design system. The system also includes components, patterns, guidelines and documentation. Tokens hold the smallest decisions, such as colour and spacing, which the rest of the system builds on.
Do I need Style Dictionary to use design tokens on mobile?
No, but you need some automated step from token file to native code. Style Dictionary is a common choice because it exports to iOS, Android and web. A small app can start with hand-maintained theme files, then add a pipeline when the maintenance burden grows.
How many token tiers should I use?
Three is the usual answer: primitive, semantic and component. If your app is small, primitive and semantic may be enough. Add component tokens only where a component genuinely needs its own overrides.
Can design tokens handle dark mode and accessibility settings?
They handle dark mode very well through modes on semantic tokens. Accessibility is partly covered, but system settings such as high contrast and dynamic colour usually need platform-specific overrides alongside the token set.
Sources
- W3C Design Tokens Community Group: specification reaches first stable version
- Style Dictionary: overview and installation
- Style Dictionary v4 and W3C DTCG pipeline for web, iOS and Android (DEV BAK)
- Figma Learn: the difference between variables and styles
- Figma Learn: tokens, variables and styles
- Figma Blog: the future of design systems is semantic
- Figma: design tokens, how to sync design and code
- Penpot: the developer's guide to design tokens and CSS variables