fix(typography): bundle Noto Sans JP by default for real Japanese medium weight

[interacsean]

Fixes the Japanese font-medium bug reported in
tailor-professional-service/knowledge#219,
tracked at tailor-inc/platform-planning#1397.

The bug

Inter carries no CJK glyphs, so Japanese text falls through to the OS font — and system Japanese fonts have no 500 weight. Yu Gothic UI on Windows ships only Light/Semilight/Regular/Semibold/Bold, so CSS weight matching resolves font-weight: 500 down to Regular. font-medium accounts for 71 of the 91 weight utilities in core (labels, table cells, card titles), so most of the UI's weight hierarchy silently collapses in Japanese.

Reproduction status, stated plainly: verified macOS 15 is unaffected — it ships Hiragino W0–W9 including W5, and measured ink deltas at 500/600/700 are +15.0%/+27.8%/+42.9%, i.e. a real medium. The Windows failure is inferred, not measured: no Windows machine was available, so it rests on Yu Gothic UI's documented face inventory plus the CSS Fonts 4 matching rule. The original report's claim that Hiragino lacks W5 is outdated for current macOS. The reporter's OS is not stated in the discussion. So the bug is real as reported but has not been reproduced here on any platform — worth confirming before release.

Either way no system-font stack can guarantee the weight, which is what the fix addresses.

What changed

Noto Sans JP Variable ships in @tailor-platform/app-shell/styles. Continuous 100–900 axis, so every weight the design system names is real by construction. No opt-in import.

--app-shell-font-sans replaces the whole stack. --font-sans previously compiled to a literal (body{font-family:Inter Variable,…}), so consumers could not change it at all. It now compiles to var(--app-shell-font-sans, <default>).

Note the name: under prefix(astw) Tailwind emits this theme key as --astw-font-sans, so calling the override that produced the self-referential --astw-font-sans: var(--astw-font-sans, …) — invalid at computed-value time, working only by falling through to the var() fallback. Unprefixed --font-sans is unavailable too, since an unprefixed Tailwind in the consuming app defines it and would silently win.

Metric harmonisation. Shipping the font alone would regress mixed Japanese/Latin strings. Descriptors were measured in Chromium, not derived from font tables:

	value
Inter cap height / x-height	0.727em / 0.545em
Inter fontBox ascent + descent	0.97 + 0.24
Noto kanji / kana height	0.795em / 0.794em
Noto fontBox ascent + descent	1.16 + 0.29

• size-adjust: 94% — Noto's kanji run 1.09× Inter's cap height, oversized next to Inter's large x-height. Chosen from a rendered sweep; above ~96% the Japanese dominates, below ~90% it looks undersized.
• ascent-override: 103.2% / descent-override: 25.5% / line-gap-override: 0% — pre-divided by the size-adjust, because size-adjust also scales the override percentages (97 × 0.94 = 91, not 97). These land the face on Inter's actual 97%/24% box.

Metric-matched local() fallback, rendered during font-display: swap and for uncovered glyphs. Carries the same size-adjust: 94% as the Noto faces plus Inter's line box, so a subset arriving mid-scroll changes neither row heights nor advance widths. Weight is bucketed across four faces (100–449 → Hiragino W3, 450–549 → W5, 550–649 → W6, 650–900 → W7) so that 500 lands on a real medium; W0–W9 verified present and distinct on macOS 15 by rasterised ink.

Both faces are clamped to Japanese codepoint blocks via one JP_BLOCKS constant — kana, kanji, CJK punctuation, fullwidth forms, and the compatibility blocks carrying ㈱ ㍿ ㎡, plus Extension B for name kanji. Upstream's ranges also cover arrows, dingbats and letterlike symbols shared with Latin; leaving those in meant a Latin-only app fetched a Japanese subset the first time it rendered the DataTable's boolean ✓ (U+2713). 116 of 124 subsets survive the clamp; the other 8 ship neither face nor file.

Vendoring: committed, matching Inter. inter.css and its 7 woff2 files are already vendored this way — copied verbatim from fontsource and committed, with no script and no devDependency in the build path. The 116 Noto subsets follow the same convention, and the URLs are written ./fonts/files/* so they resolve once Tailwind inlines the stylesheet into dist/app-shell-core.css.

This started out generating them at build time to keep ~5 MB of binaries out of git. That divergence didn't survive scrutiny:

• The cost lands almost entirely on full clones (packed history 6.9 MB → ~12 MB). It is not paid by CI — actions/checkout defaults to fetch-depth: 1 and 12 of 13 workflows here are shallow, so historical blobs are never fetched. No effect on Actions minutes, the published package, or test time (nothing in the suite reads the fonts).
• Against that, the build step was a real failure surface — it broke CI once on a lint rule — and a cold build now needs nothing but a checkout.

scripts/sync-noto-fonts.mjs survives as a manual re-vendoring tool (pnpm --filter @tailor-platform/app-shell vendor:fonts) rather than being deleted: clamping subsets to JP_BLOCKS and the fallback weight ladder are where four review defects lived, so re-deriving them by hand on the next bump is a trap worth avoiding. Since the committed stylesheet is now the artifact of record, its header carries the reasoning the script used to hold. Renovate is disabled for @fontsource-variable/** so bumps are deliberate — not because 5 MB is dangerous, but because 116 binary files a week for glyph tweaks is noise.

What it costs, and who pays

Because this is on by default, every consumer pays the build-output cost, including Latin-only apps:

	before	after
npm install, unpacked	1.15 MB / 39 files	6.25 MB / 159 files
git packed history	6.9 MB	~12 MB (full clones only)
consumer build output	177 KB (7 Inter subsets)	~5.0 MB (123 subsets)
app-shell-core.css raw	98 KB	200 KB (+101 KB)
app-shell-core.css gzipped	15 KB	45 KB (+30 KB)

A bundler emits every unicode-range subset it can see; it cannot know at build time which characters the data will contain, and ERP content is DB-driven. Verified with a clean build of both examples: 124 Noto files each.

End users download far less, because unicode-range defers subsetting to runtime. Measured in the browser, not estimated:

page	Noto subsets fetched
Latin-only, including a boolean DataTable column	0 — Inter and the system font only
Japanese-heavy demo	27 of 116 (~1.1 MB)

Modelled against the real subset tables: ~237 KB for all kana, ~910 KB for a typical first Japanese screen. Weight costs nothing extra — every weight shares one file.

Upgrade impact

Japanese previously rendered in the OS font and now renders in Noto on every platform. This is a bug fix rather than a staged breaking change — the weight scale the package already documented was simply not true for Japanese — so there is no migration entry: an app that upgrades and does nothing gets the correct weights. The rendering change and the --app-shell-font-sans opt-out are described in the changeset, which reaches consumers as the changelog.

Japanese runs measure ~6% narrower. Narrower text can relieve truncation and wrapping but cannot cause it, so the risk is under-filled boxes and moved ellipsis positions, not overflow. Latin is unaffected; line boxes are unchanged.

Two findings worth knowing:

• The shift is the size-adjust, not the typeface. Noto at 100% measures within 0.18% of Hiragino, because CJK glyphs sit on a full-width em grid. size-adjust: 100% would leave widths essentially untouched, at the cost of the optical match. This also bounds the Windows uncertainty: Yu Gothic UI is very likely ~1em/glyph too, so its delta should also be ≈ the size-adjust.
• The missing weight was never a layout bug. Hiragino's 400 and 500 advance widths differ by 0.00–0.27% — weight changes ink, not width, on an em grid. So the bug being fixed is purely visual, and the layout change comes entirely from the font swap.

Measured across nine constrained shapes: 5 identical, button intrinsic width −8px, a sidebar label stops truncating, and two cases with widths deliberately tuned to the boundary drop a line (2→1, 3→2).

Verification

• Weight ladder: Japanese 500 is +18.0% ink over 400, 600 +29.3%, 700 +40.1% — four distinct weights where there was one.
• Layout-neutral: Latin-only, Japanese-only and mixed lines all measure 20px, against 23–25px unharmonised.
• Cold build from a clean tree works (the CI path — generated assets are gitignored); sync is idempotent.
• type-check, lint, test (1554 tests / 81 files), fmt, and the generated-skill drift check all clean.

For the reviewer

• size-adjust: 94% is an aesthetic call, not a derived constant. The measured kanji/cap ratio of 1.0926 sits inside the conventional 1.05–1.10 band for Japanese/Latin mixing, so 100% is defensible — and would make this change nearly layout-neutral. One constant in sync-noto-fonts.mjs; the overrides derive from it. Worth a second opinion.
• The Windows local() fallback names are unverified. local() matches PostScript/full names, never family names — local("Hiragino Sans") silently fails where local("HiraginoSans-W3") resolves. macOS names confirmed; YuGothicUI-Regular etc. follow the same convention but could not be checked here. A wrong name degrades to today's behaviour rather than breaking.
• Per-script weight mapping is out of scope. Noto 500 and Inter 500 don't read as identical weight — CJK packs more stroke into the same area. Mapping one semantic token to per-script numerics changes the token layer and deserves its own PR.
• Someone should open a Japanese screen on Windows before release, both to confirm the bug and to confirm the fix. That's the one gap the local evidence can't close. The Windows local() names in the fallback ladder (YuGothic-Medium, YuGothicUI-Semibold, YuGothicUI-Bold) are unverified from macOS; an unresolvable local() is skipped, so a wrong name degrades to the next entry rather than breaking.

Review history

An adversarial review of the first implementation raised 13 findings; 10 survived a hostile refutation panel and are fixed in 1508ccd1. The four substantive ones were all in the generated stylesheet: the fallback bucketed weight 500 onto Regular faces (reintroducing this PR's own bug, and regressing macOS, where the family pre-empted the cascade that already found Hiragino W5); the fallback omitted size-adjust, so only the vertical half of "metric-matched" was implemented; Noto's unicode-range was unclamped, so ✓ pulled a Japanese subset into Latin-only apps; and the fallback's range omitted 4,140 codepoints Noto covered. The size figures above were also wrong — 46 KB was the stylesheet total, reused as a delta.

🤖 Generated with Claude Code

[interacsean]

/review

[github-actions]

✅ API Design Review completed successfully!

API design review complete for PR #449. No High or Medium issues found. The changes are purely additive: a new opt-in subpath export (./fonts/noto-sans-jp) and a new CSS custom property override (--astw-font-sans). No TypeScript/React public API surface was modified. Verdict: Approve.

[github-actions]

Code Metrics Report

	main (de6ef76)	#449 (ee6738f)	+/-
Coverage	90.0%	90.0%	0.0%
Test Execution Time	2m4s	2m2s	-2s

Details

  |                     | main (de6ef76) | #449 (ee6738f) | +/-  |
  |---------------------|----------------|----------------|------|
  | Coverage            |          90.0% |          90.0% | 0.0% |
  |   Files             |            126 |            126 |    0 |
  |   Lines             |           5174 |           5174 |    0 |
  |   Covered           |           4661 |           4661 |    0 |
+ | Test Execution Time |           2m4s |           2m2s |  -2s |

Code coverage of files in pull request scope (0.0% → 0.0%)

Files	Coverage	+/-	Status
packages/core/package.json	0.0%	0.0%	modified

---

Reported by octocov