docs: several enhancements for readability (#2713)

Co-authored-by: Louis-Maxime Piton <[email protected]>
Co-authored-by: Julien Déramond <[email protected]>

site/content/docs/0.0/customize/custom-libraries.md

@@ -12,19 +12,21 @@ toc: true
 **This content is not intended for standalone projects.** It is specifically for those looking to customize the entire library to fit a completely different design or brand.
 {{< /callout >}}
 
-## Architecture
+## Tokens architecture
+
+OUDS Web is built on the basis of design tokens that capture all the design decisions utilized within our design system. They ensure the consistency of components between them and facilitate the configuration of the library.
 
 ### Raw tokens
 
-The [`scss/tokens/_raw.scss`]({{< param repo >}}/blob/v{{< param current_version >}}-ouds-web/scss/tokens/_raw.scss) file consolidates all basic tokens. While these tokens don't carry semantic meaning and aren't meant to be used directly, they form the foundation of the Orange Unified Design System. Their primary purpose is to be utilized by semantic tokens, and occasionally, by component tokens.
+The [`scss/tokens/_raw.scss`]({{< param repo >}}/blob/v{{< param current_version >}}-ouds-web/scss/tokens/_raw.scss) file consolidates all basic tokens. While these tokens don't carry semantic meaning and aren't meant to be used directly in projects, they form the foundation of the Orange Unified Design System. Their primary purpose is to be utilized by semantic tokens, and occasionally, by component tokens.
 
 ### Semantic tokens
 
-The [`scss/tokens/_semantic.scss`]({{< param repo >}}/blob/v{{< param current_version >}}-ouds-web/scss/tokens/_semantic.scss) file contains all the semantic tokens. Unlike raw tokens, these are intended to be used directly. They are built on raw tokens, assigning them semantic meaning through media queries or specific contexts. These tokens are ready to be applied either in utilities or directly within component tokens.
+The [`scss/tokens/_semantic.scss`]({{< param repo >}}/blob/v{{< param current_version >}}-ouds-web/scss/tokens/_semantic.scss) file contains all the semantic tokens. Unlike raw tokens, these are intended to be used directly in projects. They are built on raw tokens, assigning them semantic meaning through media queries or specific contexts. These tokens are ready to be applied either in utilities or directly within components. The names of these tokens are not intended to be modified for a custom library, only the link between a token and its value defined by a raw token.
 
 ### Component tokens
 
-The [`scss/tokens/_component.scss`]({{< param repo >}}/blob/v{{< param current_version >}}-ouds-web/scss/tokens/_component.scss) file is dedicated to component tokens. These tokens should be used exclusively within components, often relying on semantic tokens, though they may occasionally reference raw tokens. Essentially, they map the semantic tokens to components.
+The [`scss/tokens/_component.scss`]({{< param repo >}}/blob/v{{< param current_version >}}-ouds-web/scss/tokens/_component.scss) file is dedicated to component tokens. These tokens could be used in projects, but exclusively within components, often relying on semantic tokens, though they may occasionally reference raw tokens. Essentially, they map the semantic tokens to components.
 
 ## Customization
 
@@ -34,11 +36,11 @@ The [`scss/tokens/_component.scss`]({{< param repo >}}/blob/v{{< param current_v
 
 If you have a designer (which is highly recommended when creating a new brand), implementing changes should be straightforward. You'll need to replace our token files with those provided by your designer, manually substituting and remapping tokens to match your brand’s specifications.
 
-For a practical example of how this process works and what your customized library should look like after the changes, refer to [our guide on Stackblitz](https://stackblitz.com/edit/github-j5teen).
+For a practical example of how this process works and what your customized library should look like after the changes, refer to [our example on Stackblitz](https://stackblitz.com/edit/github-j5teen).
 
 #### Having no designer
 
-In the absence of a designer, it’s advisable to reach out to the [OUDS Web core team]({{< docsref "/about/team" >}}).
+In the absence of a designer, it’s advisable to reach out to the [OUDS Web core team]({{< docsref "/about/team" >}}) for support.
 
 ### Building and deploying documentation
 

site/content/docs/0.0/customize/options.md

@@ -15,22 +15,22 @@ You can find and customize these variables for key global options in OUDS Web's
 | Variable                          | Values                                | Description                                                                            |
 | --------------------------------- | ------------------------------------- | -------------------------------------------------------------------------------------- |
 | `$enable-bootstrap-compatibility` | `true` or `false` (default)           | Enforces Bootstrap compatibility. |
+| `$enable-grid-classes`            | `true` (default) or `false`           | Enables the generation of CSS classes for the grid system (e.g. `.row`, `.col-md-1`, etc.). |
+| `$enable-important-utilities`     | `true` (default) or `false`           | Enables the `!important` suffix in utility classes. |
 <!--| `$spacer`                      | `1.25rem` (default), or any value > 0 | Specifies the default spacer value to programmatically generate our [spacer utilities]({{< docsref "/utilities/spacing" >}}). |
 | `$enable-dark-mode`            | `true` (default) or `false`           | Enables built-in [dark mode support]({{< docsref "/customize/color-modes#dark-mode" >}}) across the project and its components. |
 | `$enable-rounded`              | `true` or `false` (default)           | Enables predefined `border-radius` styles on various components. |
 | `$enable-shadows`              | `true` or `false` (default)           | Enables predefined decorative `box-shadow` styles on various components. Does not affect `box-shadow`s used for focus states. |
 | `$enable-gradients`            | `true` or `false` (default)           | Enables predefined gradients via `background-image` styles on various components. |
 | `$enable-transitions`          | `true` (default) or `false`           | Enables predefined `transition`s on various components. |
 | `$enable-reduced-motion`       | `true` (default) or `false`           | Enables the [`prefers-reduced-motion` media query]({{< docsref "/getting-started/accessibility#reduced-motion" >}}), which suppresses certain animations/transitions based on the users' browser/operating system preferences. |
-| `$enable-grid-classes`         | `true` (default) or `false`           | Enables the generation of CSS classes for the grid system (e.g. `.row`, `.col-md-1`, etc.). |
 | `$enable-container-classes`    | `true` (default) or `false`           | Enables the generation of CSS classes for layout containers. (New in v5.2.0) |
 | `$enable-caret`                | `true` (default) or `false`           | Enables pseudo element caret on `.dropdown-toggle`. |
 | `$enable-button-pointers`      | `true` (default) or `false`           | Add "hand" cursor to non-disabled button elements. |
 | `$enable-rfs`                  | `true` or `false` (default)           | Globally enables [RFS]({{< docsref "/getting-started/rfs" >}}). |
 | `$enable-validation-icons`     | `true` (default) or `false`           | Enables `background-image` icons within textual inputs and some custom forms for validation states. |
 | `$enable-negative-margins`     | `true` or `false` (default)           | Enables the generation of [negative margin utilities]({{< docsref "/utilities/spacing#negative-margin" >}}). |
 | `$enable-deprecation-messages` | `true` (default) or `false`           | Set to `false` to hide warnings when using any of the deprecated mixins and functions that are planned to be removed in `v6`. |
-| `$enable-important-utilities`  | `true` (default) or `false`           | Enables the `!important` suffix in utility classes. |
 | `$enable-smooth-scroll`        | `true` (default) or `false`           | Applies `scroll-behavior: smooth` globally, except for users asking for reduced motion through [`prefers-reduced-motion` media query]({{< docsref "/getting-started/accessibility#reduced-motion" >}}) |
 | `$enable-fixed-header`         | `true` (default) or `false`           | Set `scroll-padding-top` rule to root element, preventing focus from being hidden under a fixed header. |-->
 {{< /bs-table >}}

site/content/docs/0.0/extend/approach.md

@@ -43,6 +43,17 @@ As such, components should be built with a base class that houses common, not-to
 
 Modifier classes should only be used when there are multiple properties or values to be changed across multiple variants. Modifiers are not always necessary, so be sure you're actually saving lines of code and preventing unnecessary overrides when creating them. Good examples of modifiers are our theme color classes and size variants.
 
+
+## Bootstrap compatibility
+
+OUDS Web is built on the basis of [design tokens]({{< docsref "/customize/custom-libraries/#tokens-architecture" >}}) that capture all the design decisions utilized within our design system. They ensure the consistency of components between them and facilitate the configuration of the library.
+
+These tokens are specific to OUDS Web. They are notably used as a basis for the construction of utilities. This is why the names (and not only the values) of the OUDS Web utilities differ from the Bootstrap utilities.
+
+The [option `$enable-bootstrap-compatibility`]({{< docsref "/customize/options/" >}}), if set to `true`, allows to keep in the library the Bootstrap elements in addition to the OUDS Web elements (like helpers, utilities, variables, components variants, etc.). In this case, we made a best-effort attempt to style the Bootstrap elements to resemble those of OUDS.
+
+However, we recommend not to enable this option, even if it is enabled for the OUDS Web site itself, for obvious documentation reasons. You should not need it to build Orange branded sites with OUDS Web. It should only be useful whenever a project relies on external Bootstrap-based libraries or plugins used in combination with OUDS Web CSS.
+
 <!--
 ## z-index scales
 
@@ -74,13 +85,11 @@ Lastly, our styles build on the fundamental behaviors of common web elements. Wh
 
 The same goes for more complex components. While we _could_ write our own form validation plugin to add classes to a parent element based on an input's state, thereby allowing us to style the text say red, we prefer using the `:valid`/`:invalid` pseudo-elements every browser provides us.
 
-<!--
 ## Utilities
 
 Utility classes are a powerful ally in combating CSS bloat and poor page performance. A utility class is typically a single, immutable property-value pairing expressed as a class (e.g., `.d-block` represents `display: block;`). Their primary appeal is speed of use while writing HTML and limiting the amount of custom CSS you have to write.
 
 Specifically regarding custom CSS, utilities can help combat increasing file size by reducing your most commonly repeated property-value pairs into single classes. This can have a dramatic effect at scale in your projects.
--->
 
 ## Flexible HTML
 

site/content/docs/0.0/getting-started/contents.md

@@ -83,8 +83,8 @@ OUDS Web includes a handful of options for including some or all of our compiled
 {{< bs-table "table" >}}
 | CSS files | Layout | Content | Components | Utilities |
 | --- | --- | --- | --- | --- |
-| `ouds-web.css`<br> `ouds-web.min.css`<br> `ouds-web.rtl.css`<br> `ouds-web.rtl.min.css` | Included | Included | Included | Included |
-| `ouds-web-bootstrap.css`<br> `ouds-web-bootstrap.min.css`<br> `ouds-web-bootstrap.rtl.css`<br> `ouds-web-bootstrap.rtl.min.css` | Included | Included | Included | Included (with Bootstrap utilities) |
+| `ouds-web.css`<br> `ouds-web.min.css`<br> `ouds-web.rtl.css`<br> `ouds-web.rtl.min.css` | Included | Included | Included | Included without Bootstrap utilities |
+| `ouds-web-bootstrap.css`<br> `ouds-web-bootstrap.min.css`<br> `ouds-web-bootstrap.rtl.css`<br> `ouds-web-bootstrap.rtl.min.css` | Included | Included | Included | Included with Bootstrap utilities |
 | `ouds-web-grid.css`<br> `ouds-web-grid.rtl.css`<br> `ouds-web-grid.min.css`<br> `ouds-web-grid.rtl.min.css` | <!--[Only grid system]({{< docsref "/layout/grid" >}})-->— | — | — | [Only flex utilities]({{< docsref "/utilities/flex" >}}) |
 | `ouds-web-utilities.css`<br> `ouds-web-utilities.rtl.css`<br> `ouds-web-utilities.min.css`<br> `ouds-web-utilities.rtl.min.css` | — | — | — | Included |
 | `ouds-web-reboot.css`<br> `ouds-web-reboot.rtl.css`<br> `ouds-web-reboot.min.css`<br> `ouds-web-reboot.rtl.min.css` | — | <!--[Only Reboot]({{< docsref "/content/reboot" >}})-->— | — | — |

site/content/docs/0.0/migration-from-boosted.md

@@ -9,7 +9,7 @@ aliases:
 toc: true
 ---
 
-This guide provides information on how to migrate from Boosted (latest release) to OUDS Web, with Bootstrap compatibility turned off.
+This guide provides information on how to migrate from Boosted (latest release) to OUDS Web, with Bootstrap compatibility turned off. [Learn more about Bootstrap compatibility]({{< docsref "/extend/approach/#bootstrap-compatibility" >}}).
 
 Let's start with the most obvious change you'll notice: the name. **Boosted is now OUDS Web.**
 

site/content/docs/0.0/migration.md

@@ -136,7 +136,7 @@ toc: true
 
 ### Pre-compiled versions
 
-From now on, OUDS Web won't embed Bootstrap elements that are not part of Orange Unified Design System. However, you can still use our Bootstrap compatibility mode by using `ouds-web-bootstrap.css` and `ouds-web-bootstrap.min.css`.
+From now on, by default, OUDS Web won't embed Bootstrap elements (like helpers, utilities, variables, components variants, etc.) that do not comply with Orange Unified Design System. However, you can still use our Bootstrap compatibility mode by using `ouds-web-bootstrap.css` and `ouds-web-bootstrap.min.css`. [Learn more about Bootstrap compatibility]({{< docsref "/extend/approach/#bootstrap-compatibility" >}}).
 
 ### Utilities
 
@@ -147,7 +147,7 @@ From now on, OUDS Web won't embed Bootstrap elements that are not part of Orange
 ### CSS and Sass variables
 
 - <span class="badge text-bg-success">New</span> `$enable-bootstrap-compatibility` option set to `false` by default. This option allows you to compile the Sass files with a Bootstrap compatibility mode.
-  - For instance, without the Bootstrap compatibility mode, you won't have the opacity Bootstrap utilities such as `opacity-0`, `opacity-1`, `opacity-50`, etc. You will only have the semantic OUDS Web utilities such as `opacity-transparent`, `opacity-weaker`, `opacity-weak`, etc.
+  - For instance, without the Bootstrap compatibility mode, you won't have the opacity Bootstrap utilities such as `opacity-0`, `opacity-1`, `opacity-50`, etc. You will only have the OUDS Web utilities such as `opacity-transparent`, `opacity-weaker`, `opacity-weak`, etc. [Learn more about Bootstrap compatibility]({{< docsref "/extend/approach/#bootstrap-compatibility" >}}).
 
 - <span class="badge text-bg-success">New</span> OUDS Web fully implements the design tokens. If you were using the Sass compilation, you must import the new Sass files before the variables.
 

site/layouts/shortcodes/bootstrap-compatibility.html

@@ -5,7 +5,7 @@
 
   <div class="alert alert-info alert-sm mt-2 mb-4" role="alert">
     <span class="alert-icon"><span class="visually-hidden">Info</span></span>
-    <p>This part is enabled only when <code>$enable-bootstrap-compatibility</code> is set to <code>true</code>.</p>
+    <p>This part is enabled only when <code>$enable-bootstrap-compatibility</code> is set to <code>true</code>. Read more about <a href="/docs/extend/approach/#bootstrap-compatibility">Bootstrap compatibility</a>.</p>
   </div>
 
   {{- if $markdown -}}