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

package/doc/llms.md

@@ -17,12 +17,17 @@ 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.
@@ -133,7 +138,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 +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
 
@@ -263,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
 
@@ -278,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,12 +2,13 @@
 
 ## 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.
@@ -123,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
@@ -136,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

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-beta.2",
     "license": "MIT",
     "repository": {
         "type": "git",