Add font-width property and descriptor #42935

pepelsbey · 2026-01-27T12:36:43Z

Description

Adds new font-width property and descriptor pages, mostly duplicating existing font-stretch ones
Enhances the font-width and font-stretch descriptor examples with live samples
Adds cross-links between properties and descriptors, modern and legacy, in the “See also” section
Cleans up demos: “Required by Chrome” is no longer required, it seems
Updates the CSS fonts module landing

Motivation

Support added in Safari for

font-width property (Safari 18.4, March 2025)
font-width descriptor (Safari 26, September 2025).

Related issues and pull requests

Fixes #42409 and one item from the openwebdocs/project#234 list

github-actions · 2026-01-27T12:38:10Z

Preview URLs (6 pages)

Flaws (18)

Note! 2 documents with no flaws that don't need to be listed. 🎉

Found an unexpected or unresolvable flaw? Please report it here.

URL: /en-US/docs/Web/CSS/Reference/At-rules/@font-face/font-stretch
Title: font-stretch
Flaw count: 6

broken_links:
- Link /en-US/docs/Web/CSS/At-rule is a redirect
- Link /en-US/docs/Web/CSS/@font-face is a redirect
- Link /en-US/docs/Web/CSS/font-width doesn't resolve
- Link /en-US/docs/Web/CSS/percentage is a redirect
macros:
- Macro cssinfo produces link /en-US/docs/Web/CSS/CSS_cascade/Value_processing which is a redirect
- Macro cssinfo produces link /en-US/docs/Web/CSS/CSS_cascade/Value_processing which is a redirect

URL: /en-US/docs/Web/CSS/Reference/At-rules/@font-face/font-width
Title: font-width
Flaw count: 2

broken_links:
- Link /en-US/docs/Web/CSS/font-width doesn't resolve
- Link /en-US/docs/Web/CSS/percentage is a redirect

URL: /en-US/docs/Web/CSS/Reference/Properties/font-stretch
Title: font-stretch
Flaw count: 5

broken_links:
- Link /en-US/docs/Web/CSS/percentage is a redirect
macros:
- Macro cssinfo produces link /en-US/docs/Web/CSS/CSS_cascade/Value_processing which is a redirect
- Macro cssinfo produces link /en-US/docs/Web/CSS/CSS_cascade/Inheritance which is a redirect
- Macro cssinfo produces link /en-US/docs/Web/CSS/CSS_cascade/Value_processing which is a redirect
- Macro cssinfo produces link /en-US/docs/Web/CSS/CSS_animated_properties which is a redirect

URL: /en-US/docs/Web/CSS/Reference/Properties/font-width
Title: font-width
Flaw count: 5

broken_links:
- Link /en-US/docs/Web/CSS/percentage is a redirect
macros:
- Macro cssinfo produces link /en-US/docs/Web/CSS/CSS_cascade/Value_processing which is a redirect
- Macro cssinfo produces link /en-US/docs/Web/CSS/CSS_cascade/Inheritance which is a redirect
- Macro cssinfo produces link /en-US/docs/Web/CSS/CSS_cascade/Value_processing which is a redirect
- Macro cssinfo produces link /en-US/docs/Web/CSS/CSS_animated_properties which is a redirect

External URLs (8)

URL: /en-US/docs/Web/CSS/Reference/At-rules/@font-face/font-stretch
Title: font-stretch

https://drafts.csswg.org/css-fonts/ (1 time) (Note! This may be a new URL 👀)
https://www.theleagueofmoveabletype.com/league-mono (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/CSS/Reference/At-rules/@font-face/font-width
Title: font-width

https://www.theleagueofmoveabletype.com/league-mono (1 time) (Note! This may be a new URL 👀)
https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-visual-presentation.html (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/CSS/Reference/Properties/font-stretch
Title: font-stretch

https://drafts.csswg.org/css-fonts/ (1 time) (Note! This may be a new URL 👀)
https://fonts.google.com/specimen/Anek+Malayalam (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/CSS/Reference/Properties/font-width
Title: font-width

https://fonts.google.com/specimen/Anek+Malayalam (1 time) (Note! This may be a new URL 👀)
https://fonts.google.com/specimen/Inconsolata (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2026-01-28 11:50:53)

files/en-us/web/css/guides/fonts/variable_fonts/index.md

chrisdavidmills

Nice work, @pepelsbey. I've got a bunch of comments for you to check over.

chrisdavidmills · 2026-01-27T13:25:42Z

files/en-us/web/css/guides/fonts/index.md

 - {{cssxref("font-size")}}
 - {{cssxref("font-size-adjust")}}
- {{cssxref("font-stretch")}}
+- {{cssxref("font-width")}} and its legacy alias {{cssxref("font-stretch")}}


Question: In such cases, don't we usually tend to remove the legacy alias pages, redirect them towards the new name pages, and then cover the legacy name in the BCD for the new name (with "alternative name") and in the page description if we need to say something more?

Yes, but it’s a special case: adoption and browser support for the legacy property are so big, compared to the modern one, that it’s much more practical to use the legacy one. So most of the developers (and search engines) will start looking for the font-stretch.

Only when the font-width becomes widely supported and used, should we start considering redirecting the font-stretch.

files/en-us/web/css/reference/at-rules/@font-face/font-stretch/index.md

files/en-us/web/css/reference/at-rules/@font-face/font-width/index.md

files/en-us/web/css/reference/properties/font-width/index.md

files/en-us/web/css/reference/at-rules/@font-face/font-width/index.md

files/en-us/web/css/reference/properties/font-width/index.md

Co-authored-by: Chris Mills <[email protected]>

Josh-Cena · 2026-01-27T16:05:39Z

I agree with @chrisdavidmills: we should delete and redirect the page. As long as the legacy alias is mentioned, it will show up in search engines and site search. Maintaining two pages that document the exact same feature is inviting for more confusion and bugs. This approach has been taken many times in the past and this should be no exception.

pepelsbey · 2026-01-27T21:20:14Z

The problem with keeping only the font-width is that it's not good advice to use it. More than that, it's terrible advice. No matter how much we say "oh, by the way, there's font-stretch", it won't be enough. We need to stay practical and useful for developers, not just stick to the spec. Even if it brings a little maintenance cost.

We're not changing the rules here. The whole situation is a big exception made by CSSWG, which renamed a CSS feature with a long history and wide adoption. Not a good idea, if you ask me. Oh well.

And this is an exception for us as well, and it's only two pages to keep in sync. One of them has an expiration date on it. The moment font-width gains wider browser support (at least Baseline newly, I think), we can start deprecating font-stretch.

Josh-Cena · 2026-01-27T21:24:36Z

OK, but we document new things with no legacy fallback just fine? Legacy fallback is an engineering decision that's not up for us to decide or even recommend. This is even transparent to most developers because postcss would handle it.

chrisdavidmills · 2026-01-28T11:02:24Z

And this is an exception for us as well, and it's only two pages to keep in sync. One of them has an expiration date on it. The moment font-width gains wider browser support (at least Baseline newly, I think), we can start deprecating font-stretch.

Hrm, I agree that this is a bit of an exception. Usually, when we delete and redirect to the new name page, it is due to a change made to a fairly new feature that hasn't had such a history of widespread adoption.

This being the case, I am OK with it, although I think we should explain the situation a bit more clearly, and provide examples, so maybe:

on the font-stretch page, say clearly that font-width is the new name for font-stretch, but that font-stretch will be needed for a while until adoption increases of font-width
on the font-width page, explain the same thing but kind of the opposite way round
on both pages, consider providing an example that shows using font-width, but also providing font-stretch as a fallback (maybe this is only needed on the font-width page?)
Consider mentioning a solution such as PostCSS as well.

OK, but we document new things with no legacy fallback just fine? Legacy fallback is an engineering decision that's not up for us to decide or even recommend. This is even transparent to most developers because postcss would handle it.

I wouldn't say this is 100% true. Where possible, we've been trying to provide basic fallbacks, or at the very least, feature detection along with "not supported" banners, to at least draw attention to the issue. It is not realistic to provide perfect fallbacks and equivalent functionality in all cases. I agree that this is not our decision.

pepelsbey · 2026-01-28T11:55:22Z

Consider mentioning a solution such as PostCSS as well.

I don’t think there’s one yet. Both the most popular PostCSS-based tools currently do nothing for the font-width property:

pepelsbey · 2026-01-28T11:59:46Z

@chrisdavidmills, I synchronized your suggestions for font-width pages back to font-stretch ones and added a fallback screenshot for the font-width property demo. I would appreciate any suggestions on this:

on the font-stretch page, say clearly that font-width is the new name for font-stretch, but that font-stretch will be needed for a while until adoption increases of font-width

chrisdavidmills

@pepelsbey a few more comments; nearly there!

chrisdavidmills · 2026-01-28T13:33:22Z

files/en-us/web/css/reference/at-rules/@font-face/font-width/index.md

+font-width: 100%;
+font-width: 200%;
+
+/* multiple values */


Suggested change

/* multiple values */

/* Multiple values */

For consistency with the previous comment. This needs changing on the font-stretch descriptor page too.

chrisdavidmills · 2026-01-28T13:37:52Z

files/en-us/web/css/reference/at-rules/@font-face/font-width/index.md

+sidebar: cssref
+---
+
+The **`font-width`** [CSS](/en-US/docs/Web/CSS) descriptor allows authors to specify a normal, condensed, or expanded face for the fonts specified in the {{cssxref("@font-face")}} at-rule.


I think this page needs a similar note to the one you've got at the start of the font-width page to explain the relationship between the two, but probably tweaked so that it makes sense for this page.

chrisdavidmills · 2026-01-28T13:40:37Z

files/en-us/web/css/reference/at-rules/@font-face/font-width/index.md

+
+## Examples
+
+### Setting a percentage range for font-width


Could this example be expanded so that it also incorporates font-stretch in a sensible way to provide backwards compat? If not, maybe include a note about the potential compat issues, and what to do about it.

chrisdavidmills · 2026-01-28T13:43:12Z

files/en-us/web/css/reference/properties/font-stretch/index.md

-> The `font-stretch` property was renamed to `font-width` in the [CSS Fonts specification](https://drafts.csswg.org/css-fonts/#font-stretch-prop). To preserve compatibility, the specification retains `font-stretch` as an alias for the `font-width` property.
+> The `font-stretch` property was renamed to {{cssxref("font-width")}} in the [CSS Fonts specification](https://drafts.csswg.org/css-fonts/#font-stretch-prop). To preserve compatibility, the specification retains `font-stretch` as a legacy alias for the `font-width` property.

 The **`font-stretch`** [CSS](/en-US/docs/Web/CSS) property selects a normal, condensed, or expanded face from a font.


In the Syntax section, replace the comment

/* <font-stretch-css3> keyword values */

with

/* Keyword values */

Again, <font-stretch-css3> is a spec detail that I don't think is very useful to mention on this page.

chrisdavidmills · 2026-01-28T13:45:25Z

files/en-us/web/css/reference/properties/font-stretch/index.md

@@ -96,11 +95,11 @@ This property may be specified as a single `<font-stretch-css3>` keyword value o
 ### Values


For the line above this one, replace

This property may be specified as a single <font-stretch-css3> keyword value or a single

with

This property may be specified as a single keyword or

chrisdavidmills · 2026-01-28T13:48:02Z

files/en-us/web/css/reference/properties/font-width/index.md

+sidebar: cssref
+---
+
+The **`font-width`** [CSS](/en-US/docs/Web/CSS) property selects a normal, condensed, or expanded face from a font.


Again, I think this needs a similar note to the font-stretch property page, to explain the relationship between the two

chrisdavidmills · 2026-01-28T13:52:17Z

files/en-us/web/css/reference/properties/font-width/index.md

+
+{{EmbedLiveSample('Font face selection', "100%", "250px")}}
+
+A browser rendering of the above example in case your browser doesn't support `font-width` property:


Suggested change

A browser rendering of the above example in case your browser doesn't support `font-width` property:

The following screenshot shows how the above table is rendered, in case your browser doesn't support the `font-width` property:

chrisdavidmills · 2026-01-28T13:54:17Z

files/en-us/web/css/reference/properties/font-width/index.md

+
+## Examples
+
+### Setting font width percentages


Again, would it make sense to include font-stretch fallbacks here, along with a bit of explanation as to why they are currently needed? The reader could then choose to include them in their CSS, or dynamically as part of their build process, or whatever.

chrisdavidmills · 2026-01-28T13:56:13Z

@chrisdavidmills, I synchronized your suggestions for font-width pages back to font-stretch ones and added a fallback screenshot for the font-width property demo. I would appreciate any suggestions on this:

on the font-stretch page, say clearly that font-width is the new name for font-stretch, but that font-stretch will be needed for a while until adoption increases of font-width

I think your notes at the start of the articles do a good enough job.

Add font-width property and descriptor

177695b

pepelsbey requested a review from a team as a code owner January 27, 2026 12:36

pepelsbey requested review from chrisdavidmills and removed request for a team January 27, 2026 12:36

github-actions bot added Content:CSS Cascading Style Sheets docs size/l [PR only] 501-1000 LoC changed labels Jan 27, 2026

pepelsbey commented Jan 27, 2026

View reviewed changes

files/en-us/web/css/guides/fonts/variable_fonts/index.md Show resolved Hide resolved

pepelsbey mentioned this pull request Jan 27, 2026

Font-width CSS property and @font-face descriptor docs are missing #42409

Open

chrisdavidmills requested changes Jan 27, 2026

View reviewed changes

pepelsbey commented Jan 27, 2026

View reviewed changes

files/en-us/web/css/reference/at-rules/@font-face/font-width/index.md Outdated Show resolved Hide resolved

pepelsbey commented Jan 27, 2026

View reviewed changes

files/en-us/web/css/reference/properties/font-width/index.md Outdated Show resolved Hide resolved

Apply suggestions from code review

2c59164

Co-authored-by: Chris Mills <[email protected]>

pepelsbey added 2 commits January 28, 2026 12:12

Sync changes across the docs

304f338

Update demo, add fallback screenshot

930c00e

chrisdavidmills requested changes Jan 28, 2026

View reviewed changes

		@@ -96,11 +95,11 @@ This property may be specified as a single `<font-stretch-css3>` keyword value o
		### Values


		{{EmbedLiveSample('Font face selection', "100%", "250px")}}

		A browser rendering of the above example in case your browser doesn't support `font-width` property:

	A browser rendering of the above example in case your browser doesn't support `font-width` property:
	The following screenshot shows how the above table is rendered, in case your browser doesn't support the `font-width` property:

Add font-width property and descriptor #42935

Are you sure you want to change the base?

Add font-width property and descriptor #42935

Conversation

pepelsbey commented Jan 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Motivation

Related issues and pull requests

Uh oh!

github-actions bot commented Jan 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

chrisdavidmills left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Josh-Cena commented Jan 27, 2026

Uh oh!

pepelsbey commented Jan 27, 2026

Uh oh!

Josh-Cena commented Jan 27, 2026

Uh oh!

chrisdavidmills commented Jan 28, 2026

Uh oh!

pepelsbey commented Jan 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pepelsbey commented Jan 28, 2026

Uh oh!

chrisdavidmills left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chrisdavidmills commented Jan 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

pepelsbey commented Jan 27, 2026 •

edited

Loading

github-actions bot commented Jan 27, 2026 •

edited

Loading

pepelsbey commented Jan 28, 2026 •

edited

Loading