Understanding the Variable Setup

Before you start building layouts and tweaking components, it helps to understand how we’ve structured our variables. Our variable setup is designed to scale, stay organized, and make swapping themes or brands feel like magic. Here’s a quick intro to the three core collections you’ll see: Brand, Alias, and Mapped.

Brand Collection: The Source of Truth

The Brand Collection holds all the raw, foundational values that define our visual identity. These are the actual hex codes, spacing values, type ramp numbers, and other design constants.

• Examples: #000000 for Black, 16px for base spacing, 12 for base font size.

• These values don’t reference anything else—they are the root variables.

• This is the only collection where we define hard values.

📝 Think of it as your design DNA—raw, unchanging, and brand-specific.

Alias Collection: Named and Ready to Use

The Alias Collection takes the raw values from the Brand Collection and gives them meaningful, reusable names.

• Examples: Primary/100

• Instead of using #000000, you’d use Primary/100—which maps to that hex.

• Aliases help maintain clarity and consistency, especially across different brands or themes.

📝 This is where things start to make sense for real-life usage

Mapped Collection: Context-Aware Variables

The Mapped Collection connects Alias variables to specific component or UI contexts.

• Examples: Surface/default, Border/error

• These are the most semantic and specific—they answer the question: Where is this used?

• By mapping aliases to components, we make it easy to theme or update specific UI parts without changing the underlying values.

📝 This is the layer that gives your components "design smarts"—it adapts and scales beautifully.

Now that you understand the stack, you're ready to use variables like a pro—and maybe even teach someone else how they work.

👨‍🔬 Variables aren't just for devs anymore.