Token Layers

Token layers form the real backbone of design systems that do not collapse six months after launch. They organize your design decisions into three distinct levels that keep raw values separate from meaning and from specific usage. The foundation is global tokens. These store the primitive raw values like color-blue-500 as #2563eb spacing-16 as 16px and font-size-xl as 1.25rem. These tokens define your palettes scales and constants but you never use them directly in production code or designs. They exist to be referenced by higher layers. Semantic tokens sit in the middle layer. They add human meaning to the raw numbers. color-primary references the global blue. color-text-secondary pulls from gray. background-danger uses red. This is where the power lives for theming. Update a semantic token and every button icon and card updates instantly across light mode dark mode and brand variations. The final layer is component tokens. They bind everything to specific interface elements. button-background-primary uses the semantic color-primary. card-shadow uses semantic shadow-medium. This allows fine tuning. Maybe your primary button needs a slightly different treatment than other primary elements. The component layer lets you adjust without polluting the semantic namespace. The connections create a cascade. Tweak a global color and it flows up through semantics and components like a well designed river system.

Token layers are not a simple color palette slapped into Figma. They are not flat lists of variables with no hierarchy. They are not something you add after your components are built and they sure are not optional for teams serious about consistency. Too many teams build component libraries first then slap on tokens as an afterthought like the article warns against in Failure 4. That is backwards and it shows in the final product. The layers are what make change safe and fast. Ignore them and your system becomes a brittle collection of one off decisions that nobody trusts.

Look at Shopify Polaris for a concrete example that actually worked. When they first released the system in 2016 they invested heavily in token layers from day one. Their global tokens defined an 8 point spacing scale and a precise color palette with nine shades of blue. Semantic tokens mapped those to roles like interactive-primary surface and border. Component tokens connected the dots for their data visualizations forms navigation and those famous Polaris data tables. Fast forward to their 2022 brand refresh. Instead of months of painful updates they changed a handful of semantic token values in their token package. The update propagated to their entire ecosystem of tools partner apps and admin interfaces. No designer had to update 50 Figma files. No engineer chased down stray hex codes in the codebase. The layers handled the heavy lifting while the team focused on new features. GitHub took a similar path with Primer. Their 2020 token overhaul introduced full layer support that enabled the dark theme launch the following year. Global tokens held the base values. Semantic tokens managed theme switching with CSS variables that swapped on a class. Component tokens kept their unique UI elements like the diff viewer pull request timeline and octicons consistent. IBM Carbon follows the same playbook with even more granularity including dedicated motion tokens for easing curves that every team at IBM references through the layered structure.

Roll out token layers when your team hits the pain of inconsistent spacing and color usage that the article describes. Use them before you create your first reusable component. They become indispensable when you need to support dark mode multiple brands or when multiple squads contribute to the same codebase. The structure prevents the forking problem that kills most systems. Define your globals first then semantics then components just like the table in the main article shows. Start with colors spacing typography border radius shadows and motion. Tools like Tokens Studio for Figma and Style Dictionary turn these layers into CSS Android iOS and documentation output with one command. Set up the connections once and reap the benefits for years. Reach for them the moment your standups include arguments about whether a button should be blue or slate.

Avoid token layers on tiny projects where you are the only consumer. A three person team building a simple SaaS dashboard can survive with basic CSS variables. Do not bother with full component token layers until your interface has at least a dozen recurring patterns that need consistency. Overbuilding too early leads to the perfection paralysis failure mode the article calls out. If your organization lacks dedicated ownership for the system the layers will fall out of date quickly and become more hindrance than help. Start small with colors spacing and typography as the article recommends. Grow the layers as real needs emerge from product teams instead of theoretical perfection.

Nail your token layers or watch your design system become yesterday's unused Figma library.