@capsizecss/metrics 1.3.0 → 2.0.0

package/README.md

@@ -41,20 +41,34 @@ const capsizeStyles = createStyleObject({
 
 The font metrics object returned contains the following properties if available:
 
-| Property   | Type   | Description                                                                                                                                                                                     |
-| ---------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| familyName | string | The font family name as authored by font creator                                                                                                                                                |
-| category   | string | The style of the font: serif, sans-serif, monospace, display, or handwriting.                                                                                                                   |
-| capHeight  | number | The height of capital letters above the baseline                                                                                                                                                |
-| ascent     | number | The height of the ascenders above baseline                                                                                                                                                      |
-| descent    | number | The descent of the descenders below baseline                                                                                                                                                    |
-| lineGap    | number | The amount of space included between lines                                                                                                                                                      |
-| unitsPerEm | number | The size of the font’s internal coordinate grid                                                                                                                                                 |
-| xHeight    | number | The height of the main body of lower case letters above baseline                                                                                                                                |
-| xWidthAvg  | number | The average width of lowercase characters.<br/><br/>Currently derived from latin [character frequencies] in English language, falling back to the built in [xAvgCharWidth] from the OS/2 table. |
-
-[character frequencies]: https://en.wikipedia.org/wiki/Letter_frequency#Relative_frequencies_of_letters_in_other_languages
+| Property   | Type   | Description                                                                                                                                                                                   |
+| ---------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| familyName | string | The font family name as authored by font creator                                                                                                                                              |
+| category   | string | The style of the font: serif, sans-serif, monospace, display, or handwriting.                                                                                                                 |
+| capHeight  | number | The height of capital letters above the baseline                                                                                                                                              |
+| ascent     | number | The height of the ascenders above baseline                                                                                                                                                    |
+| descent    | number | The descent of the descenders below baseline                                                                                                                                                  |
+| lineGap    | number | The amount of space included between lines                                                                                                                                                    |
+| unitsPerEm | number | The size of the font’s internal coordinate grid                                                                                                                                               |
+| xHeight    | number | The height of the main body of lower case letters above baseline                                                                                                                              |
+| xWidthAvg  | number | The average width of character glyphs in the font. Calculated based on character frequencies in written text ([see below]), falling back to the built in [xAvgCharWidth] from the OS/2 table. |
+
+#### How `xWidthAvg` is calculated
+
+The `xWidthAvg` metric is derived from character frequencies in written language.
+The value takes a weighted average of character glyph widths in the font, falling back to the built in [xAvgCharWidth] from the OS/2 table if the glyph width is not available.
+
+The purpose of this metric is to support generating CSS metric overrides (e.g. [`ascent-override`], [`size-adjust`], etc) for fallback fonts, enabling inference of average line lengths so that a fallback font can be scaled to better align with a web font. This can be done either manually or using [`createFontStack`].
+
+For this technique to be effective, the metric factors in a character frequency weightings as observed in written language, using “abstracts” from [Wikinews] articles as a data source.
+Currently only supporting English ([source](https://en.wikinews.org/)).
+
+[see below]: #how-xwidthavg-is-calculated
 [xavgcharwidth]: https://learn.microsoft.com/en-us/typography/opentype/spec/os2#xavgcharwidth
+[`ascent-override`]: https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/ascent-override
+[`size-adjust`]: https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/size-adjust
+[`createfontstack`]: ../core/README.md#createfontstack
+[wikinews]: https://www.wikinews.org/
 
 ## Supporting APIs