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
|
|
||
| #### 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"
| ## 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
Collaborator
There was a problem hiding this comment.
The sentence seems to indicate the contrary.
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