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>

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>

Issue(5518):


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

Issue(806):

Issue(731):

Issue(5892):

<pre class='descdef'>
    Name: font-size
    Value: auto | [<<number>>]#
    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>




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

<h3 id="font-metrics-override-desc">
Default font metrics overriding:
the 'ascent-override', 'descent-override', 'line-gap-override', and 'advance-override' descriptors</h3>

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

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

<pre class='descdef'>
Name: line-gap-override
Value: normal | <<percentage>>
For: @font-face
Initial: normal
</pre>

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

The 'ascent-override', 'descent-override', and 'line-gap-override' descriptors define 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 'advance-override'
descriptor adjusts the <dfn export>tracking</dfn> between adjacent
<a spec="CSS-TEXT-3">typographic character units</a>.

When the descriptor value is 'normal', the corresponding metric value is obtained from the
font file directly.

Note: User agents may draw data from different places from the font file as the metric values,
which results in different text layouts.

For the 'ascent-override', 'descent-override' and 'line-gap-override' descriptors, when the
descriptor value is a percentage, the corresponding metric value is resolved as the
given percentage multiplied by the used font size. Negative values are invalid at parse time.

For the 'advance-override' descriptor, when the descriptor value is a percentage, the
advance from one <a>typographic character unit</a> to the next is multiplied by the percentage.

Note: Using the 'ascent-override', 'descent-override', and 'line-grap-override' descriptors can
achieve a similar effect as specifying a percentage for 'line-height' property. Also, using the
'advance-override' has a similar effect as using the 'letter-spacing' property. However,
contrary to 'letter-spacing', 'advance-override' scales the spacing, rather than adding a
constant to the spacing.

Note: 'ascent-override', 'descent-override', 'line-gap-override', and 'advance-override'
are applied per-font rather than per-element. Multiple fonts may be used
within an individual element e.g. for characters not supported by the primary font.

<div class="example">
    Consider the following content:

<xmp>
@font-face {
  font-family: "MyHelvetica";
  src: local("Helvetica");
}
...
<div style="font: 96px 'MyHelvetica';">Ha</div>
</xmp>
    This image shows each glyph's local origin, and the natural advance between them:
    <figure>
        <img alt="Natural advance of Helvetica glyphs" src="images/Helvetica Natural Advance.png" width="147" height="114">
    </figure>
    In this example, the natural advance is 69.328125 pixels.

    However, if we modify the content as such:
<pre>
@font-face {
  font-family: "MyHelvetica";
  src: local("Helvetica");
  advance-override: 140%;
}
</pre>
   The rendering will look like this:
    <figure>
        <img alt="Overridden advance of Helvetica glyphs" src="images/Helvetica Overridden Advance.png" width="176" height="112">
    </figure>
    In this example, the used advance between the glyphs is 69.328125 pixels * 1.4 = 97.059375 pixels.
</div>

<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%;
  advance-override: 109%;
}

&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">
    Default font metrics overriding:
    the 'superscript-position-override', 'subscript-position-override','superscript-size-override' and 'subscript-size-override' descriptors</h3>

Issue(5518):

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

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

    <pre class='descdef'>
        Name: superscript-size-override
        Value: normal | <<percentage>>
        For: @font-face
        Initial: normal
    </pre>

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



<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>
-->