From 9db1ce9e11a9f2470671e2a4d70e7a18ddb410d1 Mon Sep 17 00:00:00 2001 From: "louismaxime.piton" Date: Tue, 17 Dec 2024 11:29:15 +0100 Subject: [PATCH] Add background utilities to the Colors tokens PR --- hugo.yml | 2 + js/tests/visual/dropdown.html | 2 +- js/tests/visual/modal.html | 2 +- js/tests/visual/scrollspy.html | 2 +- js/tests/visual/toast.html | 4 +- scss/_config.scss | 3 + scss/_functions.scss | 4 + scss/_grid.scss | 2 +- scss/_maps.scss | 25 ++ scss/_mixins.scss | 2 +- scss/_reboot.scss | 2 +- scss/_root.scss | 8 +- scss/_utilities.scss | 18 +- scss/_variables.scss | 4 +- scss/mixins/_color-mode.scss | 21 +- .../_ouds-web-bootstrap-utilities.test.scss | 371 ++++++++++++++++- scss/tests/mixins/_color-modes.test.scss | 8 +- .../tokens/_semantic-colors-custom-props.scss | 9 +- site/assets/scss/_callouts.scss | 4 +- site/assets/scss/_component-examples.scss | 12 +- site/assets/scss/_masthead.scss | 2 +- site/assets/scss/_ouds-web.scss | 2 +- site/assets/scss/_search.scss | 10 +- site/assets/scss/_subnav.scss | 2 +- site/assets/scss/_syntax.scss | 3 +- site/assets/scss/_tarteaucitron.scss | 4 +- site/assets/scss/_toc.scss | 2 +- site/assets/scss/_variables.scss | 7 +- .../content/docs/0.0/customize/color-modes.md | 390 +++++++++++++++++- .../docs/0.0/customize/color-palette.md | 5 +- .../docs/0.0/customize/custom-libraries.md | 37 ++ .../docs/0.0/examples/grid-system/index.html | 2 +- site/content/docs/0.0/helpers/clearfix.md | 2 +- site/content/docs/0.0/helpers/icon.md | 14 +- .../docs/0.0/helpers/stretched-link.md | 4 +- site/content/docs/0.0/utilities/api.md | 15 +- site/content/docs/0.0/utilities/background.md | 266 +++++++++++- site/content/docs/0.0/utilities/opacity.md | 22 +- site/content/docs/0.0/utilities/overflow.md | 2 +- site/content/docs/0.0/utilities/shadows.md | 24 +- site/content/docs/0.0/utilities/text.md | 2 +- site/data/sidebar.yml | 2 - site/layouts/partials/skippy.html | 4 +- 43 files changed, 1221 insertions(+), 107 deletions(-) diff --git a/hugo.yml b/hugo.yml index 68e404cb66..beef87dd95 100644 --- a/hugo.yml +++ b/hugo.yml @@ -80,6 +80,8 @@ params: icons_license: "https://design.orange.com/0c1af118d/p/92bb17-usage/t/63532c" icons_usage: "https://design.orange.com/0c1af118d/p/92bb17-usage" bootstrap: "https://getbootstrap.com" + ouds: + web: "https://unified-design-system.orange.com/" # TODO LM: replace this URL by the web one or even "https://oran.ge/ds-web" when it will changed algolia: appId: "F4PKENW3TB" diff --git a/js/tests/visual/dropdown.html b/js/tests/visual/dropdown.html index 928df91931..711a48b991 100644 --- a/js/tests/visual/dropdown.html +++ b/js/tests/visual/dropdown.html @@ -10,7 +10,7 @@

Dropdown Bootstrap Visual Test

-
diff --git a/site/content/docs/0.0/helpers/clearfix.md b/site/content/docs/0.0/helpers/clearfix.md index 1a20b1009a..f68bff2fe5 100644 --- a/site/content/docs/0.0/helpers/clearfix.md +++ b/site/content/docs/0.0/helpers/clearfix.md @@ -33,7 +33,7 @@ Use the mixin in SCSS: - +/* ... */ +.bg-transparent { + --bs-bg-opacity: 1; + background-color: transparent !important; +} +``` ### States diff --git a/site/content/docs/0.0/utilities/background.md b/site/content/docs/0.0/utilities/background.md index 4aaa138bc6..ca5053404f 100644 --- a/site/content/docs/0.0/utilities/background.md +++ b/site/content/docs/0.0/utilities/background.md @@ -8,4 +8,268 @@ aliases: toc: true --- -{{< callout-soon "page" >}} +{{< callout info >}} +{{< partial "callouts/warning-color-assistive-technologies.md" >}} +{{< /callout >}} + +## Background color + +Background utilities like `.bg-*` are generated from our `$ouds-backgrounds` Sass map and respond to color modes. + +Similar to the contextual text color classes, set the background of an element to any contextual class. Background utilities **do not set `color`**, so depending on the cases you'll want to use an additional: +* `[data-bs-theme]` [color mode attribute]({{< docsref "/customize/color-modes#how-to-use" >}}) when the element using a background utility contains complex sub-elements such as components that need to respond to color modes + + +{{< bootstrap-compatibility >}} + +Here are the equivalent Bootstrap background that you shouldn't be using. Prefer using the classes above according to [our design system]({{< param ouds.web >}}). + + +{{< example >}} +{{< colors.inline >}} +{{- range (index $.Site.Data "theme-colors") }} +
.bg-{{ .name }}
+
.bg-{{ .name }}-subtle
+{{- end -}} +{{< /colors.inline >}} +
.bg-body-secondary
+
.bg-body-tertiary
+
.bg-body
+
.bg-black
+
.bg-white
+
.bg-transparent
+{{< /example >}} + +{{< /bootstrap-compatibility >}} + +### `data-bs-theme` attribute + +Here are the nominal cases you should be using, when there is no other theme interferences than the root one, using `data-bs-theme` attribute: + +{{< callout info >}} +Please note that we use `[data-bs-theme]` attribute on a child element to avoid interfering with the parent theme. This is a workaround to avoid switching the colors between light and dark modes and keep having the good ones displayed. +{{< /callout >}} + +{{< example >}} +

.bg-primary

+

.bg-secondary

+

.bg-tertiary

+

.bg-emphasized

+

.bg-brand-primary

+

.bg-status-neutral-emphasized

+

.bg-status-neutral-muted

+

.bg-status-accent-emphasized

+

.bg-status-accent-muted

+

.bg-status-positive-emphasized

+

.bg-status-positive-muted

+

.bg-status-negative-emphasized

+

.bg-status-negative-muted

+

.bg-status-warning-emphasized

+

.bg-status-warning-muted

+

.bg-status-info-emphasized

+

.bg-status-info-muted

+

.bg-always-black

+

.bg-always-white

+

.bg-transparent

+{{< /example >}} + +#### Inside a static theme + +Here is a more complex example to understand how to use `[data-bs-theme]` in specific static contexts. In here you should only use the inverse static theme by replacing all `data-bs-theme="root-inverted"` by `data-bs-theme="light"`. So if you're in a dark theme context, use only `data-bs-theme="light"` when and if needed and respectively. + +
+ You're in a static light context + + {{< example class="p-none" >}} +
+
+

.bg-primary

+

.bg-secondary

+

.bg-tertiary

+

.bg-emphasized

+

.bg-brand-primary

+

.bg-status-neutral-emphasized

+

.bg-status-neutral-muted

+

.bg-status-accent-emphasized

+

.bg-status-accent-muted

+

.bg-status-positive-emphasized

+

.bg-status-positive-muted

+

.bg-status-negative-emphasized

+

.bg-status-negative-muted

+

.bg-status-warning-emphasized

+

.bg-status-warning-muted

+

.bg-status-info-emphasized

+

.bg-status-info-muted

+

.bg-always-black

+

.bg-always-white

+

.bg-transparent

+
+
+ {{< /example >}} + +
+ +
+ You're in a static dark context + + {{< example class="p-none" >}} +
+
+

.bg-primary

+

.bg-secondary

+

.bg-tertiary

+

.bg-emphasized

+

.bg-brand-primary

+

.bg-status-neutral-emphasized

+

.bg-status-neutral-muted

+

.bg-status-accent-emphasized

+

.bg-status-accent-muted

+

.bg-status-positive-emphasized

+

.bg-status-positive-muted

+

.bg-status-negative-emphasized

+

.bg-status-negative-muted

+

.bg-status-warning-emphasized

+

.bg-status-warning-muted

+

.bg-status-info-emphasized

+

.bg-status-info-muted

+

.bg-always-black

+

.bg-always-white

+

.bg-transparent

+
+
+ {{< /example >}} + +
+ +#### Inside a dynamic theme + +Here is a more complex example to understand how to use `[data-bs-theme]` in specific dynamic contexts. In here you should only replace `data-bs-theme="root-inverted"` by `data-bs-theme="root"` and respectively. + +
+ You're in a dynamic root-inverted context + + {{< example class="p-none" >}} +
+
+

.bg-primary

+

.bg-secondary

+

.bg-tertiary

+

.bg-emphasized

+

.bg-brand-primary

+

.bg-status-neutral-emphasized

+

.bg-status-neutral-muted

+

.bg-status-accent-emphasized

+

.bg-status-accent-muted

+

.bg-status-positive-emphasized

+

.bg-status-positive-muted

+

.bg-status-negative-emphasized

+

.bg-status-negative-muted

+

.bg-status-warning-emphasized

+

.bg-status-warning-muted

+

.bg-status-info-emphasized

+

.bg-status-info-muted

+

.bg-always-black

+

.bg-always-white

+

.bg-transparent

+
+
+ {{< /example >}} + +
+ + + + + +## CSS + + + +### Sass tokens + +#### Raw tokens + +Colors raw tokens as Sass variables. **Not to be used as-is**. + +{{< scss-docs name="ouds-raw-color" file="scss/tokens/_raw.scss" >}} + +#### Semantic tokens + +Color semantic tokens as Sass variables. **Should not be used as-is**. Prefer use our [CSS semantic tokens](#css-semantic-tokens). + +{{< scss-docs name="ouds-semantic-color" file="scss/tokens/_semantic.scss" >}} + +### CSS semantic tokens + +Color semantic tokens as CSS variables. + +{{< scss-docs name="ouds-semantic-css-color" file="scss/tokens/_semantic-colors-custom-props.scss" >}} + +The same happens for the dark mode by replacing `-light` by `-dark`. + + + +### Sass variables + + + + + + + +Grayscale colors are also available, but only a subset are used to generate any utilities. + +{{< scss-docs name="gray-color-variables" file="scss/_variables.scss" >}} + +Variables for setting `background-color` in `.bg-*-subtle` utilities in light and dark mode: + +{{< scss-docs name="theme-bg-subtle-variables" file="scss/_variables.scss" >}} + +{{< scss-docs name="theme-bg-subtle-dark-variables" file="scss/_variables-dark.scss" >}} + +### Sass maps + +Theme colors are then put into a Sass map so we can loop over them to generate our utilities, component modifiers, and more. + +{{< scss-docs name="theme-colors-map" file="scss/_variables.scss" >}} + +{{< scss-docs name="theme-colors-dark-map" file="scss/_variables-dark.scss" >}} + +Grayscale colors are also available as a Sass map. **This map is not used to generate any utilities.** + +{{< scss-docs name="gray-colors-map" file="scss/_variables.scss" >}} + +RGB colors are generated from a separate Sass map: + +{{< scss-docs name="theme-colors-rgb" file="scss/_maps.scss" >}} + +{{< scss-docs name="theme-colors-rgb-dark" file="scss/_maps.scss" >}} + +Background color opacities build on that with their own map that's consumed by the utilities API: + +{{< scss-docs name="utilities-bg-colors" file="scss/_maps.scss" >}} + +Color mode background colors are also available as a Sass map: + +{{< scss-docs name="theme-bg-subtle-map" file="scss/_maps.scss" >}} + +{{< scss-docs name="theme-bg-subtle-dark-map" file="scss/_maps.scss" >}} + +### Sass mixins + +**No mixins are used to generate our background utilities**, but we do have some additional mixins for other situations where you'd like to create your own gradients. + +{{< scss-docs name="gradient-bg-mixin" file="scss/mixins/_gradients.scss" >}} + + + +### Sass utilities API + +Background utilities are declared in our utilities API in `scss/_utilities.scss`. [Learn how to use the utilities API.]({{< docsref "/utilities/api#using-the-api" >}}) + +{{< scss-docs name="utils-bg-color" file="scss/_utilities.scss" >}} diff --git a/site/content/docs/0.0/utilities/opacity.md b/site/content/docs/0.0/utilities/opacity.md index 4a224a8ab0..b53a6dd483 100644 --- a/site/content/docs/0.0/utilities/opacity.md +++ b/site/content/docs/0.0/utilities/opacity.md @@ -13,12 +13,12 @@ The `opacity` property sets the opacity level for an element. The opacity level Set the opacity of an element using `.opacity-{value}` utilities.
-
-
-
-
-
-
+
+
+
+
+
+
```html @@ -41,11 +41,11 @@ Set the `opacity` of an element using `.opacity-{value}` utilities. - Removed div text content to avoid a11y issue with semi-transparent text -->
-
-
-
-
-
+
+
+
+
+
```html diff --git a/site/content/docs/0.0/utilities/overflow.md b/site/content/docs/0.0/utilities/overflow.md index 0bd0ae6407..82d5b91209 100644 --- a/site/content/docs/0.0/utilities/overflow.md +++ b/site/content/docs/0.0/utilities/overflow.md @@ -51,7 +51,7 @@ Adjust the `overflow-x` property to affect the overflow of content horizontally.
.overflow-x-visible example
on an element with set width and height dimensions.
-
+
.overflow-x-scroll example on an element
with set width and height dimensions.
diff --git a/site/content/docs/0.0/utilities/shadows.md b/site/content/docs/0.0/utilities/shadows.md index 13ede6d34c..3259e8561a 100644 --- a/site/content/docs/0.0/utilities/shadows.md +++ b/site/content/docs/0.0/utilities/shadows.md @@ -18,14 +18,14 @@ Box-shadow styles are referred to as 'elevation' within the design system. You can quickly add or remove a shadow with our `box-shadow` utility classes. Includes support for `.shadow-none` and new semantic helpers. {{< example class="overflow-hidden" >}} -
No shadow
-
Default shadow
-
Drag shadow
-
Emphasized shadow
-
Raised shadow
-
Sticky default shadow
-
Sticky emphasized shadow
-
Sticky navigation shadow
+
No shadow
+
Default shadow
+
Drag shadow
+
Emphasized shadow
+
Raised shadow
+
Sticky default shadow
+
Sticky emphasized shadow
+
Sticky navigation shadow
{{< /example >}} {{< bootstrap-compatibility >}} @@ -33,10 +33,10 @@ You can quickly add or remove a shadow with our `box-shadow` utility Includes support for three default sizes (which have associated variables to match). {{< example class="overflow-hidden" >}} -
No shadow
-
Small shadow
-
Regular shadow
-
Larger shadow
+
No shadow
+
Small shadow
+
Regular shadow
+
Larger shadow
{{< /example >}} {{< /bootstrap-compatibility >}} diff --git a/site/content/docs/0.0/utilities/text.md b/site/content/docs/0.0/utilities/text.md index 84ce8425a4..b613ce7694 100644 --- a/site/content/docs/0.0/utilities/text.md +++ b/site/content/docs/0.0/utilities/text.md @@ -47,7 +47,7 @@ Wrap text with a `.text-wrap` class. Prevent text from wrapping with a `.text-nowrap` class. {{< example >}} -
+
This text should overflow the parent.
{{< /example >}} diff --git a/site/data/sidebar.yml b/site/data/sidebar.yml index 9847e431ee..ec5a101d6a 100644 --- a/site/data/sidebar.yml +++ b/site/data/sidebar.yml @@ -39,7 +39,6 @@ - title: Color theme draft: true - title: Color modes - draft: true - title: Components draft: true - title: CSS variables @@ -194,7 +193,6 @@ pages: - title: API - title: Background - draft: true - title: Borders - title: Colors draft: true diff --git a/site/layouts/partials/skippy.html b/site/layouts/partials/skippy.html index 6f13333da5..ad4eb1a968 100644 --- a/site/layouts/partials/skippy.html +++ b/site/layouts/partials/skippy.html @@ -1,9 +1,9 @@