[css-env-1] Add a text-scale env() (name to be bikeshedded). #10674

css-env-1/Overview.bs

@@ -215,7 +215,7 @@ calculating the area between the position of the viewport segments.
 
 <div class="example">
 	When the viewport is split into two side-by-side segments, the viewport segment on
-	the left would have indices (0, 0). It's width would be represented as
+	the left would have indices (0, 0). Its width would be represented as
 	''env(viewport-segment-width 0 0, 300px)''. 
 	The viewport segment on the right would have indices (1, 0).
 	Similarly, for a viewport split into two vertical segments, the viewport segment
@@ -227,6 +227,57 @@ Viewport units should be used instead when there is no hardware feature
 splitting the viewport, otherwise content will not display as intended when
 viewed on a device with multiple segments.
 
+Preferred Text Zoom {#text-zoom}
+--------------------------------
+
+<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 ''preferred-text-scale'' [=environment variable=]
+represents the user's preferred text scale factor;
+aka, the adjustment they make to the "default" font size
+of the OS and/or user agent.
+(On devices where 'text-size-adjust' has an effect,
+this is the scale factor applied by ''text-size-adjust: auto''.)
+
+For example, if ''text-size-adjust:auto''
+would cause text sizes to double,
+then ''env(preferred-text-scale)'' would resolve to ''2''.
+
+Note: The ''pem'' unit represents this same information;
+''1em'' is exactly equivalent to ''calc(1em * env(preferred-text-scale))''.
+When directly sizing things, ''bsem'' is just a more convenient length to use.
+
+<div class=example>
+	This [=environment variable=] requires care to be used correctly.
+	By default, text scaling is applied automatically;
+	using ''env(preferred-text-scale)'' or ''pem''
+	would result in the scale being <em>double</em>-applied,
+	making text or UI elements too large.
+
+	Typically, authors should either:
+
+	* set ''text-size-adjust: calc(100% * env(preferred-text-scale));'',
+		to ensure that all the text in the page is automatically scaled
+		to the user's preference,
+		and when necessary scale non-text sizes by the scale factor as well.
+	* or set ''text-size-adjust:none'',
+		and then consistently use this [=environment variable=]
+		and/or the ''pem'' unit
+		to scale relevant text and UI to the user's preference.
+</div>
+
+
+
+
 Using Environment Variables: the ''env()'' notation {#env-function}
 ===================================================================
 
@@ -337,4 +388,4 @@ This specification provides read-only access
 to some new types of information about the device.
 
 The [=environment variables=] defined by this specification
-do not expose any security-sensitive information.
+do not expose any security-sensitive information.