Teams love component libraries. But components without tokens become decoration — pretty buttons that drift apart across platforms.
Tokens are the contract between design and engineering.
Define once, map everywhere
Color roles, type scale, spacing units, radius, elevation, and motion duration — shared by every surface:
- WordPress marketing sites via Tailwind config
- React dashboards via CSS variables
- Flutter apps via ThemeData
The names stay identical so designers and developers speak one language.
Incremental adoption
- Primitives — color, type, space
- Core components — buttons, inputs, cards
- Patterns — forms, tables, empty states
Each increment reduces design review time and QA surprises — especially when Arabic RTL layouts must mirror English LTR without breaking alignment. The payoff shows in velocity: new features ship faster, white-label variants become cheaper, and brand refreshes propagate everywhere from a single source.
Naming that survives three platforms
Prefer role-based names (color.text.muted, space.3) over raw values (gray-400, 12px). Raw values tempt one-off overrides; roles force intent. When Flutter, web, and WordPress disagree, the role name is the meeting agenda — not a screenshot quarrel.
- Document dark-mode aliases only where product needs them
- Keep motion durations in the same token file as color
- Ban hard-coded hex in PRs once tokens exist for that role
- Review token PRs like API contracts — breaking renames need a migration note
How we keep tokens honest in QA
Visual regression alone is not enough. We spot-check that production CSS variables resolve to the token file, that Flutter ThemeData pulls the same roles, and that marketing pages do not silently reintroduce hex in a one-off section. Drift is a process failure, not a design failure.
iFynx takeaway
Ship tokens before you ship a second platform. Components will follow; without tokens they will fork — and bilingual products will fork twice.
Acceptance checklist for cross-platform tokens
A token file is not a design system until web, iOS, and Android resolve the same semantic names to predictable values under dark mode, large type, and RTL.
- Every semantic token (color.bg.surface, space.stack.md, type.label.sm) has a documented mapping table for CSS, Swift, and Kotlin — not tribal knowledge
- Primitive → semantic → component layers are enforced in CI; PRs that skip a layer fail the token lint
- Dark mode and high-contrast aliases are first-class, not a late theme override
- Arabic RTL does not invent parallel token names; spacing and radius stay shared while typography scale may carry locale-aware line-height
- Figma variables and code tokens share the same IDs; a weekly drift report lists orphans on either side
- A kill switch can freeze a broken token publish without rolling back the whole app binary
If design and engineering cannot answer “what is space.stack.md on Android today?” in under a minute, the system is not ready.
UX and eng pitfalls that explode token debt
- Teams ship hard-coded hex in hotfixes and never backfill tokens — drift becomes permanent
- Marketing sites invent a parallel palette that looks “on brand” but breaks accessibility contrast
- Component libraries reference primitives directly, so a brand refresh rewrites hundreds of files
- Mobile and web rename the same concept differently (padding vs inset), so bilingual docs disagree
- Token PRs ship without visual regression snapshots for Arabic and English screens
Acceptance should include a chaos hour: rename one primitive, republish, and prove every platform picks up the change without silent fallbacks.
Ops playbook: four weeks to boring token hygiene
- Week 1: inventory primitives vs semantics; kill unused aliases; publish the mapping table
- Week 2: wire token lint into CI for web + one mobile client; block hard-coded colors in new code
- Week 3: bilingual visual QA pack for core components (button, field, card, modal) in light/dark/RTL
- Week 4: ownership runbook — who publishes, who reviews drift, how to freeze a bad release
- Success metric: zero new hard-coded brand colors in PRs for two consecutive sprints
Tokens win when they are duller than the demos — predictable, auditable, and shared.
MENA product notes for token platforms
Studios shipping Gulf and Levant products hit Arabic typography, density, and brand dual-language constraints early.
- Budget line-height and letter-spacing tokens for Arabic display sizes — Latin defaults often clip diacritics
- Keep brand mark clearspace tokens identical in AR/EN so co-marketing assets do not fight layout
- Document which tokens are market-specific (e.g. payment badge colors) versus global
- Treat accessibility contrast as a release gate for both languages, not an English-only checklist
One source of truth beats three “almost the same” palettes.
Related reading
- Figma Code Layers and Specs (Config India, 15 Oct 2026): A Hands-On Checklist for Arabic RTL Products — Design-to-Code Handoff, Specs for AI Coding Agents, and the Figma MCP in Claude Code and Cursor
- Noto 3D emoji: design-system rollout lessons
- Material 3 × Liquid Glass for fintech DS
- Landing pages that convert
- All featured articles
New to the topic? Start with what is a design system.
