Design variables are fundamental, reusable key-value pairs that represent specific design attributes such as color, typography, or spacing. They ensure consistency and streamline development across all platforms. Variables must be preferred over plain values to e.g. ensure that colors adapt automatically between light and dark mode or spacings are updated depending on the selected density.
Developers and designers
Design variables are used by both developers and designers to ensure customizability while maintaining a unified visual identity.
Copy link to headline:Architecture
Our variable system uses a three-layer architecture though only the semantic variables are relevant / accessed directly during application development.
- Global variables
Global variables provide a context-free foundation for the design language by systematically storing plain values — such as colors and spacing. They are NOT intended to be used directly in custom components or applications.
- Semantic variablesused by applications
Semantic variables map global variables to fundamental contexts/ use cases and automatically adapt between light and dark mode. They allow developers and designers to build (custom) components with a clear usage intent and guaranteed theme switching.
- Component variables
Component variables are restricted to the design system maintainers to manage unique overrides and exceptions within specific components, such as a primary button's hover state. They are NOT intended to be used directly in custom components or applications.
Global variable
Semantic variable
Copy link to headline:Usage
For a full overview of available variables, please refer to the following pages:
We use a strict naming convention for all variables to ensure clarity and avoid conflicts with custom application variables. Therefore, all our variables are prefixed with "onyx". Due to technical reasons, variables are separated by dashes in development and by slashes in Figma - meaning these usages refer to the same variable: --onyx-color-text-icons-neutral-intense (development) and onyx/color/text/icons/neutral/intense (Figma).
All our variables are represented by CSS custom properties(opens in a new tab) so they can easily be used in CSS using the var()(opens in a new tab) function: