@cupra/ui-react 2.0.0-canary.260 → 2.0.0-canary.262

package/README.md

@@ -249,7 +249,7 @@ The provider requires **three required props plus one optional**:
 | Prop                 | Type    | Required | Description                                                                                                     |
 |----------------------|---------|----------|-------------------------------------------------------------------------------------------------------------------|
 | `theme`              | string  | Yes      | Visual theme identifier (e.g. `cupra-diagonal`)                                                                 |
-| `load-fonts`         | boolean | Yes      | Auto-load DS-UI font files                                                                                       |
+| `load-fonts`         | boolean | Yes      | Auto-load `fonts.css`, the stylesheet that declares the theme's `@font-face` rules                               |
 | `load-styles`        | boolean | Yes      | Auto-load `theme.css`, the stylesheet the `ui-kit` components require                                           |
 | `load-unused-styles` | boolean | No, defaults to `true` | Auto-load `unused-styles.css`, the theme's `--ds-` tokens that `ui-kit` doesn't consume internally, only needed if your own CSS reads raw tokens |
 
@@ -275,7 +275,9 @@ read raw tokens. If your own CSS does read raw tokens, load `unused-styles.css`
     export function App() {
       return (
         <>
-          <link rel="preload" as="font" type="font/woff2" href="https://ds-assets.cupra.com/fonts/[theme]/[font-file]" crossOrigin="anonymous" />
+          {/* One preload per critical font weight, see Fonts below */}
+          <link rel="preload" as="font" type="font/woff2" href="https://ds-assets.cupra.com/fonts/[theme]/[font-file].woff2" crossOrigin="anonymous" />
+          <link rel="stylesheet" href="https://ds-assets.cupra.com/[version]/styles/[theme]/fonts.css" />
           <link rel="stylesheet" href="https://ds-assets.cupra.com/[version]/styles/[theme]/theme.css" />
           {/* Lower priority; only needed if your own CSS reads raw --ds- tokens directly */}
           <link
@@ -312,6 +314,43 @@ read raw tokens. If your own CSS does read raw tokens, load `unused-styles.css`
 
 ---
 
+## Fonts
+
+Each theme publishes `fonts.css` next to `theme.css`. It only declares the theme's `@font-face` rules
+(woff2, `font-display: fallback`), so the browser downloads just the weights a page renders and only
+swaps the typeface within the first ~3 seconds: later, text doesn't shift. `ThemeProvider` adds it while `load-fonts`
+is `true`; with `load-fonts={false}` link it yourself, as in Option A. That is also the setup for
+server-side rendering, since no JavaScript is needed to load the fonts.
+
+**Preload the critical weights.** With `fallback` the browser waits about 100 ms for a font, then shows the
+fallback typeface and swaps to the real one if it arrives within ~3 seconds. After that it keeps the
+fallback for that page view and uses the real one on the next, cached, navigation. While `load-fonts` is `true`, `ThemeProvider` preloads the Regular and Medium weights of the
+theme next to `fonts.css`, while its content waits for `theme.css`. With `load-fonts={false}` or
+server-side rendering, add the preloads to your `<head>` yourself. Adding them there also helps with
+`ThemeProvider`: the download starts before the JavaScript loads, and the provider skips any preload
+already present. In Next.js, render the `<link>` in the root layout; React 19 hoists it to the `<head>`.
+
+```tsx
+<link
+  rel="preload"
+  as="font"
+  type="font/woff2"
+  href="https://ds-assets.cupra.com/fonts/[theme]/[font-file].woff2"
+  crossOrigin="anonymous"
+/>
+```
+
+- Preload only the weights rendered above the fold, usually Regular and Medium. Every preload competes
+  with other critical requests.
+- Keep `crossOrigin`, even on the same origin. Fonts are fetched in CORS mode, and a preload without it
+  is not reused: the font downloads twice.
+- The `href` must match the URL in `fonts.css` exactly.
+
+| Theme            | `font-family`  | Font files (`[font-file]`)                                                                  |
+|---------|--------|-----------------------------------------------|
+| `seat`           | `seat`         | `SeatBcn-Book` (350), `SeatBcn-Regular` (400), `SeatBcn-Medium` (500), `SeatBcn-Bold` (700), `SeatBcn-Black` (900) |
+| `cupra-diagonal` | `cupra-screen` | `CupraScreen-Light` (300), `CupraScreen-Book` (350), `CupraScreen-Regular` (400), `CupraScreen-Medium` (500) |
+
 ## Icons
 
 Icons must always be consumed through the `<Icon>` React component — never by loading SVG files directly from the CDN.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cupra/ui-react",
-  "version": "2.0.0-canary.260",
+  "version": "2.0.0-canary.262",
   "description": "React components library",
   "author": "SEAT S.A.",
   "license": "SEAT S.A. Library EULA 1.0",
@@ -50,7 +50,7 @@
     }
   ],
   "peerDependencies": {
-    "@cupra/ui-kit": "2.0.0-canary.244",
+    "@cupra/ui-kit": "2.0.0-canary.246",
     "react": ">= 18.3.1 < 20",
     "react-dom": ">= 18.3.1 < 20",
     "typescript": ">=5.0.0"
@@ -74,7 +74,7 @@
     "storybook": "^10.6.2",
     "typescript": "^5.9.3",
     "vite": "^8.3.3",
-    "@cupra/ui-kit": "2.0.0-canary.244"
+    "@cupra/ui-kit": "2.0.0-canary.246"
   },
   "scripts": {
     "build": "rm -rf dist && pnpm --filter @cupra/ui-kit build:react && tsc --declaration --emitDeclarationOnly && BUILD_FORMAT=esm vite build --emptyOutDir false && BUILD_FORMAT=cjs vite build --emptyOutDir false",