diff --git a/site/content/docs/0.0/customize/custom-libraries.md b/site/content/docs/0.0/customize/custom-libraries.md index 71b3602f37..14f8359b72 100644 --- a/site/content/docs/0.0/customize/custom-libraries.md +++ b/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 diff --git a/site/content/docs/0.0/customize/options.md b/site/content/docs/0.0/customize/options.md index 46c645a4d6..508783a69a 100644 --- a/site/content/docs/0.0/customize/options.md +++ b/site/content/docs/0.0/customize/options.md @@ -15,6 +15,8 @@ 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. | {{< /bs-table >}} diff --git a/site/content/docs/0.0/extend/approach.md b/site/content/docs/0.0/extend/approach.md index 2810cd081c..f6624ed825 100644 --- a/site/content/docs/0.0/extend/approach.md +++ b/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. + ## Flexible HTML diff --git a/site/content/docs/0.0/getting-started/contents.md b/site/content/docs/0.0/getting-started/contents.md index 994d18cd21..20581896a2 100644 --- a/site/content/docs/0.0/getting-started/contents.md +++ b/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`
`ouds-web.min.css`
`ouds-web.rtl.css`
`ouds-web.rtl.min.css` | Included | Included | Included | Included | -| `ouds-web-bootstrap.css`
`ouds-web-bootstrap.min.css`
`ouds-web-bootstrap.rtl.css`
`ouds-web-bootstrap.rtl.min.css` | Included | Included | Included | Included (with Bootstrap utilities) | +| `ouds-web.css`
`ouds-web.min.css`
`ouds-web.rtl.css`
`ouds-web.rtl.min.css` | Included | Included | Included | Included without Bootstrap utilities | +| `ouds-web-bootstrap.css`
`ouds-web-bootstrap.min.css`
`ouds-web-bootstrap.rtl.css`
`ouds-web-bootstrap.rtl.min.css` | Included | Included | Included | Included with Bootstrap utilities | | `ouds-web-grid.css`
`ouds-web-grid.rtl.css`
`ouds-web-grid.min.css`
`ouds-web-grid.rtl.min.css` | — | — | — | [Only flex utilities]({{< docsref "/utilities/flex" >}}) | | `ouds-web-utilities.css`
`ouds-web-utilities.rtl.css`
`ouds-web-utilities.min.css`
`ouds-web-utilities.rtl.min.css` | — | — | — | Included | | `ouds-web-reboot.css`
`ouds-web-reboot.rtl.css`
`ouds-web-reboot.min.css`
`ouds-web-reboot.rtl.min.css` | — | — | — | — | diff --git a/site/content/docs/0.0/migration-from-boosted.md b/site/content/docs/0.0/migration-from-boosted.md index 1ef434891c..d21f646eed 100644 --- a/site/content/docs/0.0/migration-from-boosted.md +++ b/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.** diff --git a/site/content/docs/0.0/migration.md b/site/content/docs/0.0/migration.md index d99a532ddd..ed219dc403 100644 --- a/site/content/docs/0.0/migration.md +++ b/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 - New `$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" >}}). - New OUDS Web fully implements the design tokens. If you were using the Sass compilation, you must import the new Sass files before the variables. diff --git a/site/layouts/shortcodes/bootstrap-compatibility.html b/site/layouts/shortcodes/bootstrap-compatibility.html index c4702ee19c..40186a025a 100644 --- a/site/layouts/shortcodes/bootstrap-compatibility.html +++ b/site/layouts/shortcodes/bootstrap-compatibility.html @@ -5,7 +5,7 @@ {{- if $markdown -}}