From 8cb896db41ef17577941067991a2a805d7f661e4 Mon Sep 17 00:00:00 2001 From: yarusome <97945148+yarusome@users.noreply.github.com> Date: Mon, 17 Jul 2023 16:05:41 +0800 Subject: [PATCH] Document missing color components (#27523) * Update `` * Update `color()` * Fix link id * Improve punctuation and simplify wording * Apply suggestions from code review Co-authored-by: Brian Thomas Smith * Tweak * Add missing components info to all color functions * Update analogous components See https://github.com/w3c/csswg-drafts/commit/238064bb0e17a64a5e2ac0c1407bac2baae0f55a. * Apply suggestions from code review Co-authored-by: Brian Thomas Smith * Tweak `` --------- Co-authored-by: Brian Thomas Smith --- .../en-us/web/css/color_value/color/index.md | 10 ++- files/en-us/web/css/color_value/hsl/index.md | 10 ++- files/en-us/web/css/color_value/hwb/index.md | 8 +- files/en-us/web/css/color_value/index.md | 87 +++++++++++++++++++ files/en-us/web/css/color_value/lab/index.md | 17 ++-- files/en-us/web/css/color_value/lch/index.md | 10 ++- .../en-us/web/css/color_value/oklab/index.md | 15 ++-- .../en-us/web/css/color_value/oklch/index.md | 10 ++- files/en-us/web/css/color_value/rgb/index.md | 10 +-- 9 files changed, 130 insertions(+), 47 deletions(-) diff --git a/files/en-us/web/css/color_value/color/index.md b/files/en-us/web/css/color_value/color/index.md index eae1f61251ee08d..3a91612c3356913 100644 --- a/files/en-us/web/css/color_value/color/index.md +++ b/files/en-us/web/css/color_value/color/index.md @@ -20,19 +20,21 @@ color(display-p3 1 0.5 0 / .5); ### Values -Functional notation: `color(colorspace p1 p2 p3[ / A])` +Functional notation: `color(colorspace c1 c2 c3[ / A])` - `colorspace` - : An {{CSSXref("<ident>")}} denoting one of the predefined color spaces: `srgb`, `srgb-linear`, `display-p3`, `a98-rgb`, `prophoto-rgb`, `rec2020`, `xyz`, `xyz-d50`, and `xyz-d65`. -- `p1`, `p2`, `p3` +- `c1`, `c2`, `c3` - - : {{CSSXref("number")}} or {{CSSXref("percentage")}} values providing the parameter values that the color space takes. + - : {{CSSXref("number")}}, {{CSSXref("percentage")}} values or the keyword `none`, which provide the component values in the color space. - `A` {{optional_inline}} - - : An {{CSSXref("<alpha-value>")}}, where the number `1` corresponds to `100%` (full opacity). + - : An {{CSSXref("<alpha-value>")}} or the keyword `none`, where the number `1` corresponds to `100%` (full opacity). + +> **Note:** See [Missing color components](/en-US/docs/Web/CSS/color_value#missing_color_components) for the effect of `none`. ### Formal syntax diff --git a/files/en-us/web/css/color_value/hsl/index.md b/files/en-us/web/css/color_value/hsl/index.md index 11892c2ac7817f2..8fc7d38533df5a1 100644 --- a/files/en-us/web/css/color_value/hsl/index.md +++ b/files/en-us/web/css/color_value/hsl/index.md @@ -29,13 +29,15 @@ The function also accepts a legacy syntax in which all values are separated with Functional notation: `hsl(H S L[ / A])` - `H` - - : A {{CSSXref("<number>")}} or an {{CSSXref("<angle>")}} representing the hue angle. More details on this type can be found on the {{CSSXref("<hue>")}} reference. + - : A {{CSSXref("<number>")}}, an {{CSSXref("<angle>")}}, or the keyword `none`, which represents the hue angle. More details on this type can be found on the {{CSSXref("<hue>")}} reference. - `S` - - : A {{CSSXref("<percentage>")}} representing saturation, where `100%` is completely saturated, while `0%` is completely unsaturated (gray). + - : A {{CSSXref("<percentage>")}} or the keyword `none`, which represents saturation. Here `100%` is completely saturated, while `0%` is completely unsaturated (gray). - `L` - - : A {{CSSXref("<percentage>")}} representing lightness, where `100%` is white, `0%` is black, and `50%` is "normal". + - : A {{CSSXref("<percentage>")}} or the keyword `none`, which represents lightness. Here `100%` is white, `0%` is black, and `50%` is "normal". - `A` {{optional_inline}} - - : An {{CSSXref("<alpha-value>")}}, where the number `1` corresponds to `100%` (full opacity). + - : An {{CSSXref("<alpha-value>")}} or the keyword `none`, where the number `1` corresponds to `100%` (full opacity). + +> **Note:** See [Missing color components](/en-US/docs/Web/CSS/color_value#missing_color_components) for the effect of `none`. ### Formal syntax diff --git a/files/en-us/web/css/color_value/hwb/index.md b/files/en-us/web/css/color_value/hwb/index.md index 12eb0b1e3acc593..39f223dbe9f02a2 100644 --- a/files/en-us/web/css/color_value/hwb/index.md +++ b/files/en-us/web/css/color_value/hwb/index.md @@ -24,17 +24,19 @@ Functional notation: `hwb(H W B[ / A])` - `H` - - : A {{CSSXref("<number>")}} or an {{CSSXref("<angle>")}} representing the hue angle. More details on this type can be found on the {{CSSXref("<hue>")}} reference. + - : A {{CSSXref("<number>")}}, an {{CSSXref("<angle>")}}, or the keyword `none`, which represents the hue angle. More details on this type can be found on the {{CSSXref("<hue>")}} reference. - `W`, `B` - - : {{CSSXref("<percentage>")}} representing whiteness and blackness, respectively, that specifies the amount of white and black to mix in, from 0% (no whiteness or blackness) to 100% (full whiteness or blackness). + - : Each as a {{CSSXref("<percentage>")}} or the keyword `none`, which represent whiteness and blackness, respectively. They specify the amount of white and black to mix in, from `0%` (no whiteness or blackness) to `100%` (full whiteness or blackness). If `W + B = 100%`, it defines some shade of gray. If `W + B > 100%`, `W` and `B` are effectively normalized as `W / (W + B)` and `B / (W + B)`, respectively. - `A` {{optional_inline}} - - : An {{CSSXref("<alpha-value>")}}, where the number `1` corresponds to `100%` (full opacity). + - : An {{CSSXref("<alpha-value>")}} or the keyword `none`, where the number `1` corresponds to `100%` (full opacity). + +> **Note:** See [Missing color components](/en-US/docs/Web/CSS/color_value#missing_color_components) for the effect of `none`. ### Formal syntax diff --git a/files/en-us/web/css/color_value/index.md b/files/en-us/web/css/color_value/index.md index 317ceec1a51ee51..ed4605cfb6fc3ea 100644 --- a/files/en-us/web/css/color_value/index.md +++ b/files/en-us/web/css/color_value/index.md @@ -79,12 +79,99 @@ If `currentcolor` is used as the value of the `color` property, it instead takes {{EmbedLiveSample("currentcolor_keyword", "100%", 80)}} +### Missing color components + +Each component of any CSS color functions - except for those using the legacy comma-separated syntax - can be specified as the keyword `none` to be a missing component. + +Explicitly specifying missing components is useful in [color interpolation](#interpolation_with_missing_components) for cases where you would like to interpolate some color components but not others. For all other purposes, a missing component will effectively have a zero value in an appropriate unit: `0`, `0%`, or `0deg`. For example, the following colors are equivalent when used outside of interpolation: + +```css +/* These are equivalent */ +color: oklab(50% none -0.25); +color: oklab(50% 0 -0.25); + +/* These are equivalent */ +background-color: hsl(none 100% 50%); +background-color: hsl(0deg 100% 50%); +``` + ## Interpolation Color interpolation happens with [gradients](/en-US/docs/Web/CSS/gradient), [transitions](/en-US/docs/Web/CSS/CSS_transitions/Using_CSS_transitions), and [animations](/en-US/docs/Web/CSS/CSS_animations/Using_CSS_animations). When interpolating `` values, they are first converted to a given color space, and then each component of the [computed values](/en-US/docs/Web/CSS/computed_value) are interpolated linearly, with interpolation's speed being determined by the [timing function](/en-US/docs/Web/CSS/easing-function) in transitions and animations. The interpolation color space defaults to Oklab, but can be overridden through {{CSSXref("<color-interpolation-method>")}} in some color-related functional notations. +### Interpolation with missing components + +#### Interpolating colors in the same space + +When interpolating colors that are exactly in the interpolation color space, missing components from one color are replaced with existing values of the same components from the other color. +For example, the following two expressions are equivalent: + +```css +color-mix(in oklch, oklch(none 0.2 10), oklch(60% none 30)) +color-mix(in oklch, oklch(60% 0.2 10), oklch(60% 0.2 30)) +``` + +> **Note:** If a component is missing from both colors, this component will be missing after the interpolation. + +#### Interpolating colors from different spaces: analogous components + +If any color to be interpolated is not in the interpolation color space, its missing components are transferred into the converted color based on **analogous components** of the same category as described in the following table: + +| Category | Analogous components | +| ------------ | -------------------- | +| Reds | `R`, `X` | +| Greens | `G`, `Y` | +| Blues | `B`, `Z` | +| Lightness | `L` | +| Colorfulness | `C`, `S` | +| Hue | `H` | +| a | `a` | +| b | `b` | + +For example: + +- `X` (`0.2`) in `color(xyz 0.2 0.1 0.6)` is analogous to `R` (`50%`) in `rgb(50% 70% 30%)`. +- `H` (`0deg`) in `hsl(0deg 100% 80%)` is analogous to `H` (`140`) in `oklch(80% 0.1 140)`. + +Using Oklch as the interpolation color space and the two colors below as an example: + +```css +lch(80% 30 none) +color(display-p3 0.7 0.5 none) +``` + +the preprocessing procedure is: + +1. Replace the missing components in both colors with a zero value: + + ```css + lch(80% 30 0) + color(display-p3 0.7 0.5 0) + ``` + +2. Convert both colors into the interpolation color space: + + ```css + oklch(83.915% 0.0902 0.28) + oklch(63.612% 0.1522 78.748) + ``` + +3. If any component of the converted colors is analogous to a missing component in the corresponding original color, reset it as a missing component: + + ```css + oklch(83.915% 0.0902 none) + oklch(63.612% 0.1522 78.748) + ``` + +4. Replace any missing component with the same component from the other converted color: + + ```css + oklch(83.915% 0.0902 78.748) + oklch(63.612% 0.1522 78.748) + ``` + ## Accessibility considerations Some people have difficulty distinguishing colors. The [WCAG 2.2](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable/Use_of_color) recommendation strongly advises against using color as the only means of conveying a specific message, action, or result. See [color and color contrast](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable/Color_contrast) for more information. diff --git a/files/en-us/web/css/color_value/lab/index.md b/files/en-us/web/css/color_value/lab/index.md index bd93b12ab453a05..da96f4e63dd22d2 100644 --- a/files/en-us/web/css/color_value/lab/index.md +++ b/files/en-us/web/css/color_value/lab/index.md @@ -22,24 +22,19 @@ lab(52.2345% 40.1645 59.9971 / .5); Functional notation: `lab(L a b[ / A])` - `L` - - - : A {{CSSXref("<number>")}} between `0` and `100` or a {{CSSXref("<percentage>")}} between `0%` and `100%` that specifies the CIE Lightness where the number `0` corresponds to `0%` (black) and the number `100` corresponds to `100%` (white). - + - : A {{CSSXref("<number>")}} between `0` and `100`, a {{CSSXref("<percentage>")}} between `0%` and `100%`, or the keyword `none`, which specifies the CIE Lightness. Here the number `0` corresponds to `0%` (black) and the number `100` corresponds to `100%` (white). - `a` - - - : A {{CSSXref("<number>")}} between `-125` and `125` or a {{CSSXref("<percentage>")}} between `-100%` and `100%`, specifying the distance along the `a` axis in the Lab colorspace, that is how green/red the color is. - + - : A {{CSSXref("<number>")}} between `-125` and `125`, a {{CSSXref("<percentage>")}} between `-100%` and `100%`, or the keyword `none`, which specifies the distance along the `a` axis in the CIELAB colorspace, that is how green/red the color is. - `b` - - - : A {{CSSXref("<number>")}} between `-125` and `125` or a {{CSSXref("<percentage>")}} between `-100%` and `100%`, specifying the distance along the `b` axis in the Lab colorspace, that is how blue/yellow the color is. - + - : A {{CSSXref("<number>")}} between `-125` and `125`, a {{CSSXref("<percentage>")}} between `-100%` and `100%`, or the keyword `none`, which specifies the distance along the `b` axis in the CIELAB colorspace, that is how blue/yellow the color is. - `A` {{optional_inline}} - - - : An {{CSSXref("<alpha-value>")}}, where the number `1` corresponds to `100%` (full opacity). + - : An {{CSSXref("<alpha-value>")}} or the keyword `none`, where the number `1` corresponds to `100%` (full opacity). > **Note:** Usually when percentage values have a numeric equivalent in CSS, `100%` is equal to the number `1`. > This case is notable where `100%` is equal to the number `100` for the `L` value and `125` for the `a` and `b` values. +> **Note:** See [Missing color components](/en-US/docs/Web/CSS/color_value#missing_color_components) for the effect of `none`. + ### Formal syntax {{csssyntax}} diff --git a/files/en-us/web/css/color_value/lch/index.md b/files/en-us/web/css/color_value/lch/index.md index f68de5f9af5b8e8..290cd6eee7668d2 100644 --- a/files/en-us/web/css/color_value/lch/index.md +++ b/files/en-us/web/css/color_value/lch/index.md @@ -22,17 +22,19 @@ lch(52.2345% 72.2 56.2 / .5); Functional notation: `lch(L C H[ / A])` - `L` - - : A {{CSSXref("<number>")}} between `0` and `100` or a {{CSSXref("<percentage>")}} between `0%` and `100%` that specifies the CIE Lightness where the number `0` corresponds to `0%` (black) and the number `100` corresponds to `100%` (white). + - : A {{CSSXref("<number>")}} between `0` and `100`, a {{CSSXref("<percentage>")}} between `0%` and `100%`, or the keyword `none`, which specifies the CIE Lightness. Here the number `0` corresponds to `0%` (black) and the number `100` corresponds to `100%` (white). - `C` - - : A {{CSSXref("<number>")}} or a {{CSSXref("<percentage>")}} where `0%` is `0` and `100%` is the number `150`. It is a measure of the chroma (roughly representing the "amount of color"). Its minimum useful value is `0`, while its maximum is theoretically unbounded (but in practice does not exceed `230`). + - : A {{CSSXref("<number>")}}, a {{CSSXref("<percentage>")}}, or the keyword `none`, where `0%` is `0` and `100%` is the number `150`. It is a measure of the chroma (roughly representing the "amount of color"). Its minimum useful value is `0`, while its maximum is theoretically unbounded (but in practice does not exceed `230`). - `H` - - : A {{CSSXref("<number>")}} or an {{CSSXref("<angle>")}} representing the hue angle. More details on this type can be found on the {{CSSXref("<hue>")}} reference. + - : A {{CSSXref("<number>")}}, an {{CSSXref("<angle>")}}, or the keyword `none`, which represents the hue angle. More details on this type can be found on the {{CSSXref("<hue>")}} reference. - `A` {{optional_inline}} - - : An {{CSSXref("<alpha-value>")}}, where the number `1` corresponds to `100%` (full opacity). + - : An {{CSSXref("<alpha-value>")}} or the keyword `none`, where the number `1` corresponds to `100%` (full opacity). > **Note:** Usually when percentage values have a numeric equivalent in CSS, `100%` is equal to the number `1`. > This case is notable where `100%` is equal to the number `100` for the `L` value and `150` for the `C` value. +> **Note:** See [Missing color components](/en-US/docs/Web/CSS/color_value#missing_color_components) for the effect of `none`. + ### Formal syntax {{csssyntax}} diff --git a/files/en-us/web/css/color_value/oklab/index.md b/files/en-us/web/css/color_value/oklab/index.md index a5232f925c2b102..c9bf938a449ec42 100644 --- a/files/en-us/web/css/color_value/oklab/index.md +++ b/files/en-us/web/css/color_value/oklab/index.md @@ -30,20 +30,15 @@ oklab(59.69% 0.1007 0.1191 / 0.5); Functional notation: `oklab(L a b[ / A])` - `L` - - - : A {{CSSXref("<number>")}} between `0` and `1` or a {{CSSXref("<percentage>")}} between `0%` and `100%`, where the number `0` corresponds to `0%` (black) and the number `1` corresponds to `100%` (white). `L` specifies the perceived lightness. - + - : A {{CSSXref("<number>")}} between `0` and `1`, a {{CSSXref("<percentage>")}} between `0%` and `100%`, or the keyword `none`, where the number `0` corresponds to `0%` (black) and the number `1` corresponds to `100%` (white). `L` specifies the perceived lightness. - `a` - - - : A {{CSSXref("<number>")}} between `-0.4` and `0.4` or a {{CSSXref("<percentage>")}} between `-100%` and `100%`. It specifies the distance along the `a` axis in the Oklab colorspace, that is, how green or red the color is. - + - : A {{CSSXref("<number>")}} between `-0.4` and `0.4`, a {{CSSXref("<percentage>")}} between `-100%` and `100%`, or the keyword `none`. It specifies the distance along the `a` axis in the Oklab colorspace, that is, how green or red the color is. - `b` - - - : A {{CSSXref("<number>")}} between `-0.4` and `0.4` or a {{CSSXref("<percentage>")}} between `-100%` and `100%`. It specifies the distance along the `b` axis in the Oklab colorspace, that is, how blue or yellow the color is. - + - : A {{CSSXref("<number>")}} between `-0.4` and `0.4`, a {{CSSXref("<percentage>")}} between `-100%` and `100%`, or the keyword `none`. It specifies the distance along the `b` axis in the Oklab colorspace, that is, how blue or yellow the color is. - `A` {{optional_inline}} + - : An {{CSSXref("<alpha-value>")}} or the keyword `none`, where the number `1` corresponds to `100%` (full opacity). - - : An {{CSSXref("<alpha-value>")}}, where the number `1` corresponds to `100%` (full opacity). +> **Note:** See [Missing color components](/en-US/docs/Web/CSS/color_value#missing_color_components) for the effect of `none`. ### Formal syntax diff --git a/files/en-us/web/css/color_value/oklch/index.md b/files/en-us/web/css/color_value/oklch/index.md index 99b01000e09ec8f..ccf1970a467afed 100644 --- a/files/en-us/web/css/color_value/oklch/index.md +++ b/files/en-us/web/css/color_value/oklch/index.md @@ -22,13 +22,15 @@ oklch(59.69% 0.156 49.77 / .5) Functional notation: `oklch(L C H[ / A])` - `L` - - : A {{CSSXref("<number>")}} between `0` and `1` or a {{CSSXref("<percentage>")}} between `0%` and `100%`, where the number `0` corresponds to `0%` (black) and the number `1` corresponds to `100%` (white). `L` specifies the perceived lightness. + - : A {{CSSXref("<number>")}} between `0` and `1`, a {{CSSXref("<percentage>")}} between `0%` and `100%`, or the keyword `none`, where the number `0` corresponds to `0%` (black) and the number `1` corresponds to `100%` (white). `L` specifies the perceived lightness. - `C` - - : A {{CSSXref("<number>")}} or a {{CSSXref("<percentage>")}}, where `0%` is `0` and `100%` is the number `0.4`. It is a measure of the chroma (roughly representing the "amount of color"). Its minimum useful value is `0`, while the maximum is theoretically unbounded (but in practice does not exceed `0.5`). + - : A {{CSSXref("<number>")}}, a {{CSSXref("<percentage>")}}, or the keyword `none`, where `0%` is `0` and `100%` is the number `0.4`. It is a measure of the chroma (roughly representing the "amount of color"). Its minimum useful value is `0`, while the maximum is theoretically unbounded (but in practice does not exceed `0.5`). - `H` - - : A {{CSSXref("<number>")}} or an {{CSSXref("<angle>")}} representing the hue angle. More details on this type can be found on the {{CSSXref("<hue>")}} reference. + - : A {{CSSXref("<number>")}}, an {{CSSXref("<angle>")}}, or the keyword `none`, which represents the hue angle. More details on this type can be found on the {{CSSXref("<hue>")}} reference. - `A` {{optional_inline}} - - : An {{CSSXref("<alpha-value>")}}, where the number `1` corresponds to `100%` (full opacity). + - : An {{CSSXref("<alpha-value>")}} or the keyword `none`, where the number `1` corresponds to `100%` (full opacity). + +> **Note:** See [Missing color components](/en-US/docs/Web/CSS/color_value#missing_color_components) for the effect of `none`. ### Formal syntax diff --git a/files/en-us/web/css/color_value/rgb/index.md b/files/en-us/web/css/color_value/rgb/index.md index e7c96858ba1c077..f8b7ee2c785b8ab 100644 --- a/files/en-us/web/css/color_value/rgb/index.md +++ b/files/en-us/web/css/color_value/rgb/index.md @@ -27,15 +27,11 @@ The function also accepts a legacy syntax in which all values are separated with Functional notation: `rgb(R G B[ / A])` - `R`, `G`, `B` - - - : Each as a {{CSSXref("<number>")}} between `0` and `255`, or a {{CSSXref("<percentage>")}} between `0%` and `100%`, or the keyword `none`, representing red, green, and blue channels, respectively. You can't mix percentages and numbers, so: - - - if any of these values is a number, then they must all be numbers or `none` - - if any of these values is a percentage, then they must all be percentages or `none`. - + - : Each as a {{CSSXref("<number>")}} between `0` and `255`, a {{CSSXref("<percentage>")}} between `0%` and `100%`, or the keyword `none`, which represent the red, green, and blue channels, respectively. - `A` {{optional_inline}} + - : An {{CSSXref("<alpha-value>")}} or the keyword `none`, where the number `1` corresponds to `100%` (full opacity). - - : An {{CSSXref("<alpha-value>")}}, where the number `1` corresponds to `100%` (full opacity). +> **Note:** See [Missing color components](/en-US/docs/Web/CSS/color_value#missing_color_components) for the effect of `none`. ### Formal syntax