Add explainer for font-palette

css-fonts-4/palette-explainer.md

@@ -0,0 +1,118 @@
+# `font-palette` and `@font-palette-values`
+
+## Authors
+
+* Dominik Röttsches, [@drott]([email protected])
+
+## 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;
+}
+```