Add a note to discourage the abuse of `system-ui` in articles, documents, and blogs

[tats-u]

MDN URL

https://developer.mozilla.org/en-US/docs/Web/CSS/font-family

What specific section or headline is this issue about?

Values

What information was incorrect, unhelpful, or incomplete?

Many sites abuse system-ui as a prettier alternative to sans-serif, but it cause some problems to reduce compatibility with non-application sites.

1. system-ui in Windows can be too condensed to cram a long label or description text into a narrow area. (e.g. Yu Gothic UI in Japanese)
2. If the page language is CJK and the OS language is different from the page language (except for the page is in simplified Chinese and OS language is non-CJK), the shapes of han (kanji) characters are different form intended ones. This occurs in:
   • Windows
   • Android or Linux that adopt a font other than Pan-CJK fonts (e.g. Noto Sans CJK) as UI font
3. Users cannot change system-ui font in Windows since Vista
4. Hiragana and katakana in system-ui in Japanese (Yu Gothic UI) and Chinese (Microsoft YaHei) are ugly

What did you expect to see?

Add a note to discourage the abuse of system-ui.

Note

It is compatible with applications that want to look similar to OS native applications. It does not guarantee that it is the most readable in or optimized for long paragraphs in e.g. articles, documents, and blogs in the page language. If you want to ensure that the chosen font is optimized for long paragraphs in the language of the page, you should stick to sans-serif. sans-serif is the font that the user believes that is the most readable.

Do you have any supporting links, references, or citations?

• [css-fonts] system-ui behavior is undesired for some users w3c/csswg-drafts#3658
• [css-text-4] text-spacing-trim (and font-feature-settings: "palt") is harmful for Yu Gothic UI (system-ui in Japanese Windows) w3c/csswg-drafts#11074
• [css-fonts] Add notes for system-ui #3658 w3c/csswg-drafts#12831

Do you have anything more you want to share?

Example of 3.:

w3c/csswg-drafts#3658 (comment)
w3c/csswg-drafts#3658 (comment)

MDN metadata

Page report details

• Folder: en-us/web/css/font-family
• MDN URL: https://developer.mozilla.org/en-US/docs/Web/CSS/font-family
• GitHub URL: https://github.com/mdn/content/blob/main/files/en-us/web/css/font-family/index.md
• Last commit: 0cc9980
• Document last modified: 2025-07-14T14:43:58.000Z

[robinmetral]

Given that this has been discussed at length over at w3c/csswg-drafts#3658 and a warning was just merged into the CSS fonts spec, I'd suggest directly opening a PR for this 👍

[brysonbw]

Created PR in attempt to resolve: #41302