Skip to content

[css-fonts-5] Define behavior for <meta text-scale> from #12380 #13052

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.

Sign up for GitHub

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 9 commits into
base: main
Choose a base branch
from
Open

[css-fonts-5] Define behavior for <meta text-scale> from #12380 #13052

Changes from 3 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
8d5f5e2
no bs edits
davidsgrogan Nov 2, 2025
18f2f8b
Small revisions
davidsgrogan Nov 4, 2025
b729d74
after review round 1
davidsgrogan Nov 5, 2025
0206973
Apply suggestions from code review
davidsgrogan Nov 9, 2025
c287984
Josh's suggestions from review round 1
davidsgrogan Nov 12, 2025
f6d1a0c
full example
davidsgrogan Nov 14, 2025
3716341
add 'environment variable' following ''preferred-text-scale''
davidsgrogan Nov 14, 2025
828b01e
put Value Definitions back in the right place
davidsgrogan Nov 22, 2025
65d7813
add link to scaling rate issue
davidsgrogan Nov 22, 2025
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
72 changes: 72 additions & 0 deletions css-fonts-5/Overview.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@ spec:css-color-4; type:property; text:color
spec:css-values; type:value; text:ex
spec:css22; type:value; for:/; text:block
spec:html; type:element; text:font
spec:html; type:element; text:meta
spec:css-fonts-4; type:property; text:font-size
spec:css-fonts-4; type:descriptor; text:font-language-override
spec:css-fonts-4; type:property; text:font-family
Expand Down Expand Up @@ -59,7 +60,78 @@ 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="text-scale-meta">
Text-Scale <code class=html>&lt;meta&gt;</code> element</h2>
Copy link
Contributor

@JoshTumath JoshTumath Nov 7, 2025

Choose a reason for hiding this comment

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

I noticed the HTML spec also mentions when a metadata name should not appear more than once in the document. Maybe you should add this line somewhere:

There must not be more than one meta element with its name attribute value set to an ASCII case-insensitive match for text-scale per document.

Copy link
Member Author

@davidsgrogan davidsgrogan Nov 12, 2025

Choose a reason for hiding this comment

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

Done


A document with a <{meta}> 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 computed value
of the ''font-size/medium'' font size
and consequently scaling the computed size of the other <<absolute-size>> keywords.

The value of the <code>content</code>
attribute must be an <a>ASCII case-insensitive</a> match for one of the
Copy link
Collaborator

@fantasai fantasai Nov 5, 2025

Choose a reason for hiding this comment

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

Must -> otherwise what?

Copy link
Member Author

@davidsgrogan davidsgrogan Nov 5, 2025

Choose a reason for hiding this comment

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

Added 'Otherwise the tag is ignored.'

Copy link
Contributor

@JoshTumath JoshTumath Nov 7, 2025

Choose a reason for hiding this comment

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

I'm wondering specifying the 'otherwise' case is neccessary here, because, to me, the HTML spec seems to imply it is ignored anyway.

recognized keywords. Otherwise the tag is ignored.

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=]
<{meta}> element are:

<dl>
<dt><dfn for="text-scale"><code>legacy</code></dfn></dt>
<dd>''env()/preferred-text-scale'' returns the user's OS-level font factor on mobile,
but 1 on desktop.
The document's initial font size only incorporates UA-level font preferences.
OS-level font preferences are ignored.</dd>
<dt><dfn>scale</dfn></dt>
<dd>''env()/preferred-text-scale'' returns the user's OS-level font preferences.
The document's initial font size incorporates both UA-level and OS-level font preferences.</dd>
</dl>

<h3 id="legacy-keyword">The 'legacy' keyword</h3>

When the value of the [=text-scale=] content attribute is
[=text-scale/legacy=]
the user agent must set the computed ''font-size/medium'' font size
to 16px multiplied by
the font scale factor
the user has chosen from any settings <i>provided by the user agent</i>.
The ''preferred-text-scale'' value must be 1 on desktop platforms.
Copy link
Contributor

@JoshTumath JoshTumath Nov 7, 2025

Choose a reason for hiding this comment

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

Wherever you reference the preferred-text-scale env(), maybe it should be prefixed with 'environment variable' in the prose. Since this is not the css-env spec, it's not clear that you're referencing an env().

Copy link
Member Author

@davidsgrogan davidsgrogan Nov 12, 2025

Choose a reason for hiding this comment

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

Bikeshed linkifies ''preferred-text-scale'' to https://drafts.csswg.org/css-env-1/#valdef-env-preferred-text-scale. Do you think that's sufficient? (I couldn't tell if you already knew the linkification part)

Copy link
Contributor

@JoshTumath JoshTumath Nov 14, 2025

Choose a reason for hiding this comment

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

Yeah, I'm using the Bikeshed preview tool and I'm aware of the linkification, but still think it would be useful to say something like:

The ''preferred-text-scale'' environment variable value must be 1 on desktop platforms.

That matches how it's worded in the css-env-1 spec as well.

Copy link
Member Author

@davidsgrogan davidsgrogan Nov 14, 2025

Choose a reason for hiding this comment

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

Ah, ok, will do.

Copy link
Member Author

@davidsgrogan davidsgrogan Nov 14, 2025

Choose a reason for hiding this comment

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

And aside, how do you use that preview tool for this PR? Do you put something into the "Load from URL" box?
Screenshot 2025-11-14 at 1 49 53 PM

Copy link
Member Author

@davidsgrogan davidsgrogan Nov 14, 2025

Choose a reason for hiding this comment

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

Done

Copy link
Contributor

@JoshTumath JoshTumath Nov 15, 2025

Choose a reason for hiding this comment

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

Thanks. And yeah I just pasted the URL of the 'raw' version of the BS file on GitHub.

On mobile:
<ul>
<li>if the operating system provides a text scale setting AND the UA hasn't already applied that factor to the initial font size, ''env()/preferred-text-scale'' returns the mulitplier that the user has chosen in the operating system's text scale setting.

Note: As of this writing, all combinations of Android, iOS, Gecko, WebKit, Blink satisfy this first condition.

</li>
<li>Otherwise ''env()/preferred-text-scale'' returns 1.</li>
</ul>

<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>
computed ''font-size/medium'' font size must match the user's preferred paragraph text size as determined from a combination of OS and UA preferences.

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.

Further, when the value of the [=text-scale=] content attribute is
<a for=text-scale>scale</a>, the user agent should skip all font-sizing interventions it would otherwise perform in an attempt to automatically honor the user's preferences. E.g. text autosizing on mobile (See [[css-size-adjust#intro]]) and full-application zoom (<a href="https://github.com/w3c/csswg-drafts/blob/main/css-env-1/explainers/env-preferred-text-scale.md#windows-11">popular browsers do this on Windows)</a>.

Note: It is expected that authors will use
''&lt;meta name="text-scale" content="scale"&gt;'' in stylesheets so that the initial font size will reflect a combination of the user's font preferences, whether those are specified at the OS level or the UA level. The author will then be able to use ''rem'' throughout the page to honor the user's font preferences.
Copy link
Contributor

@JoshTumath JoshTumath Nov 7, 2025

Choose a reason for hiding this comment

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

Maybe the sentence about using rem is actually better explained in an example block.

So you could keep the Note block to explain how authors are expected to use scale in their documents, with the example block below it to explain how, if you set scale and don't alter the default font size, content sized with rem units will be relative to the preferred text scale.

Also, I'm not sure if the Note should actually be an orange Assertion box. But maybe not because assertions are normative? Where I've seen Assertion boxes in the past are places like the css-flexbox spec, where it tells authors to use the flex shorthand rather than the longhands.

Copy link
Member Author

@davidsgrogan davidsgrogan Nov 12, 2025

Choose a reason for hiding this comment

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

Yeah, Advisement (you meant "advisement", not "assertion". I think :) boxes are supposed to be normative. This Note seems merely descriptive as is now, but I suppose we can strengthen the language to say that authors must use it to obey the user's font preferences. Oh, though, we kind of don't care if authors use the more difficult env(..) instead to honor the user's preferences. So maybe we leave it non-normative?

Copy link
Member Author

@davidsgrogan davidsgrogan Nov 12, 2025

Choose a reason for hiding this comment

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

So you could keep the Note block to explain how authors are expected to use scale in their documents, with the example block below it to explain how, if you set scale and don't alter the default font size, content sized with rem units will be relative to the preferred text scale.

I'd like to think we included a good example in the explainer we can crib from.
... and we didn't.

Yeah, an example would be good here.

Copy link
Member Author

@davidsgrogan davidsgrogan Nov 14, 2025

Choose a reason for hiding this comment

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

Example added.

Copy link
Contributor

@JoshTumath JoshTumath Nov 14, 2025

Choose a reason for hiding this comment

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

Yeah, Advisement (you meant "advisement", not "assertion". I think :) boxes are supposed to be normative. This Note seems merely descriptive as is now, but I suppose we can strengthen the language to say that authors must use it to obey the user's font preferences. Oh, though, we kind of don't care if authors use the more difficult env(..) instead to honor the user's preferences. So maybe we leave it non-normative?

Sorry yeah, an advisement box. And yes that makes sense to me.

The example is great! 👍🏼


<h3 id="values">
Value Definitions</h3>
Expand Down