feat(docs): add Figma Tokens page

scss/_maps.scss

@@ -147,7 +147,7 @@ $ouds-icon-sizes: ("small", "medium", "large") !default;
 // scss-docs-start ouds-maps-opacities
 $ouds-opacities: (
   "invisible":  $ouds-opacity-invisible,
-  "weakest":     $ouds-opacity-weakest,
+  "weakest":    $ouds-opacity-weakest,
   "weaker":     $ouds-opacity-weaker,
   "weak":       $ouds-opacity-weak,
   "disabled":   $ouds-opacity-disabled,

site/data/sidebar-utilities.yml

@@ -10,6 +10,7 @@
     - title: Colored link
     - title: Color
     - title: Display
+    - title: Figma tokens
     - title: Flex
     - title: Float
     - title: Interaction

site/src/components/header/Navigation.astro

@@ -94,7 +94,7 @@ const { addedIn, layout, title } = Astro.props
           </LinkItem>
           <LinkItem
             active={layout === 'docs' && Astro.url.pathname.includes('/utilities/')}
-            href={getVersionedDocsPath('utilities/api')}
+            href={getVersionedDocsPath('utilities')}
             onclick="dataLayer.push({'event': 'clic', 'site_name':'accessibility-boosted', 'phase':'prod', 'track_category':'navbar', 'track_name':'utilities'});"
           >
             Utilities

site/src/content/docs/utilities.mdx

@@ -0,0 +1,13 @@
+---
+title: Utilities
+description: All OUDS utilities at a glance.
+aliases:
+  - "/utilities/"
+  - "/docs/utilities/"
+  - "/docs/[[config:docs_version]]/utilities/"
+toc: true
+---
+
+import { getVersionedDocsPath } from '@libs/path';
+
+<Callout type="info" title="Getting started with utilities" titleLevel="2" action="Understand the link between Figma tokens and our utilities" actionHref={getVersionedDocsPath('/utilities/figma-tokens/')} />

site/src/content/docs/utilities/api.mdx

@@ -2,9 +2,6 @@
 title: Utility API
 description: The utility API is a Sass-based tool to generate utility classes.
 aliases:
-  - "/utilities/"
-  - "/docs/utilities/"
-  - "/docs/[[config:docs_version]]/utilities/"
   - "/docs/utilities/api/"
 toc: true
 ---

site/src/content/docs/utilities/figma-tokens.mdx

@@ -0,0 +1,130 @@
+---
+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](https://youtu.be/EnGJE0jZLPU?t=200), 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
+
+<Callout type="info" title="This method is the preferred one." />
+
+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.
+
+<BsTable>
+  | 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`<br/>`ouds/color/surface/brand-primary` | `.bg-secondary`<br/>`.bg-surface-brand-primary` | [Background]([[docsref:/utilities/background]]) |
+  | A border using a standard token `ouds/color/border/*` or `ouds/border/*`. | `ouds/color/border/default`<br/>`ouds/border/radius/small`<br/>`ouds/border/width/thick` | `.border-default`<br/>`.rounded-small`<br/>`.border-thick` | [Border]([[docsref:/utilities/border]]) |
+  | A content using a standard color token `ouds/color/content/*`. | `ouds/color/content/muted`<br/>`ouds/color/content/on/brand-primary` | `.text-muted`<br/>`.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`<br/>`ouds/space/fixed/medium`<br/>`ouds/space/row-gap/none` | `.p-scaled-2xlarge`<br/>`.p-medium`<br/>`.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`<br/>`Body/Large/Strong` | `.fs-bl`<br/>`.fs-bl.fw-bold` | [Typography]([[docsref:/utilities/text#font-size]]) |
+  | A spacing using a grid token `ouds/grid/*` | `ouds/grid/column-gap`<br/>`ouds/grid/margin` | `.gap-gridgap`<br/>`.px-gridmargin` | [Spacing]([[docsref:/utilities/spacing#grid-measures]]) |
+</BsTable>
+
+### 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.
+
+<BsTable>
+  | On Figma I see | Used Figma token | Associated variables |
+  | -------------- | ---------- | --------------- |
+  | A background color using a standard token `ouds/color/*`. | `ouds/color/bg/secondary`<br/>`ouds/color/surface/brand-primary`<br/>`ouds/color/action/hover` | `--bs-color-bg-secondary`<br/>`--bs-color-surface-brand-primary`<br/>`--bs-color-action-hover` |
+  | A border using a standard token `ouds/color/border/*` or `ouds/border/*`. | `ouds/color/border/default`<br/>`ouds/border/radius/small`<br/>`ouds/border/width/thick` | `--bs-color-border-default`<br/>`$ouds-border-radius-small`<br/>`$ouds-border-width-thick` |
+  | A content using a standard color token `ouds/color/content/*`. | `ouds/color/content/muted`<br/>`ouds/color/content/on/brand-primary`<br/>`ouds/color/content/on/action/hover` | `--bs-color-content-muted`<br/>`--bs-color-content-on-brand-primary`<br/>`--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`<br/>`ouds/space/fixed/medium`<br/>`ouds/space/row-gap/none` | `--bs-space-scaled-2xlarge`<br/>`$ouds-space-fixed-medium`<br/>`$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`<br/>`Body/Large/Strong` | `get-font-size("body-large")`<br/>`$ouds-font-weight-web-body-strong`<br/>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`<br/>`ouds/grid/margin` | `--bs-grid-gap`<br/>`--bs-grid-margin` |
+</BsTable>
+
+## 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](https://r.orange.fr/r/S-ouds-doc-token-intro).
+
+<Callout type="info">
+  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](#semantic-tokens) and [composite tokens](#composite-tokens) are meant to be used directly in projects, and even for them, you should prefer using our [utilities](#using-our-utilities) when possible. The others are meant to be used by other tokens or by our components.
+</Callout>
+
+### Raw tokens
+
+The [`@ouds/web-[[config:brand]]/scss/tokens/_raw.scss`]([[config:repo]]/blob/v[[config:current_version]]-ouds-web/packages/[[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](#semantic-tokens), and occasionally, by [component tokens](#component-tokens).
+
+### Semantic tokens
+
+The [`@ouds/web-[[config:brand]]/scss/tokens/_semantic.scss`]([[config:repo]]/blob/v[[config:current_version]]-ouds-web/packages/[[config:brand]]/scss/tokens/_semantic.scss) file contains all the semantic tokens. Unlike [raw tokens](#raw-tokens), these tokens are intended to be used directly in projects (Be careful, many of them are already [available in our utilities](#using-our-utilities)). They are built on [raw tokens](#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`]([[config:repo]]/blob/v[[config:current_version]]-ouds-web/packages/[[config:brand]]/scss/tokens/_semantic-colors-custom-props.scss) file contains all the usable semantic color tokens. They are built on [semantic tokens](#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`]([[config:repo]]/blob/v[[config:current_version]]-ouds-web/packages/[[config:brand]]/scss/tokens/_composite.scss) file contains all the composite tokens. They are built (manually until now) on top of [semantic tokens](#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`]([[config:repo]]/blob/v[[config:current_version]]-ouds-web/packages/[[config:brand]]/scss/tokens/_component.scss) file is dedicated to component tokens. These tokens are used exclusively within components, often relying on [semantic tokens](#semantic-tokens) and [composite tokens](#composite-tokens), though they may occasionally reference [raw tokens](#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](#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](#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](#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](#css-variables) or to the [utilities](#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](#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()`]([[docsref:/foundation/typography/#text-style-for-custom-components]]) that takes the font reference name as a parameter. So `ouds/font/**/body-large` are aggregated via `get-font-size("body-large")`.
+- [Component tokens](#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](#raw-tokens): We don’t have any raw token transformed into a CSS variable.
+- [Semantic tokens](#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](#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](#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](#utilities) when possible.
+  - Our font tokens are aggregated in a mixin [`get-font-size()`]([[docsref:/foundation/typography/#text-style-for-custom-components]]) 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](#composite-tokens): We don’t have any composite token transformed into a CSS variable, but they are available as [Sass variables](#sass-variables).
+- [Component tokens](#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](#semantic-tokens) and our [composite tokens](#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](#raw-tokens): No raw token is available as a utility.
+- [Semantic tokens](#semantic-tokens): Semantic tokens are all [available as utilities](#using-our-utilities).
+- [Composite tokens](#composite-tokens): Composite tokens are all [available as utilities](#using-our-utilities).
+- [Component tokens](#component-tokens): No component token is available as a utility.

site/src/scss/_content.scss

@@ -37,7 +37,7 @@
 
     // Prevent breaking of code
     th,
-    td:first-child > code { // stylelint-disable-line selector-max-compound-selectors
+    code {
       white-space: nowrap;
     }
   }