@archetypeai/ds-lib-tokens 0.8.0 → 0.8.1

package/README.md

@@ -53,4 +53,17 @@ Brand tokens are defined in `tokens.css` and loaded automatically via `theme.css
 
 ## Fonts
 
-`fonts.css` is included in this package with `@font-face` declarations (15 faces of PP Neue Montreal Sans + Mono, `font-display: swap`) pointing to `/fonts/`. The font binaries themselves are **not** part of the npm package - the CLI (`ds create` / `ds init` / `ds add --fonts <path>`) copies them into your project's `static/fonts/`. Without fonts, the theme falls back to system fonts (`system-ui`, `Courier New`).
+`fonts.css` is included in this package with two kinds of `@font-face` declarations: **15 binary faces** of PP Neue Montreal Sans + Mono (`font-display: swap`) pointing to `/fonts/`, plus **15 metric-matched fallback faces** (per-OS base × per weight). The font binaries themselves are **not** part of the npm package - the CLI (`ds create` / `ds init` / `ds add --fonts <path>`) copies them into your project's `static/fonts/`.
+
+**When the binaries are absent**, the fallback faces take over: each re-shapes a *local* system font to PP Neue Montreal's own metrics — x-height, average character width, and line box — via `size-adjust` + `ascent`/`descent`/`line-gap-override`, so an un-provisioned project still renders at the brand font's proportions and lays out identically. **When the binaries are present**, the same faces make the fallback→brand-font swap shift-free (no layout shift / CLS).
+
+The fallback bases are chosen **per operating system** (the stacks in `theme.css` order them so each platform resolves its closest native font, all confirmed `local()`-reachable):
+
+| | Apple | Windows | Android |
+|---|---|---|---|
+| **Sans** | Helvetica Neue | Arial | Roboto |
+| **Mono** | Menlo | Consolas / Cascadia Mono | Roboto Mono |
+
+SF Mono is intentionally not used — it is not reachable via `local()`. Override numbers are generated with `@capsizecss` from the Regular weights (regenerate if the brand font's metrics change).
+
+Weights are declared **per instance**: `local('Helvetica Neue')` always resolves to the *Regular* cut regardless of the `font-weight` descriptor, so a single face would silently render Medium as Regular and *faux-bold* 700. Each weight therefore names its real cut (`local('HelveticaNeue-Medium')` / `-Bold`, etc.). Bases without a true Medium (Arial, Menlo, Cascadia) omit 500, so it matches down to Regular.

package/fonts.css

@@ -1,3 +1,5 @@
+/* OFFICIAL BRAND FONTS */
+
 /* PP Neue Montreal Sans*/
 
 @font-face {
@@ -40,14 +42,6 @@
   font-display: swap;
 }
 
-@font-face {
-  font-family: 'PP Neue Montreal';
-  src: url('/fonts/PPNeueMontreal-Book.ttf') format('truetype');
-  font-weight: 400;
-  font-style: normal;
-  font-display: swap;
-}
-
 @font-face {
   font-family: 'PP Neue Montreal';
   src: url('/fonts/PPNeueMontreal-Medium.ttf') format('truetype');
@@ -98,14 +92,6 @@
   font-display: swap;
 }
 
-@font-face {
-  font-family: 'PP Neue Montreal Mono';
-  src: url('/fonts/PPNeueMontrealMono-Book.otf') format('opentype');
-  font-weight: 400;
-  font-style: normal;
-  font-display: swap;
-}
-
 @font-face {
   font-family: 'PP Neue Montreal Mono';
   src: url('/fonts/PPNeueMontrealMono-Medium.otf') format('opentype');
@@ -121,3 +107,199 @@
   font-style: normal;
   font-display: swap;
 }
+
+/* METRIC-MATCHED FALLBACKS */
+
+/* sans — Helvetica Neue (MacOS) */
+@font-face {
+  font-family: 'PP Neue Montreal Fallback Helvetica';
+  src: local('HelveticaNeue-UltraLight'), local('Helvetica Neue UltraLight');
+  font-weight: 100;
+  ascent-override: 101.4353%;
+  descent-override: 25.6235%;
+  line-gap-override: 0%;
+  size-adjust: 94.4444%;
+}
+@font-face {
+  font-family: 'PP Neue Montreal Fallback Helvetica';
+  src: local('HelveticaNeue-Light'), local('Helvetica Neue Light');
+  font-weight: 300;
+  ascent-override: 101.4353%;
+  descent-override: 25.6235%;
+  line-gap-override: 0%;
+  size-adjust: 94.4444%;
+}
+@font-face {
+  font-family: 'PP Neue Montreal Fallback Helvetica';
+  src: local('Helvetica Neue'), local('HelveticaNeue');
+  font-weight: 400;
+  ascent-override: 101.4353%;
+  descent-override: 25.6235%;
+  line-gap-override: 0%;
+  size-adjust: 94.4444%;
+}
+@font-face {
+  font-family: 'PP Neue Montreal Fallback Helvetica';
+  src: local('HelveticaNeue-Medium'), local('Helvetica Neue Medium');
+  font-weight: 500;
+  ascent-override: 101.4353%;
+  descent-override: 25.6235%;
+  line-gap-override: 0%;
+  size-adjust: 94.4444%;
+}
+@font-face {
+  font-family: 'PP Neue Montreal Fallback Helvetica';
+  src: local('HelveticaNeue-Bold'), local('Helvetica Neue Bold');
+  font-weight: 700;
+  ascent-override: 101.4353%;
+  descent-override: 25.6235%;
+  line-gap-override: 0%;
+  size-adjust: 94.4444%;
+}
+
+/* sans — Roboto (Android) */
+@font-face {
+  font-family: 'PP Neue Montreal Fallback Roboto';
+  src: local('Roboto Thin'), local('Roboto-Thin');
+  font-weight: 100;
+  ascent-override: 100.2686%;
+  descent-override: 25.3288%;
+  line-gap-override: 0%;
+  size-adjust: 95.5434%;
+}
+@font-face {
+  font-family: 'PP Neue Montreal Fallback Roboto';
+  src: local('Roboto Light'), local('Roboto-Light');
+  font-weight: 300;
+  ascent-override: 100.2686%;
+  descent-override: 25.3288%;
+  line-gap-override: 0%;
+  size-adjust: 95.5434%;
+}
+@font-face {
+  font-family: 'PP Neue Montreal Fallback Roboto';
+  src: local('Roboto'), local('Roboto-Regular');
+  font-weight: 400;
+  ascent-override: 100.2686%;
+  descent-override: 25.3288%;
+  line-gap-override: 0%;
+  size-adjust: 95.5434%;
+}
+@font-face {
+  font-family: 'PP Neue Montreal Fallback Roboto';
+  src: local('Roboto Medium'), local('Roboto-Medium');
+  font-weight: 500;
+  ascent-override: 100.2686%;
+  descent-override: 25.3288%;
+  line-gap-override: 0%;
+  size-adjust: 95.5434%;
+}
+@font-face {
+  font-family: 'PP Neue Montreal Fallback Roboto';
+  src: local('Roboto Bold'), local('Roboto-Bold');
+  font-weight: 700;
+  ascent-override: 100.2686%;
+  descent-override: 25.3288%;
+  line-gap-override: 0%;
+  size-adjust: 95.5434%;
+}
+
+/* sans — Arial (Windows + universal); ships only Regular + Bold → 100/300/500 match to Regular */
+@font-face {
+  font-family: 'PP Neue Montreal Fallback Arial';
+  src: local('Arial'), local('ArialMT');
+  font-weight: 400;
+  ascent-override: 100.4887%;
+  descent-override: 25.3844%;
+  line-gap-override: 0%;
+  size-adjust: 95.3341%;
+}
+@font-face {
+  font-family: 'PP Neue Montreal Fallback Arial';
+  src: local('Arial Bold'), local('Arial-BoldMT');
+  font-weight: 700;
+  ascent-override: 100.4887%;
+  descent-override: 25.3844%;
+  line-gap-override: 0%;
+  size-adjust: 95.3341%;
+}
+
+/* mono — Menlo (Apple); ships only Regular + Bold → 100/500 match to Regular */
+@font-face {
+  font-family: 'PP Neue Montreal Mono Fallback Menlo';
+  src: local('Menlo'), local('Menlo-Regular');
+  font-weight: 400;
+  ascent-override: 96.1274%;
+  descent-override: 24.2827%;
+  line-gap-override: 0%;
+  size-adjust: 99.6594%;
+}
+@font-face {
+  font-family: 'PP Neue Montreal Mono Fallback Menlo';
+  src: local('Menlo Bold'), local('Menlo-Bold');
+  font-weight: 700;
+  ascent-override: 96.1274%;
+  descent-override: 24.2827%;
+  line-gap-override: 0%;
+  size-adjust: 99.6594%;
+}
+
+/* mono — Consolas / Cascadia (Windows); Consolas ships only Regular + Bold → 100/500 match to Regular */
+@font-face {
+  font-family: 'PP Neue Montreal Mono Fallback Cascadia';
+  src: local('Cascadia Mono'), local('Cascadia Code'), local('Consolas');
+  font-weight: 400;
+  ascent-override: 93.5547%;
+  descent-override: 23.6328%;
+  line-gap-override: 0%;
+  size-adjust: 102.4%;
+}
+@font-face {
+  font-family: 'PP Neue Montreal Mono Fallback Cascadia';
+  src:
+    local('Cascadia Mono Bold'), local('CascadiaMono-Bold'), local('Consolas Bold'),
+    local('Consolas-Bold');
+  font-weight: 700;
+  ascent-override: 93.5547%;
+  descent-override: 23.6328%;
+  line-gap-override: 0%;
+  size-adjust: 102.4%;
+}
+
+/* mono — Roboto Mono (Android) */
+@font-face {
+  font-family: 'PP Neue Montreal Mono Fallback Roboto';
+  src: local('Roboto Mono Thin'), local('RobotoMono-Thin');
+  font-weight: 100;
+  ascent-override: 95.8156%;
+  descent-override: 24.2039%;
+  line-gap-override: 0%;
+  size-adjust: 99.9837%;
+}
+@font-face {
+  font-family: 'PP Neue Montreal Mono Fallback Roboto';
+  src: local('Roboto Mono'), local('RobotoMono-Regular');
+  font-weight: 400;
+  ascent-override: 95.8156%;
+  descent-override: 24.2039%;
+  line-gap-override: 0%;
+  size-adjust: 99.9837%;
+}
+@font-face {
+  font-family: 'PP Neue Montreal Mono Fallback Roboto';
+  src: local('Roboto Mono Medium'), local('RobotoMono-Medium');
+  font-weight: 500;
+  ascent-override: 95.8156%;
+  descent-override: 24.2039%;
+  line-gap-override: 0%;
+  size-adjust: 99.9837%;
+}
+@font-face {
+  font-family: 'PP Neue Montreal Mono Fallback Roboto';
+  src: local('Roboto Mono Bold'), local('RobotoMono-Bold');
+  font-weight: 700;
+  ascent-override: 95.8156%;
+  descent-override: 24.2039%;
+  line-gap-override: 0%;
+  size-adjust: 99.9837%;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@archetypeai/ds-lib-tokens",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "Archetype AI Design System Tokens",
   "type": "module",
   "exports": {

package/theme.css

@@ -112,8 +112,14 @@
 
 /* Tailwind Theme */
 @theme {
-  --font-sans: 'PP Neue Montreal', system-ui, -apple-system, sans-serif;
-  --font-mono: 'PP Neue Montreal Mono', 'Courier New', monospace;
+  /* '… Fallback …' faces (metric-matched, per-OS bases) are defined in fonts.css */
+  --font-sans:
+    'PP Neue Montreal', 'PP Neue Montreal Fallback Helvetica', 'PP Neue Montreal Fallback Roboto',
+    'PP Neue Montreal Fallback Arial', ui-sans-serif, system-ui, -apple-system, sans-serif;
+  --font-mono:
+    'PP Neue Montreal Mono', 'PP Neue Montreal Mono Fallback Menlo',
+    'PP Neue Montreal Mono Fallback Cascadia', 'PP Neue Montreal Mono Fallback Roboto',
+    ui-monospace, monospace;
   --radius-xs: 0.125rem;
   --radius-sm: 0.25rem;
   --radius-md: var(--radius);