Skip to content

Fix weird character rendering on Windows with Japanese locale - #20318

Merged
RobinMalfait merged 3 commits into
mainfrom
fix/issue-19768
Jul 14, 2026
Merged

Fix weird character rendering on Windows with Japanese locale#20318
RobinMalfait merged 3 commits into
mainfrom
fix/issue-19768

Conversation

@RobinMalfait

@RobinMalfait RobinMalfait commented Jul 9, 2026

Copy link
Copy Markdown
Member

This PR fixes an issue where some characters are incorrectly rendered on Windows with the Japanese locale.

This is arguably a bug in the font that's loaded by Windows when it encounters system-ui. But waiting for fixes there might ... take a while.

Another option is to not change the defaults in Tailwind CSS and instead let the users that support different locales implement a fallback by overriding the --font-sans variable.

The biggest reason for me to not change it in Tailwind CSS is that it requires us to know what the (proper) fallback fonts need to be on a per OS basis.

But the main reason why I did want to make the change is that MDN says this about the system-ui font:

Glyphs are taken from the default user interface font on a given platform. Because typographic traditions vary widely across the world, this generic is provided for typefaces that don't map cleanly into the other generics.

Note: As the name implies, system-ui is intended to make UI elements look like native apps, and not for typesetting large paragraphs of text. It may cause the displayed typeface to be undesirable for some users—for example, the default Windows CJK font may render Latin scripts poorly, and the lang attribute may not affect the displayed font. Some operating systems do not allow customizing system-ui, while browsers generally allow customizing the sans-serif font family. For large paragraphs, use sans-serif or some other non-UI font family instead.

https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/font-family#system-ui

There are PRs in other big projects that made this kind of change as well. E.g.:

The reasoning for getting rid of ui-sans-serif is twofold:

  1. Because the starlight PR seems very well tested, and they got rid of it
  2. In the event that the browser decided to load the broken font when it encounters ui-sans-serif, then we will run into the same issue again.

Fixes: #19767
Fixes: #19768

Test plan

  1. system-ui is not used anymore, so the bug doesn't happen
  2. Everything still looks the same for the places I checked, but it's hard to know if this created other issues on other OS + Locale combinations...
Replace `ui-sans-serif` and `system-ui` with the following set of fonts:
- `-apple-system`
- `BlinkMacSystemFont`
- 'Segoe UI'
- Roboto
- 'Helvetica Neue'
- 'Noto Sans'
- Arial

For most peole this will look exactly the same, but it's for places like
Windows where a different font is used for `system-ui` in case your
machine is using a Japanese locale for example. Then the font used is
'Yu Gothic UI' which is the font that has bugs.

You could argue that it's a bug in that font and even an OS bug for not
providing a proper font for `system-ui`.
@RobinMalfait
RobinMalfait marked this pull request as ready for review July 14, 2026 15:01
@RobinMalfait
RobinMalfait requested a review from a team as a code owner July 14, 2026 15:01
@greptile-apps

greptile-apps Bot commented Jul 14, 2026

Copy link
Copy Markdown
Contributor

Confidence Score: 4/5

Safe to merge — the change is a direct substitution of a well-known font stack (Bootstrap v4/v5) for the system-ui-based one, and it is consistent across every affected file.

The new font list fixes a real rendering defect on Windows CJK locales and the approach is validated by prior art (Starlight, VitePress). The main residual uncertainty — which the author openly acknowledges — is that dropping system-ui might produce subtly different rendering on exotic or future OS/locale combinations that are hard to test exhaustively. All snapshot tests are updated consistently, so there is no snapshot drift risk.

No files require special attention; all changed files are in sync with the new font stack.

Reviews (1): Last reviewed commit: "update CHANGELOG" | Re-trigger Greptile

@RobinMalfait
RobinMalfait merged commit e48c5e8 into main Jul 14, 2026
10 checks passed
@RobinMalfait
RobinMalfait deleted the fix/issue-19768 branch July 14, 2026 15:04
@coderabbitai

coderabbitai Bot commented Jul 14, 2026

Copy link
Copy Markdown
Contributor

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 4f476dab-db3d-4a15-8b1d-aea990acb3e6

📥 Commits

Reviewing files that changed from the base of the PR and between b03e5e7 and d3ba8c0.

⛔ Files ignored due to path filters (2)
  • packages/@tailwindcss-postcss/src/__snapshots__/index.test.ts.snap is excluded by !**/*.snap
  • packages/tailwindcss/src/__snapshots__/index.test.ts.snap is excluded by !**/*.snap
📒 Files selected for processing (7)
  • CHANGELOG.md
  • integrations/cli/index.test.ts
  • packages/tailwindcss/preflight.css
  • packages/tailwindcss/src/compat/default-theme.ts
  • packages/tailwindcss/src/css-functions.test.ts
  • packages/tailwindcss/src/source-maps/source-map.test.ts
  • packages/tailwindcss/theme.css

Walkthrough

Updated Tailwind’s default sans-serif font stack to use explicit platform fonts, including Apple, Windows, Android, and common fallback families, replacing ui-sans-serif and system-ui. Applied the stack in theme configuration, theme CSS, and preflight CSS. Updated CLI, CSS function, and source-map snapshots to match the generated output, and documented the change in the unreleased changelog.

🚥 Pre-merge checks | ✅ 4
✅ Passed checks (4 passed)
Check name Status Explanation
Title check ✅ Passed The title is concise and accurately describes the Windows Japanese-locale rendering fix.
Description check ✅ Passed The description directly explains the font-stack change and its motivation, matching the patch.
Linked Issues check ✅ Passed The font-stack updates remove system-ui/ui-sans-serif and address both linked Windows CJK rendering issues [#19767, #19768].
Out of Scope Changes check ✅ Passed All changes are related to the font-stack fix; the changelog and snapshot updates are expected supporting edits.

Comment @coderabbitai help to get the list of available commands.

@akfaew

akfaew commented Jul 18, 2026

Copy link
Copy Markdown

This change broke Tailwind defaults in a patch release: #20348

RobinMalfait pushed a commit to tailwindlabs/tailwindcss.com that referenced this pull request Jul 28, 2026
Tailwind CSS v4.3.3 changed the default `--font-sans` value to fix
broken character rendering on Windows with CJK locales
(tailwindlabs/tailwindcss#20318), but the docs still show the
previous`ui-sans-serif, system-ui, sans-serif` stack.

Update the `font-family` quick reference and the four
`theme.css`examples on the theme page to match the stack that actually
ships (tailwindlabs/tailwindcss/packages/tailwindcss/theme.css).

Reported in tailwindlabs/tailwindcss#20348.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

2 participants