Tokens

Design tokens

Design tokens (from Figma) provide a shared language and mutual understanding of the design system between designers and developers. They also serve as a single source of truth for the design system, which is crucial for its maintenance and evolution. We have structured them into a three-tier architecture: raw scope, semantic scope, and component scope. For more information, please refer to the design guidelines on design tokens.

Raw tokens

The @ouds/web-orange/scss/tokens/_raw.scss file aggregates all raw tokens. While these tokens don’t carry semantic meaning and aren’t meant to be used directly in projects, they are the foundation of the Orange Unified Design System. Their primary purpose is to be used by semantic tokens, and occasionally, by component tokens.

Semantic tokens

The @ouds/web-orange/scss/tokens/_semantic.scss file contains all the semantic tokens. Unlike raw tokens, these tokens can be used directly in projects (check the cheatsheet for their recommended usage). They are derived from raw tokens and add semantic meaning through specific contexts. Most of these tokens are available in our utilities or used within our components. The colors tokens should not be used directly but via their custom properties version, see below.

Semantic colors with CSS variables

The @ouds/web-orange/scss/tokens/_semantic-colors-custom-props.scss file contains all the usable semantic color tokens custom properties. They are built on semantic tokens switching the color depending on the color mode. Most of these tokens are already used in utilities or directly within our components. We also provide equivalence for Sass variables. For more information, check out our colors documentation.

Composite tokens

The @ouds/web-orange/scss/tokens/_composite.scss file contains all the composite tokens. They are aggregations of several semantic tokens or brand-specific icons. These tokens are already used either in utilities or directly within our components. Apart from the icons, these are shadows tokens and typographic definition.

Component tokens

The @ouds/web-orange/scss/tokens/_component.scss file is dedicated to component tokens. These tokens are used exclusively within components, often relying on semantic tokens and composite tokens, though they may occasionally reference raw tokens. Unless you’re sure of what you’re doing, you should avoid using these tokens in your codebase, as they are defined for a specific component.

Variables

Sass variables

Almost every token provided in the design specification and potentially needed in various contexts is represented in our codebase as a Sass variable. However, as explained in the the previous section, not all tokens should be used directly in your codebase.

We build our Sass variables following the architecture of the design tokens:

• Raw tokens: $core-{ouds|orange}-{border|color|dimension|effect|elevation|font|grid|opacity}-{token-name}.
  • They shouldn’t be used.
  • Ex: core/ouds/color/functional/black becomes $core-ouds-color-functional-black.
• Semantic tokens: $ouds-{border|color|dimension|effect|elevation|font|grid|opacity|size|space}-{token-name}.
  • Our scaled spacing, font and icon sizes tokens don’t have a Sass variable, please refer to the CSS variables or to the utilities instead.
  • Colors and elevation colors also have their versions using suffixes *-light and *-dark.
  • Ex: ouds/color/content/on/brand-primary becomes $ouds-color-content-on-brand-primary, ouds/elevation/blur/emphasized becomes $ouds-elevation-blur-emphasized.
• Composite tokens: $ouds-elevation-{token-name}
  • Ex: ouds/elevation/**/emphasized are aggregated via $ouds-elevation-emphasized.
  • Our font tokens are aggregated in a mixin get-font-size() that takes the font reference name as a parameter. So ouds/font/**/body-large are aggregated via get-font-size("body-large").
• Component tokens: $ouds-{component-name}-{token-name}
  • Ex: ouds/button/color/bg/minimal/hover becomes $ouds-button-color-bg-minimal-hover.

CSS variables

All the colors and the tokens suffixed by *-mobile, *-tablet, or *-desktop are available as CSS variables.

We build our CSS variables following the architecture of the design tokens:

• Raw tokens: We don’t have any raw token transformed into a CSS variable.
• Semantic tokens: --bs-{color|elevation|font|icon|space}-{token-name}.
  • Our scaled spacing are only declared as CSS variables --bs-space-scaled-{size}. It’s equivalent to ouds/space/scaled/{size} in Figma. Prefer using our utilities when possible.
  • Our colors and elevation colors are declared as CSS variables --bs-color-{token-name}. It’s equivalent to ouds/color/{token-name} in Figma. Prefer using our utilities when possible.
  • Our icon sizes are declared as CSS variables --bs-icon-{size}. It’s equivalent to ouds/size/icon/{size} in Figma. Prefer using our utilities when possible.
  • Our font tokens are aggregated in a mixin get-font-size() that takes the font reference name as a parameter. So ouds/font/**/body-large are aggregated via get-font-size("body-large"). Don’t use our CSS variables for font alone.
• Composite tokens: We don’t have any composite token transformed into a CSS variable, but they are available as Sass variables.
• Component tokens: We don’t have any component token transformed into a CSS variable. The only CSS variables that we have for components are the ones that we need to build the component internally.