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

Author: tabatkins

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,55 @@ 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>bikeshed-text-scale</dfn>
+		<td><<number>>
+		<td>0 (scalar)
+</table>
+
+The ''bikeshed-text-scale'' [=environment variable=]
+represents the scale factor
+of the user agent's operating system font scale.
+(Aka, the scale factor applied by ''text-size-adjust: auto''.)
+
+For example, if ''text-size-adjust:auto''
+would cause text sizes to double,
+then ''env(bikeshed-text-scale)'' would resolve to ''2''.
+
+Note: The ''bsem'' unit represents this same information;
+''1em'' is exactly equivalent to ''calc(1em * env(bikeshed-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(bikeshed-text-scale)'' or ''bsem''
+	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(bikeshed-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 ''bsem'' unit
+		to scale relevant text and UI to the user's preference.
+</div>
+
+
+
+
 Using Environment Variables: the ''env()'' notation {#env-function}
 ===================================================================