@cupra/ui-kit 0.2.0-canary.0 → 1.0.0-canary.10

package/README.md

@@ -1,861 +1,180 @@
 # UI Kit (Web Components)
 
 ## Overview
-Core Web Components for the DS-UI design system, built with Lit and TypeScript.
+Core Web Components for the DS-UI design system, implemented with Lit and TypeScript.  
+This package is framework-agnostic and can be consumed from any modern frontend stack, either via npm or directly from the CDN.
 
 ## Audience
-Developers who want to use DS-UI as native Web Components in any web framework or plain HTML/JS.
+Use `@cupra/ui-kit` if you want the **smallest, most portable** way to adopt DS-UI across frameworks:
 
-## Installation
-- npm: `npm install @cupra/ui-kit`
-- pnpm: `pnpm add @cupra/ui-kit`
-- yarn: `yarn add @cupra/ui-kit`
-
-Access to the @cupra registry is required (see Requirements).
-
-## Usage
-1) Load the theme CSS for your chosen theme (e.g., cupra) or use the theme provider.
-2) Wrap components with `<ds-theme-provider theme="cupra">`.
-
-Example (snippet):
-```html
-<link rel="stylesheet" href="https://ds-assets.cupra.com/[version]/styles/cupra/theme.css">
-<ds-theme-provider theme="cupra">
-  <ds-button variant="destructive">Hello</ds-button>
-</ds-theme-provider>
-```
-
-## Requirements
-- Node.js per .nvmrc
-- pnpm 9.4.0 or compatible
-- Access to GitHub Packages for @cupra (configure .npmrc or .yarnrc.yml with your token)
-
-## Versioning
-This package follows semantic versioning. See repository releases for changes.
+- Works with any environment (React, Vue, Svelte, Angular, plain JS, HTML).
+- Provides encapsulation through Shadow DOM.
+- Gives full control over when and how assets (CSS, fonts, icons) load.
 
-## License
-License: SEAT S.A. Library EULA 1.0
-See LICENSE.md in this package for the full text. Third-party license attributions (if any) may be provided in THIRD_PARTY_LICENSES.md.
-
-## Support
-Please open issues in the repository issue tracker.
+If your application is **React-only**, and you prefer idiomatic React props & JSX, use `@cupra/ui-react` instead.
 
 ## Installation
 
-<details><summary>View installation instructions</summary>
-
-### Using npm
-
-Run the following command to install the library:
-
-```bash
-npm install @cupra/ui-kit
-```
-
-### Using pnpm
-
-If you're using **pnpm**, install the library with:
-
-```bash
-pnpm add @cupra/ui-kit
-```
+### Install the package
+- npm: `npm install @cupra/ui-kit`
+- pnpm: `pnpm add @cupra/ui-kit`
+- yarn: `yarn add @cupra/ui-kit`
 
-### Using yarn
+### Registry configuration (only if needed)
 
-To install the library with **yarn**, use:
+**.npmrc**
 
-```bash
-yarn add @cupra/ui-kit
+```ini
+@cupra:registry=https://registry.npmjs.org
 ```
 
-### .NPMRC
->[!Important]
->To be able to install the **ui-kit** library in your project you need access to the **@cupra**. To solve this, you need to have a **.npmrc** file if you are using **npm** or **pnpm** with a code similar to this:
-```code
-@cupra:registry=https://npm.pkg.github.com
-//npm.pkg.github.com/:_authToken=<your_github_token>
-always-auth=true
-```
+**.yarnrc.yml**
 
-### .YARNRC.YML
->[!Important]
->To be able to install the **ui-kit** library in your project you need access to the **@cupra**. To solve this, you need to have a **.yarnrc.yml** file if you are using **yarn** with a code similar to this:
-```code
+```yaml
 npmScopes:
-  seatcode:
-    npmRegistryServer: "https://npm.pkg.github.com"
-    npmAuthToken: "your_github_token"
+cupra:
+npmRegistryServer: "https://registry.npmjs.org"
 ```
-</details>
-
-## Component usage
 
-<details><summary>View usage instructions</summary>
+---
 
-### Web Components
+## Documentation & Live Playground
 
-To use the components directly on an HTML page, ensure that the bundle and theme are loaded correctly as shown below. Wrap your components within the `<ds-theme-provider>` component to provide the necessary theme context.
+You can explore all `ui-kit` Web Components, their APIs, theming options and live examples in the online documentation and playground:
 
-#### Loading the Bundle
+[https://diagonal.cupra.com/ui-kit/index.html](https://diagonal.cupra.com/ui-kit/index.html)
 
-The bundle for the components can be loaded directly from the CDN by using the following script:
+---
 
-```html
-<script src='https://ds-assets.cupra.com/[version]/dist/index.iife.js'></script>
-```
+## Versioning and Release Channels
 
-- **[version]**: Specify the exact version of the library, such as `1.0`, `1.1.1`, or `2.0`. Wildcards like `1.x` or `1.*` are not supported.
+This package is published to npm under **two channels**: `latest` (stable) and `canary` (early access).
 
-Example:
+### Stable Releases (`latest`)
+These versions represent production-ready builds:
 
-```html
-<script src='https://ds-assets.cupra.com/1.0.3/dist/index.iife.js'></script>
-```
+- Follow Semantic Versioning
+- Include validated and approved changes
+- Recommended for all production usage
 
-#### Loading the CSS
+Install latest stable:
 
-You can load the CSS directly with a `<link>`, which is the most performant option. Specify the theme and version in the URL:
-
-```html
-<link rel='stylesheet' href='https://ds-assets.cupra.com/[version]/styles/[theme]/theme.css'>
+```bash
+npm install @cupra/ui-kit
 ```
 
-- **[theme]**: Specify the theme name (e.g., `cupra`).
-- **[version]**: Use the fixed version, such as `1.0`, `1.1.1`, etc.
-
-> **Note**: Even when loading the CSS with a `<link>` for better performance, it is still necessary to use the `<ds-theme-provider>` component. This component provides a theme context with the `theme` attribute (e.g., `theme="cupra"`), which is required for certain components, such as `<ds-icon>`, to function correctly.
-
-Example:
+Specific stable version:
 
-```html
-  <ds-theme-provider theme="cupra">
-    <ds-button variant="destructive" icon-name="filters-background">Hello</ds-button>
-    <ds-icon icon-name="filters-background"></ds-icon>
-    <ds-modal open="false">
-    <p slot="content">Hello</p>
-    </ds-modal>
-    <ds-tag icon-name="magnifying-glass">Hello</ds-tag>
-    <ds-input type="date" label="Hello"></ds-input>
-  </ds-theme-provider>
+```bash
+npm install @cupra/ui-kit@0.1.3
 ```
-</details>
-
-## Web Components
-
-<details><summary>View web components documentation</summary>
-
-Here is the documentation for the [Web Components](https://github.com/seatcode/ds-ui/blob/main/packages/ui-kit/web-components.md).
-
->[!NOTE]
->For more information you can access our [Storybook](https://65c4ab0114027d1f28fa89a1-uzhfdyxnjn.chromatic.com/), where you will find detailed documentation and interactive examples for each component, making it easier to use and understand them. Feel free to ask us for [Storybook](https://65c4ab0114027d1f28fa89a1-uzhfdyxnjn.chromatic.com/) **access permissions** or consult us any question about a component implementation.
-</details>
-
-## Fonts
-
-<details><summary>View font information</summary>
-
-The font family is 'cupra-screen'. The following are the CSS tokens that should be used in your project:
-
-- `--ds-cp-type-display-[weight]`
-- `--ds-cp-type-headline-[weight]`
-- `--ds-cp-type-title1-[weight]`
-- `--ds-cp-type-title2-[weight]`
-- `--ds-cp-type-title3-[weight]`
-- `--ds-cp-type-title4-[weight]`
-- `--ds-cp-type-title5-[weight]`
-- `--ds-cp-type-title6-[weight]`
-- `--ds-cp-type-quote-[weight]`
-- `--ds-cp-type-lead-[weight]`
-- `--ds-cp-type-body-[weight]`
-- `--ds-cp-type-bodytight-[weight]`
-- `--ds-cp-type-small-[weight]`
-- `--ds-cp-type-smalltight-[weight]`
-- `--ds-cp-type-tiny-[weight]`
-- `--ds-cp-type-micro-[weight]`
-
-Where `[weight]` can be `book`, `regular`, or `medium`. The properties (size, line height, etc.) are automatically adapted based on the viewport.
-</details>
-
-## Scroll
-
-<details><summary>View scroll customization</summary>
-
-### `.ds-scroll` Class
-This class is used to customize the appearance of scrollbars in your web application. Applying `.ds-scroll` will give the scrollbar a modern and consistent look that aligns with the DS-UI.
-
-### `.ds-scroll-global` Class
-This class extends the customization of scrollbars to **all** elements within the container. By using `.ds-scroll-global`, you ensure that every scrollable area within a specified section shares the same scrollbar styling for a unified user experience.
-
----
-
-### Using Dark Mode with `.ds-mode-dark`
-> **Note:** This section only applies to themes that support dark mode.
-
-To activate dark mode for scrollbars, add the `.ds-mode-dark` class in combination with either `.ds-scroll` or `.ds-scroll-global`. This switches the scrollbar styling to a darker palette, suitable for dark-themed interfaces.
 
 ---
 
-### Using Size with `.ds-scroll--size-[size]`
-> **Note:** This section only applies to themes that support size.
+### Canary Releases (`canary`)
+Canary versions include the **most recent changes merged into `main`**.
 
-E.g. To activate 'S' forced size you must use `.ds-scroll--size-s` class in combination with either `.ds-scroll` or `.ds-scroll-global`.
+Choose a canary version if you:
 
----
+- Want early access to upcoming features
+- Are testing the next stable release
+- Accept small instability or rapid iteration
 
-### Usage Example
-```html
-<!-- For light mode -->
-<div class="ds-scroll">
-  <!-- Content that requires scrolling -->
-</div>
-
-<!-- For dark mode (only if the theme supports it) -->
-<div class="ds-scroll ds-mode-dark">
-  <!-- Content that requires scrolling -->
-</div>
-
-<!-- For size medium (only if the theme supports it) -->
-<div class="ds-scroll ds-scroll--size-m">
-  <!-- Content that requires scrolling -->
-</div>
-
-<!-- Applying global scroll -->
-<div class="ds-scroll-global">
-  <!-- Content (including children) that requires scrolling -->
-</div>
-
-<!-- Applying global scroll in dark mode (only if the theme supports it) -->
-<body class="ds-scroll-global ds-mode-dark">
-  <!-- Content (including children) that requires scrolling -->
-</body>
-
-<!-- Applying global scroll and size medium (only if the theme supports it) -->
-<div class="ds-scroll-global ds-scroll--size-m">
-  <!-- Content that requires scrolling -->
-</div>
+Install latest canary:
 
+```bash
+npm install @cupra/ui-kit@canary
 ```
-</details>
-
-## Gradients
-
-<details><summary>View gradient classes</summary>
 
-### `.ds-gradient-default` Class
-This class applies a subtle white-to-transparent gradient, ideal for sections requiring a light-themed overlay. It transitions from transparent at the top to solid white at the bottom, using the `--ds-color-white` variable.
+Specific canary version:
 
-### `.ds-gradient-inverted` Class
-This class creates a dark gradient transitioning from transparent to solid black at the bottom. It is suitable for dark-themed overlays, leveraging the `--ds-color-black` variable.
-
-### `.ds-gradient-soft` Class
-The `.ds-gradient-soft` class provides a soft grey gradient that fades from transparent to `--ds-color-grey-15`. It is perfect for neutral or subtle styling.
-
-### `.ds-gradient-grey` Class
-This class offers a slightly more pronounced grey gradient, transitioning from transparent to `--ds-color-grey-50`. Use it for elements requiring a moderate grey tone.
-
-### `.ds-gradient-muffled` Class
-The `.ds-gradient-muffled` class applies a gradient that fades from transparent to `--ds-cp-color-back-muffled-default`. It is ideal for muted or desaturated color themes.
-
-### `.ds-gradient-dark-inverted` Class
-This gradient transitions from transparent to a soft grey (`--ds-color-grey-15`), offering a light-grey inverted effect for darker themes.
-
-### Usage Example
-```html
-<!-- Default gradient -->
-<div class="ds-gradient-default">
-  <!-- Content -->
-</div>
-
-<!-- Inverted gradient -->
-<div class="ds-gradient-inverted">
-  <!-- Content -->
-</div>
-
-<!-- Soft grey gradient -->
-<div class="ds-gradient-soft">
-  <!-- Content -->
-</div>
-
-<!-- Pronounced grey gradient -->
-<div class="ds-gradient-grey">
-  <!-- Content -->
-</div>
-
-<!-- Muffled gradient -->
-<div class="ds-gradient-muffled">
-  <!-- Content -->
-</div>
-
-<!-- Dark inverted gradient -->
-<div class="ds-gradient-dark-inverted">
-  <!-- Content -->
-</div>
+```bash
+npm install @cupra/ui-kit@0.1.4-canary.2
 ```
-</details>
-
-## Slider component
-
-<details><summary>View slider component documentation</summary>
-
-This component provides a customizable slider for selecting values within a specified range. It supports single-value and range sliders with extensive formatting options.
-
-### Attributes
-
-#### Basic Attributes
-| Attribute               | Type               | Default   | Description                                   |
-|-------------------------|--------------------|-----------|-----------------------------------------------|
-| `min`                | `number`        | `0`     | Minimum value for the slider.                |
-| `max`                | `number`        | `100`   | Maximum value for the slider.                |
-| `step`               | `number`        | `1`     | Step size for the slider.                    |
-| `initial-value-min`     | `number`        | `0`     | Initial value for the first thumb.           |
-| `initial-value-max`     | `number`        |           | Initial value for the second thumb (optional, for range sliders). |
-
-#### Internationalization (Intl) Attributes
 
-These attributes are directly tied to the [Intl](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl) API and are used to format numbers according to locale and style.
+### Recommended usage
+- **Production:** always use **stable (`latest`)**
+- **Testing upcoming features:** use the **canary channel**
+- **Deterministic builds:** pin exact versions (stable or canary)
 
-| Attribute                 | Type               | Default     | Description                                      |
-|---------------------------|--------------------|-------------|--------------------------------------------------|
-| `locale`               | `string`        | `undefined` | Locale for formatting values (e.g., `en-US`, `es-ES`). |
-| `locale-matcher`       | `"lookup"` \| `"best fit"` | `"lookup"`  | Algorithm to match locales.                     |
-| `unit-style`           | `"decimal"` \| `"currency"` \| `"percent"` \| `"unit"` |             | Style for formatting the unit (e.g., percentages, currency). |
-| `currency`             | `string`        |             | Currency for formatting values (e.g., `USD`, `EUR`).   |
-| `unit`                | `string`        |             | Unit of measurement for formatting values (e.g., `kilometer`). |
-| `minimum-integer-digits` | `number`        | `1`         | Minimum number of integer digits to display.    |
-| `minimum-fraction-digits` | `number`        | `0`         | Minimum number of fractional digits to display. |
-| `maximum-fraction-digits` | `number`        | `3`         | Maximum number of fractional digits to display. |
-
-#### Component-Specific ("Manual") Attributes
-
-These attributes extend the functionality of the standard `Intl` API by introducing additional formatting or display options.
-
-| Attribute                 | Type               | Default         | Description                                      |
-|---------------------------|--------------------|-----------------|--------------------------------------------------|
-| `unit-symbol`          | `string`        |                 | Custom symbol to display alongside values (e.g., "km", "°C"). |
-| `unit-symbol-position` | `"left"` \| `"right"` | `"right"` | Position of the custom unit symbol.             |
-| `thousand-separator`   | `string`        |                 | Character used to separate thousands. Overrides Intl's formatting. |
-| `fraction-separator`   | `string`        |                 | Character used to separate fractional parts. Overrides Intl's formatting. |
-
-#### Styling Attributes
-| Attribute  | Type         | Default   | Description                                  |
-|------------|--------------|-----------|----------------------------------------------|
-| `mode`   | `"dark"` \| `"light"` | `"light"` | Visual mode for the slider.                  |
-
----
-
-### How It Works
-
-Internally, `<ds-slider>` uses the [Intl](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl) API to handle number formatting via a helper named `formatNumber`. Component attributes like `locale`, `currency`, `unit`, and `unit-style` are passed directly to `Intl.NumberFormat`.
-
-- Intl options drive the core formatting (grouping, decimals, symbol availability and position):
-  - `unit-style="currency"` with `currency` uses the locale’s currency symbol and spacing.
-  - `unit-style="percent"` uses the locale’s percent sign and placement.
-  - `unit-style="unit"` with `unit` uses the locale’s unit label/symbol and placement.
-  - `minimum-/maximum-fraction-digits` control decimal precision; `minimum-integer-digits` controls integer padding.
-- `formatNumber` also returns `unitSymbol` and `unitSymbolPosition` (left/right) when the chosen style implies a symbol (currency/percent/unit).
-- Component props `unit-symbol` and `unit-symbol-position` override the Intl‑provided symbol and position. If you don’t set them, the Intl-derived ones will be used when available.
-- `thousand-separator` and `fraction-separator` override the group and decimal separators in the final output string (they don’t affect rounding).
-
-#### Formatting guide (quick reference)
-- Currency (managed by Intl): set `unit-style="currency"` and a `currency` code; do not set `unit-symbol`.
-- Percent (managed by Intl): set `unit-style="percent"`; no custom symbol needed.
-- Unit (managed by Intl): set `unit-style="unit"` and `unit` (e.g., `kilometer`); optionally override with `unit-symbol` like `"km"` and your preferred `unit-symbol-position`.
-- Custom symbol (manual): leave `unit-style` unset or `decimal`, set `unit-symbol` (e.g., `"°C"`), and choose `unit-symbol-position`.
-
----
-
-### Slots
-This component does not have slots.
+```bash
+npm install @cupra/ui-kit@0.1.4-canary.2
+```
 
 ---
 
-### Events
-
-| Event    | Description                           | Detail          |
-|----------|---------------------------------------|-----------------|
-| `change` | Fired when the slider value changes. | `{ targetId, value }` |
+## Usage
+How to consume the package, either through the CDN or your application build.
 
 ---
 
-### Examples
-
-#### Single Value Slider
+### Option A — CDN in plain HTML
+1) Load the DS-UI Web Components bundle:
 
 ```html
-<ds-slider
-  min="0"
-  max="100"
-  step="1"
-  initial-value-min="50"
-></ds-slider>
+<script src="https://ds-assets.cupra.com/[version]/dist/index.iife.js"></script>
 ```
 
-#### Range Slider
+2) Wrap your UI with the theme provider.  
 
-```html
-<ds-slider
-  min="0"
-  max="1000"
-  step="50"
-  initial-value-min="100"
-  initial-value-max="500"
-></ds-slider>
-```
-
-#### Currency Slider (Intl)
-
-```html
-<ds-slider
-  min="0"
-  max="1000"
-  step="100"
-  initial-value-min="200"
-  locale="en-US"
-  unit-style="currency"
-  currency="USD"
-></ds-slider>
-```
-
-#### Custom Symbol Slider
-
-```html
-<ds-slider
-  min="0"
-  max="100"
-  step="5"
-  initial-value-min="20"
-  unit-symbol="°C"
-  unit-symbol-position="right"
-></ds-slider>
-```
-
-#### Percent Slider (Intl)
-
-```html
-<ds-slider
-  min="0"
-  max="1"
-  step="0.1"
-  initial-value-min="0.25"
-  locale="en-US"
-  unit-style="percent"
-></ds-slider>
-```
-
-#### Unit Slider (Intl with optional override)
+`load-fonts` and `load-styles` control whether the provider loads assets automatically.
+Replace `[theme]` with your theme name (e.g. `cupra-diagonal`).
 
 ```html
-<ds-slider
-  min="0"
-  max="2000"
-  step="100"
-  initial-value-min="1200"
-  locale="en-GB"
-  unit-style="unit"
-  unit="kilometer"
->
-</ds-slider>
+<ds-theme-provider theme="[theme]" load-fonts="true" load-styles="true">
+    <ds-button variant="destructive" icon-name="filters-background">Hello</ds-button>
+    <ds-icon icon-name="filters-background"></ds-icon>
+</ds-theme-provider>
 ```
 
-To override the Intl-derived unit label with a shorter custom symbol:
+**Performance note:**  
+For optimal behaviour, manually preload the fonts and load the theme CSS via a stylesheet link.
 
 ```html
-<ds-slider
-  min="0"
-  max="2000"
-  step="100"
-  initial-value-min="1200"
-  locale="en-GB"
-  unit-style="unit"
-  unit="kilometer"
-  unit-symbol="km"
-  unit-symbol-position="right"
-></ds-slider>
-```
+<!-- Preload fonts (one line per required font file) -->
+<link rel="preload" as="font" type="font/woff2" href="https://ds-assets.cupra.com/fonts/[theme]/[font-file]" crossorigin />
 
-#### Combined Intl and Manual Formatting
+<!-- Load the theme stylesheet normally -->
+<link rel="stylesheet" href="https://ds-assets.cupra.com/[version]/styles/[theme]/theme.css" />
 
-```html
-<ds-slider
-  min="0"
-  max="10000"
-  step="500"
-  initial-value-min="2000"
-  locale="es-ES"
-  currency="EUR"
-  unit-symbol="approx."
-  unit-symbol-position="left"
-  thousand-separator="."
-  fraction-separator=","
-></ds-slider>
+<ds-theme-provider theme="[theme]" load-fonts="false" load-styles="false">
+    <!-- components -->
+</ds-theme-provider>
 ```
 
 ---
 
-### When to Use
-
-- **Single Value Sliders**: Use for selecting a single value within a range, e.g., volume control or brightness.
-- **Range Sliders**: Use for selecting a range of values, e.g., price filters.
-- **Intl Formatting**: Use `locale`, `currency`, and `unit-style` to format values for international users.
-- **Custom Symbols**: Combine `unit-symbol` and Intl formatting for tailored user interfaces.
-
----
+### Option B — Installed via npm in an application bundle
+Install the package:
 
-### Notes
-- Ensure `min`, `max`, and `step` values are consistent to avoid unexpected behavior.
-- `unit-symbol` can complement `Intl` settings to provide additional context (e.g., "approx.").
-- Custom separators (e.g., `thousand-separator`) override Intl formatting behavior.
-</details>
-
-## Z-Index Variables
-
-<details><summary>View z-index variables documentation</summary>
-
-These CSS variables help you manage the stacking order of the components.
-
-### Introduction
-
-These predefined z-index variables provide a predictable and consistent layering strategy
-for elements such as headers, footers, modals, tooltips, and alerts. By using these variables,
-you can avoid arbitrary or conflicting z-index values across different parts of your application.
-
-### Provided Variables
-
-| Variable                       | Default | Description                                                                                          |
-|--------------------------------|---------|------------------------------------------------------------------------------------------------------|
-| `--ds-z-index-negative`        | -1      | Used for layers placed intentionally behind the base layer (e.g., background images).                |
-| `--ds-z-index-base`            | 0       | The default stacking context; typically used by elements without a specific z-index.                 |
-| `--ds-z-index-default`         | 1       | Slightly above base elements, often used for general interactive UI components.                      |
-| `--ds-z-index-app-footer`      | 1000    | Used for a main application footer if it needs to overlap default content.                           |
-| `--ds-z-index-app-header`      | 1100    | Used for a main application header if it needs to overlap default content.                           |
-| `--ds-z-index-overlay`         | 1200    | For overlays (e.g., dimmed backgrounds) that should appear above standard content.                   |
-| `--ds-z-index-tooltip`         | 1300    | Ensures tooltips appear above overlays but below modals.                                             |
-| `--ds-z-index-modal`           | 1400    | Used for modal dialogs, above tooltips but potentially below certain dropdowns.                      |
-| `--ds-z-index-context-menu`    | 1500    | For context menus or dropdowns that should appear above most overlays and modals.                    |
-| `--ds-z-index-popover`         | 1600    | For popovers that need to appear above context menus or modals.                                      |
-| `--ds-z-index-toast`           | 1700    | For toast or notification messages, typically over main interactions but under loaders.              |
-| `--ds-z-index-loader`          | 1800    | For loading indicators or progress bars that must overlay standard UI elements.                      |
-| `--ds-z-index-alert-info`      | 1900    | For informational alerts that need to appear above loaders.                                          |
-| `--ds-z-index-alert-success`   | 2000    | For success alerts, higher than info alerts.                                                         |
-| `--ds-z-index-alert-warning`   | 2100    | For warning alerts, stacked above success alerts.                                                    |
-| `--ds-z-index-alert-error`     | 2200    | For error alerts, stacked above warning alerts.                                                      |
-| `--ds-z-index-top`             | 9999    | A very high stacking level for elements that must appear above all other layers.                     |
-
-### Usage
-
-To apply one of these z-index values, reference the variable in your CSS.
-For example, a modal:
-
-```css
-.my-modal {
-  position: fixed;
-  top: 50%;
-  left: 50%;
-  transform: translate(-50%, -50%);
-  z-index: var(--ds-z-index-modal);
-}
+```bash
+npm install @cupra/ui-kit
 ```
 
-Or a context menu:
+Import only the components you will use so their custom elements are registered:
 
-```css
-.my-context-menu {
-  position: absolute;
-  z-index: var(--ds-z-index-context-menu);
-  /* Additional styling here */
-}
+```js
+import '@cupra/ui-kit/ds-theme-provider';
+import '@cupra/ui-kit/ds-button';
+import '@cupra/ui-kit/ds-icon';
 ```
 
-By consistently using these shared variables, you can maintain uniform layering logic
-across your application.
+Then include the theme provider:
 
-### When to Use
-
-- **Overlays and Dialogs**: Assign `--ds-z-index-overlay` for modal backgrounds or overlays,
-  and `--ds-z-index-modal` for dialogs that appear on top of them.
-- **Context Menus**: Utilize `--ds-z-index-context-menu` for right-click or dropdown menus,
-  ensuring they appear above standard overlays and modals.
-- **Tooltips and Popovers**: Use `--ds-z-index-tooltip` for tooltips and `--ds-z-index-popover`
-  for popovers, maintaining a proper stacking order.
-- **Notifications**: Use `--ds-z-index-toast` for toast messages, ensuring they're visible
-  but do not overshadow modals or popovers.
-- **Critical Alerts**: For error or critical alerts, consider the highest relevant index
-  (`--ds-z-index-alert-error`) to ensure they appear above other elements.
-- **Custom Needs**: If you need a layer above or below existing tiers, consider defining
-  a new variable. However, we recommend using these provided values for clarity and consistency.
-</details>
-
-## Background Classes (.ds-bg)
-
-<details><summary>View background classes</summary>
-
-### Introduction
-
-These CSS classes are designed to apply responsive backgrounds to HTML elements. The background image is loaded from a CDN using the base URL defined by the `$cdnBaseUrl` variable, and it adapts automatically to different screen sizes through media queries. The system uses a base class (`.ds-bg`) along with several variant classes to determine which background image to display.
-
-### Available Classes
-
-| **Class**            | **Description**                                                                                                                                                                                   |
-|----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| **ds-bg**            | The base background class. It applies:<br>- Vertical background repeat (`repeat-y`).<br>- Base background color using `--dg-color-bg-base`.<br>- Background size set to 100% width (auto height). |
-| **ds-bg--leon**      | Variant that applies the "leon" background image when used together with `ds-bg`.                                                                                                                 |
-| **ds-bg--terramar**  | Variant that applies the "terramar" background image when used together with `ds-bg`.                                                                                                             |
-| **ds-bg--ateca**     | Variant that applies the "ateca" background image when used together with `ds-bg`.                                                                                                                |
-| **ds-bg--born**      | Variant that applies the "born" background image when used together with `ds-bg`.                                                                                                                 |
-| **ds-bg--tavascan**  | Variant that applies the "tavascan" background image when used together with `ds-bg`.                                                                                                             |
-| **ds-bg--formentor** | Variant that applies the "formentor" background image when used together with `ds-bg`.                                                                                                            |
-
-### Responsive Behavior and Breakpoints
-
-Background images and their positions change automatically based on the screen width. Below is an overview of the breakpoints and how the background is adjusted:
-
-| **Breakpoint** | **Media Query**       | **Image Suffix** | **Background Position** |
-|----------------|-----------------------|-----------|----------------|
-| **XS**       | min-width: 0px         | `-xs.svg` | `left top`     |
-| **S**        | min-width: 480px       | `-s.svg`  | `left top`     |
-| **M**        | min-width: 768px       | `-m.svg`  | `left -338px`  |
-| **L**        | min-width: 1024px      | `-l.svg`  | `left -338px`  |
-| **XL**       | min-width: 1440px      | `-xl.svg` | `left -595px`  |
-| **XXL**      | min-width: 1920px      | `-xxl.svg` | `left -595px`  |
-
-### Usage Examples
-
-**Default Background:**
+Replace `[theme]` with your theme name (e.g. `cupra-diagonal`).
 
 ```html
-<div class="ds-bg"></div>
-```
-
-**Using a Variant (e.g., "ds-bg--leon"):**
-
-```html
-<div class="ds-bg ds-bg--leon"></div>
+<ds-theme-provider theme="[theme]" load-fonts="true" load-styles="true">
+    <ds-button variant="primary">Button</ds-button>
+</ds-theme-provider>
 ```
 
-Simply add the base class `ds-bg` to your element. To display a specific background image, combine it with one of the variant classes such as `ds-bg--leon`, `ds-bg--terramar`, `ds-bg--ateca`, `ds-bg--born`, or `ds-bg--tavascan`.
-</details>
-
-## ds-currency
-
-<details><summary>View currency component documentation</summary>
-
-`ds-currency` is a new component designed to display a currency value formatted according to your settings. It handles symbol placement, decimal and thousand separators, and optional period/note.
-
-### 🎯 Attributes
-
-- **currency-code**  
-  ISO 4217 currency code (e.g. `EUR`, `USD`).
-
-- **locale**  
-  BCP 47 locale tag (ISO 639-1 language + ISO 3166-1 alpha-2 region), e.g. `es-ES`, `en-US`.
-
-- **amount-number**  
-  Numeric value to format as currency.
-
-- **amount-text**  
-  Literal text to display instead of the formatted value.
-
-- **minimum-fraction-digits**  
-  Minimum decimals (default `0`).
-
-- **maximum-fraction-digits**  
-  Maximum decimals (default `20`).
-
-- **thousand-separator**  
-  Override default thousands separator.
-
-- **fraction-separator**  
-  Override default decimal separator.
-
-- **period**  
-  Field to display after the amount (e.g. `month`, `year`, etc.). Acceptable values: `era`, `year`, `month`, `quarter`, `weekOfYear`, `weekday`, `dayPeriod`, `day`, `hour`, `minute`, `second`. These correspond to the standard ECMA-402 `Intl.DisplayNames` `dateTimeField` values (Unicode CLDR UTS #35) and are transformed according to the locale.
-
-- **note**  
-  Used to render a superscript number (e.g. "¹", "²") that links to footnotes or explanatory text in the UI.
-
 ---
 
-### 💻 Example
-
-    <ds-currency
-      locale="es-ES"
-      currency-code="EUR"
-      amount-number="1234.56"
-      period="month"
-      note="1">
-    </ds-currency>
-
-_Renders:_ **1.234,56€¹/month**
-
----
-
-### 🌐 ISO & Standards + Functionality
-
-- **currency-code** follows **ISO 4217** for currency identifiers
-- **locale** uses **BCP 47** (ISO 639-1 + ISO 3166-1 alpha-2) to drive `Intl.NumberFormat` and `Intl.DisplayNames`
-- **period** uses **ECMA-402 Intl.DisplayNames** `dateTimeField` values (Unicode CLDR UTS #35) `era`, `year`, `month`… and localizes accordingly
-- Formats numbers with proper decimal and thousand separators
-- Positions currency symbol automatically (left/right) based on locale
-- Supports custom separators, fraction digit limits, plus optional period (`/month`, `/year`) and note text
-</details>
-
-## Toast System
-
-<details><summary>Toast</summary>
-
-The toast system provides a way to display non-intrusive notifications to users. It consists of two components:
-
-- `<ds-toast>`: The container that manages and displays toast messages
-- `<ds-toast-message>`: Individual toast message components
-
-### Basic Usage
-
-1. Add the toast container to your application:
-
-```html
-<ds-toast position="top-right"></ds-toast>
-```
-
-2. Trigger a toast from anywhere in your JavaScript:
-
-```javascript
-window.dispatchEvent(
-  new CustomEvent('toast:add', {
-    detail: {
-      title: 'Success',
-      text: 'Operation completed successfully',
-      status: 'success',
-      duration: 5000 // Optional: time in milliseconds before auto-dismissing (default: 10000ms)
-    }
-  })
-);
-```
-
-### Toast Statuses
-
-There are five possible statuses for a toast message:
-
-- `success`: Used for successful operations
-- `error`: Used for error messages
-- `warning`: Used for warning messages
-- `info`: Used for informational messages
-- `default`: Used when no specific status is needed
-
-### Custom Toast Templates
-
-You can create custom toast templates using the `<ds-toast-message>` component:
-
-```html
-<ds-toast-message
-  data-id="custom-toast-template"
-  data-template="true"
-  status="default"
-  title="Custom Toast"
-  text="This is a custom toast message"
->
-  <ds-link-button>Action Link</ds-link-button>
-</ds-toast-message>
-```
-
-Then trigger it using:
-
-```javascript
-window.dispatchEvent(
-  new CustomEvent('toast:add', {
-    detail: {
-      referenceId: 'custom-toast-template',
-      duration: 10000 // Optional: custom duration
-    }
-  })
-);
-```
-
-### Toast Positioning
-
-The `<ds-toast>` component supports four positions:
-
-- `top-right` (default)
-- `top-left`
-- `bottom-right`
-- `bottom-left`
-
-```html
-<ds-toast position="bottom-left"></ds-toast>
-```
-
-### Toast Options
-
-The `'toast:add'` event `detail` accepts the following options:
-
-| Option      | Type | Description                                                               |
-|-------------|------|---------------------------------------------------------------------------|
-| id          | string | Optional custom identifier for the toast. If not provided, the system automatically generates one. Useful when you need to reference or remove a specific toast programmatically.|
-| title       | string | The title of the toast                                                    |
-| text        | string | The message content of the toast                                          |
-| status      | string | One of: 'success', 'error', 'warning', 'info', 'default'                  |
-| duration    | number | Time in milliseconds before auto-dismissing (default: 10000ms)            |
-| referenceId | string | ID of a custom toast template to use (will ignore title, text and status) |
-
-### React Usage
-
-If you're using React, you can use the provided React components:
-
-```jsx
-import { Toast, ToastMessage } from '@cupra/ui-react';
-
-// In your component:
-return (
-  <>
-    <Toast position="top-right" />
-
-    {/* Custom template (optional) */}
-    <ToastMessage
-      data-id="custom-template"
-      data-template={true}
-      title="Custom Toast"
-      text="This is a custom toast message"
-    >
-      <button>Action Button</button>
-    </ToastMessage>
-  </>
-);
-
-// Trigger a toast from anywhere:
-window.dispatchEvent(
-  new CustomEvent('toast:add', {
-    detail: {
-      title: 'Hello',
-      text: 'This is a toast message',
-      status: 'info'
-    }
-  })
-);
-```
-
-### Removing a Toast
-
-To manually close or remove a toast, dispatch the `'toast:remove'` event.  
-It accepts either the `id` of a specific toast or the `referenceId` of a custom template.
-
-```javascript
-// Remove a specific toast by ID
-window.dispatchEvent(
-  new CustomEvent('toast:remove', { detail: { id: 'my-toast-id' } })
-);
-
-// Or remove a toast created from a template
-window.dispatchEvent(
-  new CustomEvent('toast:remove', { detail: { referenceId: 'custom-toast-template' } })
-);
-```
-
-> **Note:**  
-> This is **not the recommended approach**.  
-> Toasts are designed to close automatically after their duration expires, or manually by user interaction (for example, clicking a close button).  
-> The `'toast:remove'` event should only be used in specific cases when programmatic control is required.
->
-> When removing by `id`, each toast has a unique identifier (automatically generated unless manually provided).  
-> When removing by `referenceId`, it refers to a template identifier.  
-> If multiple toasts have been created using the same `referenceId`, only one instance —the oldest— will be removed.
+## License
+License: SEAT S.A. Library EULA 1.0  
+See `LICENSE.md` for the full license text.  
+Third-party license attributions may be listed in `THIRD_PARTY_LICENSES.md`.
 
-</details>
+## Support
+For any questions or assistance, contact: **ds.support@seat.es**