feat(docs): add Figma Tokens page#3458
Open
louismaximepiton wants to merge 9 commits intoouds/mainfrom
Open
Conversation
louismaximepiton
added
📖 documentation
github-project-automation
Bot
moved this to In Progress / Draft
in 🟣 [Orange-Boosted-Bootstrap] PRs Board
✅ Deploy Preview for boosted ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
2 tasks
boosted-bot
moved this from In Progress / Draft
to Need Dev Review
in 🟣 [Orange-Boosted-Bootstrap] PRs Board
MaxLardenois
requested changes
Apr 2, 2026
| <CalloutSoon type="page" /> | ||
| ## 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). |
Collaborator
There was a problem hiding this comment.
Suggested change
| 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). |
|
|
||
| ### 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). |
Collaborator
There was a problem hiding this comment.
Keep "raw" here to be consistent.
Suggested change
| 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. |
Collaborator
There was a problem hiding this comment.
Suggested change
| 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. |
Collaborator
There was a problem hiding this comment.
Colors is not yet there, we need to merge #3453
Suggested change
| 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]]). |
Member
Author
There was a problem hiding this comment.
Do you think that I should add a word about the other semantic vars that we provide via CSS var only ? Like icon size, font, spacing scaled ?
| | 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]]) | |
Collaborator
There was a problem hiding this comment.
Not sure I understand your sentence here "is a good sign that this reference has been used or should have been." ?
Member
Author
There was a problem hiding this comment.
Yeah I didn't know how to say it, but I wanted to say that the presence of this token is a good marker that a composite tokens should be used instead of single tokens.
| <Callout type="info" title="This method is the preferred one." /> | ||
|
|
||
| When a token is used on Figma side, you should check if there is a utility class available for it. If there is, you should use it. This way, you will be sure that the token is applied correctly, and that it will be updated automatically when the token value changes. | ||
|
|
Collaborator
There was a problem hiding this comment.
I would add a Callout here to urge people to read the Foundation / Colors page when they need to use a color token.
"Please read our colors documentation page when working with color tokens"
Comment on lines
+44
to
+45
|
|
||
| <Callout type="info"> |
Collaborator
There was a problem hiding this comment.
Maybe a warning instead of info?
| ## Using our variables | ||
|
|
||
| <Callout type="info"> | ||
| 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. |
Collaborator
There was a problem hiding this comment.
Suggested change
| 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. |
Not sure what you mean by "that it will be updated automatically when the token value changes."
Member
Author
There was a problem hiding this comment.
I mean that they won't need to update anything if a color change or whatever
| 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. | ||
| </Callout> | ||
|
|
||
| You can see how to find any variable name in our [tokens documentation]([[docsref:/foundation/tokens#variables-usage]]). |
Collaborator
There was a problem hiding this comment.
Suggested change
| 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-usage]]). |
There was a problem hiding this comment.
Pull request overview
This PR introduces a new “Utilities” landing page to help developers map Figma (OUDS) tokens to available utility classes and variables, and expands the Tokens foundation page so it’s no longer a placeholder/draft.
Changes:
- Add a new
Utilitiesindex page (/utilities) with guidance and token→utility/variable mapping tables. - Replace the
Tokensplaceholder with detailed documentation about token tiers and variable usage. - Update routing/navigation (aliases + navbar link) to point utilities to the new landing page.
Reviewed changes
Copilot reviewed 7 out of 8 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| site/src/scss/_content.scss | Adjusts table code wrapping behavior in docs content. |
| site/src/content/docs/utilities/link.mdx | Removes placeholder “Link utilities” page. |
| site/src/content/docs/utilities/api.mdx | Removes aliases now handled by the new utilities landing page. |
| site/src/content/docs/utilities.mdx | Adds new utilities landing page with Figma token mapping guidance. |
| site/src/content/docs/foundation/tokens.mdx | Replaces placeholder with full tokens/variables documentation. |
| site/src/components/header/Navigation.astro | Updates navbar “Utilities” link target to the new landing page. |
| site/data/sidebar-foundation.yml | Publishes Tokens page by removing draft: true. |
| scss/_maps.scss | Minor formatting alignment in opacity map. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Co-authored-by: Maxime Lardenois <maxime.lardenois@orange.com>
…d-tokens-explanation
Member
Author
|
To merge once #3453 have been merged |
…d-tokens-explanation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Related issues
Closes #3370
Description
Add a page linking our tokens and classes.
Checklists
Progression (for Core Team only)
ouds/mainfollowing conventional commitLive previews