@cupra/ui-kit 0.0.2-placeholder → 0.2.0-canary.0

package/README.md

@@ -1,27 +1,861 @@
-# @cupra/ui-kit · Placeholder Package
+# UI Kit (Web Components)
 
 ## Overview
-This package represents a **placeholder release** for the `@cupra/ui-kit` module of the **DS-UI Design System**.  
-It has been published to establish the package namespace and to support internal configuration activities related to the continuous integration and release infrastructure.
+Core Web Components for the DS-UI design system, built with Lit and TypeScript.
 
-No functional implementation or production assets are included in this version.
+## Audience
+Developers who want to use DS-UI as native Web Components in any web framework or plain HTML/JS.
 
-## Purpose
-- Reserve the `@cupra/ui-kit` package name under the Cupra organization.
-- Facilitate configuration and validation of the associated build and release systems.
-- Provide an initial reference point for future official releases of the Web Components library.
+## Installation
+- npm: `npm install @cupra/ui-kit`
+- pnpm: `pnpm add @cupra/ui-kit`
+- yarn: `yarn add @cupra/ui-kit`
 
-## Contents
-This release includes:
-- `package.json` metadata
-- `LICENSE.md`
-- `README.md`
+Access to the @cupra registry is required (see Requirements).
 
-No source code, compiled output, or runtime components are distributed at this stage.
+## 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">`.
 
-## Future Releases
-Subsequent versions will deliver the complete implementation of the Web Components library, developed with **Lit** and **TypeScript**, following the principles of **Semantic Versioning 2.0.0**.
+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.
 
 ## License
-**SEE LICENSE IN LICENSE.md**  
-This package is distributed under the SEAT S.A. Library EULA. 1.0
+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.
+
+## 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
+```
+
+### Using yarn
+
+To install the library with **yarn**, use:
+
+```bash
+yarn add @cupra/ui-kit
+```
+
+### .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
+>[!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
+npmScopes:
+  seatcode:
+    npmRegistryServer: "https://npm.pkg.github.com"
+    npmAuthToken: "your_github_token"
+```
+</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.
+
+#### Loading the Bundle
+
+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>
+```
+
+- **[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.
+
+Example:
+
+```html
+<script src='https://ds-assets.cupra.com/1.0.3/dist/index.iife.js'></script>
+```
+
+#### Loading the CSS
+
+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'>
+```
+
+- **[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:
+
+```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>
+```
+</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.
+
+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`.
+
+---
+
+### 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>
+
+```
+</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.
+
+### `.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>
+```
+</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.
+
+| 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.
+
+---
+
+### Events
+
+| Event    | Description                           | Detail          |
+|----------|---------------------------------------|-----------------|
+| `change` | Fired when the slider value changes. | `{ targetId, value }` |
+
+---
+
+### Examples
+
+#### Single Value Slider
+
+```html
+<ds-slider
+  min="0"
+  max="100"
+  step="1"
+  initial-value-min="50"
+></ds-slider>
+```
+
+#### Range Slider
+
+```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)
+
+```html
+<ds-slider
+  min="0"
+  max="2000"
+  step="100"
+  initial-value-min="1200"
+  locale="en-GB"
+  unit-style="unit"
+  unit="kilometer"
+>
+</ds-slider>
+```
+
+To override the Intl-derived unit label with a shorter custom symbol:
+
+```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>
+```
+
+#### 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>
+```
+
+---
+
+### 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 */
+}
+```
+
+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>
+```
+
+**Using a Variant (e.g., "ds-bg--leon"):**
+
+```html
+<div class="ds-bg ds-bg--leon"></div>
+```
+
+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.
+
+</details>