diff --git a/scss/_maps.scss b/scss/_maps.scss index 04e247adff..7cbe5d955f 100644 --- a/scss/_maps.scss +++ b/scss/_maps.scss @@ -141,6 +141,27 @@ $ouds-backgrounds: ( "transparent": transparent, ) !default; // scss-docs-end ouds-maps-opacities + +// scss-docs-start ouds-maps-text-colors +$ouds-text-colors: ( + "brand-primary": var(--#{$prefix}color-content-brand-primary), + "default": var(--#{$prefix}color-content-default), + "disabled": var(--#{$prefix}color-content-disabled), + "muted": var(--#{$prefix}color-content-muted), + "on-brand-primary": var(--#{$prefix}color-content-on-brand-primary), + "on-status-emphasized": var(--#{$prefix}color-content-on-status-emphasized), + "on-status-emphasized-alt": var(--#{$prefix}color-content-on-status-emphasized-alt), + "on-status-muted": var(--#{$prefix}color-content-on-status-muted), + "status-info": var(--#{$prefix}color-content-status-info), + "status-negative": var(--#{$prefix}color-content-status-negative), + "status-positive": var(--#{$prefix}color-content-status-positive), + "status-warning": var(--#{$prefix}color-content-status-warning), + "always-black": var(--#{$prefix}color-always-black), + "always-white": var(--#{$prefix}color-always-white), + "always-on-black": var(--#{$prefix}color-always-on-black), + "always-on-white": var(--#{$prefix}color-always-on-white), +) !default; +// scss-docs-end ouds-maps-text-colors // End mod // Re-assigned maps diff --git a/scss/_utilities.scss b/scss/_utilities.scss index 5c34472a45..897c663fe1 100644 --- a/scss/_utilities.scss +++ b/scss/_utilities.scss @@ -980,7 +980,8 @@ $utilities: map-merge( "body-emphasis": var(--#{$prefix}emphasis-color), "reset": inherit, ) - ) + ), + bootstrap-compatibility: true ), "text-opacity": ( css-var: true, @@ -990,14 +991,23 @@ $utilities: map-merge( 50: .5, 75: .75, 100: 1 - ) + ), + bootstrap-compatibility: true ), "text-color": ( property: color, class: text, - values: $utilities-text-emphasis-colors + values: $utilities-text-emphasis-colors, + bootstrap-compatibility: true ), // scss-docs-end utils-color + // scss-docs-start utils-color-ouds + "color-ouds": ( + property: color, + class: text, + values: $ouds-text-colors + ), + // scss-docs-end utils-color-ouds // scss-docs-start utils-links "link-opacity": ( css-var: true, diff --git a/site/content/docs/0.0/content/typography.md b/site/content/docs/0.0/content/typography.md index b71c14020f..bf31a69ad7 100644 --- a/site/content/docs/0.0/content/typography.md +++ b/site/content/docs/0.0/content/typography.md @@ -240,7 +240,7 @@ While not shown above, feel free to use `` and `` in HTML5. `` is meant ## Text utilities -Change text alignment, transform, style, weight, line-height, decoration with our [text utilities]({{< docsref "/utilities/text" >}}). +Change text alignment, transform, style, weight, line-height, decoration and color with our [text utilities]({{< docsref "/utilities/text" >}}) and [color utilities]({{< docsref "/utilities/colors" >}}). ## Abbreviations diff --git a/site/content/docs/0.0/customize/color-palette.md b/site/content/docs/0.0/customize/color-palette.md index 7903bb3026..90294c5d6a 100644 --- a/site/content/docs/0.0/customize/color-palette.md +++ b/site/content/docs/0.0/customize/color-palette.md @@ -128,8 +128,7 @@ Here's how you should use these in your Sass: } ``` - -[Background]({{< docsref "/utilities/background" >}}) utility classes are also available for setting `background-color`. +[Color]({{< docsref "/utilities/colors" >}}) and [Background]({{< docsref "/utilities/background" >}}) utility classes are also available for setting `color` and `background-color`. ## CSS diff --git a/site/content/docs/0.0/getting-started/accessibility.md b/site/content/docs/0.0/getting-started/accessibility.md index a1005b9e44..d7cb0c237a 100644 --- a/site/content/docs/0.0/getting-started/accessibility.md +++ b/site/content/docs/0.0/getting-started/accessibility.md @@ -24,7 +24,7 @@ OUDS Web's interactive components +* `[data-bs-theme]` [color mode attribute]({{< docsref "/customize/color-modes#how-to-use" >}}) is the best option all the time and moreover when the element using a background utility contains complex sub-elements such as components that need to respond to color modes +* `.text-*` [color utilities]({{< docsref "/utilities/colors" >}}) when the background color remains the same in light and dark mode + {{< bootstrap-compatibility >}} diff --git a/site/content/docs/0.0/utilities/colors.md b/site/content/docs/0.0/utilities/colors.md index 1e707516dd..8d16a63e1f 100644 --- a/site/content/docs/0.0/utilities/colors.md +++ b/site/content/docs/0.0/utilities/colors.md @@ -8,4 +8,228 @@ aliases: toc: true --- -{{< callout-soon "page" >}} +{{< callout info >}} +{{< partial "callouts/warning-color-assistive-technologies.md" >}} +{{< /callout >}} + +## Colors + +Colorize text with color utilities. + + +OUDS Web provides many `.text-*` and `.bg-*` utilities, but they should be used with care to meet our design specifications and [WCAG 2.2 accessibility standards for color contrast](https://www.w3.org/TR/WCAG/#distinguishable). +To be sure to respect the specifications, it is necessary to define `color`, `background-color` and `font-size` altogether. + +Thus, the `.text-primary` color on white background (`#f16e00`) can only be used in a font size greater than 24px (using for example `.fs-3` utility), or 19px bold (using for example `.fs-4` and `.fw-bold` utilities). +The `.text-primary` color on dark background (`#ff7900`) can be used in any size, and it shouldn't be used on light grey backgrounds at all. + +Here are some compliant combinations examples for texts: + +{{< example >}} +
+

Text brand-primary

+

Text default

+

Text disabled

+

Text muted

+

Text on-brand-primary

+

Text on-status-emphasized

+

Text on-status-emphasized-alt

+

Text on-status-muted

+

Text status-info

+

Text status-negative

+

Text status-positive

+

Text status-warning

+

Text always-black

+

Text always-white

+

Text always-on-black

+

Text always-on-white

+
+{{< /example >}} + + + +If you don't see the couple you need, please mind using one of the table + +{{< bs-table >}} +| Font reference | Allowed `.text-*` and `.bg-*` couples | +| --- | --- | +| All `font-sizes`/`font-weight` are allowed | | +| | | +| | | +{{< /bs-table >}} + +{{< callout warning >}} +When the interface allows to switch between light and dark backgrounds, the light mode stricter restrictions must be applied! +{{< /callout >}} + + + + + + + +## Specificity + +Sometimes contextual classes cannot be applied due to the specificity of another selector. In some cases, a sufficient workaround is to wrap your element's content in a `
` or more semantic element with the desired class. + +## CSS + + + +In addition to the following Sass functionality, consider reading about our included [CSS custom properties]({{< docsref "/customize/css-variables" >}}) (aka CSS variables) for colors and more. + +### Sass variables + +Most `color` utilities are generated by our theme colors, reassigned from our generic color palette variables. + + +Boosted supersedes Bootstrap color variables with Orange brand color. + +{< scss-docs name="brand-colors" file="scss/_variables.scss" >}} + +{< scss-docs name="brand-colors-dark" file="scss/_variables-dark.scss" >}} + +{{< scss-docs name="color-variables" file="scss/_variables.scss" >}} + +{{< scss-docs name="theme-color-variables" file="scss/_variables.scss" >}} + +{{< scss-docs name="theme-color-dark-variables" file="scss/_variables-dark.scss" >}} + +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" >}} + +{{< scss-docs name="theme-text-map" file="scss/_maps.scss" >}} + +Variables for setting colors in `.text-*-emphasis` utilities in light and dark mode: + +{{< scss-docs name="theme-text-variables" file="scss/_variables.scss" >}} + +{{< scss-docs name="theme-text-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" >}} + +Color opacities build on that with their own map that's consumed by the utilities API: + +{{< scss-docs name="utilities-text-colors" file="scss/_maps.scss" >}} + +Color mode adaptive text colors are also available as a Sass map: + +{{< scss-docs name="theme-text-map" file="scss/_maps.scss" >}} + +{{< scss-docs name="theme-text-dark-map" file="scss/_maps.scss" >}} + +### Sass utilities API + +Color 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-color" file="scss/_utilities.scss" >}} diff --git a/site/data/sidebar.yml b/site/data/sidebar.yml index ec5a101d6a..92ccd96176 100644 --- a/site/data/sidebar.yml +++ b/site/data/sidebar.yml @@ -195,7 +195,6 @@ - title: Background - title: Borders - title: Colors - draft: true - title: Display - title: Flex - title: Float