@cosxai/ui 0.3.4 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosxai/ui",
-  "version": "0.3.4",
+  "version": "0.4.1",
   "description": "COSX design system — React 19 component primitives shared across product-meta and other consumers",
   "license": "UNLICENSED",
   "type": "module",

package/src/styles/fonts.css

@@ -1,22 +1,36 @@
-/* @font-face declarations for the kit's default sans + mono.
-   Consumer projects supply the OTF/WOFF2 files under /fonts/ (the
-   library's public/fonts/ directory is a reference copy for when
-   the kit is consumed standalone). Swap out for your own brand
-   stack by overriding --ck-font-sans / --ck-font-mono after
-   importing this file. */
+/* Web-font loading for the kit's typographic vocabulary.
+   Loaded from Google Fonts CDN — Geist + Geist Mono cover the
+   default sans/mono slots; Playfair Display drives the editorial
+   chrome's display heading; Caveat covers the sketch chrome's
+   handwritten display; Noto Serif SC is the matching CJK serif for
+   the editorial heading so a name like "本杰明 Zoë" renders Latin in
+   Playfair Display and Chinese in Noto Serif SC without leaking to
+   PingFang SC / SimSun (sans-serif system fallbacks that mis-pair
+   with the editorial high-contrast serif). All five are SIL OFL.
 
-@font-face {
-  font-family: "Geist";
-  src: url("/fonts/Geist-Regular.otf") format("opentype");
-  font-weight: 400 700;
-  font-style: normal;
-  font-display: swap;
-}
+   Why Google Fonts CDN over self-hosting:
+     1. Self-hosted /fonts/*.otf had to be shipped per-consumer
+        (the previous setup), and consumers that forgot returned
+        SPA index.html for the font URL, surfacing a noisy
+        "Failed to decode downloaded font" warning in every
+        production console.
+     2. The CDN handles font-display, variable-font subsetting,
+        and per-browser format selection automatically; we just
+        consume the @import.
+     3. font-display=swap means the system fallback paints first,
+        the web font upgrades on arrival — no FOIT.
 
-@font-face {
-  font-family: "Geist Mono";
-  src: url("/fonts/GeistMono-Regular.otf") format("opentype");
-  font-weight: 400 600;
-  font-style: normal;
-  font-display: swap;
-}
+   Bandwidth shape — Noto Serif SC is the only large family in the
+   set (CJK fonts dwarf Latin by character count). Google Fonts ships
+   it as ~100 unicode-range subsets; the browser only fetches a
+   subset when a character in its range is rendered. Pure-Latin
+   pages pay the CSS file (~5-10KB gzip) but no .woff2 — pages with
+   Chinese names pay an additional ~200-400KB of subset binaries
+   spread across the few CJK ranges they actually use.
+
+   For offline / enterprise deploys that block Google Fonts, a
+   consumer can override --ck-font-sans/serif/mono in tokens.css
+   to fall back entirely to the system-font slot at the tail of
+   each stack. */
+
+@import url("https://fonts.googleapis.com/css2?family=Geist:wght@300..700&family=Geist+Mono:wght@400..700&family=Playfair+Display:wght@400..900&family=Caveat:wght@400..700&family=Noto+Serif+SC:wght@400..900&display=swap");

package/src/styles/tokens.css

@@ -13,10 +13,37 @@
      serif (editorial body), and display (headlines). By default
      display = sans so headings inherit the same neutral grotesk;
      editorial chrome overrides display → serif to flip headlines
-     to a high-contrast serif without touching component code. */
-  --ck-font-sans: "Geist", "Inter", system-ui, -apple-system, sans-serif;
-  --ck-font-mono: "Geist Mono", "JetBrains Mono", ui-monospace, "SF Mono", Menlo, monospace;
-  --ck-font-serif: "Playfair Display", "GT Sectra", "Canela", Georgia, serif;
+     to a high-contrast serif without touching component code.
+
+     Each stack ends with CJK system-font fallbacks before the
+     generic family so 中文 / 日本語 / 한국어 don't drop to the
+     browser's last-resort glyph (renders as tofu on locked-down
+     hosts). Browsers do per-character fallback — Latin hits
+     Geist/Playfair, CJK hits the next matching family in the stack.
+
+     Serif slot ALSO carries Noto Serif SC as a web-font fallback
+     (loaded via fonts.css). Reason: the editorial chrome's display
+     heading uses Playfair Display, a high-contrast modern serif —
+     pairing it with PingFang SC / SimSun (the system *sans-serif*
+     CJK fallbacks) reads as a style break. Adobe/Google's Noto Serif
+     SC matches Playfair's serif vocabulary cross-platform without
+     depending on the user having Songti SC / STSong / Source Han
+     Serif SC installed locally. Cost is lazy: subset .woff2 only
+     downloads when a CJK character is actually rendered (per
+     fonts.css's unicode-range mechanism); pure-Latin pages pay only
+     the small CSS file.
+
+     Sans + mono slots stay system-only — system sans CJK
+     (PingFang SC / Microsoft YaHei) is what users expect for UI
+     copy, and the visual mismatch concern doesn't apply when the
+     Latin half is also a clean grotesk. */
+  --ck-font-sans: "Geist", "Inter", system-ui, -apple-system,
+                  "PingFang SC", "Hiragino Sans GB", "Microsoft YaHei",
+                  "Source Han Sans SC", sans-serif;
+  --ck-font-mono: "Geist Mono", "JetBrains Mono", ui-monospace, "SF Mono", Menlo,
+                  "Sarasa Mono SC", monospace;
+  --ck-font-serif: "Playfair Display", "Noto Serif SC", "GT Sectra", "Canela",
+                   Georgia, "Songti SC", "STSong", "Source Han Serif SC", serif;
   --ck-font-display: var(--ck-font-sans);
 
   /* ---------- Radii / motion ---------- */