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-foundation.yml

@@ -5,7 +5,6 @@
     - title: Approach
     - title: Options
     - title: Tokens
-      coming_soon: true
     - title: Colors
     - title: Color modes
     - title: CSS variables

site/src/components/header/Navigation.astro

@@ -93,8 +93,8 @@ const { addedIn, layout, title } = Astro.props
             Components
           </LinkItem>
           <LinkItem
-            active={layout === 'docs' && Astro.url.pathname.includes('/utilities/')}
-            href={getVersionedDocsPath('utilities/api')}
+            active={layout === 'docs' && Astro.url.pathname.includes('/utilities')}
+            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/foundation/tokens.mdx

@@ -6,4 +6,70 @@ aliases:
 toc: true
 ---
 
-<CalloutSoon type="page" />
+## Figma tokens
+
+Figma tokens (or design tokens) 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](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](#semantic-tokens) and [composite tokens](#composite-tokens) should be used directly in projects. When possible, it is recommended to use these tokens via [utility classes]([[docsref:/utilities#using-our-utilities]]). All other tokens are intended for internal use 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 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](#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 can be used directly in projects (check the [cheatsheet for their recommended usage]([[docsref:/utilities#using-our-utilities]])). They are derived from raw tokens and add semantic meaning through media queries or 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).
+
+#### 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 custom properties. They are built on [semantic tokens](#semantic-tokens) switching the color depending on the [color mode]([[docsref:/foundation/color-modes]]). 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]([[docsref:/foundation/colors]]).
+
+### 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 aggregations of several [semantic tokens](#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-[[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 in your codebase, as they are defined for a specific component.
+
+## Variables
+
+<Callout type="info">
+  Checkout our [utilities cheatsheet]([[docsref:/utilities]]) to learn the recommended usage for tokens and variables
+</Callout>
+
+### 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](#figma-tokens), 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 variables](#css-variables) or to the [utilities]([[docsref:/utilities#using-our-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](#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]([[docsref:/utilities#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]([[docsref:/utilities#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]([[docsref:/utilities#using-our-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 internally.

site/src/content/docs/utilities.mdx

@@ -0,0 +1,62 @@
+---
+title: Utilities
+description: All OUDS utilities at a glance.
+aliases:
+  - "/utilities/"
+  - "/docs/utilities/"
+  - "/docs/[[config:docs_version]]/utilities/"
+toc: true
+---
+
+## General usage
+
+Our utilities are built on top of our [semantic tokens]([[docsref:/foundation/tokens#semantic-tokens]]) and our [composite tokens]([[docsref:/foundation/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]([[docsref:/foundation/tokens#raw-tokens]]): No raw token is available as a utility.
+- [Semantic tokens]([[docsref:/foundation/tokens#semantic-tokens]]): Semantic tokens are all [available as utilities](#using-our-utilities).
+- [Composite tokens]([[docsref:/foundation/tokens#composite-tokens]]): Composite tokens are all [available as utilities](#using-our-utilities).
+- [Component tokens]([[docsref:/foundation/tokens#component-tokens]]): No component token is available as a utility.
+
+## Using our utilities
+
+To [integrate a Figma design](https://youtu.be/EnGJE0jZLPU?t=200), you will have to use tokens that are defined as `ouds/**`. This page gives you some directions on how to use these tokens within your codebase.
+
+<Callout type="info" title="This is the recommended method." />
+
+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 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` | <Callout type="warning" class="my-none"><p>This case is a bit special and you should read about [our color page]([[docsref:/foundation/colors]]).</p></Callout> |
+  | 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 our variables
+
+<Callout type="warning">
+  This method should only be use 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 if you are creating 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.
+</Callout>
+
+Variables names can be easily inferred from token names, [this is explained in the tokens documentation]([[docsref:/foundation/tokens#variables]]).
+
+<BsTable>
+  | On Figma I see | Used token | Associated CSS variables | Associated Sass 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` | `$ouds-color-bg-secondary`<br/>`$ouds-color-surface-brand-primary`<br/>`$ouds-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/>`none`<br/>`none` | `$ouds-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` | `$ouds-color-content-muted`<br/>`$ouds-color-content-on-brand-primary`<br/>`$ouds-color-content-on-action-hover` |
+  | An opacity using a standard token `ouds/opacity/*`. Be careful where the token is applied. | `ouds/opacity/medium` | `none` | `$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` | `none` | `$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/>`none`<br/>`none` | `none`<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/>`none`<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]]). | `none`<br/>`$ouds-font-weight-web-body-strong` |
+  | A spacing using a grid token `ouds/grid/*` | `ouds/grid/column-gap`<br/>`ouds/grid/margin` | `--bs-grid-gap`<br/>`--bs-grid-margin` | `none`<br/>`none` |
+</BsTable>

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/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;
     }
   }