@telefonica/mistica 16.56.1-beta.1 → 16.57.0-beta.2

package/doc/fonts.md

@@ -1,127 +1,260 @@
 # Fonts
 
-<!-- TOC -->
+Mistica does **not** inject a font family automatically. Without explicit setup, browsers fall back to their
+default serif font (Times New Roman on desktop). You must declare `@font-face` rules and set `font-family` on
+`body`.
 
-- [Fonts](#fonts)
-  - [Font family](#font-family)
-    - [System Fonts (Roboto / San Francisco)](#system-fonts-roboto--san-francisco)
-    - [OnAir or Telefonica fonts](#onair-or-telefonica-fonts)
-    - [Override brower fonts for some specific html elements](#override-brower-fonts-for-some-specific-html-elements)
-  - [Dynamic font sizes](#dynamic-font-sizes)
+## Font per skin
 
-<!-- /TOC -->
+Each skin has a designated font family. Use the correct one for the skin your app is using:
 
-## Font family
+| Skin                         | Getter function        | Font family         |
+| ---------------------------- | ---------------------- | ------------------- |
+| `movistar-new` _(preferred)_ | `getMovistarNewSkin()` | `'Movistar Sans'`   |
+| `movistar` _(legacy)_        | `getMovistarSkin()`    | `'On Air'`          |
+| `o2-new` _(preferred)_       | `getO2NewSkin()`       | `'On Air'`          |
+| `o2` _(legacy)_              | `getO2Skin()`          | `'On Air'`          |
+| `vivo-new` _(preferred)_     | `getVivoNewSkin()`     | `'Vivo Type'`       |
+| `vivo` _(legacy)_            | `getVivoSkin()`        | `'Roboto'`          |
+| `telefonica`                 | `getTelefonicaSkin()`  | `'Telefonica Sans'` |
+| `blau`                       | `getBlauSkin()`        | `'Roboto'`          |
+| `tu`                         | `getTuSkin()`          | `'Telefonica Sans'` |
+| `esimflag`                   | `getEsimflagSkin()`    | `'On Air'`          |
 
-Mistica components are optimized to work with iOS/Android system fonts (Roboto and San Francisco), but it can
-also work fine with other font families.
+## Setting font-family
 
-### System Fonts (Roboto / San Francisco)
+Set the font from inside a component rendered under `ThemeContextProvider`. This keeps font and background
+color in sync with the active theme, including in dark mode:
 
-If you use system fonts in your web application we recommend you to setup it as follows:
+```tsx
+import {skinVars} from '@telefonica/mistica';
+
+const GlobalStyles = () => (
+  <style>{`
+    body {
+      font-family: 'Movistar Sans', 'Helvetica', 'Arial', sans-serif;
+      background-color: ${skinVars.colors.background};
+    }
+  `}</style>
+);
+```
+
+Render `<GlobalStyles />` as a direct child of `ThemeContextProvider`, before the rest of the app.
+
+## @font-face setup
+
+Declare the font weights your app needs. Mistica uses **300 (light), 400 (regular), 500 (medium) and 700
+(bold)**. Serve the `.woff2` files from your own static hosting.
+
+### On Air (Movistar, O2, O2 New, Esimflag)
 
 ```css
+@font-face {
+  font-family: 'On Air';
+  font-style: normal;
+  font-weight: 300;
+  src: url('/fonts/OnAir-Light.woff2') format('woff2');
+}
+@font-face {
+  font-family: 'On Air';
+  font-style: normal;
+  font-weight: 400;
+  src: url('/fonts/OnAir-Regular.woff2') format('woff2');
+}
+@font-face {
+  font-family: 'On Air';
+  font-style: normal;
+  font-weight: 500;
+  src: url('/fonts/OnAir-Medium.woff2') format('woff2');
+}
+@font-face {
+  font-family: 'On Air';
+  font-style: normal;
+  font-weight: 700;
+  src: url('/fonts/OnAir-Bold.woff2') format('woff2');
+}
+
 body {
-  font-family: -apple-system, 'Roboto', 'Helvetica', 'Arial', sans-serif;
+  font-family: 'On Air', 'Helvetica', 'Arial', sans-serif;
 }
 ```
 
-And additionaly declare a Roboto font family for desktop browsers. For example:
+### Movistar Sans (Movistar New)
 
 ```css
 @font-face {
-  font-family: 'Roboto';
+  font-family: 'Movistar Sans';
   font-style: normal;
   font-weight: 300;
-  src:
-    local('Roboto Light'),
-    local('Roboto-Light'),
-    url('/static/fonts/roboto-v18-latin_latin-ext-300.woff2') format('woff2');
+  src: url('/fonts/MovistarSans-Light.woff2') format('woff2');
 }
 @font-face {
-  font-family: 'Roboto';
+  font-family: 'Movistar Sans';
   font-style: normal;
   font-weight: 400;
-  src:
-    local('Roboto'),
-    local('Roboto-Regular'),
-    url('/static/fonts/roboto-v18-latin_latin-ext-regular.woff2') format('woff2');
+  src: url('/fonts/MovistarSans-Regular.woff2') format('woff2');
 }
 @font-face {
-  font-family: 'Roboto';
+  font-family: 'Movistar Sans';
   font-style: normal;
   font-weight: 500;
-  src:
-    local('Roboto Medium'),
-    local('Roboto-Medium'),
-    url('/static/fonts/roboto-v18-latin_latin-ext-500.woff2') format('woff2');
+  src: url('/fonts/MovistarSans-Medium.woff2') format('woff2');
 }
 @font-face {
-  font-family: 'Roboto';
+  font-family: 'Movistar Sans';
   font-style: normal;
   font-weight: 700;
-  src:
-    local('Roboto Bold'),
-    local('Roboto-Bold'),
-    url('/static/fonts/roboto-v18-latin_latin-ext-700.woff2') format('woff2');
+  src: url('/fonts/MovistarSans-Bold.woff2') format('woff2');
+}
+
+body {
+  font-family: 'Movistar Sans', 'Helvetica', 'Arial', sans-serif;
 }
 ```
 
-This is just an example, you'll need to change the `url()` declarations to point to the fonts served by your
-web server. The important part here is to serve different font weights for 300 (light), 400 (regular), 500
-(medium) and 700 (bold).
+### Vivo Type (Vivo New)
 
-### OnAir or Telefonica fonts
+```css
+@font-face {
+  font-family: 'Vivo Type';
+  font-style: normal;
+  font-weight: 300;
+  src: url('/fonts/vivo-type-light.woff2') format('woff2');
+}
+@font-face {
+  font-family: 'Vivo Type';
+  font-style: normal;
+  font-weight: 400;
+  src: url('/fonts/vivo-type-regular.woff2') format('woff2');
+}
+@font-face {
+  font-family: 'Vivo Type';
+  font-style: normal;
+  font-weight: 500;
+  src: url('/fonts/vivo-type-medium.woff2') format('woff2');
+}
+@font-face {
+  font-family: 'Vivo Type';
+  font-style: normal;
+  font-weight: 700;
+  src: url('/fonts/vivo-type-bold.woff2') format('woff2');
+}
+
+body {
+  font-family: 'Vivo Type', 'Helvetica', 'Arial', sans-serif;
+}
+```
 
-Mistica works fine too with other fonts like OnAir or Telefonica fonts, but these fonts don't have a medium
-weight (only light, regular and bold). In these cases, we recomend to use the regular font weight for the 500
-`font-weight`. Something like this:
+### Telefonica Sans (Telefonica, Tu)
 
 ```css
 @font-face {
-  font-family: 'OnAir';
+  font-family: 'Telefonica Sans';
   font-style: normal;
   font-weight: 300;
-  src: url('/static/fonts/OnAir-Light.woff2') format('woff2');
+  src: url('/fonts/Telefonica_Sans_Light.woff2') format('woff2');
 }
 @font-face {
-  font-family: 'OnAir';
+  font-family: 'Telefonica Sans';
   font-style: normal;
   font-weight: 400;
-  src: url('/static/fonts/OnAir-Regular.woff2') format('woff2');
+  src: url('/fonts/Telefonica_Sans_Regular.woff2') format('woff2');
 }
 @font-face {
-  font-family: 'OnAir';
+  font-family: 'Telefonica Sans';
   font-style: normal;
   font-weight: 500;
-  /* Note we are using OnAir Regular for medium (500) font-weight too: */
-  src: url('/static/fonts/OnAir-Regular.woff2') format('woff2');
+  src: url('/fonts/Telefonica_Sans_Medium.woff2') format('woff2');
 }
 @font-face {
-  font-family: 'OnAir';
+  font-family: 'Telefonica Sans';
   font-style: normal;
   font-weight: 700;
-  src: url('/static/fonts/OnAir-Bold.woff2') format('woff2');
+  src: url('/fonts/Telefonica_Sans_Bold.woff2') format('woff2');
 }
 
 body {
-  font-family: 'OnAir', 'Helvetica', 'Arial', sans-serif;
+  font-family: 'Telefonica Sans', 'Helvetica', 'Arial', sans-serif;
 }
 ```
 
-### Override brower fonts for some specific html elements
+### Roboto (Vivo, Blau)
 
-All the html elements in your page will inherit the body font by default, except if a style sheet sets a
-different font family for the element, and most browsers use to set specific font families for some elements
-like `input`, `textarea`, `pre`, etc. If you want to avoid that browser behavior, you have different options:
+Roboto is available via [Google Fonts](https://fonts.google.com/specimen/Roboto) or
+[Bunny Fonts](https://fonts.bunny.net/family/roboto) (GDPR-friendly alternative). The weights needed are 300,
+400, 500, and 700.
 
-1. Explicitly set the your font family for those elements:
+Google Fonts import:
+
+```html
+<link rel="preconnect" href="https://fonts.googleapis.com" />
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+<link
+  href="https://fonts.googleapis.com/css2?family=Roboto:wght@300;400;500;700&display=swap"
+  rel="stylesheet"
+/>
+```
+
+Or self-hosted `@font-face`:
 
 ```css
+@font-face {
+  font-family: 'Roboto';
+  font-style: normal;
+  font-weight: 300;
+  src:
+    local('Roboto Light'),
+    local('Roboto-Light'),
+    url('/fonts/roboto-300.woff2') format('woff2');
+}
+@font-face {
+  font-family: 'Roboto';
+  font-style: normal;
+  font-weight: 400;
+  src:
+    local('Roboto'),
+    local('Roboto-Regular'),
+    url('/fonts/roboto-400.woff2') format('woff2');
+}
+@font-face {
+  font-family: 'Roboto';
+  font-style: normal;
+  font-weight: 500;
+  src:
+    local('Roboto Medium'),
+    local('Roboto-Medium'),
+    url('/fonts/roboto-500.woff2') format('woff2');
+}
+@font-face {
+  font-family: 'Roboto';
+  font-style: normal;
+  font-weight: 700;
+  src:
+    local('Roboto Bold'),
+    local('Roboto-Bold'),
+    url('/fonts/roboto-700.woff2') format('woff2');
+}
+
 body {
   font-family: -apple-system, 'Roboto', 'Helvetica', 'Arial', sans-serif;
 }
+```
 
+## Body background color
+
+Always set `body` background from inside a component under `ThemeContextProvider` using the
+`skinVars.colors.background` token. This ensures the background matches the active theme in both light and
+dark mode:
+
+```tsx
+const GlobalStyles = () => <style>{`body { background-color: ${skinVars.colors.background}; }`}</style>;
+```
+
+## Override browser fonts for form elements
+
+Some browsers apply a different `font-family` to form inputs, textareas, and code elements. Override with:
+
+```css
 input,
 textarea,
 pre,
@@ -130,23 +263,12 @@ code {
 }
 ```
 
-2. Apply the font-family with a wildcard selector:
-
-```css
-* {
-  font-family: -apple-system, 'Roboto', 'Helvetica', 'Arial', sans-serif;
-}
-```
-
-3. Use a [reset.css](https://meyerweb.com/eric/tools/css/reset/) that does this for you.
-
-We use to recomend option 3.
+Or use a CSS reset that handles this, such as
+[modern-normalize](https://github.com/sindresorhus/modern-normalize).
 
 ## Dynamic font sizes
 
-Mistica components support scalling font sizes automatically based on OS or browser accesibility settings. If
-you want your web to properly work with dynamic font sizes, we recommend to setup a base font size of 16px or
-100% (which is the same as 16px in most browsers):
+To support OS/browser accessibility font size settings, set the base size on `html`:
 
 ```css
 html {
@@ -154,13 +276,9 @@ html {
 }
 ```
 
-Also, to make dynamic font sizes work properly in iOS devices you need to include this:
+To support Dynamic Type on iOS:
 
 ```css
-/**
- * To enable Dynamic Type in apple devices:
- * See: https://dev.to/colingourlay/how-to-support-apple-s-dynamic-text-in-your-web-content-with-css-40c0
- */
 @supports (font: -apple-system-body) {
   html {
     font: -apple-system-body !important;

package/doc/layout.md

@@ -73,15 +73,22 @@ Vertically distributes its children using the given `space` separation.
 ## Inline
 
 Horizontally distributes its children using the given `space` separation. This component can be considered as
-an horizontal `Stack`.
+a horizontal `Stack`, and it covers the most common row-layout use cases you might otherwise solve with
+`display: flex`.
 
-:information_source: Items can be aligned vertically. Check `Inline` component in
+It supports:
+
+- horizontal distribution via `space={number}` or `space="between" | "around" | "evenly"`
+- vertical alignment of children via `alignItems="flex-start" | "flex-end" | "center" | "stretch" | "baseline"`
+- wrapping via `wrap` and row spacing via `verticalSpace`
+
+:information_source: Check `Inline` in
 [Storybook](https://mistica-web.vercel.app/?path=/story/layout-inline--default) to learn more about it.
 
 ### numeric space
 
 ```tsx
-<Inline space={16}>
+<Inline space={16} alignItems="center">
   <Child1 />
   <Child2 />
   <Child3 />

package/doc/llms.md

@@ -17,16 +17,31 @@ repository at `https://github.com/Telefonica/mistica-web/blob/master/doc/<filena
 
 ## Critical Rules
 
-1. **NEVER hardcode colors.** Always use `skinVars.colors.*` design tokens from `@telefonica/mistica`.
+1. **NEVER hardcode colors in app/component UI code.** Always use `skinVars.colors.*` design tokens from
+   `@telefonica/mistica`. The exception is skin authoring: when creating or extending a `Skin`, you may use
+   built-in palette exports (for example `movistarNewPalette`) or your own custom palette/colors inside the
+   skin definition.
 2. **Try not to use raw `<div>` for layout.** Use Mistica layout components: `Box`, `Stack`, `Inline`,
    `Align`, `ResponsiveLayout`, `GridLayout`, `Grid`.
 3. **NEVER set font sizes manually.** Use text components: `Text1`-`Text10`, `Title1`-`Title4`.
 4. **NEVER set border radius manually.** Use `skinVars.borderRadii.*` or Mistica components that handle it
-   automatically.
+   automatically. If you need to change the default visual styling of components (colors, border radius,
+   etc.) and there is no specific prop for it, create or extend a custom skin instead of adding ad hoc style
+   overrides.
 5. **Always wrap your app** with `<ThemeContextProvider>` and import `@telefonica/mistica/css/mistica.css`.
 6. **Always namespace React hooks**: `React.useState`, `React.useEffect`, `React.useRef`.
 7. **Add `'use client';`** directive to client components when using Next.js app router.
 8. Use `skinVars.rawColors.*` (not `skinVars.colors.*`) when applying alpha with `applyAlpha`.
+9. **Always set `font-family` on `body` and use the correct font for the active skin.** Mistica does NOT
+   inject a font — without it browsers render text with their default serif font (Times New Roman on desktop).
+   Each skin has a designated font; see the [fonts reference](./fonts.md) for `@font-face` setup and the
+   per-skin font table.
+10. **Always set `body` background color using `skinVars.colors.background`.** Without it the page background
+    won't match the theme (especially in dark mode). Do this inside a component rendered under
+    `ThemeContextProvider` so `skinVars` resolves to the correct theme values:
+    ```tsx
+    <style>{`body { background-color: ${skinVars.colors.background}; }`}</style>
+    ```
 
 ## Install
 
@@ -42,13 +57,22 @@ npm install @telefonica/mistica
 
 ## Quick Start
 
+**Two global CSS concerns that Mistica does NOT handle automatically:**
+
+1. **Font family** — without it, browsers fall back to their default serif font (Times New Roman on desktop).
+   Each skin has its own font; see [fonts.md](./fonts.md) for the per-skin table and `@font-face` setup.
+2. **Body background color** — without it, the page background won't match the active theme (critical in dark
+   mode). Set it from inside a component rendered under `ThemeContextProvider` using
+   `skinVars.colors.background`.
+
 ```tsx
 'use client';
 
 import '@telefonica/mistica/css/mistica.css';
 import {
   ThemeContextProvider,
-  getMovistarSkin,
+  getMovistarNewSkin,
+  skinVars,
   ResponsiveLayout,
   Box,
   Stack,
@@ -58,12 +82,23 @@ import {
 } from '@telefonica/mistica';
 
 const misticaTheme = {
-  skin: getMovistarSkin(),
+  skin: getMovistarNewSkin(),
   i18n: {locale: 'es-ES', phoneNumberFormattingRegionCode: 'ES'},
 };
 
+// Rendered under ThemeContextProvider so skinVars resolves correctly
+const GlobalStyles = () => (
+  <style>{`
+    body {
+      font-family: 'Movistar Sans', 'Helvetica', 'Arial', sans-serif; /* font for Movistar New skin */
+      background-color: ${skinVars.colors.background};
+    }
+  `}</style>
+);
+
 const App = () => (
   <ThemeContextProvider theme={misticaTheme}>
+    <GlobalStyles />
     <ResponsiveLayout>
       <Box paddingY={24}>
         <Stack space={16}>
@@ -100,8 +135,13 @@ type ThemeConfig = {
 };
 ```
 
-Available skins: `getMovistarSkin()`, `getVivoSkin()`, `getO2Skin()`, `getTelefonicaSkin()`, `getBlauSkin()`,
-`getTuSkin()`, and others via `getSkinByName()`. You can also create a custom skin.
+Available skins: `getMovistarNewSkin()`, `getVivoNewSkin()`, `getO2NewSkin()`, `getTelefonicaSkin()`,
+`getBlauSkin()`, `getTuSkin()`, and others via `getSkinByName()`. Legacy variants without the `New` suffix
+also exist (`getMovistarSkin()`, `getVivoSkin()`, `getO2Skin()`); prefer the `New` versions for new projects.
+You can also create a custom skin. If you need to customize default component colors, radii, or other visual
+tokens beyond the props exposed by a component, prefer extending a skin over overriding component styles.
+Built-in palette exports such as `movistarNewPalette`, `o2NewPalette`, `vivoNewPalette`, etc. are available
+for skin authoring, and custom skins may also define their own palette colors from scratch.
 
 Built-in Link integrations: `Next12`, `Next13`, `Next14`, `ReactRouter5`, `ReactRouter6`.
 
@@ -159,11 +199,11 @@ Vertical rhythm: containers 24px padding, sections 32px spacing, elements 16px s
 ### Buttons
 
 `ButtonPrimary`, `ButtonSecondary`, `ButtonDanger`, `ButtonLink`, `ButtonLinkDanger`, `ButtonGroup`,
-`ButtonLayout`, `IconButton`, `ToggleIconButton`
+`ButtonLayout`, `IconButton`, `ToggleIconButton`, `TextLink`
 
 ### Text
 
-`Text1`-`Text10`, `Title1`-`Title4`, `TextLink`
+`Text1`-`Text10`, `Title1`-`Title4`
 
 ### Cards
 
@@ -231,6 +271,9 @@ All tokens via `skinVars` from `@telefonica/mistica`:
 
 - **Colors**: `skinVars.colors.*` (286 tokens for backgrounds, text, borders, controls, status, tags)
 - **Raw colors**: `skinVars.rawColors.*` (same tokens as RGB values, for use with `applyAlpha`)
+- **Palettes for skin authoring**: built-in palette exports such as `movistarNewPalette`, `o2NewPalette`,
+  `vivoNewPalette`, etc. Use these only when creating/extending a `Skin`, not for styling app components
+  directly.
 - **Border radii**: `skinVars.borderRadii.*` (container, button, input, popup, chip, sheet, avatar, tag, etc.)
 - **Text presets**: Handled by text components, not accessed directly
 
@@ -246,7 +289,7 @@ All tokens via `skinVars` from `@telefonica/mistica`:
 - [Layout](./layout.md): Core layout primitives (Box, Stack, Inline, Align, Grid/GridItem, NegativeBox,
   Divider, HorizontalScroll, Boxed, Overlay, StackingGroup) and page layouts (ResponsiveLayout, HeaderLayout,
   GridLayout, MasterDetailLayout, FixedFooterLayout, ButtonFixedFooterLayout, ButtonLayout, DoubleField),
-  vertical rhythm
+  vertical rhythm, and `Inline` alignment/wrapping capabilities
 - [Forms](./forms.md): Form component, all form field types, DoubleField, useForm hook
 - [Analytics](./analytics.md): trackingEvent prop, logEvent setup, default tracking, GA4 support,
   TrackingConfig

package/doc/patterns.md

@@ -2,15 +2,18 @@
 
 ## Critical rules
 
-1. **NEVER hardcode colors.** Always use `skinVars.colors.*` from `@telefonica/mistica`.
+1. **NEVER hardcode colors in app/component UI code.** Always use `skinVars.colors.*` from
+   `@telefonica/mistica`. For skins and theme-level customization, see [theme-config.md](./theme-config.md).
 2. **NEVER use raw `<div>` for layout.** Use `Box`, `Stack`, `Inline`, `ResponsiveLayout`, `GridLayout`,
    `Grid`.
 3. **NEVER set font sizes manually.** Use text components (`Text1`-`Text10`, `Title1`-`Title4`).
 4. **NEVER set border radius manually.** Use `skinVars.borderRadii.*` or components that handle it (`Boxed`,
-   cards, etc.).
+   cards, etc.). For theme-level visual customization without a dedicated component prop, use a custom skin.
 5. **Always wrap your app** with `ThemeContextProvider` and import `@telefonica/mistica/css/mistica.css`.
 6. **Always namespace React hooks**: `React.useState`, `React.useEffect`, `React.useRef`, etc.
 7. **Add `'use client';`** directive to client components when using Next.js app router.
+8. **Set `font-family` and `body` background color.** See [llms.md](./llms.md) rules 9–10 and
+   [fonts.md](./fonts.md) for the per-skin font table, `@font-face` setup, and the `GlobalStyles` pattern.
 
 ## Page layout composition
 
@@ -121,7 +124,7 @@ import {skinVars, applyAlpha} from '@telefonica/mistica';
 const overlay = applyAlpha(skinVars.rawColors.backgroundBrand, 0.8);
 ```
 
-### DON'T: Hardcode colors
+### DON'T: Hardcode colors in component code
 
 ```tsx
 // BAD - hardcoded colors
@@ -134,6 +137,9 @@ const overlay = applyAlpha(skinVars.rawColors.backgroundBrand, 0.8);
 <Boxed><Text2 regular>Content in container</Text2></Boxed>
 ```
 
+If you need brand-specific defaults, put those colors in a custom skin and then consume them through
+`skinVars.colors.*` instead of styling individual components with palette values.
+
 ## Responsive patterns
 
 ### Conditional rendering by screen size
@@ -509,7 +515,7 @@ return (
 import Link from 'next/link';
 
 const theme = {
-  skin: getMovistarSkin(),
+  skin: getMovistarNewSkin(),
   i18n: {locale: 'es-ES', phoneNumberFormattingRegionCode: 'ES'},
   Link: {type: 'Next14', Component: Link},
 };
@@ -521,7 +527,7 @@ const theme = {
 import {Link} from 'react-router-dom';
 
 const theme = {
-  skin: getMovistarSkin(),
+  skin: getMovistarNewSkin(),
   i18n: {locale: 'es-ES', phoneNumberFormattingRegionCode: 'ES'},
   Link: {type: 'ReactRouter6', Component: Link},
 };

package/doc/theme-config.md

@@ -95,6 +95,13 @@ If your app doesn't follow the branding of mistica builtin skins (Movistar, Vivo
 can still use mistica with your custom skin. Just import the `Skin` type and create a new skin config that
 implements the `Skin` interface (you need to define all the required color constants):
 
+If you need to customize default component colors, border radii, or similar visual tokens and there is no
+component prop for that, prefer a custom skin over ad hoc CSS/style overrides. You can:
+
+- start from a built-in skin like `getMovistarNewSkin()` and override the tokens you need
+- start from a built-in palette export like `movistarNewPalette`
+- define your own palette/colors from scratch
+
 ```ts
 import type {Skin} from '@telefonica/mistica';
 
@@ -121,4 +128,35 @@ const skin: Skin = {
 </ThemeContextProvider>;
 ```
 
+You can also extend an existing skin instead of defining everything from scratch:
+
+```ts
+import {getMovistarNewSkin, movistarNewPalette, type Skin} from '@telefonica/mistica';
+
+const baseSkin = getMovistarNewSkin();
+const palette = {
+  ...movistarNewPalette,
+  brandPrimary: '#0050D8',
+};
+
+const skin: Skin = {
+  ...baseSkin,
+  name: 'Acme',
+  colors: {
+    ...baseSkin.colors,
+    brand: palette.brandPrimary,
+    backgroundBrand: palette.brandPrimary,
+    backgroundBrandTop: palette.brandPrimary,
+    backgroundBrandBottom: palette.blue800,
+    buttonPrimaryBackground: palette.brandPrimary,
+    buttonPrimaryBackgroundHover: palette.blue800,
+    buttonPrimaryBackgroundPressed: palette.blue800,
+    textButtonPrimary: palette.white,
+  },
+};
+```
+
+If you also need different default radii, override `borderRadii` in the custom skin rather than setting
+border radius ad hoc in component styles.
+
 You can see an example in the [examples folder](../examples/custom-skin/).

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@telefonica/mistica",
-    "version": "16.56.1-beta.1",
+    "version": "16.57.0-beta.2",
     "license": "MIT",
     "repository": {
         "type": "git",