CSS Color Module Level 4

1. Introduction

This section is not normative.

This module describes CSS properties which allow authors to specify the foreground color and opacity of the text content of an element. This module also describes in detail the CSS <color> value type.

It not only defines the color-related properties and values that already exist in CSS1 and CSS2, but also defines new properties and values.

2. Foreground Color: the color property

This property describes the foreground fill color of an element’s text content. In addition, it provides the value that currentcolor resolves to. If the currentcolor keyword is set on the color property itself, it is treated as color: inherit.

The initial value of this property is black.

There are several different ways to syntactically specify a given color.

em { color: lime; }              /* color keyword   */
em { color: rgb(0,255,0); }      /* RGB range 0-255 */
em { color: rgb(0.0,100.0,0.0); }      /* RGB range 0%-100% */

<color>

The <color> type is defined in a later section.

3. Representing sRGB Colors: the <color> type

CSS colors in the sRGB color space are represented by a triplet of values—red, green, and blue—identifying a point in the sRGB color space [SRGB]. This is an internationally-recognized, device-independent color space, and so is useful for specifying colors that will be displayed on a computer screen, but is also useful for specifying colors on other types of devices, like printers. (See [COLORIMETRY].) Additionally, every color is accompanied by an alpha component, indicating how transparent it is, and thus how much of the backdrop one can see behind the color. The components are also sometimes called "channels". Each channel has a minimum and maximum value, and can take any value between those two.

While all colors share an underlying storage format, CSS contains several syntaxes for specifying <color> values. Some directly specify the sRGB color, such as the rgb() and rgba() functions and the hex notation. Others are more human-friendly to write and understand, and are converted to an sRGB color by CSS, such as the hsl() and hsla() functions, or the long list of named colors defined by CSS.

In total, the definition of <color> is:

<color>#typedef-colorReferenced in:1. 
Introduction2. 
Foreground Color: the color property (2) (3)3. 
Representing sRGB Colors: the <color> type (2) (3)5. 
Named Colors (2)11. 
Device-dependent CMYK Colors: the device-cmyk() function12. 
Modifying Colors: the color-mod() function (2) (3)12.4. 
Color Blending: the blend and blenda adjusters (2) (3) (4) (5) = <rgb()> | <rgba()> | <hsl()> | <hsla()> |
          <hwb()> | <gray()> | <device-cmyk()> | <color-mod()> |
          <hex-color> | <named-color> | currentcolor |
          <deprecated-system-color>

Some operations work differently on achromatic#achromaticReferenced in:3. Representing sRGB Colors: the <color> type (2) (3) (4)7. HWB Colors: hwb() function12. Modifying Colors: the color-mod() function (2) (3) (4) (5) (6) (7)12.1. RGBA Adjustment colors. An achromatic color is a shade of gray: in the RGB colorspace, a color is achromatic if the red, green, and blue channels are all the same value; in the HSL colorspace, a color is achromatic if the saturation is 0%; in the HWB colorspace, a color is achromatic if the sum of the whiteness and blackness is at least 100%.

3.1. Notes On Using Colors

Although colors can add significant amounts of information to documents and make them more readable, color by itself should not be the sole means to convey important information. Please consider the W3C Web Content Accessibility Guidelines [WCAG20] when including color in your documents.

• 1.4.1 Use of Color: Color is not used as the only visual means of conveying information, indicating an action, prompting a response, or distinguishing a visual element

3.2. Colors in sRGB

Colors specified in CSS, HTML, and untagged images are in the sRGB color space ([SRGB]).

This is not yet reliably implemented across implementations, though it has been shown to be implementable. Implementing it compatibly may require notifying plugins to treat untagged colors in the same way to avoid issues with colors not matching each other within a page.

An untagged image is an image that is not explicitly assigned a color profile, as defined by the image format.

Note that this rule does not apply to videos, since untagged video should be presumed to be in CCIR 601.

Really? Isn’t HD video in Rec.709? Shouldn’t video be consistent with images? Or do implementations really do this differently?

4. RGB Colors

There are several methods of directly specifying a color in terms of its RGBA channels.

4.1. The RGB functions: rgb() and rgba()

The rgb() function defines an RGB color by specifying the red, green, and blue channels directly. Its syntax is:

rgb()#funcdef-rgbReferenced in:3. 
Representing sRGB Colors: the <color> type (2)4.1. 
The RGB functions: rgb() and rgba() (2)4.2. 
The RGB hexadecimal notations: #RRGGBB8. 
Specifying Grays: the gray() functional notation (2)
Changes from Colors 3 = rgb( <rgb-component>#{3} )
rgba()#funcdef-rgbaReferenced in:3. 
Representing sRGB Colors: the <color> type (2)4.1. 
The RGB functions: rgb() and rgba()6. 
HSL Colors: hsl() and hsla() functions7. 
HWB Colors: hwb() function11. 
Device-dependent CMYK Colors: the device-cmyk() function13. 
Transparency: the opacity property16.6.2. 
Adding New Color Classes
Changes from Colors 3 = rgba( <rgb-component>#{3} , <alpha-value> )
<rgb-component>#typedef-rgb-componentReferenced in:4.1. 
The RGB functions: rgb() and rgba() (2) (3) = <number> | <percentage>
<alpha-value>#typedef-alpha-valueReferenced in:4.1. 
The RGB functions: rgb() and rgba() (2)6. 
HSL Colors: hsl() and hsla() functions7. 
HWB Colors: hwb() function8. 
Specifying Grays: the gray() functional notation11. 
Device-dependent CMYK Colors: the device-cmyk() function13. 
Transparency: the opacity property (2)
Changes from Colors 3 = <number> | <percentage>

The three <rgb-component>s specify the red, green, and blue channels of the color, respectively. 0% represents the minimum value for that color channel in the sRGB gamut, and 100% represents the maximum value. A <number> is equivalent to a <percentage>, but with a different range: 0 again represents the minimum value for the color channel, but 255 represents the maximum. These values come from the fact that many graphics engines store the color channels internally as a single byte, which can hold integers between 0 and 255. However, the CSS syntax allows full <number>s, not just <integer>s, for authoring convenience.

Some devices can output colors technically outside of the sRGB gamut, represented by channels with values less than 0% or greater than 100%. For this reason, values outside of the 0%-100% range are allowed, but are clamped to the device’s gamut.)

The final argument, the <alpha-value>, specifies the alpha of the color. If given as a <number>, the useful range of the value is 0 (representing a fully transparent color) to 1 (representing a fully opaque color). If given as a <percentage>, 0% represents a fully transparent color, while 100% represents a fully opaque color. Values outside these ranges are not invalid, but are clamped to the ranges defined here at computed-value time. If omitted, it defaults to 100%.

4.2. The RGB hexadecimal notations: #RRGGBB

The CSS hex color#hex-colorReferenced in:12.1. RGBA Adjustment notation allows a color to be specified by giving the channels as hexadecimal numbers, which is similar to how colors are often written directly in computer code. It’s also shorter than writing the same color out in rgb() notation.

The syntax of a <hex-color>#typedef-hex-colorReferenced in:3. Representing sRGB Colors: the <color> type is a <hash-token> token whose value consists of 3, 4, 6, or 8 hexadecimal digits. In other words, a hex color is written as a hash character, "#", followed by some number of digits 0-9 or letters a-f (the case of the letters doesn’t matter - #00ff00 is identical to #00FF00).

The number of hex digits given determines how to decode the hex notation into an RGB color:

6 digits

The first pair of digits, interpreted as a hexadecimal number, specifies the red channel of the color, where 00 represents the minimum value and ff (255 in decimal) represents the maximum. The next pair of digits, interpreted in the same way, specifies the green channel, and the last pair specifies the blue. The alpha channel of the color is fully opaque.

In other words, #00ff00 represents the same color as rgb(0, 255, 0) (a lime green).

8 digits

The first 6 digits are interpreted identically to the 6-digit notation. The last pair of digits, interpreted as a hexadecimal number, specifies the alpha channel of the color, where 00 represents a fully transparent color and ff represent a fully opaque color.

In other words, #0000ffcc represents the same color as rgba(0, 0, 100%, 80%) (a slightly-transparent blue).

3 digits

This is a shorter variant of the 6-digit notation. The first digit, interpreted as a hexadecimal number, specifies the red channel of the color, where 0 represents the minimum value and f represents the maximum. The next two digits represent the green and blue channels, respectively, in the same way. The alpha channel of the color is fully opaque.

This syntax is often explained by saying that it’s identical to a 6-digit notation obtained by "duplicating" all of the digits. For example, the notation #123 specifies the same color as the notation #112233. This method of specifying a color has lower "resolution" than the 6-digit notation; there are only 4096 possible colors expressible in the 3-digit hex syntax, as opposed to approximately 17 million in 6-digit hex syntax.

4 digits

This is a shorter variant of the 8-digit notation, "expanded" in the same way as the 3-digit notation is. The first digit, interpreted as a hexadecimal number, specifies the red channel of the color, where 0 represents the minimum value and f represents the maximum. The next three digits represent the green, blue, and alpha channels, respectively.

5. Named Colors

In addition to the various numeric syntaxes for <color>s, CSS defines a large set of named colors#named-colorReferenced in:16.1. The RGBColor Object that can be used instead, so that common colors can be written and read more easily. A <named-color>#typedef-named-colorReferenced in:3. Representing sRGB Colors: the <color> type5.1. The transparent keyword is written as an <ident>, accepted anywhere a <color> is. As usual for CSS-defined <ident>s, all of these keywords are case-insensitive.

16 of CSS’s named colors come from HTML originally: aqua, black, blue, fuchsia, gray, green, lime, maroon, navy, olive, purple, red, silver, teal, white, and yellow. Most of the rest come from one version of the X11 color system, used in Unix-derived systems to specify colors for the console. (Two special color values, transparent and currentcolor, are specially defined in their own sections.)

Note: The history of the X11 color system is interesting, and was excellently summarized by Alex Sexton in his talk “Peachpuffs and Lemonchiffons”.

The following table defines all of the opaque named colors, by giving equivalent numeric specifications in the other color syntaxes.

Note: this list of colors and their definitions is a superset of the list of named colors defined by SVG 1.1.

5.1. The transparent keyword

The keyword transparent#valdef-color-transparentReferenced in:5. Named Colors5.1. The transparent keyword15. Default Style Rules specifies a transparent black color; that is, a color with its red, green, and blue channels all set to the minimum value and its alpha channel set to full transparency, equivalent to rgba(0, 0, 0, 0). It is a type of <named-color>.

5.2. The currentcolor keyword

The keyword currentcolor#valdef-color-currentcolorReferenced in:2. Foreground Color: the color property (2)5. Named Colors5.2. The currentcolor keyword (2) (3) (4) (5) (6) takes its value from the value of the color property on the same element. This happens at used-value time, which means that if the value is inherited, it’s inherited as currentcolor, not as the value of the color property, so descendants will use their own color property to resolve it.

If currentcolor is used as the value of the color property, it instead takes its value from the inherited value of the color property.

.foo {
  color: red;
  background-color: currentcolor;
}

.foo {
  color: red;
  background-color: red;
}

<p><em>Some <strong>really</strong> emphasized text.</em>
<style>
p { color: black; }
em { text-emphasis: dot; }
strong { color: red; }
</style>

Note: Multi-word keywords in CSS usually separate their component words with hyphens. currentcolor doesn’t, because it was originally introduced in SVG as a special attribute value spelled "currentColor", rather than a CSS value. Only later did CSS pick it up, at which point the capitalization stopped mattering, as CSS keywords are case-insensitive.

6. HSL Colors: hsl() and hsla() functions

The RGB system for specifying colors, while convenient for machines and graphic libraries, is often regarded as very difficult for humans to gain an intuitive grasp on. It’s not easy to tell, for example, how to alter an RGB color to produce a lighter variant of the same hue.

There are several other color schemes possible. One such is the HSL color scheme, which is much more intuitive to use, but still maps easily back to RGB colors.

HSL colors are specified as a triplet of hue, saturation, and lightness. The syntax of the hsl() function is:

hsl()#funcdef-hslReferenced in:3. 
Representing sRGB Colors: the <color> type (2)6. 
HSL Colors: hsl() and hsla() functions (2)7. 
HWB Colors: hwb() function8. 
Specifying Grays: the gray() functional notation12.2. 
HSL/HWB Adjustment16.6.3. 
The CSSColor Object
Changes from Colors 3 = hsl( <hue>, <percentage>, <percentage> )
hsla()#funcdef-hslaReferenced in:3. 
Representing sRGB Colors: the <color> type (2)6. 
HSL Colors: hsl() and hsla() functions16. 
APIs for Parsing and Manipulating Colors
Changes from Colors 3 = hsla( <hue>, <percentage>, <percentage>, <alpha-value> )
<hue>#typedef-hueReferenced in:6. 
HSL Colors: hsl() and hsla() functions (2)7. 
HWB Colors: hwb() function12. 
Modifying Colors: the color-mod() function (2) (3) = <number> | <angle>

The first argument specifies the hue. Hue is represented as an angle of the color circle (the rainbow, twisted around into a circle). The angle 0deg represents red (as does 360deg, 720deg, etc.), and the rest of the hues are spread around the circle, so 120deg represents green, 240deg represents blue, etc. Because this value is so often given in degrees, the argument can also be given as a number, which is interpreted as a number of degrees.

The next two arguments are the saturation and lightness, respectively. For saturation, 100% is a fully-saturated, bright color, and 0% is a fully-unsaturated gray. For lightness, 50% represents the "normal" color, while 100% is white and 0% is black. If the saturation or lightness is less than 0% or the lightness is greater than 100%, they are clipped to those values before being converted to an RGB color. Some output devices may support saturations greater than 100%, just as they support RGB values greater than 100%. If the saturation exceeds the output device’s gamut, it must be clipped to that device’s gamut before being converted to an RGB color. This clipping should preserve the hue of the color (that is, it’s shouldn’t be the same thing as clipping an RGB component to the device’s gamut), but this specification does not define how to do so.

The final argument specifies the alpha channel of the color. It’s interpreted identically to the fourth argument of the rgba() function. If omitted, it defaults to 100%.

The advantage of HSL over RGB is that it is far more intuitive: one can guess at the colors they want, and then tweak. It is also easier to create sets of matching colors (by keeping the hue the same and varying the saturation and lightness).

hsl(120, 100%, 50%) lime green
hsl(120, 100%, 25%) dark green
hsl(120, 100%, 75%) light green
hsl(120, 75%, 85%)  pastel green

6.1. Converting HSL colors to RGB colors

Converting an HSL color to RGB is straightforward mathematically. Here’s a simple implementation of the conversion algorithm in JavaScript. For simplicity, this algorithm assumes that the hue has been normalized to a number in the half-open range [0, 6), and the saturation and lightness have been normalized to the range [0, 1]. It returns an array of three numbers representing the red, green, and blue channels of the colors, normalized to the range [0, 1].

function hslToRgb(hue, sat, light) {
  if( light <= .5 ) {
    var t2 = light * (sat + 1);
  } else {
    var t2 = light + sat - (light * sat);
  }
  var t1 = light * 2 - t2;
  var r = hueToRgb(t1, t2, hue + 2);
  var g = hueToRgb(t1, t2, hue);
  var b = hueToRgb(t1, t2, hue - 2);
  return [r,g,b];
}

function hueToRgb(t1, t2, hue) {
  if(hue < 0) hue += 6;
  if(hue >= 6) hue -= 6;

  if(hue < 1) return (t2 - t1) * hue + t1;
  else if(hue < 3) return t2;
  else if(hue < 4) return (t2 - t1) * (4 - hue) + t1;
  else return t1;
}

6.2. Examples of HSL colors

The tables below illustrate a wide range of possible HSL colors. Each table represents one hue, selected at 30° intervals, to illustrate the common "core" hues: red, yellow, green, cyan, blue, magenta, and the six intermediary colors between these.

In each table, the X axis represents the saturation while the Y axis represents the lightness.

7. HWB Colors: hwb() function

HWB (short for Hue-Whiteness-Blackness) is another method of specifying colors, similar to HSL, but often even easier for humans to work with. It describes colors with a starting hue, then a degree of whiteness and blackness to mix into that base hue.

Many color-pickers are based on the HWB color system, due to its intuitiveness.

The syntax of the hwb() function is:

hwb()#funcdef-hwbReferenced in:3. 
Representing sRGB Colors: the <color> type7. 
HWB Colors: hwb() function (2)12.2. 
HSL/HWB Adjustment
Changes from Colors 3 = hwb( <hue>, <percentage>, <percentage> [, <alpha-value> ]? )

The first argument specifies the hue, and is interpreted identically to hsl().

The second argument specifies the amount of white to mix in, as a percentage from 0% (no whiteness) to 100% (full whiteness). Similarly, the third argument specifies the amount of black to mix in, also from 0% (no blackness) to 100% (full blackness). Values outside of these ranges make the function invalid. If the sum of these two arguments is greater than 100%, then at computed-value time they are normalized to add up to 100%, with the same relative ratio.

The fourth argument specifies the alpha channel of the color. It’s interpreted identically to the fourth argument of the rgba() function. If omitted, it defaults to 100%.

The resulting color can be thought of conceptually as a mixture of paint in the chosen hue, white paint, and black paint, with the relative amounts of each determined by the percentages. If white+black is equal to 100% (after normalization), it defines an achromatic color, or some shade of gray, without any hint of the chosen hue.

7.1. Converting HWB colors to RGB colors

Converting an HWB color to RGB is straightforward, and related to how one converts HSL to RGB. The following Javascript implementation of the algorithm assumes that the white and black components have already been normalized, so their sum is no larger than 100%, and have been converted into numbers in the range [0,1].

function hwbToRgb(hue, white, black) {
  var rgb = hslToRgb(hue, 1, .5);
  for(var i = 0; i < 3; i++) {
    rgb[i] *= (1 - white - black);
    rgb[i] += white;
  }
  return rgb;
}

7.2. Examples of HWB Colors

8. Specifying Grays: the gray() functional notation

Grays are a very special set of colors. They’re fully desaturated (lacking any actual color at all), which means that specifying a gray with any of the other notations requires specifying some redundant information: if specifying the color with rgb(), all three channels are identical; if specifying the color with hsl(), the hue is irrelevant and the saturation is locked to 0%.

The gray() functional notation simplifies specifying this common set of colors, so that only the necessary information is required.

gray()#funcdef-grayReferenced in:3. 
Representing sRGB Colors: the <color> type8. 
Specifying Grays: the gray() functional notation (2) (3)
Changes from Colors 3 = gray( [<number> | <percentage>] [, <alpha-value>]? )

The first argument specifies the shade of gray, while the second optional argument specifies the alpha channel of the color.

gray(A) represents the same color as rgb(A,A,A). gray(A,B) represents the same color as rgb(A,A,A,B).

9. Device-independent Colors: Lab and LCH

Physical measurements of a color are typically expressed in a color space created in 1976 by the CIE, Lab. Color conversions from one device to another also use Lab as an intermediate step. Derived from human vision experiments, Lab represents the entire range of color that humans can see.

Lab is a rectangular coordinate system with a central Lightness axis. L=0 is deep black (no light at all) while L=100 is white (D50 white, a standardized daylight spectrum with a color temperature of 5000K). Usefully, L=50 is mid gray, by design: the Lab color space is intended to be perceptually uniform. The a and b axes convey hue; positive values along the a axis are red while negative values are the complementary color, green. Similarly positive values along the b axis are yellow and negative are the complementary blue/violet. Desaturated colors have small values of a and b and are close to the L axis; saturated colors lie far from the L axis.

D50 is also the whitepoint used for the profile connection space in ICC color interconversion, the values used in image editors which offer Lab editing, and the value used by physical measurement devices such as spectrometers, when they report measured colors in Lab. Conversion from colors specified using other white points is called a chromatic adaptation transform, which models the changes in the human visual system as we adapt to a new lighting condition. The Bradford algorithm is the industry standard chromatic adaptation transform, and is easy to calculate as it is a simple matrix multiplication.

In Lab if two colors have the same L value, they appear to have the same visual lightness – regardless of how different their hues are. This is different from HSL, where for example blue (#00F) and yellow (#FF0) have the same HSL lightness despite yellow being obviously far lighter than blue.

LCH has the same L axis as Lab, but uses polar coordinates C (chroma) and H (hue). C is the geometric distance from the L axis and H is the angle, in degrees, from the positive a axis.

The Lightness axis in Lab should not be confused with the L axis in HSL. For example, in HSL, the sRGB colors blue (#00F) and yellow (#FF0) have the same value of L even though visually, blue is much darker. In Lab, if two colors have the same measured L value, they have identical visual lightness. HSL and related polar RGB models were developed to give similar usability benefits for RGB that LCH gave to Lab.

9.1. Specifying Lab and LCH: the lab() and lch() functional notations

lab()#funcdef-labReferenced in:
Changes from Colors 3 = lab( <number> , <number> , <number> )

The first argument specifies the CIE Lightness, the second argument is a and the third is b. L is constrained to the range [0, 100] while a and b are signed values and theoretically unbounded but in practice do not exceed ±160.

lch() = lch( <number> , <number> , <number> )

The first argument specifies the CIE Lightness, the second argument is C and the third is H. L is constrained to the range [0, 100]. C is an unsigned number while H is constrained to the range [0, 360).

9.2. Converting sRGB colors to Lab colors

Conversion from sRGB to Lab requires several steps, although in practice all but the first step are linear calculations and can be combined.

1. Convert from sRGB to linear-light sRGB (undo gamma correction)
2. Convert from linear sRGB to CIE XYZ
3. Convert from a D65 whitepoint (used by sRGB) to the D50 whitepoint used in Lab, with the Bradford transform
4. Convert D50-adapted XYZ to Lab

9.3. Converting Lab colors to sRGB colors

Conversion from Lab to sRGB also requires multiple steps, and again in practice all but the last step are linear calculations and can be combined.

1. Convert Lab to (D50-adapted) XYZ
2. Convert from a D50 whitepoint (used by Lab) to the D65 whitepoint used in sRGB, with the Bradford transform
3. Convert from (D65-adapted) CIE XYZ to linear sRGB
4. Convert from linear-light sRGB to sRGB (do gamma correction)

9.4. Converting Lab colors to LCH colors

Conversion to LCH is trivial:

1. H = atan2(b, a)
2. C = sqrt(a^2 + b^2)
3. L is the same

9.5. Converting LCH colors to Lab colors

Conversion to Lab is trivial:

1. a = C cos(H)
2. b = C sin(H)
3. L is the same

10. Profiled, Device-dependent Colors

When the measured physical characteristics (such as the chromaticities of the primary colors it uses, or the colors produced in response to a given set of inputs) of a color space or a color-producing device are known, it is said to be characterised. This characterization information is stored in a profile. The most common type of color profile is defined by the International Color Consortium (ICC).

If in addition adjustments have been made so that a device meets calibration targets such as white point, neutrality of greys, predictability and consistency of tone response, then it is said to be calibrated.

CSS allows colors to be specified by reference to a color profile. This could be for example a calibrated CMYK printer, or an RGB colorspace (such as ProPhoto , widely used by photographers), or any other color or monochrome output defice which has been characterized. In addition, for conveninnce, CSS provides two predefined RGB color spaces - DCI P3, which is a wide gamut space typical of current wide-gamut monitors, and Rec.2020 which is a ultra-wide gamut space capable of representing almost all visible real-world colors. Both are broadcast industry standards.

color(swopc, 0, 206, 190, 77);
color(indigo, 24, 160, 86, 42, 0, 18, 31);
color(prophoto, 233, 150, 122);
color(P3, 97, 253, 36);

@color-profile swopc {
  src: url('http://example.org/swop-coated.icc'');}
@color-profile indigo {
  src: url('http://example.org/indigo-seven.icc'');}
profile prophoto {
  src: url('http://example.org/prophoto.icc'');}

10.1. Specifying profiled colors: the color() function

The color function takes an indentifier as the first parameter, followed by as many numerical parameters as are needed (three for an RGB colorspace, four for CMYK, one for greyscale, and so on). The identifier is either one of the predefined spaces (P3 or Rec2020) or the name of a profile.

color()#funcdef-colorReferenced in:10.1. Specifying profiled colors: the color() function
Changes from Colors 3 = color( <ident> , <number>+ )

How to handle cases where there are too many, or too few, numbers supplied? Seems like ignoring extra numbers, and treating unspecified numbers ar zero, would be the most robust?

10.2. Predefined colorspaces: DCI P3 and Rec.2020.

These two colorspaces are indicated by using the predefined identifiers P3 or Rec.2020 in the color function. No <@color-profile> at-rule is needed; if one is supplied, it will be ignored.

The DCI P3 colorspace has the following characteristics:

The ITU Rec.2020 colorspace has the following characteristics:

Rec.2020 transfer function has the same form as the one for sRGB, but with the constants at higher precision to cope with 10 or 12-bit components:

 E < β ? 4.5 * E : α * Math.pow(E, 0.45) - (α - 1);

Where α=1.09929682680944 and β=0.018053968510807 .

For both predefined color spaces, conversion to Lab requires several steps, although in practice all but the first step are linear calculations and can be combined.

1. Convert from gamma-corrected RGB to linear-light RGB (undo gamma correction)
2. Convert from linear RGB to CIE XYZ
3. Convert from a D65 whitepoint (used by both P3 and Rec.2020) to the D50 whitepoint used in Lab, with the Bradford transform
4. Convert D50-adapted XYZ to Lab

Conversion from Lab to P3 or Rec.2020 also requires multiple steps, and again in practice all but the last step are linear calculations and can be combined.

1. Convert Lab to (D50-adapted) XYZ
2. Convert from a D50 whitepoint (used by Lab) to the D65 whitepoint used in sRGB, with the Bradford transform
3. Convert from (D65-adapted) CIE XYZ to linear RGB
4. Convert from linear-light RGB to RGB (do gamma correction)

Implementations may choose to implement these steps in some other way (for example, using an ICC profile with relative colorimetric rendering intent) provided the results are the same for colors inside the source and destination gamuts.

10.3. Specifying a color profile: the color-profile at-rule

The @color-profile rule is a group rule. It consists of the at-keyword '@color-profile' followed by a name, followed by a group rule body.

In a very similar way to the <@font-face. at-rule, the <@color-profile> at-rule has a name (which will be used inside the stylesheet), and a descriptor to point to the actual data (src, just like src in font-face.) The src descriptor takes a url() as it’s value.'

A third, optional descriptor defines the rendering intent to use when mapping colors from a larger to a smaller gamut.

This descriptor is only needed if the profile linked to has data for multiple rendering intents. There are four values for rendering intent

relative-colorimetric

Media-relative colorimetric is required to leave source colors that fall inside the destination medium gamut unchanged relative to the respective media white points. Source colors that are out of the destination medium gamut are mapped to colors on the gamut boundary using a variety of different methods.

Note: the media-relative colorimetric rendering intent is often used with black point compensation, where the source medium black point is mapped to the destination medium black point as well.

This method must map the source white point to the desination white point. If black point compensation is in use, the source black point must also be mapped to the destination black point. Adaptation algorithms should be used to adjust for the change in white point. Relative relationships of colors inside both source and destination gamuts should be preserved. Relative relationships of colors outside the destination gamut may be changed.

absolute-colorimetric

ICC-absolute colorimetric is required to leave source colors that fall inside the destination medium gamut unchanged relative to the adopted white (a perfect reflecting diffuser). Source colors that are out of the destination medium gamut are mapped to colors on the gamut boundary using a variety of different methods. This method produces the most accurate color matching of in-gamut colors, but will result in highlight clipping if the destination medium white point is lower than the source medium white point. For this reason it is recommended for use only in applications that need exact color matching and where highlight clipping is not a concern.

This method MUST disable white point matching and black point matching when converting colors. In general, this option is not recommended except for testing purposes.

perceptual

This method is often the preferred choice for images, especially when there are substantial differences between the source and destination (such as a screen display image reproduced on a reflection print). It takes the colors of the source image and re-optimizes the appearance for the destination medium using proprietary methods. This re-optimization may result in colors within both the source and destination gamuts being changed, although perceptual transforms are supposed to maintain the basic artistic intent of the original in the reproduction. They will not attempt to correct errors in the source image.

With v2 ICC profiles there is no specified perceptual reference medium, which can cause interoperability problems. When v2 ICC profiles are used it may be safer to use the media-relative colorimetric rendering intent with black point compensation, instead of the perceptual rendering intent, unless the specific source and destination profiles to be used have been checked to ensure the combination produces the desired result.

This method should maintain relative color values among the pixels as they are mapped to the target device gamut. This method may change pixel values that were originally within the target device gamut, in order to avoid hue shifts and discontinuities and to preserve as much as possible the overall appearance of the scene.

saturation

This option was created to preserve the relative saturation (chroma) of the original, and to keep solid colors pure. However, it experienced interoperability problems like the perceptual intent, and as solid color preservation is not amenable to a reference medium solution using v4 profiles does not solve the problem. Use of this rendering intent is not recommended unless the specific source and destination profiles to be used have been checked to ensure the combination produces the desired result. This option should preserve the relative saturation (chroma) values of the original pixels. Out of gamut colors should be converted to colors that have the same saturation but fall just inside the gamut.

FIX ME: MISSING

11. Device-dependent CMYK Colors: the device-cmyk() function

While screens typically display colors directly with RGB pixels, printers often represent colors in different ways. In particular, one of the most common print-based ways of representing colors is with CMYK: a combination of cyan, magenta, yellow, and black which yields a particular color on that device. The device-cmyk() function allows authors to specify a color in this way:

device-cmyk()#funcdef-device-cmykReferenced in:3. 
Representing sRGB Colors: the <color> type11. 
Device-dependent CMYK Colors: the device-cmyk() function (2) (3) (4)16. 
APIs for Parsing and Manipulating Colors16.5. 
The CMYKColor Class
Changes from Colors 3 = device-cmyk( <cmyk-component>#{4} , <alpha-value>? , <color>? )
<cmyk-component>#typedef-cmyk-componentReferenced in:11. 
Device-dependent CMYK Colors: the device-cmyk() function = <number> | <percentage>

The arguments of the device-cmyk() function specify the cyan, magenta, yellow, and black components, in order, as a number between 0 and 1 or a percentage between 0% and 100%. These two usages are equivalent, and map to each other linearly. Values less than 0 or 0%, or greater than 1 or 100%, are not invalid; instead, they are clamped to 0/0% or 1/100%.

The fifth argument specifies the alpha channel of the color. It’s interpreted identically to the fourth argument of the rgba() function. If omitted, it defaults to 100%.

The sixth argument specifies the fallback color, used when the user agent doesn’t know how to accurately transform the CMYK color to RGB. If omitted, it defaults to the CMYK color naively converted to RGBA.

Typically, print-based applications will actually store the used colors as CMYK, and send them to the printer in that form. Unfortunately, CSS cannot do that; various CSS features require an RGB color, so that compositing/blending/etc. can be done. As such, CMYK colors must be converted to an equivalent RGB color. This is not trivial, like the conversion from HSL or HWB to RGB; the precise conversion depends on the precise characteristics of the output device.

If the user agent has information about the output device such that it believes it can accurately convert the CMYK color to a correct RGB color, the computed value of the device-cmyk() function must be that RGBA color. Otherwise, the computed value must be the fallback color.

color: device-cmyk(0, 81%, 81%, 30%);
color: rgb(178, 34, 34);
color: firebrick;

11.1. Converting Between Uncalibrated CMYK and RGB-Based Colors

This section now needs to clearly distinguish between calibrated (icc-based) color on the one hand, and uncalibrated device-cmyk on the other. This particularly affects conversion to and from RGB.

While most colors defined in this specification are directly compatible with RGBA, and thus can be mechanically and consistently converted back and forth with it, CMYK colors are not directly compatible; a given CMYK color will map to various RGBA colors depending on the physical characteristics of the output device.

Ideally, the user agent will be aware of the output device’s color profiles for RGBA and CMYK. If this is true, then the user agent must convert between CMYK and RGBA colors (and vice versa) by first converting the color into an appropriate device-independent color space, such as CIELab, and then converting into the output color space, using the appropriate color profiles for each operation.

This is not always possible, however. In that case, the user agent must use the following naive conversion algorithms.

To naively convert from CMYK to RGBA#naively-convert-from-cmyk-to-rgbaReferenced in:11. Device-dependent CMYK Colors: the device-cmyk() function:

If a fallback color was specified, return that color (converting it to RGB as well, if necessary). Otherwise:

• red = 1 - min(1, cyan * (1 - black) + black)
• green = 1 - min(1, magenta * (1 - black) + black)
• blue = 1 - min(1, yellow * (1 - black) + black)
• Alpha is same as for input color.

To naively convert from RGBA to CMYK:

• black = 1 - max(red, green, blue)
• cyan = (1 - red - black) / (1 - black), or 0 if black is 1
• magenta = (1 - green - black) / (1 - black), or 0 if black is 1
• yellow = (1 - blue - black) / (1 - black), or 0 if black is 1
• alpha is the same as the input color
• fallback color must be set to the input color

12. Modifying Colors: the color-mod() function

When specifying a color scheme for a site, one often wants a color that is close to another color, but slightly different. This becomes more important when CSS Variables are used, where an author may wish to define a "base" color, and then produce an array of slightly modified colors to use elsewhere.

The color-mod() function takes an existing color, and applies zero or more "color adjusters" to it, which specify how to manipulate the color in some way.

Several of the color adjusters straightforwardly manipulate the color as an RGB, HSL, or HWB color, as if you’d specified a color in the appropriate syntax with one argument slightly modified. Others perform more complex manipulations of the color, such as blending it or finding contrasting colors.

Additionally, the color-mod() function defines a new, more intuitive syntax for specifying named colors, based on CNS.

Actually add the CNS thing.

color-mod()#funcdef-color-modReferenced in:3. 
Representing sRGB Colors: the <color> type12. 
Modifying Colors: the color-mod() function (2) (3) (4) (5) (6) (7) (8)12.2. 
HSL/HWB Adjustment12.3. 
Tints and Shades: the tint and shade adjusters
Changes from Colors 3 = color( [ <color> | <hue> ] <color-adjuster>* )
<color-adjuster>#typedef-color-adjusterReferenced in:12. 
Modifying Colors: the color-mod() function (2) (3) (4) (5) (6) (7) (8) (9)12.1. 
RGBA Adjustment (2) =
    [red( | green( | blue( | alpha( | a(] ['+' | '-']? [<number> | <percentage>] ) |
    [red( | green( | blue( | alpha( | a(] '*' <percentage> ) |
    rgb( ['+' | '-'] [<number> | <percentage>]{3} ) |
    rgb( ['+' | '-'] <hash-token> ) |
    rgb( '*' <percentage> ) |

    [hue( | h(] ['+' | '-' | '*']? <angle> ) |
    [saturation( | s(] ['+' | '-' | '*']? <percentage> ) |
    [lightness( | l(] ['+' | '-' | '*']? <percentage> ) |
    [whiteness( | w(] ['+' | '-' | '*']? <percentage> ) |
    [blackness( | b(] ['+' | '-' | '*']? <percentage> ) |

    tint( <percentage> ) |
    shade( <percentage> ) |

    blend( <color> <percentage> [rgb | hsl | hwb]? ) |
    blenda( <color> <percentage> [rgb | hsl | hwb]? ) |

    contrast( <percentage>? )

The first argument specifies the base color. If a <hue> is given, the base color is the HSL color with the given <hue>, 100% saturation, and 50% lightness (in other words, the fully-saturated color with the given hue).

After the base color, zero or more <color-adjuster>s can be specified. Each <color-adjuster> modifies the color in some way, passing a new base color to the next <color-adjuster> in the list. The same <color-adjuster> can be specified more than once in the list, such as color(red s(- 10%) s(- 10%)); each instance just modifies the color appropriately (in this case, producing hsl(0deg, 80%, 50%)).

There are several classes of <color-adjuster>s with various effects, defined in the following sections.

The computed value of a color-mod() function is the color produced by applying all the <color-adjuster>s to the base color.

Note: While scaling can be specified without any spaces, like lightness(*150%), adding/subtracting must be done with spaces after the +/-, or else the +/- will be interpreted as part of the number by the CSS parser.

An achromatic color doesn’t have a unique hue, so some <color-adjuster>s that would make the color no longer achromatic (such as s(50%)) have special behavior for achromatic colors, as described in each adjuster’s description. However, it is possible for, within the space of a single color-mod() function, for the base color to be chromatic, an adjuster to make it achromatic, and a following adjuster to make it chromatic again, with an author having the reasonable expectation that the hue is maintained.

To allow this, during the evaluation of a color-mod() function’s <color-adjuster>s, rather than storing intermediate colors as a 4-tuple of red, green, blue, and alpha, as usual for CSS colors, intermediate colors must be stored as a 5-tuple of red, green, blue, alpha, and hue angle#hue-angle-is-nullReferenced in:12.1. RGBA Adjustment12.2. HSL/HWB Adjustment (2) (3)12.4. Color Blending: the blend and blenda adjusters (2) (3), where the hue angle may be null for some colors and after some operations.

Whenever an operation interprets an achromatic color in HSL or HWB space, if the color has a non-null hue angle, that hue must be used for the color’s HSL/HWB interpretation. (Individual operations define how to handle null hue angles.)

If the base color is achromatic, the hue angle is initially null.

color(X w(+ 20%) s(+ 20%))

12.1. RGBA Adjustment

The most basic set of <color-adjuster>s modify the color’s channels directly, altering the amount of red, green, blue, or alpha in the color.

[red( | green( | blue( | alpha( | a(] ['+' | '-']? [<number> | <percentage>] )

[red( | green( | blue( | alpha( | a(] * <percentage> )

Sets or adjust the red, blue, green, or alpha channels of the base color.

If there is no operator, the given channel is set to the given value.

If the operator is + or -, the given channel is interpreted as the matching type (<number> or <percentage>) and then incremented or decremented by the given value.

If the operator is *, the given channel is multipled by the given value.

rgb( ['+' | '-']? [<number> | <percentage>]{3} )

Adjusts the base color in the red, green, and blue channels simultaneously. All three channels are interpreted as the matching type (<number> or <percentage>) and then incremented or decremented by the given values, with the first value adjusting the red channel, the second value adjusting the green channel, and the third value adjusting the blue channel.

rgb( ['+' | '-'] <hash-token> )

Identical to the previous clause, except that the adjustments to the three channels are specified in hexadecimal format; the <hash-token> is interpreted as a hex color, then the red, green, and blue channels of the color are applied as adjustments to the base color.

For example, in color(red rgb(+ #004400)), the base color is red (#ff0000). The red and blue channels aren’t adjusted at all (those channels in the given color are both 0), and the green channel is increased by 44₁₆, resulting in a final color of #ff4400.

rgb( * <percentage> )

The red, green, and blue channels of the base color are multiplied by the given value.

All <color-adjuster>s in this section, except for alpha() and a(), set the hue angle to null if the resulting color is achromatic.

12.2. HSL/HWB Adjustment

The hsl() and hwb() functions provide alternative ways to specify colors numerically, intended to be easier and more intuitive for humans. Similarly, the color-mod() function allows a color to be adjusted in these "virtual channels".

[hue( | h(] ['+' | '-' | *]? <angle> )

Sets or adjusts the hue of the base color, when base color is interpreted as an HSL color.

If there is no operator, the hue is set to the given value, regardless of what the hue angle was previously.

Otherwise, the hue is incremented or decremented, as appropriate, by the given value. If the hue angle is null, the adjuster instead does nothing.

[saturation( | s(] ['+' | '-' | *]? <percentage> )

[lightness( | l(] ['+' | '-' | *]? <percentage> )

[whiteness( | w(] ['+' | '-' | *]? <percentage> )

[blackness( | b(] ['+' | '-' | *]? <percentage> )

Sets or adjusts the saturation, lightness, whiteness, or blackness of the base color, when base color is interpreted as an HSL or HWB color, as appropriate.

If there is no operator, the given channel is set to the given value.

If the operator is + or -, the given channel is incremented or decremented by the given value.

If the operator is *, the given channel is multiplied by the given value.

If the hue angle is null, the operation is s() or saturation(), and the adjuster would make the saturation greater than 0%, it instead does nothing.

If the hue angle is null, the operation is w(), white(), b(), or black(), and the adjuster would make the sum of whiteness and blackness less than 100%, it additionally adjusts the opposite HWB channel to make the sum equal to 100%. (That is, color(white w(- 20%)) would represent the same color as hwb(0, 80%, 20%).)

12.3. Tints and Shades: the tint and shade adjusters

While the color-mod() function does allow HWB adjustment of colors, the peculiarities of how HWB is defined make it more difficult than it should be to just define a lighter or darker version of a color. The tint and shade adjusters fix this, by simply mixing the base color with white or black.

''tint( <percentage> )''

Mixes the base color with pure white to produce a lighter version of the base color.

Specifying a <percentage> less than 0% or greater than 100% is a syntax error, and makes the function invalid.

Linearly interpolate the red, green, and blue channels of the base color with the red, green, and blue channels of pure white (rgb(255,255,255)), where 0% returns the base color and 100% returns pure white.

Note: tint(X%) is identical to blend(white X% rgb).

''shade( <percentage> )''

Mixes the base color with pure black to produce a darker version of the base color.

Identical to the previous clause, except the base color is mixed with pure black (rgb(0,0,0)) rather than pure white.

12.4. Color Blending: the blend and blenda adjusters

The tint() and shade() adjusters are common cases of the more general blend() adjuster, which mixes the base color with an arbitrary color.

''blend( <color> <percentage> [rgb | hsl | hwb]? )''

Mixes the base color with the given color to produce an intermediate color.

Specifying a <percentage> less than 0% or greater than 100% is a syntax error, and makes the function invalid.

The final argument specifies which color space to blend the colors in, defaulting to rgb if not specified. Both the base color and the given color are interpreted as colors in the given color space, then the components are blended.

For example, color(yellow blend(blue 50%)) blends yellow (#ffff00) with blue (#0000ff) equally, resulting in #808080, a medium gray.

On the other hand, color(yellow blend(blue 50% hsl)) blends the same colors in HSL space, where yellow is hsl(60, 100%, 50%) and blue is hsl(240, 100%, 50%), which results in hsl(150, 100%, 50%), a fully-saturated shade of green.

To determine the resulting color, interpret the base color and the given color in the appropriate color space (RGB, HSL, or HWB). Linearly interpolate each of the channels of the colors according to the given <percentage>, where 0% produces the specified <color> and 100% produces the base color.

If the color space is hsl or hwb, interpolate the hue channel either clockwise or counterclockwise, whichever results in a shorter "path" between the two hue angles. If the two hue angles are on opposite sides of the hue circle (separated by 180 degrees), take the clockwise path.

If the hue angle is null for one of the colors but not the other, treat the null hue angle as being equal to the non-null hue angle for the purpose of this adjuster. If both hue angles are null, the resulting color’s hue angle is null as well.

Note: The choice of how to transition when the difference is 180deg is arbitrary, and was chosen merely to provide an unambiguous answer. To achieve counter-clockwise behavior, adjust either color’s hue angle by a small amount toward the desired direction.

For example, blending yellow (hue angle 60deg) with 50% purple (hue angle 300deg) results in red (hue angle 0deg), not cyan (hue angle 180deg), even though 60*50% + 300*50% == 180, because the distance between the two colors when moving counter-clockwise is only 120 degrees, as opposed to 240 degrees when going clockwise.

''blenda( <color> <percentage> [rgb | hsl | hwb]? )''

Identical to the previous clause, except it pays attention to the alpha channel of the two colors (blend() just preserves the alpha channel of the base color).

Let w be the specified <percentage>, rescaled to the range [-1,1], where 0% maps to -1 and 100% maps to 1. Let a be the difference of the alpha channels of the base color and the specified <color>, also rescaled to the range [-1,1], where -100% (0% base color alpha and 100% specified color alpha) maps to -1 and 100% maps to 1.

If w * a == -1, let new weight equal w. Otherwise, let new weight equal (w + a) / (1 + w*a).

Reinterpret new weight as a percentage in the range [0%, 100%], where -1 maps to 0% and 1 maps to 100%. Calculate the result color as if blend() had been specified, using the new weight percentage instead of the specified <percentage>, and set the alpha channel of the result color to the average of the alpha channels of the base color and the specified <color>.

This blends the two colors in a way that pays attention to alpha, similar to how compositing does. Is there a better formula? The current one was determined empirically to give good results, but isn’t motivated by any theory.

Should we swap the defaults, so blend() does the alpha blending, and another name (or maybe another parameter) ignores alpha like blend() currently does? Check with definitions in CSS compositing and blending module.

12.5. Guaranteeing Adequate Contrast: the contrast adjuster

Guaranteeing that foreground and background colors contrast sufficiently is important, but even if one knows the mathematical definition of "appropriate contrast", it’s not trivial to calculate and figure out whether two arbitrary colors are good enough. The contrast() adjuster makes this easy, automatically computing a color that is sufficiently contrasting with the base color to satisfy accessibility guidelines.

''contrast( <percentage>? )''

Finds a color that contrasts with the base color suffficiently to satisfy accessibility guidelines, using the definition of "contrast" given by WCAG 2.0 Guideline 1.4.3.

The <percentage> specifies the desired similarity between the base color and the returned color. 0% will return the minimum-contrast color (the closest color to the base color that still contrasts sufficiently), while 100% will return the maximum-contrast color (white or black, whichever contrasts the base color more) Specifying a value less than 0% or greater than 100% is invalid and a syntax error. If omitted, the <percentage> defaults to 100%.

1. Compute the luminance of the base color. If it’s less than .5, the maximum-contrast color is hwb(X, 100%, 0%), where X is the hue angle of the base color. Otherwise, the maximum-contrast color is hwb(X, 0%, 100%), where X is the hue angle of the base color.

   Note: In other words, the maximum-contrast color is either white or black, but with the hue set up correctly for the next step’s linear interpolation.

2. Looking only at colors that are linear interpolations in HWB space (a la the blend() adjuster) between the base color and the maximum-contrast color, find the color with the smallest contrast ratio with the base color that is greater than 4.5. This is the minimum-contrast color. If there is no color with contrast ratio greather than 4.5, return the maximum-contrast color immediately.

   Note: 4.5 is the contrast ratio required by WCAG for Level AA contrast.

   Note: Using this method, the contrast ratio will be monotonically non-increasing as you go from the maximum-contrast color to the base color, so a simple binary search will identify the minimum-contrast color in a small number of iterations.

3. Blend the minimum-contrast color and maximum-contrast color according to the specified <percentage>, as if ''color(maximum-contrast color blend(minimum-contrast color <percentage> hwb))'' were specified. Return the blended color.

To compute the luminance#luminanceReferenced in:12.5. Guaranteeing Adequate Contrast: the contrast adjuster (2) of a color:

1. Scale the red, green, and blue channels of the color to the range [0,1].
2. For each channel, if the channel’s value is less than or equal to 0.03928, set the channel’s value to channel / 12.92. Otherwise, set the channel’s value to ((channel + 0.055) / 1.055) ^ 2.4.

   Note: This reverses the logarithmic power scaling of the sRGB gamut, so the value of the channel is approximately linear related to the amount of light required to represent it.

3. The luminance is:

   0.2126*R + 0.7152*G + 0.0722*B

   where R, G, and B are the adjusted red, green, and blue channels from the previous step.

Note: The luminance of a color within the sRGB gamut is contained within the range [0,1], where black is 0 and white is 1.

To compute the contrast ratio#contrast-ratioReferenced in:12.5. Guaranteeing Adequate Contrast: the contrast adjuster of two colors:

1. Compute the luminance of both colors.
2. The contrast ratio is:

   (L1 + 0.05) / (L2 + 0.05)

   where L1 is the larger of the two luminances, and L2 is the smaller.

Note: The contrast ratio of two colors is contained within the range [1,21], where two identical colors are 1 and the ratio of white and black is 21.

13. Transparency: the opacity property

Opacity can be thought of as a postprocessing operation. Conceptually, after the element (including its descendants) is rendered into an RGBA offscreen image, the opacity setting specifies how to blend the offscreen rendering into the current composite rendering. See simple alpha compositing for details.

<alpha-value>

The opacity to be applied to the element. It is interpreted identically to its definition in rgba(), except that the resulting opacity is applied to the entire element, rather than a particular color.

The opacity property applies the specified opacity to the element as a whole, including its contents, rather than applying it to each descendant individually. This means that, for example, an opaque child occluding part of the element’s background will continue to do so even when opacity is less than 1, but the element and child as a whole will show the underlying page through themselves.

If opacity has a value less than 1, the element forms a stacking context for its children. This means that any content outside of it cannot be layered in z-order between pieces of content inside of it, and vice versa. If the element is in a context where the z-index property applies, the auto value is treated as 0 for the element. See section 9.9 and Appendix E of [CSS21] for more information on stacking contexts. The rules in this paragraph do not apply to SVG elements, since SVG has its own rendering model ([SVG11], Chapter 3).

13.1. Simple alpha compositing

When drawing, implementations must handle alpha according to the rules in Section 14.2 Simple alpha compositing of [SVG11]. (If the color-interpolation or color-rendering properties mentioned in that section are not implemented or do not apply, implementations must act as though they have their initial values.)

14. Preserving Colors in Different-Capability Devices: the color-adjust property

On most monitors, the color choices that authors make have no significant difference in terms of how the device performs; displaying a document with a white background or a black background is approximately equally easy.

However, some devices have limitations and other qualities that make this assumption untrue. For example, printers tend to print on white paper; a document with a white background thus has to spend no ink on drawing that background, while a document with a black background will have to expend a large amount of ink filling in the background color. This tends to look fairly bad, and sometimes has deleterious physical effects on the paper, not to mention the vastly increased printing cost from expending the extra ink. Even fairly small differences, such as coloring text black versus dark gray, can be quite different when printing, as it switches from using a single black ink to a mixture of cyan, magenta, and yellow ink, resulting in higher ink usage and lower resolution.

As a result, in some circumstances user agents will alter the styles an author specifies in some particular context, adjusting them to be more appropriate for the output device and to accommodate what they assume the user would prefer. However, in some cases the document may be using colors in important, well-thought-out ways that the user would appreciate, and so the document would like some way to hint to the user agent that it might want to respect the page’s color choices. The color-adjust property controls this.

The color-adjust property provides a hint to the user-agent about how it should treat color and style choices that might be expensive or generally unwise on a given device, such as using light text on a dark background in a printed document. If user agents allow users to control this aspect of the document’s display, the user preference must be respected more strongly than the hint provided by color-adjust. It has the following values:

economy

The user agent should make adjustments to the page’s styling as it deems necessary and prudent for the output device.

For example, if the document is being printed, a user agent might ignore any backgrounds and adjust text color to be sufficiently dark, to minimize ink usage.

exact

This value indicates that the page is using color and styling on the specified element in a way which is important and significant, and which should not be tweaked or changed except at the user’s request.

For example, a mapping website offering printed directions might "zebra-stripe" the steps in the directions, alternating between white and light gray backgrounds. Losing this zebra-striping and having a pure-white background would make the directions harder to read with a quick glance when distracted in a car.

15. Default Style Rules

The following stylesheet is informative, not normative. This style sheet could be used by an implementation as part of its default styling of HTML4, XHTML1, XHTML1.1, XHTML Basic, and other XHTML Family documents.

html {
  color: black;
}

/* traditional desktop user agent colors for hyperlinks */
:link    { color: blue; }
:visited { color: purple; }

The default background of the root element must be transparent. The default color of the canvas (the surface on which the document is painted) is UA-dependent, but is recommended to be white, especially if the above color rules are used.

16. APIs for Parsing and Manipulating Colors

In many applications, authors have to use and manipulate colors. CSS allows many different useful syntaxes for colors, but these are only usable in stylesheets, not in script.

This section defines a number of APIs for creating and manipulating colors in script:

• It allows CSS colors to be parsed into JS objects—use the CSSColor.parse("rebeccapurple") method to get a corresponding color object, or one of the specific color constructors, like new HSLColor("rebeccapurple"), to get back a specific type of color class.
• It allows colors to be manipulated in any of the syntaxes that CSS exposes: RGBColor for RGBA colors, with components ranging from 0-1; HexColor for RGBA colors, with components ranging from 0-255; HSLColor for HSLA colors, corresponding to the hsla() syntax; and CMYKColor for CMYK colors, corresponding to the device-cmyk() syntax.

  All of these expose their components as attributes you can manipulate directly, and colors can be easily converted between any of the classes with methods like toRGB() and toHSL().

• It allows colors to be automatically stringified back into a form that CSS understands, so you can write code like:

  var c = new HSLColor("red");
  c.l += .1;
  el.style.backgroundColor = c;
  // c is automatically turned into the string "hsla(0deg, 100%, 60%, 100%)"

  If you wish, you can control what type of syntax it stringifies as, like c.toString("hsl").

• It’s explicitly designed to be easy to extend with new methods and new color types, and gives guidance to help you do it correctly (see §16.6 Extending the Color Classes).

16.1. The RGBColor Object

The RGBColor class is the "primary" color class, because all CSS colors must be RGB-compatible (that is, capable of being converted into a roughly equivalent RGB color). As a result, it’s always possible to convert a UA-defined color class (and any properly-designed author-defined color classes, see §16.6 Extending the Color Classes) into an equivalent RGBColor instance. This fact is used to aid in automatic handling of several methods common to all color classes.

[Constructor(double r, double g, double b, optional double a=1),
 Constructor(RGBColor rgb),
 Constructor(CSSColor css),
 Constructor(optional RGBColorInit color),
 Constructor(DOMString cssstring)]
interface RGBColor#rgbcolorReferenced in:16. 
APIs for Parsing and Manipulating Colors16.1. 
The RGBColor Object (2) (3) (4) (5) (6) (7) (8) (9)16.2. 
The HSLColor Class (2) (3)16.3. 
The HWBColor Class (2) (3)16.4. 
The HexColor Class (2) (3)16.5. 
The CMYKColor Class (2) (3) (4) (5) (6) (7)16.6.1. 
Adding New Color-Manipulating Methods (2)16.6.2. 
Adding New Color Classes (2) (3) (4) (5) (6) (7)16.6.3. 
The CSSColor Object (2) (3) (4) (5) : CSSColor {
  attribute double r;
  attribute double g;
  attribute double b;
  attribute double a;

  RGBColor   toRGB();
  HSLColor   toHSL();
  HexColor   toHex();
  CMYKColor  toCMYK();
  DOMString? toName();

  static attribute ColorStringifiers stringifiers;
  attribute ColorStringifierType defaultStringifier;

};

dictionary RGBColorInit#dictdef-rgbcolorinitReferenced in:16.1. 
The RGBColor Object (2) {
  double r = 0;
  double g = 0;
  double b = 0;
  double a = 1;
};

enum ColorStringifierType#enumdef-colorstringifiertypeReferenced in:16.1. 
The RGBColor Object (2)16.2. 
The HSLColor Class (2)16.3. 
The HWBColor Class (2)16.4. 
The HexColor Class (2)16.5. 
The CMYKColor Class (2)16.6.3. 
The CSSColor Object (2) {
  "rgb",
  "hsl",
  "hex",
  "cmyk"
};

dictionary ColorStringifiers#dictdef-colorstringifiersReferenced in:16.1. 
The RGBColor Object (2)16.2. 
The HSLColor Class (2)16.3. 
The HWBColor Class (2)16.4. 
The HexColor Class (2)16.5. 
The CMYKColor Class (2) {
  ColorStringifierCallback rgb;
  ColorStringifierCallback hsl;
  ColorStringifierCallback hex;
  ColorStringifierCallback cmyk;
};

callback ColorStringifierCallback#callbackdef-colorstringifiercallbackReferenced in:16.1. 
The RGBColor Object (2) (3) (4) = DOMString (CSSColor color, any ...args);

RGBColor(double r, double g, double b, optional double a=1)#dom-rgbcolor-rgbcolorReferenced in:16.1. The RGBColor Object

Defined as follows in ECMAScript:

function(r, g, b, a) {
  this.r = r;
  this.g = g;
  this.b = b;
  this.a = a === undefined ? 1 : a;
  return this;
}

Note: The RGBColor class’s attributes have a normal range of 0 to 1, not 0 to 255. See the HexColor class if you prefer working in the 0-255 range.

RGBColor(RGBColor rgb)#dom-rgbcolor-rgbcolor-rgbReferenced in:16.1. The RGBColor Object

Defined as follows in ECMAScript:

function(rgb) {
  this.r = rgb.r;
  this.g = rgb.g;
  this.b = rgb.b;
  this.a = rgb.a;
  return this;
}

RGBColor(CSSColor css)#dom-rgbcolor-rgbcolor-cssReferenced in:16.1. The RGBColor Object

Defined as follows in ECMAScript:

function(css) {
  const color = css.toRGB();
  this.r = color.r;
  this.g = color.g;
  this.b = color.b;
  this.a = color.a;
  return this;
}

RGBColor(optional RGBColorInit color)#dom-rgbcolor-rgbcolor-colorReferenced in:16.1. The RGBColor Object

Defined as follows in ECMAScript:

function(color) {
  if(color === undefined) color = {r:0, g:0, b:0, a:1};
  this.r = color.r === undefined ? 0 : color.r;
  this.g = color.g === undefined ? 0 : color.g;
  this.b = color.b === undefined ? 0 : color.b;
  this.a = color.a === undefined ? 1 : color.a;
  return this;
}

RGBColor(DOMString cssstring)#dom-rgbcolor-rgbcolor-cssstringReferenced in:16.1. The RGBColor Object

Parse a component value from the passed string. If this operation succeeds and the result is a valid CSS color, construct an instance of the RGBColor class with attributes initialized to represent that color.

Otherwise, throw an XXXError.

toRGB()#dom-rgbcolor-torgbReferenced in:16.1. The RGBColor Object

Defined as follows in ECMAScript:

function() {
  return new RGBColor(this);
}

toHSL()#dom-rgbcolor-tohslReferenced in:16.1. The RGBColor Object

Defined as follows in ECMAScript:

function() {
  return new HSLColor(this);
}

toHex()#dom-rgbcolor-tohexReferenced in:16.1. The RGBColor Object

Defined as follows in ECMAScript:

function() {
  return new HexColor(this);
}

toCMYK()#dom-rgbcolor-tocmykReferenced in:16.1. The RGBColor Object

Defined as follows in ECMAScript:

function() {
  return new CMYKColor(this);
}

toName()#dom-rgbcolor-tonameReferenced in:16.1. The RGBColor Object

Let thisObject be the object this method was called on.

If thisObject’s r, g, b, and a attributes, when multiplied by 255 and rounded to the nearest integer, are equal to the r, g, b, and a values assigned to a named color, return that color’s name as a DOMString.

Otherwise, return null.

r#dom-rgbcolor-rReferenced in:16.1. The RGBColor Object (2) , of type double

g#dom-rgbcolor-gReferenced in:16.1. The RGBColor Object (2) , of type double

b#dom-rgbcolor-bReferenced in:16.1. The RGBColor Object (2) , of type double

a#dom-rgbcolor-aReferenced in:16.1. The RGBColor Object (2) , of type double

The r, g, b, and a attributes represent the red, green, blue, and alpha channels of the RGB color that the RGBColor instance represents.

Note: The RGBColor class’s attributes have a normal range of 0 to 1, not 0 to 255. See the HexColor class if you prefer working in the 0-255 range.

stringifiers#dom-rgbcolor-stringifiersReferenced in:16.1. The RGBColor Object , of type ColorStringifiers

Must be initially set to the following ECMAScript object:

{
  "rgb": function(color) {
    const r = color.r*100 + "%";
    const g = color.g*100 + "%";
    const b = color.b*100 + "%";
    const a = color.a*100 + "%";
    return "rgba(" + [r,g,b,a].join(", ") + ")";
  },
  "hsl": function(color) {
    return "" + color.toHSL();
  },
  "hex": function(color) {
    return "" + color.toHex();
  },
  "cmyk": function(color) {
    return "" + color.toCMYK();
  }
}

defaultStringifier#dom-rgbcolor-defaultstringifierReferenced in:16.1. The RGBColor Object (2) , of type ColorStringifierType

The defaultStringifier attribute must be initially set to "rgb".

16.2. The HSLColor Class

[Constructor(double h, double s, double l, optional double a=1),
 Constructor(RGBColor rgb),
 Constructor(HSLColor hsl),
 Constructor(CSSColor css),
 Constructor(optional HSLColorInit color),
 Constructor(DOMString cssstring)]
interface HSLColor#hslcolorReferenced in:16. 
APIs for Parsing and Manipulating Colors16.1. 
The RGBColor Object16.2. 
The HSLColor Class (2) (3) (4) (5) (6)16.3. 
The HWBColor Class (2) (3)16.6.2. 
Adding New Color Classes16.6.3. 
The CSSColor Object (2) (3) (4) (5) : CSSColor {
  attribute double h;
  attribute double s;
  attribute double l;
  attribute double a;

  RGBColor toRGB();
  HSLColor toHSL();

  static attribute ColorStringifiers stringifiers;
  attribute ColorStringifierType defaultStringifier;
};

dictionary HSLColorInit#dictdef-hslcolorinitReferenced in:16.2. 
The HSLColor Class (2) {
  double h = 0;
  double s = 0;
  double l = 0;
  double a = 1;
};

HSLColor(double h, double s, double l, optional double a=1)#dom-hslcolor-hslcolorReferenced in:16.2. The HSLColor Class

Defined as follows in ECMAScript:

function(h, s, l, a) {
  this.h = h;
  this.s = s;
  this.l = l;
  this.a = a === undefined ? 1 : a;
  return this;
}

HSLColor(RGBColor rgb)#dom-hslcolor-hslcolor-rgbReferenced in:16.2. The HSLColor Class

Defined as follows in ECMAScript:

function(rgb) {
  const {r,g,b,a} = rgb;
  this.a = a;

  const max = Math.max(r, g, b);
  const min = Math.min(r, g, b);
  const chroma = max - min;
  if(chroma == 0) {
    this.h = 0;
  } else if(r == max) {
    this.h = (((g - b) / chroma) % 6) * 360;
  } else if(g == max) {
    this.h = ((((b - r) / chroma) + 2) % 6) * 360;
  } else {
    this.h = ((((r - g) / chroma) + 4) % 6) * 360;
  }

  this.l = (min + max)/2;

  if(this.l == 0 || this.l == 1) {
    this.s = 0;
  } else {
    this.s = chroma / (1 - Math.abs(2 * this.l - 1));
  }

  return this;
}

HSLColor(HSLColor hsl)#dom-hslcolor-hslcolor-hslReferenced in:16.2. The HSLColor Class

Defined as follows in ECMAScript:

function(hsl) {
  this.h = hsl.h;
  this.s = hsl.s;
  this.l = hsl.l;
  this.a = hsl.a;
  return this;
}

HSLColor(CSSColor css)#dom-hslcolor-hslcolor-cssReferenced in:16.2. The HSLColor Class

Defined as follows in ECMAScript:

function(css) {
  const color = css.toHSL();
  this.h = color.h;
  this.s = color.s;
  this.l = color.l;
  this.a = color.a;
  return this;
}

HSLColor(optional HSLColorInit color)#dom-hslcolor-hslcolor-colorReferenced in:16.2. The HSLColor Class

Defined as follows in ECMAScript:

function(color) {
  if(color === undefined) color = {h:0, s:0, l:0, a:1};
  this.h = color.h === undefined ? 0 : color.h;
  this.s = color.s === undefined ? 0 : color.s;
  this.l = color.l === undefined ? 0 : color.l;
  this.a = color.a === undefined ? 1 : color.a;
  return this;
}

HSLColor(DOMString cssstring)#dom-hslcolor-hslcolor-cssstringReferenced in:16.2. The HSLColor Class

Parse a component value from the passed string. If this operation succeeds and the result is a valid CSS color, construct an instance of the HSLColor class with attributes initialized to represent that color.

Otherwise, throw an XXXError.

toRGB()#dom-hslcolor-torgbReferenced in:16.2. The HSLColor Class

Defined as follows in ECMAScript:

function() {
  const max = (1 - Math.abs(2 * this.l - 1)) * this.s;
  const h_ = ((this.h / 60 % 6) + 6) % 6;
  const mid = max * (1 - Math.abs((h_ % 2) - 1));

  if(h_ >= 0 && h_ < 1) {
    return new RGBColor(max, mid, 0);
  } else if(h_ >= 1 && h_ < 2) {
    return new RGBColor(mid, max, 0);
  } else if(h_ >= 2 && h_ < 3) {
    return new RGBColor(0, max, mid);
  } else if(h_ >= 3 && h_ < 4) {
    return new RGBColor(0, mid, max);
  } else if(h_ >= 4 && h_ < 5) {
    return new RGBColor(mid, 0, max);
  } else {
    return new RGBColor(max, 0, mid);
  }
}

toHSL()#dom-hslcolor-tohslReferenced in:16.2. The HSLColor Class

Defined as follows in ECMAScript:

function() {
  return new HSLColor(this);
}

h#dom-hslcolor-hReferenced in:16.2. The HSLColor Class (2) , of type double

s#dom-hslcolor-sReferenced in:16.2. The HSLColor Class (2) , of type double

l#dom-hslcolor-lReferenced in:16.2. The HSLColor Class (2) , of type double

a#dom-hslcolor-aReferenced in:16.2. The HSLColor Class (2) , of type double

The h, s, l, and a attributes represent the hue, saturation, lightness, and alpha channels of the HSL color that the HSLColor instance represents.

Note: The HSLColor class’s hue attribute has a normal range of 0 to 360 (denoted in degrees), and its other attributes have a normal range of 0 to 1.

stringifiers#dom-hslcolor-stringifiersReferenced in:16.2. The HSLColor Class , of type ColorStringifiers

Must be initially set to the following ECMAScript object:

{
  "hsl": function(color) {
    const h = color.h + "deg";
    const s = color.s*100 + "%";
    const l = color.l*100 + "%";
    const a = color.a*100 + "%";
    return "hsla(" + [h,s,l,a].join(", ") + ")";
  }
}

defaultStringifier#dom-hslcolor-defaultstringifierReferenced in:16.2. The HSLColor Class (2) , of type ColorStringifierType

The defaultStringifier attribute must be initially set to "hsl".

16.3. The HWBColor Class

[Constructor(double h, double w, double b, optional double a=1),
 Constructor(RGBColor rgb),
 Constructor(HSLColor hsl),
 Constructor(HWBColor hwb),
 Constructor(CSSColor css),
 Constructor(optional HWBColorInit color),
 Constructor(DOMString cssstring)]
interface HWBColor#hwbcolorReferenced in:16.3. 
The HWBColor Class (2) (3) (4) (5) (6) : CSSColor {
  attribute double h;
  attribute double w;
  attribute double b;
  attribute double a;

  RGBColor toRGB();
  HSLColor toHSL();
  HWBColor toHWB();

  static attribute ColorStringifiers stringifiers;
  attribute ColorStringifierType defaultStringifier;
};

dictionary HWBColorInit#dictdef-hwbcolorinitReferenced in:16.3. 
The HWBColor Class (2) {
  double h = 0;
  double w = 0;
  double b = 0;
  double a = 1;
};

HWBColor(double h, double w, double b, optional double a=1)#dom-hwbcolor-hwbcolorReferenced in:16.3. The HWBColor Class

Defined as follows in ECMAScript:

function(h, w, b, a) {
  this.h = h;
  this.w = w;
  this.b = b;
  this.a = a === undefined ? 1 : a;
  return this;
}

HWBColor(RGBColor rgb)#dom-hwbcolor-hwbcolor-rgbReferenced in:16.3. The HWBColor Class

Defined as follows in ECMAScript:

function(rgb) {
  const {r,g,b,a} = rgb;
  this.a = a;

  const max = Math.max(r, g, b);
  const min = Math.min(r, g, b);
  const chroma = max - min;
  if(chroma == 0) {
    this.h = 0;
  } else if(r == max) {
    this.h = (((g - b) / chroma) % 6) * 360;
  } else if(g == max) {
    this.h = ((((b - r) / chroma) + 2) % 6) * 360;
  } else {
    this.h = ((((r - g) / chroma) + 4) % 6) * 360;
  }
  this.w = min;
  this.b = 1 - max;
  return this;
}

HWBColor(HSLColor hsl)#dom-hwbcolor-hwbcolor-hslReferenced in:16.3. The HWBColor Class

Defined as follows in ECMAScript:

function(hsl) {
  this.h = hsl.h;
  this.a = hsl.a;
  ...

  return this;
}

HWBColor(HWBColor hwb)#dom-hwbcolor-hwbcolor-hwbReferenced in:16.3. The HWBColor Class

Defined as follows in ECMAScript:

function(hsl) {
  this.h = hwb.h;
  this.w = hwb.w;
  this.b = hwb.b;
  this.a = hwb.a;
  return this;
}

HWBColor(CSSColor css)#dom-hwbcolor-hwbcolor-cssReferenced in:16.3. The HWBColor Class

Defined as follows in ECMAScript:

function(css) {
  const color = css.toHWB();
  this.h = color.h;
  this.w = color.w;
  this.b = color.b;
  this.a = color.a;
  return this;
}

HWBColor(optional HWBColorInit color)#dom-hwbcolor-hwbcolor-colorReferenced in:16.3. The HWBColor Class

Defined as follows in ECMAScript:

function(color) {
  if(color === undefined) color = {h:0, w:0, b:0, a:1};
  this.h = color.h === undefined ? 0 : color.h;
  this.w = color.w === undefined ? 0 : color.w;
  this.b = color.b === undefined ? 0 : color.b;
  this.a = color.a === undefined ? 1 : color.a;
  return this;
}

HWBColor(DOMString cssstring)#dom-hwbcolor-hwbcolor-cssstringReferenced in:16.3. The HWBColor Class

Parse a component value from the passed string. If this operation succeeds and the result is a valid CSS color, construct an instance of the HWBColor class with attributes initialized to represent that color.

Otherwise, throw an XXXError.

toRGB()#dom-hwbcolor-torgbReferenced in:16.3. The HWBColor Class

Defined as follows in ECMAScript:

function() {
  let w = this.w;
  let b = this.b;
  if(w+b > 1) {
    const sum = w+b;
    w /= sum;
    b /= sum;
  }

  const h = ((this.h / 60 % 6) + 6) % 6;
  const max = 1 - b;
  const mid = 1 - Math.abs((h % 2) - 1);
  const min = w;

  if(h >= 0 && h_ < 1) {
    return new RGBColor(max, mid, min);
  } else if(h >= 1 && h < 2) {
    return new RGBColor(mid, max, min);
  } else if(h >= 2 && h < 3) {
    return new RGBColor(min, max, mid);
  } else if(h >= 3 && h < 4) {
    return new RGBColor(min, mid, max);
  } else if(h >= 4 && h < 5) {
    return new RGBColor(mid, min, max);
  } else {
    return new RGBColor(max, min, mid);
  }

toHSL()#dom-hwbcolor-tohslReferenced in:16.3. The HWBColor Class

Defined as follows in ECMAScript:

...

toHWB()#dom-hwbcolor-tohwbReferenced in:16.3. The HWBColor Class

Defined as follows in ECMAScript:

function() {
  return new HWBColor(this);
}

h#dom-hwbcolor-hReferenced in:16.3. The HWBColor Class (2) , of type double

w#dom-hwbcolor-wReferenced in:16.3. The HWBColor Class (2) , of type double

b#dom-hwbcolor-bReferenced in:16.3. The HWBColor Class (2) , of type double

a#dom-hwbcolor-aReferenced in:16.3. The HWBColor Class (2) , of type double

The h, w, b, and a attributes represent the hue, whiteness, blackness, and alpha channels of the HWB color that the HWBColor instance represents.

Note: The HWBColor class’s hue attribute has a normal range of 0 to 360 (denoted in degrees), and its other attributes have a normal range of 0 to 1.

stringifiers#dom-hwbcolor-stringifiersReferenced in:16.3. The HWBColor Class , of type ColorStringifiers

Must be initially set to the following ECMAScript object:

{
  "hwb": function(color) {
    const h = color.h + "deg";
    const w = color.w*100 + "%";
    const b = color.b*100 + "%";
    const a = color.a*100 + "%";
    return "hwb(" + [h,w,b,a].join(", ") + ")";
  }
}

defaultStringifier#dom-hwbcolor-defaultstringifierReferenced in:16.3. The HWBColor Class (2) , of type ColorStringifierType

The defaultStringifier attribute must be initially set to "hwb".