Variable Collections

Variable collections are the top level groups in Figma that separate your tokens by concern so your system does not collapse when requirements change. They enforce the three layer architecture that actually survives production. Primitives collection holds raw values that never reference anything else and never get used directly on layers. Semantic collection carries all the meaning and all the modes for light dark and brand. Component collection scopes tokens to specific UI families and references only semantics. This structure creates a reliable alias chain of exactly three steps. Component tokens point to semantic tokens. Semantic tokens point to primitives. Primitives hold the actual values. Modes live only in the semantic and spacing collections. Light and dark are modes not separate collections. The same goes for brand variations. Scoping rules attach to each collection to prevent misuse. Primitives get scoped to none. Semantics get scoped to their property type. Component tokens get scoped per component family. Follow these rules and your token system stays maintainable as your product scales from one to five brands.

Variable collections are not duplicate palettes for every theme or brand. That approach creates maintenance nightmares that force manual updates across disconnected groups. They are not a new coat of paint on your old styles panel. Styles apply fixed values. Collections create living reference chains that adapt through modes. They are not the place to mix unrelated token types. Color and spacing in one collection means mode changes bleed across categories and create unpredictable results. They are not optional even for small teams with under 10 components. Skip the semantic collection today and you will rebuild everything when the first dark mode ticket arrives tomorrow. They are not a set once tool. The seven common mistakes prove that collections require constant vigilance. Semantic to semantic aliasing breaks mode resolution. Exposed primitives let designers bypass your architecture. Separate collections for brands turn theme switching into a nightmare. Component tokens that point straight to primitives require individual updates for every theme change. No scoping turns your system into suggestions instead of rules. Mixed types in one collection create override conflicts. Meaningless names force translation tables at handoff time.

Take the team at Atlassian in 2024 as a concrete example. After their initial dark mode launch created weeks of rework they rebuilt using four collections. The primitives collection contained 68 base tokens including the full OKLCH color scale with scale based names like neutral-1000 and blue-600 and zero modes attached. The semantic collection used 52 tokens with four modes including light default dark high contrast and their new Jira brand. Every semantic token referenced exactly one primitive and nothing else. The component collection held 180 tokens with names like modal-surface table-header-text and button-filled-bg scoped so tightly that a token for one never appeared in the picker for the other. Their spacing collection used number variables with compact and comfortable modes that updated every auto layout gap and padding value across 400 components instantly. When they acquired a new company with its own brand colors they added one mode to the semantic collection. The component tokens required zero edits. The alias chain for a typical button looked like button-background points to surface-action points to blue-600 which holds the actual OKLCH value. They connected the system to Tokens Studio for export. Style Dictionary transformed the JSON into everything from CSS variables to Android resources and Swift color sets. A webhook automation kept design and code in sync without manual steps. The audit at launch showed zero failures. Every alias chain was exactly three links long. Scoping worked perfectly. The team cut token related bugs by 75 percent in the following quarter. Shopify followed the same playbook for their 2025 product launch with similar results and reported that adding a winter campaign brand took two days instead of two weeks.

Use variable collections when you need to isolate different token types or enforce different scoping rules. Create a primitives collection to hide raw values from designers. Build a semantic collection to control where modes live. Add a component collection to maintain boundaries between UI families. Deploy a spacing collection with number variables so density modes update layouts globally. Set up a strings collection with locale modes to test RTL layouts in Figma before code ships. Add collections for motion or elevation when those tokens need their own rules. Do not use new collections for light and dark themes. Those are modes inside your semantic collection. Do not create separate collections for each brand. Add modes instead unless the brands use completely unrelated primitive values. Do not mix concerns in one collection. The decision tree is simple. If it is a different value of the same thing use a mode. If it is a different thing entirely use a new collection. Follow that rule and your system stays clean. Ignore it and you will spend more time managing variables than designing interfaces. Small teams benefit just as much as large ones. The architecture prevents the small problems that grow into full redesigns. Run the audit after every major release. More than three failed items means your collections have already turned into expensive technical debt.

Variable collections done right turn Figma from a vector tool into the single source of truth for your entire design system.