@cupra/ui-react 2.0.0-canary.242 → 2.0.0-canary.244

package/README.md

@@ -244,15 +244,26 @@ If your TypeScript setup does not support bundler-based module resolution, use r
 
 Wrap your React application with `ThemeProvider`.
 
-The provider requires **three props**:
+The provider requires **three required props plus one optional**:
 
-| Prop        | Type    | Required | Description                                   |
-|-------------|---------|----------|-----------------------------------------------|
-| `theme`     | string  | Yes      | Visual theme identifier (e.g. cupra-diagonal) |
-| `loadFonts` | boolean | Yes      | Auto-load DS-UI font files                    |
-| `loadStyles`| boolean | Yes      | Auto-load DS-UI CSS                           |
+| 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-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 |
 
-If `loadFonts` or `loadStyles` are `false`, you must manually include the corresponding `<link>` tags.
+`ThemeProvider` forwards its props directly to the underlying `<ds-theme-provider>` Web Component, so
+prop names match its HTML attributes (kebab-case), not idiomatic React camelCase.
+
+If `load-fonts`, `load-styles` or `load-unused-styles` are `false`, you must manually include the corresponding `<link>` tags.
+
+**Performance note:** For optimal behaviour, disable `load-styles` and `load-unused-styles` and load both
+stylesheets manually, controlling their priority: `theme.css` as a normal, high-priority stylesheet link
+(always required), and `unused-styles.css` added with lower priority — for example with `rel="preload"`
+and `as="style"`, turned into a stylesheet once loaded via `onLoad` — or omitted entirely if you don't
+read raw tokens. If your own CSS does read raw tokens, load `unused-styles.css` with the same priority as
+`theme.css`.
 
 ### Option A — Manual CSS and font links
 
@@ -266,7 +277,14 @@ If `loadFonts` or `loadStyles` are `false`, you must manually include the corres
         <>
           <link rel="preload" as="font" type="font/woff2" href="https://ds-assets.cupra.com/fonts/[theme]/[font-file]" crossOrigin="anonymous" />
           <link rel="stylesheet" href="https://ds-assets.cupra.com/[version]/styles/[theme]/theme.css" />
-          <ThemeProvider theme="[theme]" loadFonts={false} loadStyles={false}>
+          {/* Lower priority; only needed if your own CSS reads raw --ds- tokens directly */}
+          <link
+            rel="preload"
+            as="style"
+            href="https://ds-assets.cupra.com/[version]/styles/[theme]/unused-styles.css"
+            onLoad={(e) => { e.currentTarget.rel = "stylesheet"; }}
+          />
+          <ThemeProvider theme="[theme]" load-fonts={false} load-styles={false} load-unused-styles={false}>
             <Button variant="destructive" icon-name="filters-background">
               Click me
             </Button>
@@ -285,7 +303,7 @@ If `loadFonts` or `loadStyles` are `false`, you must manually include the corres
 
     export function App() {
       return (
-        <ThemeProvider theme="cupra-diagonal" loadFonts={true} loadStyles={true}>
+        <ThemeProvider theme="cupra-diagonal" load-fonts={true} load-styles={true} load-unused-styles={true}>
           <Button variant="primary">Button</Button>
         </ThemeProvider>
       );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cupra/ui-react",
-  "version": "2.0.0-canary.242",
+  "version": "2.0.0-canary.244",
   "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.227",
+    "@cupra/ui-kit": "2.0.0-canary.229",
     "react": ">= 18.3.1 < 20",
     "react-dom": ">= 18.3.1 < 20",
     "typescript": ">=5.0.0"
@@ -74,7 +74,7 @@
     "storybook": "^10.6.0",
     "typescript": "^5.9.3",
     "vite": "^8.2.2",
-    "@cupra/ui-kit": "2.0.0-canary.227"
+    "@cupra/ui-kit": "2.0.0-canary.229"
   },
   "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",