Skip to content

[css-fonts-5]: define text-scale, legacy/scale keywords, env(preferred-text-scale) #12469

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
78 changes: 77 additions & 1 deletion css-fonts-5/Overview.bs
Original file line number Diff line number Diff line change
Expand Up @@ -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()">
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Did you already crib everything appropriate from https://drafts.csswg.org/css-env-1/#text-zoom ?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Didn’t even spot this, I’ll make sure everything is moved over and update this tomorrow.

<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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The value is always 1 on desktop, but not necessarily on mobile.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, as in the Explainer, the env(preferred-text-scale) is the OS text scale on mobile. So if the user doubles their text scale, the value is 2, for example.
https://github.com/w3c/csswg-drafts/blob/main/css-env-1/explainers/env-preferred-text-scale.md#proposal

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does this mean in the legacy mode that env(preferred-text-scale) may not be congruent with the font-size? As in font-size: medium will resolve to 16px even though the rest of the user's OS is at 24px because they have a text-scale 1.5? So an author cannot rely on calc(16px * env(preferred-text-scale)) resolving to the same CSS pixels as 1rem?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's correct, and is what happens in today's pre-<meta name="text-scale"> world.

We expect/hope that <meta name="text-scale" content="scale"> becomes best practice so that authors don't have to deal with today's inconsistencies, one of which is what you pointed out.

Comment on lines +120 to +123
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does 'initial font size' need to be formally defined somewhere? My understanding is that the initial font size is the font-size: medium keyword. Maybe the definition of medium needs updating to formally define it as the UA setting by default in legacy mode and the UA setting * the OS text scale in scale mode.


<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
Copy link
Member

@davidsgrogan davidsgrogan Jul 9, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@JoshTumath I'm interested to hear your thoughts on this paragraph :) As a non-author, I don't have a good sense of what authors are expected to do.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If the meta tag is set to scale, authors would have no need to use calc(16px * env()). They can just use font-size: medium, since medium/the initial font size is now effectively that.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

font-size: medium will work for font sizes but presumably this also impacts ems & rems, such that 1rem will scale in proportion?

I think here I am simply trying to illustrate that authors might expect 16px to be the browsers font size and 16px * env() should (ideally?) resolve to the equivalent px units that 1rem * env() would.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh I think I see what you mean. Yeah if the meta tag is set to the scale keyword, provided that the author doesn't change the root font-size, 1rem will always be equivalent to 16px * env(). I think I was confused by the phrasing of 'authors are expected to use it' since I wouldn't expect anyone to practically need to do that.

''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>
Expand Down Expand Up @@ -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):

Expand Down