Back to Blog

Token Architecture for People Who Care About the Details

Hosna Mamouri / / 6 min read

There is a version of Unarchived that gets built without a design system. It probably looks fine for the first three screens but then gets messy pretty quickly. After already designing without a design system in previous projects, I vowed to never make that mistake again.

Unarchived is a high fashion iOS app with a counterculture editorial aesthetic. White background by default, warm off-white text in dark mode, deep editorial red as the single accent, League Gothic condensed headlines, zero rounded corners. The visual direction was clear from the start. What took more deliberate thinking was building the system underneath it properly.

What a design system actually is

Not a Figma file. Not a component library. A design system is a shared decision-making framework. The rules you agree on so you stop reinventing the same choices. Think of it like a constitution versus a law. The system is the constitution. Every button, card and filter tab is a law derived from it. The goal is not consistency for its own sake. The goal is to stop spending cognitive energy on decisions that have already been made.

The surprising thing is how old the idea is. Dieter Rams at Braun in the 1950s was designing entire product lines around a single unified visual language. Apple formalised it in 1984 with the Macintosh Human Interface Guidelines. Brad Frost named Atomic Design in 2013. Google shipped Material Design in 2014. The problem is older than most of the tools we use to solve it.

Three tiers and why the structure is not negotiable

The first breakthrough is the token. Instead of writing #8B0000 everywhere, you name it red-800. Change it once, it updates everywhere. But this is still primitive. A token with a name but no decision encoded in it means two people will still disagree about whether a border should use red-700 or red-800. The name carries no intent.

The real insight is that you need three tiers. Think of it like building a language from scratch. Tier 1 tokens are the alphabet. Raw, meaningless alone. gray-950 is a letter. Tier 2 gives them words, each one carrying intent but no location. color/background/primary tells you exactly what it does without telling you where. Tier 3 turns those words into sentences spoken by specific components. card/bg pointing to color/background/surface is a complete thought. Scoped, intentional, unambiguous.

When you change a letter at the source, every word and sentence built from it updates automatically. The system does not just store decisions. It speaks them.

This is also where collaboration stops being a conversation about taste and starts being a conversation about structure. The reason designers and developers spend so long negotiating colours, spacing and component behaviour is not because they disagree. It is because they are working without a shared vocabulary. Tokens give both sides the same dictionary. When a developer asks why a border is this shade and not that one, the answer is not an opinion. It is a token name with a documented chain behind it. The decision was already made, recorded and accessible to everyone. That is not a workflow improvement. That is a fundamentally different way of working.

The token chain for Unarchived, from raw value to component decision:

Tier 1 — Primitives Tier 2 — Semantic Tier 3 — Component gray-0 #FFFFFF gray-950 #0A0A0A gray-800 #1A1A1A red-800 #8B0000 color/background/primary Light: gray-0 / Dark: gray-950 color/background/surface Light: gray-0 / Dark: gray-800 color/accent/default Light: red-800 / Dark: red-800 card/bg → color/background/surface filter-tab/indicator → color/accent/default card/save-active → color/accent/default Dashed arrows show the alias chain. Change red-800 in Tier 1 and it flows through every component that references it.

How the aesthetic shaped the token decisions

This is where it gets interesting. The visual identity of Unarchived did not just inform the component design. It shaped the token decisions directly.

Take radius. Unarchived uses zero rounded corners throughout. Sharp edges, completely intentional. So radius/sharp with a value of 0 is the token every component points to. That is not a limitation of the system. That is the aesthetic encoded into the architecture. The system reflects the design philosophy at the structural level, not just the visual one.

Spacing followed the same logic. A tight editorial grid with deliberate breathing room meant the spacing scale needed restraint. Eight values, space-xs through space-5xl, and the discipline not to add more just because the option exists. Naming matters here too. radius/sharp describes a characteristic and a reason. A token name that requires explanation is a small recurring tax on every decision made after it.

What comes next

The Figma system is complete. Every tier is in place, component tokens are mapped, light and dark modes work correctly across all four screens. The next phase is building each SwiftUI component to match it exactly. card/bg in Figma becomes cardBg in Swift. The design and the code share the same vocabulary.

A design system is not a design artifact. It is a communication protocol between everyone who touches the product. Tokens are the vocabulary. The three tier architecture is the grammar. When the people building a product speak the same language, they spend less time translating intentions and more time executing them. Getting that right from the beginning, on a project at this scale, is the whole point.