Variables
How we create and manage variables
Last updated
How we create and manage variables
Last updated
The Base System provides variables for colors, typography, structure and elements, offering a robust starting point for your designs. While these variables serve as a foundation, there's no one-size-fits-all approach—you’re encouraged to add, remove, or customize them to suit your specific project needs.
Variables are divided into four variable collections.
Colors are separated into two distinct categories: Primitive Color Variables and Semantic Color Variables.
Primitive variables are the foundational, low-level design tokens that represent the raw values in your design system. These variables are not tied to specific components or use cases—they define the "building blocks" of your design. They are typically defined by their exact color name or function, such as blue-500, brand-blue, or turquoise. They don’t carry any specific meaning or context by themselves; they just represent colors.
Primitives ensure that the same values are used across the system (e.g., always the same shade of blue for "primary"). If you need to adjust a raw value, it propagates through the entire system.
By default the starter project includes a brand color and 100-900 scale for neutral colors.
Another example of how you might structure primitive colors
Semantic variables represent the applied or contextual meaning of a primitive variable in your project. They are higher-level variables that map to primitive values but are named based on their purpose or usage in the design. Semantic variables explain why a value is used, making the intent of the design clearer.
A clear separation of primitives and semantics makes it easier to manage and update designs over time. They allow different components or themes to use the same primitive values but in different ways. Semantic variables allow for quick updates to context-specific design elements as you can re-map the semantics to new values without disrupting the core design.
Semantic variable names begin with the category they belong to (e.g Background Color, Text Color, Radius). Adding the category to the start of the name makes the variables being used easier to identify at a glance in the styles panel.
When creating semantic variables, it's important to focus on their functional meaning rather than the specific color they represent. For example, the Base System used abstracted values like Primary, Secondary, Tertiary etc. Here is how we would interpret these values.
Primary is your default color, used 'primarily' throughout your project. For example, 'Background Primary' would be your default page background.
Secondary is used for slight contrast against the default background.
Background Tertiary provides a subtle, understated backdrop for less important content in cases where background-secondary still feels too strong or prominent.
Background Brand reflects the brand’s primary or accent color
You are welcome to change these names to whatever makes sense to you. For example:
Muted
Inverse
Accent
Default
Danger
Success
Disabled
