Variables in a single file? Easy.
Variables that need to work across multiple teams, brands, or design systems? That’s where things get interesting.
If your tokens are starting to feel stretched — or you’re duplicating work across files — it’s probably time to scale up with intent. This chapter will help you structure your setup to avoid chaos, reduce maintenance, and keep everyone (mostly) sane.
🧠 One file or many? Start with a strategy
Before you do anything, ask yourself:
- Are all teams using the same tokens?
- Are you supporting multiple brands or platforms?
- Do different teams need control over their own tokens?
Your answers will point you toward one of two paths:
**
1️⃣ Option 1: Centralized variable library**
Good for:
- Small teams
- One brand, one product
- Simple shared decision-making
How it looks:
- One file for all variables (e.g. Core Tokens)
- Collections grouped by type (Colors, Spacing, Radius)
- Modes like light and dark managed within those collections
This keeps things simple, but it can get crowded fast as complexity grows.
**
2️⃣Option 2: Distributed libraries**
Good for:
- Multi-brand or multi-product systems
- Larger orgs with specialized teams
- More structured governance
How it looks:
- Core Library → shared base tokens like spacing, border radius, and neutral colors
- Brand A and Brand B libraries → theme-specific tokens (e.g. brand colors)
- Optional overrides per team or component library (e.g. Team X Overrides)
This setup gives you flexibility and separation — but requires a bit more coordination.
🧱 How to organize collections across libraries
| Collection name | What it’s for | Lives in |
|---|---|---|
| core/color/neutral | Shared across all brands/themes | Core Library |
| theme/light | Light mode values | Brand or Theme Library |
| brand-a/color | Brand-specific primary/accent tones | Brand A Library |
| spacing/base | Standard spacing scale | Core Library |
🔁 Rule of thumb: Reuse > Redefine. Let libraries inherit from one another where possible — don’t reinvent the wheel in every file.
✅ Tips for managing libraries like a pro
1. Mirror structure across brands
If Brand A uses color/primary/500, make sure Brand B does too. Same pattern, different values. That way, switching themes is painless.
2. Assign owners
Every library needs a responsible human (or team). Without one, things break — and no one knows who to ask.
3. Communicate changes
Even small edits can cause downstream issues. Version your tokens, keep a changelog, and let people know what’s new (and why).
4. Include a “how to use this” note
Every library should have a short explanation:
- What’s inside
- Who it’s for
- How to contribute or request changes
Think of it like onboarding for your variables.
TL;DR: Don’t just scale — scale smart
When your system grows beyond a single file, organization becomes everything. With a thoughtful library structure and clear ownership, you’ll be able to support more teams, more brands, and more complexity — without losing control.