Skip to content

CSS font semi-shorthand property#44387

Open
estelle wants to merge 13 commits into
mainfrom
estelle-patch-11
Open

CSS font semi-shorthand property#44387
estelle wants to merge 13 commits into
mainfrom
estelle-patch-11

Conversation

@estelle

@estelle estelle commented Jun 8, 2026

Copy link
Copy Markdown
Member

Updated the 'font' property documentation to clarify usage, values, and examples.

elaborated on system fonts as a value

updated the examples to make them look a little more like exmples (didn't completely do this part). The system font one is a bit hokey, but it shows the effect.

updated the live sample to a jane eyre charlotte bronte quote.

Updated the 'font' property documentation to clarify usage, values, and examples.

elaborated on system fonts as a value
@estelle estelle requested a review from a team as a code owner June 8, 2026 12:12
@estelle estelle requested review from chrisdavidmills and removed request for a team June 8, 2026 12:12
@github-actions github-actions Bot added the Content:CSS Cascading Style Sheets docs label Jun 8, 2026
@estelle estelle marked this pull request as draft June 8, 2026 12:12
@github-actions github-actions Bot added the size/m [PR only] 51-500 LoC changed label Jun 8, 2026
@estelle estelle changed the title CSS font semi-shorthand property DRAFT: CSS font semi-shorthand property Jun 8, 2026
@github-actions

github-actions Bot commented Jun 8, 2026

Copy link
Copy Markdown
Contributor

Preview URLs (1 page)

External URLs (1)

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

(comment last updated: 2026-06-09 12:50:18)

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
@chrisdavidmills chrisdavidmills removed their request for review June 8, 2026 12:18
@chrisdavidmills

Copy link
Copy Markdown
Contributor

@estelle, removing myself as reviewer for now. Give me another ping when it is undrafted and ready.

@estelle estelle marked this pull request as ready for review June 8, 2026 17:04
@estelle estelle changed the title DRAFT: CSS font semi-shorthand property CSS font semi-shorthand property Jun 8, 2026
@estelle estelle requested a review from chrisdavidmills June 8, 2026 17:05

@chrisdavidmills chrisdavidmills left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Nice work, @estelle. A few comments and suggestions for you.


- {{cssxref("font-family")}}
- {{cssxref("font-size")}}
- {{cssxref("font-stretch")}}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

It is a legacy term, and now just an alias. I could add (or it's legacy alias font-stretch) to the width, but i prefer not to. i'll add it as a suggestion which you can merge if you think it necessary.

- `<'font-weight'>`
- : See the {{cssxref("font-weight")}} CSS property. Defaults to `normal`.
- `<font-width-css3>`
- : The keywords supported by the legacy `font-stretch` property. See the {{cssxref("font-width")}} CSS property. Defaults to `normal`.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

I can see why you've done this, but it is confusing. Linking to font-width looks like a typo or a mistake. Since the keywords are exactly the same, and font-stretch is kept as an alias of font-width, could you just say "The keywords supported by the {{cssxref("font-width")}} CSS property. Defaults to normal."

If you don't feel that this is a viable solution, I think you'll need to explain their relationship in some way.

Also, font-stretch/font-width accepts a percentage as well as keywords. Are these not supported in the font shorthand?

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

percents are not supported, explained in detail below, but why it says "keywords" here.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Ah, yes, I saw the explanation later on. We are all good on that particular point.

- `<font-width-css3>`
- : The keywords supported by the legacy `font-stretch` property. See the {{cssxref("font-width")}} CSS property. Defaults to `normal`.
- `<'font-size'>`
- : See the {{cssxref("font-size")}} CSS property. Required value.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

In other parts of MDN, we mark optional values with the appropriate macro, and not required values.

- `<system-font-family-name>`
- : A single keyword representing a system font, including:
- `caption`
- : The system font used for captioned controls (e.g., buttons, drop-downs, etc.).

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Suggested change
- : The system font used for captioned controls (e.g., buttons, drop-downs, etc.).
- : The system font used for captioned controls (e.g., buttons and drop-downs).

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

This was kept from the original. I didn't change it b/c i am not sure it's only those two.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

I appreciate that, but it looks a bit weird to include both "e.g." and "etc."; you only need one.

Maybe "(buttons, drop-downs, etc.)" would serve the purpose better.

Either way, not that important.

- `status-bar`
- : The system font used in window status bars.

There are several non-standard values are implemented with prefixes.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Suggested change
There are several non-standard values are implemented with prefixes.
There are several non-standard values implemented with prefixes.

- `font-stretch` may only be a single keyword value.
- `line-height` must immediately follow `font-size`, preceded by "/", like this: `16px/3`.
- `font-family` must be the last value specified.
As with any shorthand property, any of the longhand component properties not value that is not specified is set to its initial value, possibly overriding values previously set using non-shorthand properties. In addition, the shorthand resets the following properties to their initial values that can not be set by the shorthand:

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Suggested change
As with any shorthand property, any of the longhand component properties not value that is not specified is set to its initial value, possibly overriding values previously set using non-shorthand properties. In addition, the shorthand resets the following properties to their initial values that can not be set by the shorthand:
As with any shorthand property, any of the longhand component properties not specified are set to their initial values, possibly overriding values previously set using non-shorthand properties. In addition, the shorthand resets the following properties to their initial values. The shorthand cannot explicitly set them:

- : Browsers often implement several more, prefixed, keywords: Gecko implements `-moz-window`, `-moz-document`, `-moz-desktop`, `-moz-info`, `-moz-dialog`, `-moz-button`, `-moz-pull-down-menu`, `-moz-list`, and `-moz-field`.
### Shorthand property order

The order of some of the longhand values within the shorthand `font` declaration is partially important and must therefore follow a few rules:

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Suggested change
The order of some of the longhand values within the shorthand `font` declaration is partially important and must therefore follow a few rules:
The order of some of the longhand values within the shorthand `font` declaration must follow a few rules:


For backward compatibility, the valid values of the `font-variant` and `font-width` components do not include all the valid values or the longhand equivalents.

- The valid values for the `font-variant` component are limited `normal` or `small-caps`.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

This is an odd way to structure these bits, with the DL, and it is a bit confusing. It looks like a copy-paste error or something.

How about just using regular bullets, and saying something like:

The valid values for the font-variant component are limited to the two values specified in CSS 2.1: normal or small-caps...

And then carry on from there.

I'm not convinced that you need to mention the spec component at all, but if you are determined to do so, you could say

The valid values for the font-variant component (specified as <font-variant-css2>) are limited to the two values specified in CSS 2.1: normal or small-caps...

Same suggestion for both.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

changed to paragraphs and removes spec mentions

### Setting font properties
### Basic usage

This example defines the `font` for all {{htmlelement("p")}} elements. We set the `font-size` to `12px` and the `line-height` to `14px`, separating them with a forward slash (`/`). We know which {{cssxref("length")}} refers to each component because of the rule: "If present, the `line-height` must immediately follow the `font-size`, with the two values separated by a forward slash (`/`)". The declaration also sets the `font-family` to `sans-serif`.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Suggested change
This example defines the `font` for all {{htmlelement("p")}} elements. We set the `font-size` to `12px` and the `line-height` to `14px`, separating them with a forward slash (`/`). We know which {{cssxref("length")}} refers to each component because of the rule: "If present, the `line-height` must immediately follow the `font-size`, with the two values separated by a forward slash (`/`)". The declaration also sets the `font-family` to `sans-serif`.
This example defines the `font` for all {{htmlelement("p")}} elements. We set the `font-size` to `12px` and the `line-height` to `14px`, separating them with a forward slash (`/`). The declaration also sets the `font-family` to `sans-serif`.

I don't think you need to repeat that here. You said it in the description above.


### System font

This example demonstrates using the `font` property to set a system font. We set the paragraph's font to have the same `font-family`, `line-height`, `font-size`, etc., as the status bar of the window, then we set the `line-height` to `1.6`.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

It might not be immediately obvious to all readers what the status bar of the window is. When I saw the example, I immediately thought, "Oh, why is it a link instead of a paragraph?" why has it got a weird URL?

It might be good to clarify beforehand what the intention is here, or try to do something a bit less convoluted.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Fair! I rewrote the text around all the example components to explain the link being bad so we disabled it with javascript

Comment on lines +150 to +152
Chromium implements `-webkit-control`, `-webkit-small-control`, and `-webkit-mini-control`.
Webkit includes the Chromium values, and adds `-webkit-body`, `-webkit-pictograph`, and `-webkit-ruby-text`, along with several `-apple-system-*` prefixed system font names.
Gecko implements `-moz-window`, `-moz-document`, `-moz-desktop`, `-moz-info`, `-moz-dialog`, `-moz-button`, `-moz-pull-down-menu`, `-moz-list`, and `-moz-field`.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

[mdn-linter] reported by reviewdog 🐶

Suggested change
Chromium implements `-webkit-control`, `-webkit-small-control`, and `-webkit-mini-control`.
Webkit includes the Chromium values, and adds `-webkit-body`, `-webkit-pictograph`, and `-webkit-ruby-text`, along with several `-apple-system-*` prefixed system font names.
Gecko implements `-moz-window`, `-moz-document`, `-moz-desktop`, `-moz-info`, `-moz-dialog`, `-moz-button`, `-moz-pull-down-menu`, `-moz-list`, and `-moz-field`.
Chromium implements `-webkit-control`, `-webkit-small-control`, and `-webkit-mini-control`.
Webkit includes the Chromium values, and adds `-webkit-body`, `-webkit-pictograph`, and `-webkit-ruby-text`, along with several `-apple-system-*` prefixed system font names.
Gecko implements `-moz-window`, `-moz-document`, `-moz-desktop`, `-moz-info`, `-moz-dialog`, `-moz-button`, `-moz-pull-down-menu`, `-moz-list`, and `-moz-field`.

@estelle estelle left a comment

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Thanks @chrisdavidmills. I think i addressed everything

- {{cssxref("font-family")}}
- {{cssxref("font-size")}}
- {{cssxref("font-stretch")}}
- {{cssxref("font-width")}}

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Feel free to commit this if you think it's necessary.

Suggested change
- {{cssxref("font-width")}}
- {{cssxref("font-width")}} (or it's legacy alias {{cssxref("font-stretch")}})

- `<system-font-family-name>`
- : A single keyword representing a system font, including:
- `caption`
- : The system font used for captioned controls (e.g., buttons, drop-downs, etc.).

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

This was kept from the original. I didn't change it b/c i am not sure it's only those two.


If `font` is specified as a `<system-font-family-name>` keyword, the full property value must be set to that single, case-insensitive keyword. Valid values include `caption`, `icon`, `menu`, `message-box`, `small-caption` or `status-bar`.

Browsers also support non-standard prefixed values. Chromium implements `-webkit-control`, `-webkit-small-control`, and `-webkit-mini-control`. Webkit includes these, and adds `-webkit-body`, `-webkit-pictograph`, and `-webkit-ruby-text`, along with several `-apple-system-*` prefixed system font names. Gecko implements `-moz-window`, `-moz-document`, `-moz-desktop`, `-moz-info`, `-moz-dialog`, `-moz-button`, `-moz-pull-down-menu`, `-moz-list`, and `-moz-field`.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

good call. done.


### System font

This example demonstrates using the `font` property to set a system font. We set the paragraph's font to have the same `font-family`, `line-height`, `font-size`, etc., as the status bar of the window, then we set the `line-height` to `1.6`.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Fair! I rewrote the text around all the example components to explain the link being bad so we disabled it with javascript


For backward compatibility, the valid values of the `font-variant` and `font-width` components do not include all the valid values or the longhand equivalents.

- The valid values for the `font-variant` component are limited `normal` or `small-caps`.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

changed to paragraphs and removes spec mentions

@estelle estelle requested a review from chrisdavidmills June 9, 2026 11:52

@chrisdavidmills chrisdavidmills left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

@estelle, I've read it through again and made a few more comments, but only a few typo fixes and suggestions this time around. This is looking great, so I'll approve, and you can merge when you've looked at the new comments.


For backward compatibility, the valid values of the `font-variant` and `font-width` components do not include all the valid values or the longhand equivalents.

The valid values for the `font-variant` component are limited `normal` or `small-caps`. While no other values are supported, the shorthand `font` declaration resets all the `font-variant-*` longhand properties to `normal`, including {{cssxref("font-variation-settings")}}, {{cssxref("font-variant-position")}}, {{cssxref("font-variant-emoji")}}, {{cssxref("font-variant-caps")}}, {{cssxref("font-variant-ligatures")}}, {{cssxref("font-variant-numeric")}}, {{cssxref("font-variant-east-asian")}}, and {{cssxref("font-variant-alternates")}}.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Suggested change
The valid values for the `font-variant` component are limited `normal` or `small-caps`. While no other values are supported, the shorthand `font` declaration resets all the `font-variant-*` longhand properties to `normal`, including {{cssxref("font-variation-settings")}}, {{cssxref("font-variant-position")}}, {{cssxref("font-variant-emoji")}}, {{cssxref("font-variant-caps")}}, {{cssxref("font-variant-ligatures")}}, {{cssxref("font-variant-numeric")}}, {{cssxref("font-variant-east-asian")}}, and {{cssxref("font-variant-alternates")}}.
The valid values for the `font-variant` component are limited to `normal` or `small-caps`. While no other values are supported, the shorthand `font` declaration resets all the `font-variant-*` longhand properties to `normal`, including {{cssxref("font-variation-settings")}}, {{cssxref("font-variant-position")}}, {{cssxref("font-variant-emoji")}}, {{cssxref("font-variant-caps")}}, {{cssxref("font-variant-ligatures")}}, {{cssxref("font-variant-numeric")}}, {{cssxref("font-variant-east-asian")}}, and {{cssxref("font-variant-alternates")}}.


The valid values for the `font-variant` component are limited `normal` or `small-caps`. While no other values are supported, the shorthand `font` declaration resets all the `font-variant-*` longhand properties to `normal`, including {{cssxref("font-variation-settings")}}, {{cssxref("font-variant-position")}}, {{cssxref("font-variant-emoji")}}, {{cssxref("font-variant-caps")}}, {{cssxref("font-variant-ligatures")}}, {{cssxref("font-variant-numeric")}}, {{cssxref("font-variant-east-asian")}}, and {{cssxref("font-variant-alternates")}}.

The valid values for the `font-width` component are limited to keyword values: `normal`, `ultra-condensed`, `extra-condensed`, `condensed`, `semi-condensed`, `semi-expanded`, `expanded`, `extra-expanded`, `ultra-expanded`. The {{cssxref("font-width")}} longhand property also supports {{cssxref("percentage")}} values, which are not valid within the shorthand.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Suggested change
The valid values for the `font-width` component are limited to keyword values: `normal`, `ultra-condensed`, `extra-condensed`, `condensed`, `semi-condensed`, `semi-expanded`, `expanded`, `extra-expanded`, `ultra-expanded`. The {{cssxref("font-width")}} longhand property also supports {{cssxref("percentage")}} values, which are not valid within the shorthand.
The valid values for the `font-width` component are limited to keyword values: `normal`, `ultra-condensed`, `extra-condensed`, `condensed`, `semi-condensed`, `semi-expanded`, `expanded`, `extra-expanded`, `ultra-expanded`. The {{cssxref("font-width")}} longhand property also supports {{cssxref("percentage")}} values, but they are not valid within the shorthand.

I thought a "but" might make it sound slightly more definite/conclusive.

### Live sample
#### HTML

Our HTML includes a paragraph ({{htmlelement("p")}}) containing a link ({{htmlelement("a")}}) with a convoluted [`href`](/en-US/docs/Web/HTML/Reference/Elements/a#href) attribute value. When you hover over or focus on the rendered link, your browser's status bar should display the value of this `href` attribute.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Suggested change
Our HTML includes a paragraph ({{htmlelement("p")}}) containing a link ({{htmlelement("a")}}) with a convoluted [`href`](/en-US/docs/Web/HTML/Reference/Elements/a#href) attribute value. When you hover over or focus on the rendered link, your browser's status bar should display the value of this `href` attribute.
Our HTML includes a paragraph ({{htmlelement("p")}}) containing a link ({{htmlelement("a")}}) with a convoluted [`href`](/en-US/docs/Web/HTML/Reference/Elements/a#href) attribute value. When you hover or focus the rendered link, your browser's status bar should display the value of the `href` attribute.

As the URL in our HTML link is not good practice, we include a script that prevents the document from redirecting to a non-existent page when the link is clicked.

```js
const a = document.querySelector("a");

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Maybe change a to something like aElem so that it is easier to distinguish it from e at a glance.


{{EmbedLiveSample('System font','100%', '100')}}

Hover or focus the link, then look at your status bar. The font should be the same family and size and the text in your status bar at the bottom of your browser window..

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Suggested change
Hover or focus the link, then look at your status bar. The font should be the same family and size and the text in your status bar at the bottom of your browser window..
Hover or focus the link. The font should be the same family and size as the text in your status bar at the bottom of your browser window.

Fixing a couple of typos, plus I don't think we need the "status bar" repetition. This is pretty clear now.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Content:CSS Cascading Style Sheets docs size/m [PR only] 51-500 LoC changed

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants