Overview.bs

<pre class='metadata'>
Title: CSS Fonts Module Level 5
Shortname: css-fonts
Level: 5
Status: ED
Prepare for TR: no
Date: 2021-12-21
Work Status: exploring
Group: CSSWG
ED: https://drafts.csswg.org/css-fonts-5/
TR: https://www.w3.org/TR/css-fonts-5/
Previous Version: https://www.w3.org/TR/2021/WD-css-fonts-5-20211221/
!Delta Spec: yes
Editor: Myles C. Maxfield, Apple Inc., mmaxfield@apple.com, w3cid 77180
Editor: Chris Lilley, W3C, https://svgees.us/, w3cid 1438
Abstract: This specification defines modifications to the existing <a href="https://drafts.csswg.org/css-fonts-4/">CSS Fonts 4</a> specification along with additional features.
Repository: w3c/csswg-drafts
Inline Github Issues: title
Default Highlight: css
</pre>

<pre class="link-defaults">
spec:css-color-4; type:property; text:color
spec:css-values; type:value; text:ex
spec:css22; type:value; for:/; text:block
spec:html; type:element; text:font
spec:css-fonts-4; type:property; text:font-size
spec:css-fonts-4; type:descriptor; text:font-language-override
spec:css-fonts-4;  type:property; text:font-family
spec:css-fonts-4;  type:property; text:font-style
spec:css-fonts-4;  type:property; text:font-weight
spec:css-fonts-4; type:descriptor; text:src
</pre>


<h2 id="introduction">
Introduction</h2>

The CSS Fonts Level 4 specification ([[!CSS-FONTS-4]]) describes the
controls CSS provides for selecting and using fonts within documents,
including support for variable fonts and color fonts.
The ideas here are additions or modifications to the properties and
rules defined in CSS Fonts Level 4.

This specification is currently a delta to the CSS Fonts Level 4 specification.
Do not assume that if something is not here, it has been dropped.



<h3 id="values">
Value Definitions</h3>

This specification follows the <a href="https://www.w3.org/TR/CSS2/about.html#property-defs">CSS property definition conventions</a> from [[!CSS2]]
using the <a href="https://www.w3.org/TR/css-values-3/#value-defs">value definition syntax</a> from [[!CSS-VALUES-3]].
Value types not defined in this specification are defined in CSS Values &amp; Units [[!CSS-VALUES-3]].
Combination with other CSS modules may expand the definitions of these value types.

In addition to the property-specific values listed in their definitions,
all properties defined in this specification
also accept the <a>CSS-wide keywords</a> as their property value.
For readability they have not been repeated explicitly.

<h2 id="basic-font-props">
Basic Font Properties</h2>

Issue(126):

<h3 id="font-family-prop">
Font family: the 'font-family!!property' property</h3>

<h4 id="generic-font-families">
Generic font families</h4>

In addition to the [[css-fonts-4#generic-font-families]]
in CSS Fonts Level 4, the following new generic font families are also defined.

Issue(4910):

Issue(5054):

    <dl dfn-for="font-family,<generic-family>" dfn-type=value>
        <dt id="xxx-def"><dfn>xxx</dfn>
        <dd>
            Placeholder text for the xxx generic font family.
    </dl>

Issue(4566):

<h3 id="font-weight-prop">Font weight: the 'font-weight!!property' property</h3>

Issue(2690):


<h3 id="font-style-prop">
Font style: the 'font-style!!property' property</h3>

Issue(4044):


<h3 id="font-size-adjust-prop">
Relative sizing: the 'font-size-adjust' property</h3>

	<pre class="propdef">
	Name: font-size-adjust
	Value: none | [ ex-height | cap-height | ch-width | ic-width | ic-height ]? [ from-font | <<number>> ]
	Initial: none
	Applies to: all elements and text
	Inherited: yes
	Percentages: N/A
	Computed value: the keyword ''font-size-adjust/none'', or a pair of a metric keyword and a <<number>>
	Animation type: discrete if the keywords differ, otherwise by computed value type
	</pre>

	For any given font size, the apparent size and effective legibility of text
	varies across fonts as a function of their design.
	For example,
	for bicameral scripts such as Latin or Cyrillic that
	distinguish between upper and lowercase letters,
	the relative height of lowercase letters
	compared to their uppercase counterparts
	is a determining factor of legibility.
	In situations where font fallback occurs,
	fallback fonts might not share
	the same ratios as the desired font family
	for key typographic metrics,
	and will thus appear to be a different size
	and possibly be less readable.

	The 'font-size-adjust' property provides a way
	to preserve the readability and apparent size of text
	when font fallback occurs.
	It does this by adjusting the used font size
	so that the specified metric is the same
	regardless of the font used.

	Values have the following meanings:

	<dl dfn-type=value dfn-for="font-size-adjust">
		<dt><dfn>none</dfn>
		<dd>
			No special 'font-size!!property' adjustment is applied.

		<dt><dfn>ex-height | cap-height | ch-width | ic-width | ic-height</dfn>
		<dd>
			Specifies the font metric to normalize,
			defaulting to ''font-size-adjust/ex-height'':

			<dl>
				<dt><dfn>ex-height</dfn>
				<dd>
					Normalize the <dfn dfn>aspect value</dfn> of the fonts,
					using the x-height divided by the font size.

				<dt><dfn>cap-height</dfn>
				<dd>
					Normalize the cap-height of the fonts,
					using the cap-height by the font size.

				<dt><dfn>ch-width</dfn>
				<dd>
					Normalize the horizontal narrow pitch of the fonts,
					using the advance width of “0” (ZERO, U+0030)
					divided by the font size.

				<dt><dfn>ic-width</dfn>
				<dd>
					Normalize the horizontal wide pitch of the font,
					using the advance width of “水” (CJK water ideograph, U+6C34)
					divided by the font size.

				<dt><dfn>ic-height</dfn>
				<dd>
					Normalize the vertical wide pitch of the font,
					using the advance height of “水” (CJK water ideograph, U+6C34)
					divided by the font size.
			</dl>

			ISSUE(6384):
			If the required font metric cannot be derived from a font,
			then that font’s size is not adjusted.

		<dt><dfn><<number>></dfn>
		<dd>
			Each font’s [=used value|used=] size is normalized
			to match the chosen font metric to
			this specified proportion of the [=computed value|computed=] 'font-size!!property'.
			In other words,
			for each glyph,
			the adjusted font size to use <var>u</var>
			is calculated as:

			<pre><var>u</var>  =  ( <var>m</var> / <var>m′</var> ) <var>s</var></pre>

			where:

			<pre>
			<var>s</var>  =  computed 'font-size!!property' value
			<var>m</var>  =  metric as specified by the 'font-size-adjust' property
			<var>m′</var> =  metric as specified in the actual font
			<var>u</var>  =  adjusted font-size to use
			</pre>

			Negative values are invalid.

		<dt><dfn>from-font</dfn>
		<dd>
			Computes to the <<number>> corresponding to
			the specified metric of the [=first available font=].

			ISSUE(6384): Shouldn't this be the first available font
			that can provide the required metric?
	</dl>

	<div class="example">
		The style defined below defines Verdana as the desired font family,
		but if Verdana is not available Futura or Times will be used.
		One paragraph also has font-size-adjust specified.

		<pre>
			p {
				font-family: Verdana, Futura, Times;
			}
			p.adj {
				font-size-adjust: 0.545;
			}

			&lt;p>Lorem ipsum dolor sit amet, ...&lt;/p>
			&lt;p class="adj">Lorem ipsum dolor sit amet, ...&lt;/p>
		</pre>

		Verdana has a relatively high aspect value of 0.545,
		meaning lowercase letters are relatively tall
		compared to uppercase letters,
		so at small sizes text appears legible.
		Times has a lower aspect value of 0.447,
		and so if fallback occurs,
		the text will be less legible at small sizes than Verdana
		unless font-size-adjust is also specified.

		Note: For text which uses diacritics,
		too large an x-height will actually decrease legibility
		as the diacritics become cramped.

		How text rendered in each of these fonts compares is shown below,
		the columns show text rendered in Verdana, Futura and Times.
		The same font-size value is used across cells
		within each row and red lines are included to show the differences in x-height.
		In the upper half, each row is rendered in the same font-size value.
		The same is true for the lower half,
		but in this half the 'font-size-adjust' property is also set
		to 0.545,
		so that the actual font size is adjusted
		to preserve the x-height of Verdana across each row.
		Note how small text remains relatively legible across each row in the lower half.

		<figure>
			<img alt="text with and without 'font-size-adjust'" src="images/fontsizeadjust.png" >
			<figcaption>Text with and without the use of 'font-size-adjust'</figcaption>
		</figure>
	</div>

	The value of 'font-size-adjust' affects the [=used value|used=] value of 'font-size!!property'
	but does not affect the [=computed value|computed=] value.
	Therefore it can affect the size of relative units
	that are based on font metrics
	such as <code>ex</code> and <code>ch</code>
	but does not affect the size of <code>em</code> units.
	Since numeric values of 'line-height'
	refer to the [=computed value|computed=] size of 'font-size!!property',
	'font-size-adjust' also does not affect the [=used value|used=] value of 'line-height'.

	Note: Since 'font-size-adjust' does not factor into the 'line-height',
	specifying a line height too tightly can result in overlapping lines of text.
	For example, when a fallback font with a low [=aspect value=]
	is normalized to match one with a high [=aspect value=],
	its ascenders and descenders are likely to extend outside the line box
	with ''line-height: 1''.

	The 'font-size-adjust' adjustment applies to any font that is selected
	but in typical usage it would be based
	on the corresponding metric value
	of the first (most desired) font in the 'font-family' list.
	If this is specified accurately,
	the <code>(<var>m</var>/<var>m′</var>)</code> term in the adjustment formula
	will resolve to <code>1</code> for the first font
	and no adjustment occurs for that font;
	and the rest of the fonts will resolve to match.
	If the value is specified inaccurately,
	text rendered using the first font in the family list
	will display differently in older user agents
	that don't support 'font-size-adjust'.

	<div class="example">
		Authors can calculate the <a>aspect value</a> for a given font
		by comparing spans with the same content
		but different 'font-size-adjust' properties.
		If the same font-size is used, the spans will match
		when the 'font-size-adjust' value is accurate for the given font.

		Two spans with borders are used to determine the <a>aspect value</a> of a font.
		The 'font-size!!property' is the same for both spans
		but the 'font-size-adjust' property is specified only for the right span.
		Starting with a value of 0.5,
		the aspect value can be adjusted
		until the borders around the two letters line up.

		<pre>
		p {
			font-family: Futura;
			font-size: 500px;
		}

		span {
			border: solid 1px red;
		}

		.adjust {
			font-size-adjust: 0.5;
		}

		&lt;p>&lt;span>b&lt;/span>&lt;span class="adjust">b&lt;/span>&lt;/p>
		</pre>

		<figure>
			<img alt="Futura with an aspect value of 0.5" src="images/beforefontsizeadjust.png" >
			<figcaption>Futura with an <a>aspect value</a> of 0.5</figcaption>
		</figure>

		The box on the right is a bit bigger than the one on the left, so the <a>aspect value</a> of this font is something less than 0.5.
		Adjust the value until the boxes align.
	</div>

	Note: If the specified metric has been overridden in ''@font-face'',
	e.g. by 'size-adjust',
	then the overridden metric will be used in the 'font-size-adjust' calculation.
	Consequently, applying 'font-size-adjust' and 'size-adjust' together
	means that 'size-adjust' appears to have no effect.

<h2 id="font-resources">
Font Resources</h2>

<h3 id="font-face-rule">
The <dfn id="at-font-face-rule">''@font-face''</dfn> rule</h3>

	Note: Descriptors are applied per-font rather than per-element.
	Multiple fonts can be used within an individual element
	e.g. for characters not supported by the [=first available font=].

<h3 id="src-desc">Font reference: the 'src' descriptor</h3>


<!-- same as CSS Fonts 4, keep the two in sync -->
<h4 id="font-face-src-parsing">Parsing the 'src!!descriptor' descriptor</h4>

The 'src!!descriptor' descriptor value must be parsed
according to section [[css-syntax#parse-comma-separated-list-of-component-values]].
Then each component value is parsed according to this grammar:


<pre><<url>> [ format(<<font-format>>)]? [ tech( <<font-tech>>#)]? | local(<<font-face-name>>)</pre>

<pre class="prod"><dfn id="font-format-values">&lt;font-format&gt;</dfn>
	 = [<<string>> | collection | embedded-opentype | opentype
		| svg | truetype | woff | woff2 ]</pre>

<pre class="prod"><dfn id="font-tech-values">&lt;font-tech&gt;</dfn>
	= [<<font-features-tech>> | <<color-font-tech>>
		| variations | palettes | 
			incremental-patch | incremental-range | incremental-auto ]</pre>

<pre class="prod"><dfn id="font-features-tech-values">&lt;font-features-tech&gt;</dfn>
	= [features-opentype | features-aat | features-graphite]</pre>

<pre class="prod"><dfn id="color-font-tech-values">&lt;color-font-tech&gt;</dfn>
	= [color-COLRv0 | color-COLRv1 | color-SVG | color-sbix | color-CBDT ]</pre>

If a component value is parsed correctly
and is a supported [[css-fonts-4#font-format-definitions]] or
[[css-fonts-4#font-tech-definitions]],
add it to the list of supported sources.
If parsing a component value results in a parsing error
or its format or tech are unsupported,
do not add it to the list of supported sources.

If there are no supported entries at the end of this process,
the value for the 'src!!descriptor' descriptor is a parse error.

These parsing rules allow for graceful fallback of fonts
for user agents which don't support a particular font tech
or font format.

<div class="example" id="ex-incremental">
	For example,
	when incremental transfer is not supported,
	a woff2 compressed version of the font
	is supplied,
	for optimal performance.
	Then,
	for incremental transfer using the
	<a href="https://w3c.github.io/IFT/Overview.html#range-request-incxfer">range-request method</a>,
	the raw uncompressed OpenType font is provided
	so that the client
	can perform byte range requests.

	<pre>
	@font-face {
		font-family: "MyIncrementallyLoadedWebFont";
		src: url("FallbackURLForBrowsersWhichDontSupportIncrementalLoading.woff2") format("woff2");
		src: url("MyIncrementallyLoadedWebFont.otf") format(opentype)  tech(incremental-range);
	}
	</pre>
</div>


<h3 id="font-size-desc">
Font property descriptors: the 'font-size!!descriptor'
</h3>

Issue(806):

Issue(731):

<pre class='descdef'>
Name: font-size
Value: auto | [<<number>>]{1,2}
Initial: normal
For: @font-face
</pre>

<dl dfn-type="value" dfn-for="@font-face/font-size">
    <dt><dfn>auto</dfn></dt>
    <dd>
        The font matches any font size
    </dd>
    <dt><dfn><<number>></dfn></dt>
    <dd>
        If a single <<number>> is given
        the font matches that specific font size, only.
        If two <<number>>s are given,
        they specify a range of font sizes which will match.
    </dd>
</dl>


<h3 id="size-adjust-desc">
Glyph Size Multiplier:
the 'size-adjust' descriptor</h3>

	<pre class='descdef'>
	Name: size-adjust
	Value: <<percentage [0,∞]>>
	For: @font-face
	Initial: 100%
	</pre>

	The 'size-adjust' descriptor defines a multiplier
	for glyph outlines and metrics associated with this font,
	to allow the author to harmonize the designs of various fonts
	when rendered at the same 'font-size!!property'.

	All metrics associated with this font--
	including glyph advances, baseline tables, and overrides provided by ''@font-face'' descriptors--
	are scaled by the given percentage,
	as are the rendered glyph images.
	Consequently,
	any values derived from font metrics
	(such as ''ex'' and ''ch'' units,
	or the ''text-decoration-thickness/from-font'' value of 'text-decoration-thickness')
	are also affected when sourced from this font.
	However, the [=computed value|computed=] 'font-size!!property'
	(and thus any values that derive from it,
	such as ''em'' units, percentages in 'text-underline-offset', etc.)
	remains unaffected.

	Note: The 'size-adjust' descriptor functions similarly to
	the 'font-size-adjust' property,
	which essentially calculates an adjustment per font by matching ex heights,
	but likewise does not affect the [=computed value|computed=] 'font-size!!property'.

<!-- should this stay in Fonts 4 or be here in Fonts 5? -->

<h3 id="font-metrics-override-desc">
Line Height Font Metrics Overrides:
the 'ascent-override', 'descent-override', and 'line-gap-override' descriptors</h3>

	<pre class='descdef'>
	Name: ascent-override
	Value: [ normal | <<percentage [0,∞]>> ]{1,2}
	For: @font-face
	Initial: normal
	</pre>

	<pre class='descdef'>
	Name: descent-override
	Value: [ normal | <<percentage [0,∞]>> ]{1,2}
	For: @font-face
	Initial: normal
	</pre>

	<pre class='descdef'>
	Name: line-gap-override
	Value: [ normal | <<percentage [0,∞]>> ]{1,2}
	For: @font-face
	Initial: normal
	</pre>

	The 'ascent-override', 'descent-override', and 'line-gap-override' descriptors specify the
	<a spec="CSS-INLINE-3">ascent metric</a>,
	<a spec="CSS-INLINE-3">descent metric</a>, and
	<a spec="CSS-INLINE-3">line gap metric</a>
	of the font, respectively.
	The first value provides the value for the x axis,
	and the second value provides the value for the y axis
	(defaulting to ''ascent-override/normal'' if omitted).

	<dl dfn-for="ascent-override!!descriptor,descent-override!!descriptor,line-gap-override!!descriptor" dfn-type=value>
		<dt><dfn>normal</dfn>
		<dd>
			The corresponding metric value is obtained from the font as usual,
			as if this descriptor were absent from the <code>@font-face</code> block.

			Note: Since there are multiple sources of such metrics in some font formats,
			this can result in text layout that varies across UAs/platforms.

		<dt><dfn><<percentage>></dfn>
		<dd>
			The corresponding metric is replaced by
			the given percentage multiplied by the used font size.
	</dl>

	The 'font-size-adjust' property is applied after the 'size-adjust' descriptor.

	Note: The consequence of applying 'font-size-adjust' after 'size-adjust' is that
	'size-adjust' appears to have no effect.

	Note: None of these descriptors affect the [=computed value|computation=] of
	'font-size!!property', 'line-height', or [=font-relative lengths=].
	They can, however, affect the behavior of ''line-height: normal''
	and more generally the baseline alignment of [=inline-level=] content.

	Note: Since these metrics are only applicable in the [=block axis=],
	the y-axis value will only be used
	when [=typesetting upright=] in vertical [=typographic modes=].

<div class="example">
	The percentage is resolved against different font sizes for different elements.

	<pre>
	@font-face {
	  font-family: overridden-font;
	  ascent-override: 50%;
	  ...
	}

	&lt;span style="font-family: overridden-font; font-size: 20px;"&gt;
	  Outer span content
	  &lt;span style="font-size: 150%;"&gt;Inner span content&lt;/span&gt;
	&lt;/span&gt;
	</pre>

	The outer span uses an <a spec="CSS-INLINE-3" lt="ascent metric">ascent</a> value of
	10px, whereas the inner span uses 15px.
</div>

<div class="example">
	We may override the metrics of a local fallback font to match the primary font, which
	is a web font. This reduces layout shifting when switching from fallback to the
	primary font.

	<pre>
	@font-face {
	  font-family: cool-web-font;
	  src: url("https://example.com/font.woff");
	}

	@font-face {
	  font-family: fallback-to-local;
	  src: local(Some Local Font);
	  /* Override metric values to match cool-web-font */
	  ascent-override: 125%;
	  descent-override: 25%;
	  line-gap-override: 0%;
	  size-adjust: 96%;
	}

	&lt;div style="font-family: cool-web-font, fallback-to-local"&gt;Title goes here&lt;/div&gt;
	&lt;img src="https://example.com/largeimage" alt="A large image that you don't want to shift"&gt;
	</pre>

	The image will not be shifted as much when the user agent finishes loading and
	switches to use the web font (assuming the override values are similar to the web font's
	natural metrics).
</div>

<h3 id="font-sup-sub-override-desc">
Superscript and subscript metrics overrides:
the 'superscript-position-override', 'subscript-position-override','superscript-size-override' and 'subscript-size-override' descriptors</h3>

	<pre class='descdef'>
	Name: superscript-position-override
	Value: [ normal | from-font | <<percentage>> ]{1,2}
	For: @font-face
	Initial: normal
	</pre>

	<pre class='descdef'>
	Name: subscript-position-override
	Value: [ normal | from-font | <<percentage>> ]{1,2}
	For: @font-face
	Initial: normal
	</pre>

	<pre class='descdef'>
	Name: superscript-size-override
	Value: [ normal | from-font | <<percentage [0,∞]>> ]{1,2}
	For: @font-face
	Initial: normal
	</pre>

	<pre class='descdef'>
	Name: subscript-size-override
	Value: [ normal | from-font | <<percentage [0,∞]>> ]{1,2}
	For: @font-face
	Initial: normal
	</pre>

	The 'superscript-position-override', 'subscript-position-override',
	'superscript-size-override', and 'subscript-size-override' descriptors
	specify the superscript offset, subscript offset, superscript size, and subscript size
	metrics of the font, respectively,
	which are used to synthesize glyphs when required by 'font-variant-position'.
	The first value provides the value for the x axis,
	and the second value provides the value for the y axis
	(defaulting to the first value if omitted).

	<dl dfn-for="superscript-position-override!!descriptor,subscript-position-override!!descriptor,superscript-size-override!!descriptor,subscript-size-override!!descriptor" dfn-type=value>
		<dt><dfn>normal</dfn>
		<dd>
			The UA determines what metrics value to use,
			whether derived from the font or from some heuristic.

		<dt><dfn>from-font</dfn>
		<dd>
			The corresponding metric in the font data is used, if any.
			(If the metric is missing, same as ''superscript-position-override/normal''.)

		<dt><dfn><<percentage>></dfn>
		<dd>
			The corresponding metric is replaced by
			the given percentage multiplied by the used font size.
	</dl>

	Note: Since these metrics are only applicable in the [=block axis=],
	the y-axis value will only be used
	when [=typesetting upright=] in [=vertical typographic modes=].

<h2 id="font-rend-props">
Font Feature Properties</h2>


<h3 id="font-language-override-prop">Font language override: the 'font-language-override' property</h3>

Issue(5484):


<h2 id="font-feature-variation-resolution">
Font Feature and Variation Resolution</h3>

Issue(5635):


<h2 id="font-variation-props">
Font Variation Properties</h2>


<h3 id="font-optical-sizing-def">
Optical sizing control: the 'font-optical-sizing' property</h3>

Issue(5466):


<!-- This might get moved here -->
<!--
    <h2 id="color-font-support">
Color Font Support</h2>
-->


<h2 id="security">Security Considerations</h2>

No new security considerations have been reported on this specification.

<h2 id="privacy">Privacy Considerations</h2>

No new privacy considerations have been reported on this specification.


<h2 id="acknowledgments">
Acknowledgments</h2>

	Firstly, the editors would like to thank all of the
	<a href="https://www.w3.org/TR/css-fonts-4/#acknowledgments">contributors to the previous level of this module</a>.

	Secondly, we would like to acknowledge
	DerKoun from PDFReactor,
	Xiaocheng Hu from Google,
	and
	Jonathan Kew from Mozilla,
	for their contributions to the improvements in this Level 5.

<h2 id="changes">
Changes
</h2>

<h3 id="changes-20210729">Changes since the <a href="https://www.w3.org/TR/2021/WD-css-fonts-5-20210729/">WD of 2021-07-29</a></h3>

<ul>
	<li>Renamed technology to tech</li>
	<li>Security and Privacy are now separate sections</li>
	<li>Fixed font-technology grammar</li>
	<li>Copied section on parsing src descriptor from CSS Fonts 4</li>
</ul>

<h3 id="changes-20210629">Changes since the <a href="https://www.w3.org/TR/2021/WD-css-fonts-5-20210629/">FPWD of 2021-06-29</a></h3>

<ul>
	<li>Removed scary warning notice</li>
	<li>Added incremental font technology to supports</li>
</ul>