Decision 1
Three token tiers, named for meaning
I built the foundations as Figma variables in three tiers: Primitives (131) hold raw values; Alias (126) maps them into scales and carries the light and dark modes; Semantics (84) name what a value is for, grouped by Surface, Text, Icon, Border and Button. Typography (32) covers body, heading and display sizes, and Motion (9) holds the durations, easings, stagger step and spring used for animation.
The naming mattered most. Semantic names like action, not a colour number, let design and engineering speak the same language, and they kept the system maintainable as it grew.
I considered a single flat palette, which is quicker to set up, but every dark-mode value would have needed its own name, and renaming a colour would have meant touching every screen. Putting modes at the alias tier kept semantic names stable across light and dark, so engineers map a token once and themes switch underneath it.


















