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

‍

🔁 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.

‍