diff --git a/css-fonts-4/palette-explainer.md b/css-fonts-4/palette-explainer.md new file mode 100644 index 00000000000..f611c04691d --- /dev/null +++ b/css-fonts-4/palette-explainer.md @@ -0,0 +1,118 @@ +# `font-palette` and `@font-palette-values` + +## Authors + +* Dominik Röttsches, [@drott](drott@chromium.org) + +## Introduction ## + +The `font-palette` CSS property allows selecting a palette +from a vector color font. +In combination with the `@font-palette-values` at-rule, +custom palettes can be defined. +`font-palette` can increase efficiency of color font uses, +as no server roundtrip is needed +for changing the colors of the font. +Use cases are listed below. + +## Technical background + +Color fonts in formats such as COLRv0 and COLRv1 +allow control over their palette +by means of the [`CPAL` OpenType table](https://docs.microsoft.com/en-us/typography/opentype/spec/cpal), +from which the COLR paint tables reference colors. + +CPAL specifies a set of palettes, +each with the same number of specified entries. +Each entry is an RGB color value in 8-bit BGRA in sRGB color space. +Individual palettes can be tagged to indicate +that they are usable for a light or dark background respectively. + +A COLR/CPAL color font can be displayed in a different set of colors +by selecting a palette from the ones specified in the font, +or by providing a custom palette to the rasterization stage, +for example by starting from a defined palette and overriding +individual palette entries. + +[OT-SVG has a mechanism](https://docs.microsoft.com/en-us/typography/opentype/otspec181/svg#color-palettes) +to populate `CPAL` color table color entries +into CSS custom variables +in the form of `--color0`, `--color1` etc.. +This allows OT-SVG fonts to reference CPAL entries as well, +in addition to existing ways of specifying color in SVG. + +# Use cases # + +1. I want to select a color scheme of my color font that works well with light mode or dark mode. + +2. I want to select one of the font designer provided color schemes that come with my font. + +3. I want to adapt a color font to my page design and override colors so that colors in page and font harmonize. + +# Non-Goals # + +`font-palette` is not intended to work with bitmap color fonts. + +# Proposed Syntax # + +See +[9.1. Controlling Color Font Palettes: The font-palette property](https://www.w3.org/TR/css-fonts-4/#font-palette-prop) + +# Examples # + +## Use Case 1: Select light or dark-mode suitable palette ## + + +```CSS +@font-face { + font-family: MyVectorColorFont; + src: url(MyColorFont.woff2) tech(color-COLRv0); +} + +@media (prefers-color-scheme: dark) { + .font-colors: { font-palette: light; } +} + +@media (prefers-color-scheme: light) { + .font-colors: { font-palette: dark; } +} +``` + +## Use Case 2: Select available palette ## + +```CSS +@font-face { + font-family: MyVectorColorFont; + src: url(MyColorFont.woff2) tech(color-COLRv0); +} + +@font-palette-values --SelectedPalette { + font-family: MyVectorColorFont; + base-palette: 3; +} + +.palette-selection { + font-palette: --SelectedPalette; +} +``` + +## Use Case 3: Custom colors ## + +```CSS +@font-face { + font-family: MyVectorColorFont; + src: url(MyColorFont.woff2) tech(color-COLRv0); +} + +@font-palette-values --OverridenColors { + font-family: MyVectorColorFont; + base-palette: 0; + override-colors: 0 rgb(127, 63, 49), + 1 rgb(70, 60, 50), + 2 rgba(0, 30, 30, 30); +} + +.palette-selection { + font-palette: --OverridenColors; +} +```