Overview.bs

<pre class='metadata'>
Title: CSS Fonts Module Level 5
Shortname: css-fonts
Level: 5
Status: ED
Work Status: exploring
Group: CSSWG
ED: https://drafts.csswg.org/css-fonts-5/
TR: https://www.w3.org/TR/css-fonts-5/
!Delta Spec: yes
Editor: Myles C. Maxfield, Apple Inc., mmaxfield@apple.com, w3cid 77180
Editor: Chris Lilley, W3C, http://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
Warning: Not Ready
</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:descriptor; text:font-language-override
</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>

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.

Issue(5539):


<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="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,Infinity]>>
	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'.

	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-underline-thickness/from-font'' value of 'text-underline-thickness')
	are also affected when sourced from this font.
	However, the [=computed value|computed=] 'font-size'
	(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'.

<!-- 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,Infinity]>>
	For: @font-face
	Initial: normal
	</pre>

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

	<pre class='descdef'>
	Name: line-gap-override
	Value: normal | <<percentage [0,Infinity]>>
	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.

	<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', '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.

<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: auto | from-font | <<percentage>>
	For: @font-face
	Initial: normal
	</pre>

	<pre class='descdef'>
	Name: subscript-position-override
	Value: auto | from-font | <<percentage>>
	For: @font-face
	Initial: normal
	</pre>

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

	<pre class='descdef'>
	Name: subscript-size-override
	Value: auto | from-font | <<percentage [0,Infinity]>>
	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'.

	<dl dfn-for="superscript-position-override!!descriptor,subscript-position-override!!descriptor,superscript-size-override!!descriptor,subscript-size-override!!descriptor" dfn-type=value>
		<dt><dfn>auto</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/auto''.)

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

<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="priv-sec">
Security and Privacy Considerations
</h2>

No new security or privacy considerations have been raised on this specification.


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

The CSS Working group would like to thank:


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