[css-color-5] Rewrite relative colors section to be more specific about functionality, dfn some terms.

Author: tabatkins

css-color-5/Overview.bs

@@ -629,28 +629,125 @@ Adjusting colors: the ''color-adjust'' function {#coloradjust}
 Relative color syntax {#relative-colors}
 ----------------------------------------
 
-Besides specifying absolute coordinates, all color functions can also be used with a *relative syntax* to produce colors in the function's target [=colorspace=], based on an existing color (henceforth referred to as "origin color"). This syntax consists of the keyword ''from'', a <<color>> value, and optionally numerical coordinates specific to the color function. To allow calculations on the original color's coordinates, there are single-letter keywords for each coordinate and `alpha` that corresponds to the color's alpha. If no coordinates are specified, the function merely converts the origin color to the target function's [=colorspace=].
-
-The following sections outline the relative color syntax for each color function.
+In previous levels of this specification,
+the color functions could only specify colors in an absolute manner,
+by directly specifying all of the color channels.
+
+The new <dfn export>relative color</dfn> syntax
+allows existing colors to be modified
+using the color functions:
+if an <dfn>origin color</dfn> is specified,
+then each color channel can <em>either</em> be directly specified,
+or taken from the origin color
+(and possibly modified with [=math functions=]).
 
 Issue: A future version of this specification may define a relative syntax for ''color()'' as well.
 
+The precise details of each function's changes to accomodate [=relative colors=] are listed below,
+but they all follow a common structure:
+
+* An [=origin color=] can be specified with a ''from <<color>>'' value at the start of the function.
+* If an [=origin color=] is specified,
+	the remaining arguments can either be specified directly, as normal,
+	be specified as a <dfn>channel keyword</dfn> referring to one of the channels of the [=origin color=].
+	[=Math functions=] can also use these keywords
+	to do dynamic modifications of the [=origin color's=] channels.
+* [=Relative color=] syntax doesn't change whether an argument is required or optional.
+	If the alpha value is omitted, however,
+	it defaults to taking from the [=origin color=]
+	(rather than defaulting to ''100%'', as it does in the absolute syntax).
+
+If the [=origin color=] was originally specified with a different color function,
+it's first converted into the chosen color function,
+so it has meaningful values for the channels.
+
+<div class=example>
+	For example, if a theme color is specified as opaque,
+	but in a particular instance you need it to be partially transparent:
+
+	<pre highlight=css>
+	html { --bg-color: blue; }
+	.overlay {
+		background: rgb(from var(--bg-color) r g b / 80%);
+	}
+	</pre>
+
+	In this example, the r, g, and b channels of the [=origin color=] are unchanged,
+	indicated by specifying them with the keywords
+	drawing their values from the [=origin color=],
+	but the opacity is set to ''80%'' to make it slightly transparent,
+	regardless of what the [=origin color's=] opacity was.
+</div>
+
+<div class=example>
+	By using the [=channel keywords=] in a [=math function=],
+	an [=origin color=] can be manipulated in more advanced ways.
+
+	<pre highlight=css>
+	html { --color: green; }
+	.foo {
+		--darker-accent: lch(from var(--color) calc(l / 2) c h);
+	}
+	</pre>
+
+	In this example, the [=origin color=] is darkened
+	by cutting its lightness in half,
+	without changing any other aspect of the color.
+
+	Note as well that the [=origin color=] is a color keyword
+	(effectively RGB),
+	but it's automatically interpreted as an LCH color
+	due to being used in the ''lch()'' function.
+</div>
+
+<div class=example>
+	While most uses of [=relative color=] syntax
+	will use the [=channel keywords=] in their corresponding argument,
+	you can use them in any position.
+
+	For example, to do a rough approximation of grayscaling a color:
+
+	<pre highlight=css>
+	--blue-into-gray: rgb(from var(--color)
+		                  calc(r * .3 + g * .59 + b * .11)
+		                  calc(r * .3 + g * .59 + b * .11)
+		                  calc(r * .3 + g * .59 + b * .11));
+	</pre>
+
+	Using this,
+	''red'' would become ''rgb(30% 30% 30%)'',
+	''green'' would become ''rgb(59% 59% 59%)'',
+	and ''blue'' would become ''rgb(11% 11% 11%)''.
+	A more moderate color, like ''darkolivegreen'',
+	which has RGB values ''rgb(85 107 47)'',
+	would become approximately ''rgb(37% 37% 37%)''.
+
+	(Note, tho, that an easier and more accurate way to grayscale a color
+	is to use the ''lch()'' function,
+	as that colorspace is more accurate to human perception:
+	''lch(from var(--color) l 0 h)'' preserves the lightness,
+	but zeroes out the chroma,
+	which determines how "colorful" the color is.)
+</div>
+
 <h4 id="relative-RGB">Relative RGB colors</h4>
 
 The grammar of the ''rgb()'' function is extended as follows:
 
 <pre class='prod'>
-<dfn>rgb()</dfn> = rgb([from <<color>>]? <<percentage>>{3} [ / <<alpha-value>> ]? ) |
-		rgb([from <<color>>]? <<number>>{3} [ / <<alpha-value>> ]? )
-<dfn>&lt;alpha-value></dfn> = <<number>> | <<percentage>>
+	<dfn>rgb()</dfn> = rgb( <<percentage>>{3} [ / <<alpha-value>> ]? ) |
+	        rgb( <<number>>{3} [ / <<alpha-value>> ]? ) |
+	        rgb( [ from <<color>> ]? [ <<number>> | <<percentage>> ]{3} [ / <<alpha-value>> ]? )
 </pre>
 
-When an origin color is present, the following keywords can also be used in this function (provided the end result conforms to the expected type for the parameter) and correspond to:
+Within a [=relative color=] syntax ''rgb()'' function,
+the allowed [=channel keywords=] are:
 
-- 'r' is a <<percentage>> that corresponds to the origin color's red channel after its conversion to sRGB
-- 'g' is a <<percentage>> that corresponds to the origin color's green channel after its conversion to sRGB
-- 'b' is a <<percentage>> that corresponds to the origin color's blue channel after its conversion to sRGB
-- 'alpha' is a <<percentage>> that corresponds to the origin color's alpha transparency
+* <dfn value for="rgb()">r</dfn>, <dfn value for="rgb()">g</dfn>, and <dfn value for="rgb()">b</dfn>
+	are all <<percentage>>s
+	that correspond to the [=origin color's=] red, green, and blue channels
+	after its conversion to sRGB
+* <dfn value for="rgb()">alpha</dfn> is a <<percentage>> that corresponds to the [=origin color's=] alpha transparency
 
 <div class="example">
 	To manipulate color channels in the sRGB colorspace:
@@ -668,21 +765,25 @@ The grammar of the ''hsl()'' function is extended as follows:
 
 <pre class='prod'>
 <dfn>hsl()</dfn> = hsl([from <<color>>]? <<hue>> <<percentage>> <<percentage>> [ / <<alpha-value>> ]? )
-<dfn>&lt;hue></dfn> = <<number>> | <<angle>>
 </pre>
 
-When an origin color is present, the following keywords can also be used in this function (provided the end result conforms to the expected type for the parameter) and correspond to:
+Within a [=relative color=] syntax ''hsl()'' function,
+the allowed [=channel keywords=] are:
 
-- 'h' is a <<number>> that corresponds to the origin color's HSL hue after its conversion to sRGB, normalized to a [0, 360) range.
-- 's' is a <<percentage>> that corresponds to the origin color's HSL saturation after its conversion to sRGB
-- 'l' is a <<percentage>> that corresponds to the origin color's HSL lightness after its conversion to sRGB
-- 'alpha' is a <<percentage>> that corresponds to the origin color's alpha transparency
+* <dfn value for="hsl()">h</dfn> is an <<angle>>
+	that corresponds to the [=origin color's=] HSL hue
+	after its conversion to sRGB,
+	normalized to a [0deg, 360deg) range
+* <dfn value for="hsl()">s</dfn> and <dfn value for="hsl()">l</dfn>
+	are <<percentage>>s that correspond to the [=origin color's=] HSL saturation and lightness
+	after its conversion to sRGB
+* <dfn value for="hsl()">alpha</dfn> is a <<percentage>> that corresponds to the [=origin color's=] alpha transparency
 
 <div class="example">
 	This adds 180 degrees to the hue angle, giving a complementary color.
 	<pre>
 		--accent: <span class="swatch" style="--color: lightseagreen"></span> lightseagreen;
-		--complement:  <span class="swatch" style="--color: hsl(357deg 70% 41%)"></span> hsl(from var(--accent) calc(h+180) s l);
+		--complement:  <span class="swatch" style="--color: hsl(357deg 70% 41%)"></span> hsl(from var(--accent) calc(h + 180deg) s l);
 	</pre>
 	lightseagreen is hsl(177deg 70% 41%), so --complement is <span class="swatch" style="--color: hsl(357deg 70% 41%)"></span> hsl(357deg 70% 41%)
 </div>
@@ -695,12 +796,17 @@ The grammar of the ''hwb()'' function is extended as follows:
 	<dfn>hwb()</dfn> = hwb([from <<color>>]? <<hue>> <<percentage>> <<percentage>> [ / <<alpha-value>> ]? )
 </pre>
 
-When an origin color is present, the following keywords can also be used in this function (provided the end result conforms to the expected type for the parameter) and correspond to:
+Within a [=relative color=] syntax ''hwb()'' function,
+the allowed [=channel keywords=] are:
 
-- 'h' is a <<number>> that corresponds to the origin color's HWB hue after its conversion to sRGB
-- 'w' is a <<percentage>> that corresponds to the origin color's HWB whiteness after its conversion to sRGB
-- 'b' is a <<percentage>> that corresponds to the origin color's HWB blackness after its conversion to sRGB
-- 'alpha' is a <<percentage>> that corresponds to the origin color's alpha transparency
+* <dfn value for="hwb()">h</dfn> is an <<angle>>
+	that corresponds to the [=origin color's=] HWB hue
+	after its conversion to sRGB,
+	normalized to a [0deg, 360deg) range
+* <dfn value for="hwb()">w</dfn> and <dfn value for="hwb()">b</dfn>
+	are <<percentage>>s that correspond to the [=origin color's=] HWB whiteness and blackness
+	after its conversion to sRGB
+* <dfn value for="hwb()">alpha</dfn> is a <<percentage>> that corresponds to the [=origin color's=] alpha transparency
 
 <h4 id="relative-Lab">Relative Lab colors</h4>
 
@@ -710,12 +816,14 @@ The grammar of the ''lab()'' function is extended as follows:
 <dfn>lab()</dfn> = lab([from <<color>>]? <<percentage>> <<number>> <<number>> [ / <<alpha-value>> ]? )
 </pre>
 
-When an origin color is present, the following keywords can also be used in this function (provided the end result conforms to the expected type for the parameter) and correspond to:
+Within a [=relative color=] syntax ''lab()'' function,
+the allowed [=channel keywords=] are:
 
-- 'l' is a <<percentage>> that corresponds to the origin color's CIE Lightness
-- 'a' is a <<number>> that corresponds to the origin color's CIELab a axis
-- 'b' is a <<number>> that corresponds to the origin color's CIELab b axis
-- 'alpha' is a <<percentage>> that corresponds to the origin color's alpha transparency
+* <dfn value for="lab()">l</dfn> is a <<percentage>>
+	that corresponds to the [=origin color's=] CIE Lightness
+* <dfn value for="lab()">a</dfn> and <dfn value for="lab()">b</dfn> are <<number>>s
+	that correspond to the [=origin color's=] CIELab a and b axises
+* <dfn value for="lab()">alpha</dfn> is a <<percentage>> that corresponds to the [=origin color's=] alpha transparency
 
 <div class="example">
 	Multiple ways to adjust the transparency of a base color:
@@ -747,12 +855,17 @@ The grammar of the ''lch()'' function is extended as follows:
 <dfn>lch()</dfn> = lch([from <<color>>]? <<percentage>> <<number>> <<hue>> [ / <<alpha-value>> ]? )
 </pre>
 
-When an origin color is present, the following keywords can also be used in this function (provided the end result conforms to the expected type for the parameter) and correspond to:
+Within a [=relative color=] syntax ''lch()'' function,
+the allowed [=channel keywords=] are:
 
-- 'l' is a <<percentage>> that corresponds to the origin color's CIE Lightness
-- 'c' is a <<number>> that corresponds to the origin color's LCH chroma
-- 'h' is a <<number>> that corresponds to the origin color's LCH hue, normalized to a [0, 360) range.
-- 'alpha' is a <<percentage>> that corresponds to the origin color's alpha transparency
+* <dfn value for="lch()">l</dfn> is a <<percentage>>
+	that corresponds to the [=origin color's=] CIE Lightness
+* <dfn value for="lch()">c</dfn> is a <<number>>
+	that corresponds to the [=origin color's=] LCH chroma
+* <dfn value for="lch()">h</dfn> is an <<angle>>
+	that corresponds to the [=origin color's=] LCH hue,
+	normalized to a [0deg, 360deg) range.
+* <dfn value for="lch()">alpha</dfn> is a <<percentage>> that corresponds to the [=origin color's=] alpha transparency
 
 <div class="example">
 	''lch(from peru calc(l * 0.8) c h)'' produces a color that is 20% darker than <span class="swatch" style="--color: peru"></span> peru or lch(62.2532% 54.0114 63.6769), with its chroma and hue left unchanged.
@@ -763,7 +876,7 @@ When an origin color is present, the following keywords can also be used in this
 	This adds 180 degrees to the hue angle, giving the complementary color.
 	<pre>
 		--accent: <span class="swatch" style="--color: lightseagreen"></span> lightseagreen;
-		--complement:  <span class="swatch" style="--color: rgb(88.2814% 51.1047% 58.3039%)"></span> LCH(from var(--accent) l c calc(h + 180));
+		--complement:  <span class="swatch" style="--color: rgb(88.2814% 51.1047% 58.3039%)"></span> LCH(from var(--accent) l c calc(h + 180deg));
 	</pre>
 	lightseagreen is LCH(65.4937% 39.4484 190.1013), so --complement is <span class="swatch" style="--color: rgb(88.2814% 51.1047% 58.3039%)"></span> LCH(65.4937% 39.4484 370.1013)
 </div>