Merge pull request w3c#5521 from xiaochengh/font-metrics-override

Add @font-face descriptors for overriding font metrics

Author: svgeesus

css-fonts-4/Overview.bs

@@ -2908,6 +2908,94 @@ Initial: normal
 
 This descriptor defines initial settings that apply when the font defined by an @font-face rule is rendered. It does not affect font selection. Values are identical to those defined for the 'font-language-override!!property' property defined below except that the value inherit is omitted. When multiple font feature descriptors, properties, or variations are used, the cumulative effect on text rendering is detailed in the section [[#font-feature-variation-resolution]] below.
 
+<h3 id="font-metrics-override-desc">
+Default font metrics overriding:
+the 'ascent-override', 'descent-override' and 'line-gap-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>
+
+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.
+
+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.
+
+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.
+
+<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%;
+}
+
+&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 vertically shifted when the user agent finishes loading and
+	switches to use the web font.
+
+</div>
+
 <h2 id="font-matching-algorithm">Font Matching Algorithm</h2>
 
 The algorithm below describes how fonts are associated with individual runs of text.