npm - @cupra/ui-kit - Versions diffs - 0.2.0-canary.0 → 1.0.0-canary.2 - Mend

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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (19) hide show

package/README.md CHANGED Viewed

@@ -1,861 +1,172 @@
 # 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
+---
-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.
+## Documentation & Live Playground
-#### Loading the Bundle
+You can explore all `ui-kit` Web Components, their APIs, theming options and live examples in the online documentation and playground:
-The bundle for the components can be loaded directly from the CDN by using the following script:
+[https://diagonal.cupra.com/ui-kit/index.html](https://diagonal.cupra.com/ui-kit/index.html)
-```html
-<script src='https://ds-assets.cupra.com/[version]/dist/index.iife.js'></script>
-```
+---
-- **[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.
+## Versioning and Release Channels
-Example:
+This package is published to npm under **two channels**: `latest` (stable) and `canary` (early access).
-```html
-<script src='https://ds-assets.cupra.com/1.0.3/dist/index.iife.js'></script>
-```
+### Stable Releases (`latest`)
+These versions represent production-ready builds:
-#### Loading the CSS
+- Follow Semantic Versioning
+- Include validated and approved changes
+- Recommended for all production usage
-You can load the CSS directly with a `<link>`, which is the most performant option. Specify the theme and version in the URL:
+Install latest stable:
-```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.
+Specific stable version:
-> **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:
-```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.
-### `.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.
+Specific canary version:
-### `.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
+### Recommended usage
+- **Production:** always use **stable (`latest`)**
+- **Testing upcoming features:** use the **canary channel**
+- **Deterministic builds:** pin exact versions (stable or canary)
-<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.
-| 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) Load the theme CSS (link preferred for performance):
 ```html
-<ds-slider
-  min="0"
-  max="1000"
-  step="50"
-  initial-value-min="100"
-  initial-value-max="500"
-></ds-slider>
+<link rel="stylesheet" href="https://ds-assets.cupra.com/[version]/styles/[theme]/theme.css" />
 ```
-#### Currency Slider (Intl)
+3) Wrap your UI with the theme provider.
+   `load-fonts` and `load-styles` control whether the provider loads assets automatically.
 ```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)
-```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="cupra" 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 CSS (and fonts if required) and set the provider to not load them:
 ```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>
-```
+<link rel="preload" as="style" href="https://ds-assets.cupra.com/[version]/styles/cupra/theme.css" />
+<link rel="stylesheet" href="https://ds-assets.cupra.com/[version]/styles/cupra/theme.css" />
-#### Combined Intl and Manual Formatting
-```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="cupra" 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.
----
-### 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);
-}
-```
-Or a context menu:
-```css
-.my-context-menu {
-  position: absolute;
-  z-index: var(--ds-z-index-context-menu);
-  /* Additional styling here */
-}
-```
+### Option B — Installed via npm in an app build
+Install the package:
-By consistently using these shared variables, you can maintain uniform layering logic
-across your application.
-### 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:**
-```html
-<div class="ds-bg"></div>
+```bash
+npm install @cupra/ui-kit
 ```
-**Using a Variant (e.g., "ds-bg--leon"):**
+Then include the theme provider as in the CDN example.
+CSS may be loaded manually (recommended) or automatically via the provider:
 ```html
-<div class="ds-bg ds-bg--leon"></div>
+<ds-theme-provider theme="cupra" 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**