From 115f01273b01beaf9fc9aaec1515ef4197c00df4 Mon Sep 17 00:00:00 2001
From: Keith Cirkel <keithamus@users.noreply.github.com>
Date: Wed, 9 Jul 2025 18:55:23 +0100
Subject: [PATCH] [css-fonts-5]: define text-scale, legacy/scale keywords,
 env(preferred-text-scale)

---
 css-fonts-5/Overview.bs | 78 ++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 77 insertions(+), 1 deletion(-)

diff --git a/css-fonts-5/Overview.bs b/css-fonts-5/Overview.bs
index 422d5b0e465..7ec5c5f3a47 100644
--- a/css-fonts-5/Overview.bs
+++ b/css-fonts-5/Overview.bs
@@ -59,7 +59,83 @@ 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.
 
+<h2 id="environment-variables">
+Environment Variables</h2>
+
+Text Scale {#text-scale-envs}
+------------------------------------------------------------------
+
+<table dfn-type=value dfn-for="env()">
+	<tr>
+		<th>Name
+		<th>Value
+		<th>Number of dimensions
+	<tr>
+		<td><dfn>preferred-text-scale</dfn>
+		<td><<number>>
+		<td>0 (scalar)
+</table>
+
+The text-scale [=environment variables=] define the devices text scale, which
+must be a non-zero number for which all text can be scaled by.
+
+The preferred-text-scale unit must be a value that computes to the documents
+initial font-size, when multiplied by 16px:
+
+<pre highlight=css>
+	:root {
+		font-size: calc(16px * env(preferred-text-scale));
+	}
+</pre>
+
+<h2 id="text-scale-meta">
+Text-Scale <code class=html>&lt;meta&gt;</code> element</h2>
+
+A document with a <code>&lt;meta></code> tag whose <code>name</code> attribute
+is a <a>ASCII case-insensitive</a> match for
+<dfn lt=text-scale><code>"text-scale"</code></dfn> is recognized as setting the
+initial font size of the document. The value of the <code>content</code>
+attribute must be an <a>ASCII case-insensitive</a> match for one of the
+recognized keywords.
+
+Documents without this <code>&lt;meta></code> tag will have an assumed default
+value of <code>legacy</code>.
+
+<h3 id="text-scale-meta-keywords">
+Keywords</h3>
+
+The recognized keywords in the [=text-scale=]
+<code class=html>&lt;meta&gt;</code> element are:
+
+<ul>
+	<li><code class="index" lt="legacy!!text-scale-meta">legacy</code></li>
+	<li><code class="index" lt="scale!!text-scale-meta">scale</code></li>
+</ul>
+
+<h3 id="legacy-keyword">The 'legacy' keyword</h3>
+
+The <dfn for="text-scale" export><code>legacy</code></dfn> property is
+recognized in the [=text-scale=] content attribute value.
+
+When the value of the [=text-scale=] content attribute is
+<a for="text-scale">legacy</a> the user agent should set the initial font size
+to 16px. The user agent may chose a different initial value, such as one based
+on a user preference. The ''env()/preferred-text-scale'' value must be 1.
+
+<h3 id="scale-keyword">The 'scale' keyword</h3>
+
+The <dfn for="text-scale" export><code>scale</code></dfn> property is
+recognized in the [=text-scale=] content attribute value.
+
+When the value of the [=text-scale=] content attribute is
+<a for=text-scale>scale</a> the user agent may determine the initial font size
+based on the operating systems text scale setting. The
+''env()/preferred-text-scale'' value must be a number that, when multiplied by
+16px, provides a <<length>> that matches that of the initial font size.
 
+Note: It is expected that authors will use
+''calc(16px * env(preferred-text-scale))'' in stylesheets to match the font
+size of the user agent, based on the initial font size.
 
 <h3 id="values">
 Value Definitions</h3>
@@ -706,7 +782,7 @@ Issue(5484):
 
 
 <h2 id="font-feature-variation-resolution">
-Font Feature and Variation Resolution</h3>
+Font Feature and Variation Resolution</h2>
 
 Issue(5635):