From 324599578fa99ed7345a4a68c05ee850c30748f4 Mon Sep 17 00:00:00 2001 From: Louis-Maxime Piton Date: Wed, 18 Mar 2026 17:26:01 +0100 Subject: [PATCH 1/7] feat(docs): add Figma Tokens page --- scss/_maps.scss | 2 +- site/data/sidebar-utilities.yml | 1 + site/src/components/header/Navigation.astro | 2 +- site/src/content/docs/utilities.mdx | 13 ++++ site/src/content/docs/utilities/api.mdx | 3 - .../content/docs/utilities/figma-tokens.mdx | 70 +++++++++++++++++++ site/src/content/docs/utilities/link.mdx | 9 --- site/src/scss/_content.scss | 2 +- 8 files changed, 87 insertions(+), 15 deletions(-) create mode 100644 site/src/content/docs/utilities.mdx create mode 100644 site/src/content/docs/utilities/figma-tokens.mdx delete mode 100644 site/src/content/docs/utilities/link.mdx diff --git a/scss/_maps.scss b/scss/_maps.scss index 790c7bd744..92f82e804b 100644 --- a/scss/_maps.scss +++ b/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, diff --git a/site/data/sidebar-utilities.yml b/site/data/sidebar-utilities.yml index 13658ed0f9..f4c7dc176f 100644 --- a/site/data/sidebar-utilities.yml +++ b/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 diff --git a/site/src/components/header/Navigation.astro b/site/src/components/header/Navigation.astro index 5ec61a7263..0f3adf4279 100644 --- a/site/src/components/header/Navigation.astro +++ b/site/src/components/header/Navigation.astro @@ -94,7 +94,7 @@ const { addedIn, layout, title } = Astro.props Utilities diff --git a/site/src/content/docs/utilities.mdx b/site/src/content/docs/utilities.mdx new file mode 100644 index 0000000000..36ec6f4b63 --- /dev/null +++ b/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'; + + diff --git a/site/src/content/docs/utilities/api.mdx b/site/src/content/docs/utilities/api.mdx index 17d6576b56..c7b67167d4 100644 --- a/site/src/content/docs/utilities/api.mdx +++ b/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 --- diff --git a/site/src/content/docs/utilities/figma-tokens.mdx b/site/src/content/docs/utilities/figma-tokens.mdx new file mode 100644 index 0000000000..1e97054379 --- /dev/null +++ b/site/src/content/docs/utilities/figma-tokens.mdx @@ -0,0 +1,70 @@ +--- +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 ? */} + +## Examples + +### Using our utilities + +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. + + + | 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/typography#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 + +Pourquoi c'est important, meme langage + +Pas besoin de deviner les valeurs + +Les maintenances sont simplifiées + +Parallele Figma / tokens / var CSS / var Scss / Utilitaires + +Comment sont construits nos tokens Scss et CSS par rapport à ceux de figma + +Structure des tokens files + +Quel niveau on s'appuie pour construire les utilitaires + +Mettre des liens vers des tutos Figma devMode pour pouvoir se balader dans une planche design + +Expliquer qu'il faut surement ne pas appliquer les tokens de composants + +## General rules diff --git a/site/src/content/docs/utilities/link.mdx b/site/src/content/docs/utilities/link.mdx deleted file mode 100644 index 6fcb61fdc2..0000000000 --- a/site/src/content/docs/utilities/link.mdx +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: Link -description: Link utilities are used to stylize your anchors to adjust their color, opacity, underline offset, underline color, and more. -aliases: - - "/docs/utilities/link/" -toc: true ---- - - diff --git a/site/src/scss/_content.scss b/site/src/scss/_content.scss index 3873334ef1..5349fa04fe 100644 --- a/site/src/scss/_content.scss +++ b/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 { // stylelint-disable-line selector-max-compound-selectors white-space: nowrap; } } From 44af5abb425556890e743db6ed4bd2e755b6212c Mon Sep 17 00:00:00 2001 From: Louis-Maxime Piton Date: Thu, 19 Mar 2026 18:23:17 +0100 Subject: [PATCH 2/7] . --- .../content/docs/utilities/figma-tokens.mdx | 76 +++++++++++++++++-- 1 file changed, 68 insertions(+), 8 deletions(-) diff --git a/site/src/content/docs/utilities/figma-tokens.mdx b/site/src/content/docs/utilities/figma-tokens.mdx index 1e97054379..e4db36a66c 100644 --- a/site/src/content/docs/utilities/figma-tokens.mdx +++ b/site/src/content/docs/utilities/figma-tokens.mdx @@ -10,6 +10,8 @@ toc: true {/* TODO: Getting-started, foundation ? */} +import { getConfig } from '@libs/config'; + ## Examples ### Using our utilities @@ -49,22 +51,80 @@ This method is not the preferred one. You should only use it if there is no util ## Figma tokens -Pourquoi c'est important, meme langage +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). -Pas besoin de deviner les valeurs + + 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. + -Les maintenances sont simplifiées +### Raw tokens -Parallele Figma / tokens / var CSS / var Scss / Utilitaires +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). -Comment sont construits nos tokens Scss et CSS par rapport à ceux de figma +### 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). + +## General usage + +How do we build and use these tokens ? -Structure des tokens files +### 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**: `$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()`]([[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**: `$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 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()`]([[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**: `$ouds-{component-name}-{token-name}` + - Ex: `ouds/button/color/bg/minimal/hover` becomes `$ouds-button-color-bg-minimal-hover`. + +### Utilities + +Pas besoin de deviner les valeurs + +Comment sont construits nos tokens Scss et CSS par rapport à ceux de figma Quel niveau on s'appuie pour construire les utilitaires Mettre des liens vers des tutos Figma devMode pour pouvoir se balader dans une planche design Expliquer qu'il faut surement ne pas appliquer les tokens de composants - -## General rules From 05b987f6ded4ec7d1bea6c56e3fe83b24f8ca05a Mon Sep 17 00:00:00 2001 From: Louis-Maxime Piton Date: Fri, 20 Mar 2026 11:25:59 +0100 Subject: [PATCH 3/7] . --- .../content/docs/utilities/figma-tokens.mdx | 56 +++++++++---------- site/src/scss/_content.scss | 2 +- 2 files changed, 29 insertions(+), 29 deletions(-) diff --git a/site/src/content/docs/utilities/figma-tokens.mdx b/site/src/content/docs/utilities/figma-tokens.mdx index e4db36a66c..a073f584cc 100644 --- a/site/src/content/docs/utilities/figma-tokens.mdx +++ b/site/src/content/docs/utilities/figma-tokens.mdx @@ -14,9 +14,13 @@ 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 -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. + + +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 | @@ -55,6 +59,8 @@ Figma tokens (or design tokens) are really important in the comprehension betwee 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. ### Raw tokens @@ -75,7 +81,7 @@ The [`@ouds/web-[[config:brand]]/scss/tokens/_composite.scss`]([[config:repo]]/b ### 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). +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 @@ -86,45 +92,39 @@ How do we build and use these tokens ? 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**: `$core-{ouds|[[config:brand]]}-{border|color|dimension|effect|elevation|font|grid|opacity}-{token-name}`. +- [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**: `$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. +- [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**: `$ouds-elevation-{token-name}` +- [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**: `$ouds-{component-name}-{token-name}` +- [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 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()`]([[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**: `$ouds-{component-name}-{token-name}` - - Ex: `ouds/button/color/bg/minimal/hover` becomes `$ouds-button-color-bg-minimal-hover`. +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 -Pas besoin de deviner les valeurs - -Comment sont construits nos tokens Scss et CSS par rapport à ceux de figma - -Quel niveau on s'appuie pour construire les utilitaires - -Mettre des liens vers des tutos Figma devMode pour pouvoir se balader dans une planche design +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. -Expliquer qu'il faut surement ne pas appliquer les tokens de composants +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. diff --git a/site/src/scss/_content.scss b/site/src/scss/_content.scss index 5349fa04fe..7d80f7ec1a 100644 --- a/site/src/scss/_content.scss +++ b/site/src/scss/_content.scss @@ -37,7 +37,7 @@ // Prevent breaking of code th, - code { // stylelint-disable-line selector-max-compound-selectors + code { white-space: nowrap; } } From bed6fb970ca8315d6749d654d136223876125bf9 Mon Sep 17 00:00:00 2001 From: Louis-Maxime Piton Date: Fri, 20 Mar 2026 11:44:01 +0100 Subject: [PATCH 4/7] fix ci --- .../content/docs/utilities/figma-tokens.mdx | 24 +++++++++---------- 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/site/src/content/docs/utilities/figma-tokens.mdx b/site/src/content/docs/utilities/figma-tokens.mdx index a073f584cc..9e474a189a 100644 --- a/site/src/content/docs/utilities/figma-tokens.mdx +++ b/site/src/content/docs/utilities/figma-tokens.mdx @@ -14,7 +14,7 @@ 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. +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 @@ -32,7 +32,7 @@ When a token is used on Figma side, you should check if there is a utility class | 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/typography#font-size]]) | + | 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]]) | @@ -81,7 +81,7 @@ The [`@ouds/web-[[config:brand]]/scss/tokens/_composite.scss`]([[config:repo]]/b ### 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. +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 @@ -93,10 +93,10 @@ Almost each token that is provided by the design, and that can be needed in any 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. + - 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. + - 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}` @@ -110,14 +110,14 @@ We build our Sass variables following the architecture of the Figma tokens: 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. +- [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. + - 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 From 006bfdbcb60e1271ffa9a5b4b1698a825e611733 Mon Sep 17 00:00:00 2001 From: Louis-Maxime Piton Date: Tue, 31 Mar 2026 17:58:53 +0200 Subject: [PATCH 5/7] . Co-authored-by: Maxime Lardenois --- site/data/sidebar-utilities.yml | 1 - site/src/content/docs/foundation/tokens.mdx | 66 ++++++++- site/src/content/docs/utilities.mdx | 53 ++++++- .../content/docs/utilities/figma-tokens.mdx | 130 ------------------ 4 files changed, 116 insertions(+), 134 deletions(-) delete mode 100644 site/src/content/docs/utilities/figma-tokens.mdx diff --git a/site/data/sidebar-utilities.yml b/site/data/sidebar-utilities.yml index f4c7dc176f..13658ed0f9 100644 --- a/site/data/sidebar-utilities.yml +++ b/site/data/sidebar-utilities.yml @@ -10,7 +10,6 @@ - title: Colored link - title: Color - title: Display - - title: Figma tokens - title: Flex - title: Float - title: Interaction diff --git a/site/src/content/docs/foundation/tokens.mdx b/site/src/content/docs/foundation/tokens.mdx index c7ae3b7029..16be26b44c 100644 --- a/site/src/content/docs/foundation/tokens.mdx +++ b/site/src/content/docs/foundation/tokens.mdx @@ -6,4 +6,68 @@ aliases: toc: true --- - +## 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). + + + 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]([[docsref:/utilities#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`]([[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]([[docsref:/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. + +## Variables usage + +How are these tokens built ? [How should they be used]([[docsref:/utilities/]]) ? + +### 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 variables](#css-variables) or to the [utilities]([[docsref:/utilities#using-our-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]([[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 on our side. diff --git a/site/src/content/docs/utilities.mdx b/site/src/content/docs/utilities.mdx index 36ec6f4b63..57f4c23be3 100644 --- a/site/src/content/docs/utilities.mdx +++ b/site/src/content/docs/utilities.mdx @@ -8,6 +8,55 @@ aliases: toc: true --- -import { getVersionedDocsPath } from '@libs/path'; +## 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 + +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. + + + +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 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-our-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 our 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. + + +You can see how to find any variable name in our [tokens documentation]([[docsref:/foundation/tokens#variables-usage]]). + + + | 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`
`ouds/color/surface/brand-primary`
`ouds/color/action/hover` | `--bs-color-bg-secondary`
`--bs-color-surface-brand-primary`
`--bs-color-action-hover` | `$ouds-color-bg-secondary`
`$ouds-color-surface-brand-primary`
`$ouds-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`
`none`
`none` | `$ouds-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` | `$ouds-color-content-muted`
`$ouds-color-content-on-brand-primary`
`$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`
`ouds/space/fixed/medium`
`ouds/space/row-gap/none` | `--bs-space-scaled-2xlarge`
`none`
`none` | `none`
`$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")`
`none`
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`
`$ouds-font-weight-web-body-strong` | + | A spacing using a grid token `ouds/grid/*` | `ouds/grid/column-gap`
`ouds/grid/margin` | `--bs-grid-gap`
`--bs-grid-margin` | `none`
`none` | + diff --git a/site/src/content/docs/utilities/figma-tokens.mdx b/site/src/content/docs/utilities/figma-tokens.mdx deleted file mode 100644 index 9e474a189a..0000000000 --- a/site/src/content/docs/utilities/figma-tokens.mdx +++ /dev/null @@ -1,130 +0,0 @@ ---- -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 - - - -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](https://r.orange.fr/r/S-ouds-doc-token-intro). - - - 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. - - -### 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. From a7136dbcd26eb2f8c2946f8d4762f380d746e7fe Mon Sep 17 00:00:00 2001 From: Louis-Maxime Piton Date: Tue, 31 Mar 2026 17:59:35 +0200 Subject: [PATCH 6/7] . --- site/data/sidebar-foundation.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/site/data/sidebar-foundation.yml b/site/data/sidebar-foundation.yml index a19cdd7c20..3e4577e049 100644 --- a/site/data/sidebar-foundation.yml +++ b/site/data/sidebar-foundation.yml @@ -5,7 +5,6 @@ - title: Approach - title: Options - title: Tokens - draft: true - title: Color palette - title: Color modes - title: CSS variables From 63b4befeecfc2065432a0b295cc99721bb4c757b Mon Sep 17 00:00:00 2001 From: Louis-Maxime Piton Date: Fri, 3 Apr 2026 18:18:11 +0200 Subject: [PATCH 7/7] fix reviews Co-authored-by: Maxime Lardenois --- site/src/components/header/Navigation.astro | 2 +- site/src/content/docs/foundation/tokens.mdx | 28 +++++++++++---------- site/src/content/docs/utilities.mdx | 12 ++++----- 3 files changed, 22 insertions(+), 20 deletions(-) diff --git a/site/src/components/header/Navigation.astro b/site/src/components/header/Navigation.astro index 0f3adf4279..fe738acddb 100644 --- a/site/src/components/header/Navigation.astro +++ b/site/src/components/header/Navigation.astro @@ -93,7 +93,7 @@ const { addedIn, layout, title } = Astro.props Components diff --git a/site/src/content/docs/foundation/tokens.mdx b/site/src/content/docs/foundation/tokens.mdx index 16be26b44c..ea750948c8 100644 --- a/site/src/content/docs/foundation/tokens.mdx +++ b/site/src/content/docs/foundation/tokens.mdx @@ -8,41 +8,43 @@ toc: true ## 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). +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). 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]([[docsref:/utilities#using-our-utilities]]) when possible. The others are meant to be used by other tokens or by our components. + 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. ### 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). +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 are intended to be used directly in projects (Be careful, many of them are already [available in our utilities]([[docsref:/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. +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. 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. +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 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. +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 directly in your codebase, as they are defined for a specific component. +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 usage +## Variables -How are these tokens built ? [How should they be used]([[docsref:/utilities/]]) ? + + Checkout our [utilities cheatsheet]([[docsref:/utilities]]) to learn the recommended usage for tokens and variables + ### 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. +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}`. @@ -50,7 +52,7 @@ We build our Sass variables following the architecture of the Figma tokens: - 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 have also have their version using their suffix `*-light` and `*-dark`. + - 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`. @@ -65,9 +67,9 @@ All the colors and the tokens suffixed by `*-mobile`, `*-tablet`, or `*-desktop` 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 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 on our side. +- [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. diff --git a/site/src/content/docs/utilities.mdx b/site/src/content/docs/utilities.mdx index 57f4c23be3..c87c318c6a 100644 --- a/site/src/content/docs/utilities.mdx +++ b/site/src/content/docs/utilities.mdx @@ -20,16 +20,16 @@ We build our CSS variables following the architecture of the Figma tokens: ## Using our utilities -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. +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. - + 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 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-our-variables). | {/* TODO: Change once the color palette has been changed or doc about CSS variables has been developed */ } + | 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 read about [our color page]([[docsref:/foundation/colors]]).

 | | 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]]) | @@ -42,11 +42,11 @@ When a token is used on Figma side, you should check if there is a utility class ## Using our 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. + + 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. -You can see how to find any variable name in our [tokens documentation]([[docsref:/foundation/tokens#variables-usage]]). +Variables names can be easily inferred from token names, [this is explained in the tokens documentation]([[docsref:/foundation/tokens#variables]]). | On Figma I see | Used token | Associated CSS variables | Associated Sass variables |