@telefonica/mistica 16.57.0-beta.1 → 16.57.0

package/doc/design-tokens.md

@@ -6,100 +6,18 @@ exported from `@telefonica/mistica`. Tokens adapt automatically to the active sk
 
 ## Critical rules
 
-- **NEVER hardcode colors.** Always use `skinVars.colors.*` for all color values.
+- **NEVER hardcode colors in app/component UI code.** Always use `skinVars.colors.*` for all color values.
 - Use `skinVars.rawColors.*` (not `skinVars.colors.*`) when applying alpha with `applyAlpha`.
 - Use `skinVars.borderRadii.*` for border radius values.
+- For custom skins, palette-based skin authoring, or theme-level visual customization, see
+  [theme-config.md](./theme-config.md).
 - Tokens are CSS custom properties at runtime (e.g. `var(--colorBrand)`), so they work in both inline styles
   and CSS.
 
 ## Color tokens
 
-All colors are accessed via `skinVars.colors.*`. Each token resolves to a CSS custom property.
-
-### Semantic colors
-
-| Token                   | Usage                                                    |
-| ----------------------- | -------------------------------------------------------- |
-| `brand`                 | Primary brand color                                      |
-| `brandHigh`             | High-emphasis brand color                                |
-| `inverse`               | Inverse foreground color                                 |
-| `neutralHigh`           | High-emphasis neutral (e.g. primary text on default)     |
-| `neutralMedium`         | Medium-emphasis neutral (e.g. secondary text on default) |
-| `neutralLow`            | Low-emphasis neutral                                     |
-| `neutralLowAlternative` | Alternative low-emphasis neutral                         |
-| `success`               | Success semantic color                                   |
-| `warning`               | Warning semantic color                                   |
-| `error`                 | Error semantic color                                     |
-| `promo`                 | Promotional color                                        |
-| `highlight`             | Highlight color                                          |
-
-### Background colors
-
-| Token                            | Usage                               |
-| -------------------------------- | ----------------------------------- |
-| `background`                     | Default page background             |
-| `backgroundAlternative`          | Alternative section background      |
-| `backgroundBrand`                | Brand-colored background            |
-| `backgroundBrandSecondary`       | Secondary brand background          |
-| `backgroundContainer`            | Container/card background           |
-| `backgroundContainerBrand`       | Container on brand background       |
-| `backgroundContainerAlternative` | Container on alternative background |
-| `backgroundOverlay`              | Modal/sheet overlay                 |
-| `backgroundSkeleton`             | Skeleton loading placeholder        |
-| `appBarBackground`               | App bar background                  |
-| `navigationBarBackground`        | Navigation bar background           |
-
-### Text colors
-
-| Token                  | Usage                                      |
-| ---------------------- | ------------------------------------------ |
-| `textPrimary`          | Primary text on default background         |
-| `textPrimaryInverse`   | Primary text on brand/inverse background   |
-| `textPrimaryBrand`     | Primary text on brand background           |
-| `textPrimaryMedia`     | Primary text on media background           |
-| `textSecondary`        | Secondary text on default background       |
-| `textSecondaryInverse` | Secondary text on brand/inverse background |
-| `textSecondaryBrand`   | Secondary text on brand background         |
-| `textError`            | Error text                                 |
-| `textLink`             | Link text color                            |
-| `textLinkInverse`      | Link text on brand/inverse background      |
-| `textLinkDanger`       | Danger link text color                     |
-
-### Border colors
-
-| Token            | Usage                  |
-| ---------------- | ---------------------- |
-| `borderLow`      | Low-emphasis border    |
-| `border`         | Default border         |
-| `borderHigh`     | High-emphasis border   |
-| `borderSelected` | Selected/active border |
-
-### Status colors (low/high emphasis)
-
-| Low emphasis | High emphasis | Usage          |
-| ------------ | ------------- | -------------- |
-| `successLow` | `successHigh` | Success status |
-| `warningLow` | `warningHigh` | Warning status |
-| `errorLow`   | `errorHigh`   | Error status   |
-| `promoLow`   | `promoHigh`   | Promo status   |
-| `brandLow`   | `brandHigh`   | Brand status   |
-
-### Control colors
-
-| Token              | Usage                                     |
-| ------------------ | ----------------------------------------- |
-| `control`          | Default control (checkbox, radio, switch) |
-| `controlActivated` | Activated control                         |
-| `controlError`     | Error state control                       |
-| `loadingBar`       | Loading bar color                         |
-| `divider`          | Divider line color                        |
-
-### Tag colors
-
-Tags have paired `tagText*` and `tagBackground*` tokens for each type: `Promo`, `Active`, `Inactive`, `Info`,
-`Success`, `Warning`, `Error`. Each also has `Inverse`, `Negative`, and `Brand` variants.
-
-Example: `skinVars.colors.tagTextPromo`, `skinVars.colors.tagBackgroundPromo`.
+All colors are accessed via `skinVars.colors.*`. Each token resolves to a CSS custom property. Low/High colors
+mean low-contrast or high-contrast versions.
 
 ## Using colors in code
 
@@ -134,30 +52,47 @@ const semiTransparentBrand = applyAlpha(skinVars.rawColors.brand, 0.5);
 // applyAlpha(skinVars.colors.brand, 0.5) // Don't do this
 ```
 
+## Using palettes when authoring a skin
+
+Palette exports are for skin authoring, not for styling components directly. If you need to customize default
+colors, radii, or related visual tokens, create or extend a `Skin` and then consume those values through
+`skinVars.*` in component code. See [theme-config.md](./theme-config.md) for the full custom-skin example.
+
 ## Border radius tokens
 
-Access via `skinVars.borderRadii.*`:
-
-| Token        | Usage                   |
-| ------------ | ----------------------- |
-| `container`  | Cards, boxed containers |
-| `button`     | Buttons                 |
-| `input`      | Form inputs             |
-| `popup`      | Popups, tooltips        |
-| `checkbox`   | Checkboxes              |
-| `indicator`  | Indicators              |
-| `chip`       | Chips                   |
-| `sheet`      | Bottom sheets           |
-| `bar`        | Progress bars           |
-| `avatar`     | Avatars                 |
-| `mediaSmall` | Small media elements    |
-| `tag`        | Tags                    |
+Access via `skinVars.borderRadii.*`.
 
 ```tsx
-// Use in styles when building custom elements (prefer Mistica components instead)
+// Use in styles when building custom elements (but STRONGLY prefer Mistica components instead)
 <div style={{borderRadius: skinVars.borderRadii.container}}>...</div>
 ```
 
+## Spacing tokens
+
+Spacing tokens are exposed via `skinVars.spacing.*`. They are mainly useful for skin authoring and modifying
+the spacing of mistica layout components like `Box`, `Stack`, `Inline`, `ResponsiveLayout`, and `GridLayout`.
+
+These spacing tokens are responsive and adapt to the active skin.
+
+Some tokens expose `top` / `bottom`, some expose `left` / `right`, and some expose all four sides depending on
+the component they support.
+
+```tsx
+import {skinVars} from '@telefonica/mistica';
+
+// Use in styles when building custom elements (but STRONGLY prefer Mistica components instead)
+<div
+  style={{
+    paddingTop: skinVars.spacing.cardDefaultPadding.top,
+    paddingRight: skinVars.spacing.cardDefaultPadding.right,
+    paddingBottom: skinVars.spacing.cardDefaultPadding.bottom,
+    paddingLeft: skinVars.spacing.cardDefaultPadding.left,
+  }}
+>
+  ...
+</div>;
+```
+
 ## Text presets
 
 Text sizing is handled by text components (`Text1`-`Text10`, `Title1`-`Title4`). Do not manually set font
@@ -167,10 +102,10 @@ sizes -- use the appropriate text component instead.
 | ---------------- | ------------------------------------ | ---------------------------------- |
 | `Text1`-`Text4`  | `light`, `regular`, `medium`, `bold` | Body text with configurable weight |
 | `Text5`-`Text10` | Fixed per skin                       | Display/headline text              |
-| `Title1`         | Default weight from skin             | Section title                      |
-| `Title2`         | Default weight from skin             | Subsection title                   |
-| `Title3`         | Default weight from skin             | Card/small title                   |
-| `Title4`         | Default weight from skin             | Smallest title                     |
+| `Title4`         | Default weight from skin             | Section title                      |
+| `Title3`         | Default weight from skin             | Subsection title                   |
+| `Title2`         | Default weight from skin             | Card/small title                   |
+| `Title1`         | Default weight from skin             | Smallest title                     |
 
 ## ThemeVariant (variant contexts)
 
@@ -193,7 +128,11 @@ Some sections of a page use different color contexts. Use `variant` prop on `Res
 </ResponsiveLayout>
 ```
 
-Available variants: `'default'`, `'brand'`, `'negative'`, `'alternative'`, `'media'`.
+Also some components can receive a variant prop.
+
+Available variants: `'default'` (white background), `'brand'` (brand color background), `'negative'` (dark
+background where text should be white), `'alternative'` (light neutral background), `'media'` (meant for
+content on top of images or videos).
 
 Components inside a variant section automatically adapt their colors. You do not need to manually set inverse
 colors.

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,12 +17,18 @@ 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`.
+3. **NEVER set font sizes manually.** Use text components: `Text1`-`Text10`, `Title1`-`Title4`. If those don't
+   cover your necessities you can set custom sizes with `Text` component.
 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.
@@ -133,7 +139,10 @@ type ThemeConfig = {
 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.
+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`.
 
@@ -191,11 +200,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
 
@@ -263,14 +272,18 @@ 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.)
+- **Spacing**: `skinVars.spacing.*` (button, card, input, tag, feedback, hero, header, drawer padding tokens)
 - **Text presets**: Handled by text components, not accessed directly
 
 ## Docs
 
 - [Components reference](./components.md): full component catalog with props and usage examples
-- [Design tokens](./design-tokens.md): skinVars colors, rawColors, applyAlpha, border radii, text presets,
-  theme variants
+- [Design tokens](./design-tokens.md): skinVars colors, rawColors, applyAlpha, border radii, spacing tokens,
+  text presets, theme variants
 - [Patterns and best practices](./patterns.md): page composition, layout dos/don'ts, color rules, responsive
   patterns, form patterns, card patterns, list patterns, skeleton loading, funnel flows, routing integration,
   dark mode
@@ -278,7 +291,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,12 +2,14 @@
 
 ## 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`).
+3. **NEVER set font sizes manually.** Use text components (`Text1`-`Text10`, `Title1`-`Title4`). If those don't
+   cover your necessities you can set custom sizes with `Text` component.
 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.
@@ -123,7 +125,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
@@ -136,6 +138,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

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.57.0-beta.1",
+    "version": "16.57.0",
     "license": "MIT",
     "repository": {
         "type": "git",