figma-tokens.mdx

title	Figma tokens
description	Understand the link between Figma tokens and our utilities.
aliases	/docs/utilities/figma-tokens/ /docs/getting-started/figma-tokens/ /docs/[[config:docs_version]]/getting-started/figma-tokens/
toc	true

{/* TODO: Getting-started, foundation ? */}

import { getConfig } from '@libs/config';

Examples

When you browse the Figma design, you may encounter some tokens that are defined as ouds/**. You’ll find here some examples of how to use them in your codebase.

Using our utilities

When a token is used on Figma side, you should check if there is a utility class available for it. If there is, you should use it. This way, you will be sure that the token is applied correctly, and that it will be updated automatically when the token value changes.

| On Figma I see | Used Figma token | Utility classes | Utility link | | -------------- | ---------- | --------------- | ------------ | | A color for a background, a border or a content, used depending on a user action `ouds/color/action/*`. | `ouds/color/action/pressed` | `--bs-color-action-pressed` | This case is a bit special and you should [use a CSS variable](#using-css-variables). | {/* TODO: Change once the color palette has been changed or doc about CSS variables has been developed */ } | A background color using a standard token `ouds/color/{bg\|surface}/*`. | `ouds/color/bg/secondary`
`ouds/color/surface/brand-primary` | `.bg-secondary`
`.bg-surface-brand-primary` | [Background]([[docsref:/utilities/background]]) | | A border using a standard token `ouds/color/border/*` or `ouds/border/*`. | `ouds/color/border/default`
`ouds/border/radius/small`
`ouds/border/width/thick` | `.border-default`
`.rounded-small`
`.border-thick` | [Border]([[docsref:/utilities/border]]) | | A content using a standard color token `ouds/color/content/*`. | `ouds/color/content/muted`
`ouds/color/content/on/brand-primary` | `.text-muted`
`.text-on-brand-primary` | [Color]([[docsref:/utilities/color]]) | | An opacity using a standard token `ouds/opacity/*`. Be careful where the token is applied. | `ouds/opacity/medium` | `.opacity-medium` | [Opacity]([[docsref:/utilities/opacity]]) | | A shadow using an aggregated reference. Having a token shaped like `ouds/elevation/*` is a good sign that this reference has been used or should have been. | `ouds/elevation/**/emphasized` | `.shadow-emphasized` | [Shadow]([[docsref:/utilities/shadow]]) | | A spacing using a standard token `ouds/space/{scaled\|fixed}/*` or `ouds/space/{column-gap\|row-gap}/*`. | `ouds/space/scaled/2xlarge`
`ouds/space/fixed/medium`
`ouds/space/row-gap/none` | `.p-scaled-2xlarge`
`.p-medium`
`.row-gap-none` | [Spacing]([[docsref:/utilities/spacing]]) | | A text using an aggregated reference. Having a token shaped like `ouds/font/*` or `font-ref/size/weight` is a good sign that this reference has been used or should have been. | `ouds/font/**/body-large`
`Body/Large/Strong` | `.fs-bl`
`.fs-bl.fw-bold` | [Typography]([[docsref:/utilities/text#font-size]]) | | A spacing using a grid token `ouds/grid/*` | `ouds/grid/column-gap`
`ouds/grid/margin` | `.gap-gridgap`
`.px-gridmargin` | [Spacing]([[docsref:/utilities/spacing#grid-measures]]) |

Using CSS variables

This method is not the preferred one. You should only use it if there is no utility class available for the token you want to use, or if you need to apply the token on a pseudo element, or even on a custom component. If you use this method, you will need to check that the token value is applied correctly, and that it will be updated automatically when the token value changes.

| On Figma I see | Used Figma token | Associated variables | | -------------- | ---------- | --------------- | | A background color using a standard token `ouds/color/*`. | `ouds/color/bg/secondary`
`ouds/color/surface/brand-primary`
`ouds/color/action/hover` | `--bs-color-bg-secondary`
`--bs-color-surface-brand-primary`
`--bs-color-action-hover` | | A border using a standard token `ouds/color/border/*` or `ouds/border/*`. | `ouds/color/border/default`
`ouds/border/radius/small`
`ouds/border/width/thick` | `--bs-color-border-default`
`$ouds-border-radius-small`
`$ouds-border-width-thick` | | A content using a standard color token `ouds/color/content/*`. | `ouds/color/content/muted`
`ouds/color/content/on/brand-primary`
`ouds/color/content/on/action/hover` | `--bs-color-content-muted`
`--bs-color-content-on-brand-primary`
`--bs-color-content-on-action-hover` | | An opacity using a standard token `ouds/opacity/*`. Be careful where the token is applied. | `ouds/opacity/medium` | `$ouds-opacity-medium` | | A shadow using an aggregated reference. Having a token shaped like `ouds/elevation/*` is a good sign that this reference has been used or should have been. | `ouds/elevation/**/emphasized` | `$ouds-elevation-emphasized` | | A spacing using a standard token `ouds/space/{scaled\|fixed}/*` or `ouds/space/{column-gap\|row-gap}/*`. | `ouds/space/scaled/2xlarge`
`ouds/space/fixed/medium`
`ouds/space/row-gap/none` | `--bs-space-scaled-2xlarge`
`$ouds-space-fixed-medium`
`$ouds-space-row-gap-none` | | A text using an aggregated reference. Having a token shaped like `ouds/font/*` or `font-ref/size/weight` is a good sign that this reference has been used or should have been. | `ouds/font/**/body-large`
`Body/Large/Strong` | `get-font-size("body-large")`
`$ouds-font-weight-web-body-strong`
As you can see, this one is a bit special and calls a mixin [`get-font-size()`]([[docsref:/foundation/typography/#text-style-for-custom-components]]). | | A spacing using a grid token `ouds/grid/*` | `ouds/grid/column-gap`
`ouds/grid/margin` | `--bs-grid-gap`
`--bs-grid-margin` |

Figma tokens

Figma tokens (or design tokens) are really important in the comprehension between designers and developers. They allow to have a common language and a common understanding of the design system. They also allow to have a single source of truth for the design system, which is really important for the maintenance and the evolution. We built them in a three-tier architecture: raw scope, semantic scope, and component scope. Read more about the design tokens.

We provide a file to import them all: `@ouds/web-[[config:brand]]/scss/tokens/_index.scss`. So in a Sass context `@import "@ouds/web-[[config:brand]]/scss/tokens";` will import all the tokens.

Only semantic tokens and composite tokens are meant to be used directly in projects, and even for them, you should prefer using our utilities when possible. The others are meant to be used by other tokens or by our components.

Raw tokens

The @ouds/web-[[config:brand]]/scss/tokens/_raw.scss file aggregates all basic 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-[[config:brand]]/scss/tokens/_semantic.scss file contains all the semantic tokens. Unlike raw tokens, these tokens are intended to be used directly in projects (Be careful, many of them are already available in our utilities). They are built on raw tokens, assigning them semantic meaning through media queries or specific contexts. Most of these tokens are already applied either in utilities or directly within our components. Most of colors are built differently, using CSS variables and changing automatically depending on the context of use.

Semantic colors with CSS variables

The @ouds/web-[[config:brand]]/scss/tokens/_semantic-colors-custom-props.scss file contains all the usable semantic color tokens. They are built on semantic tokens, assigning them mode theming through media queries or specific contexts. Most of these tokens are already applied either in utilities or directly within our components. We also provide equivalence for Sass variables.

Composite tokens

The @ouds/web-[[config:brand]]/scss/tokens/_composite.scss file contains all the composite tokens. They are built (manually until now) on top of semantic tokens, they usually are an aggregation of several tokens. These tokens are already applied either in utilities or directly within our components. It concerns at least shadows and typography tokens.

Component tokens

The @ouds/web-[[config:brand]]/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 directly in your codebase, as they are defined for a specific component.

General usage

How do we build and use these tokens ?

Sass variables

Almost each token that is provided by the design, and that can be needed in any context is referenced in our codebase as a Sass variable. As explained in Figma tokens section, not all tokens should be used directly in your codebase.

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

• Raw tokens: $core-{ouds|[[config:brand]]}-{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 variable or to the utilities instead.
  • Colors and elevation colors have also have their version using their suffix *-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 Figma 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 on our side.

Utilities

Our utilities are built on top of our semantic tokens and our composite tokens. They are the preferred way to use our tokens. When a token is used on Figma side, you should check if there is a utility class available for it.

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

• Raw tokens: No raw token is available as a utility.
• Semantic tokens: Semantic tokens are all available as utilities.
• Composite tokens: Composite tokens are all available as utilities.
• Component tokens: No component token is available as a utility.