The power of variables - Primitives vs. Semantics

A well-structured design system helps ensure consistency, scalability, and efficiency across digital products. Two fundamental concepts in design systems that contribute to this structure are primitives and semantic variables. Understanding their role and how they interact can significantly improve the maintainability and flexibility of your design system.

‍

What are primitives?

Primitives are the foundational values in a design system. They are the raw, unopinionated tokens that define fundamental design attributes such as colors, spacing, typography, and border radii. These values do not convey meaning but serve as the basic building blocks, the DNA of your design language. Here is an example:

$brand-100: #007AFF;
$font-family: Inter;
$font-scale-1: 12px;
$spacing-4: 24px;

‍

Primitives provide a single source of truth for core design decisions, allowing easy updates across an entire system without affecting higher-level design choices.

‍

What Are Semantic Variables?

Semantic variables map primitives to meaningful roles within a system. Instead of referring to a color as $brand-500, a semantic variable assigns a functional meaning, such as $color-primary or $background-secondary. These mappings help designers and developers apply styles consistently based on intent rather than raw values. Here is an example:

$text-default: color-neutral-800;
%backgground-primary: brand-500;
$header1: font-family-header;

‍

Using semantic variables allows for contextual adjustments without modifying the underlying primitives. For instance, switching a theme from light to dark mode can be achieved by redefining semantic variables without altering the primitives.

‍

Why use both?

Separating primitives from semantic variables brings several benefits:

1. Scalability – Easily extend the design system by modifying semantic mappings without disrupting core values.
2. Consistency – Ensures uniform application of styles across different components and pages.
3. Theming Flexibility – Enables quick adaptation to different themes (e.g., light mode, dark mode, brand variants) with minimal effort.
4. Maintainability – Reduces the risk of inconsistencies when updating design attributes.

‍

Conclusion

Understanding and leveraging the distinction between primitives and semantic variables in a design system ensures greater flexibility, maintainability, and scalability. By carefully structuring your design tokens, you create a system that is adaptable to evolving needs while maintaining a consistent visual identity.

By embracing this methodology, teams can streamline their workflows and create more resilient design systems that stand the test of time.