WEB-2413: Improvements and fixes

Author: Marcosld

doc/design-tokens.md

@@ -6,9 +6,11 @@ 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.
 
@@ -49,6 +51,12 @@ 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.*`:

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 />

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`.
 
@@ -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

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

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/).

skills/mistica/SKILL.md

@@ -72,118 +72,8 @@ Based on what the user needs, read the appropriate documentation files:
 | **Migration from older versions** | `node_modules/@telefonica/mistica/doc/migration-guide.md` |
 | **Lottie animations**             | `node_modules/@telefonica/mistica/doc/lottie.md`          |
 
-## Critical Rules
-
-These rules MUST be followed in ALL generated code:
-
-1. **NEVER hardcode colors.** Always use `skinVars.colors.*` from `@telefonica/mistica`. For semi-transparent
-   colors, use `applyAlpha(skinVars.rawColors.*, alpha)`.
-
-2. **NEVER use raw `<div>` for layout or spacing.** Use Mistica layout components:
-
-   - `Box` for padding
-   - `Stack` for vertical spacing
-   - `Inline` for horizontal spacing
-   - `ResponsiveLayout` for page content containers
-   - `GridLayout` for column-based layouts
-   - `Grid`/`GridItem` for CSS grid
-
-3. **NEVER set font sizes or font families manually.** Use text components: `Text1`-`Text10` for body text,
-   `Title1`-`Title4` for headings.
-
-4. **NEVER set border radius manually.** Use `skinVars.borderRadii.*` or Mistica components that handle it
-   (`Boxed`, cards, etc.).
-
-5. **Always wrap the app root** with `<ThemeContextProvider>` and import
-   `@telefonica/mistica/css/mistica.css`.
-
-6. **Always namespace React hooks**: write `React.useState`, `React.useEffect`, not bare `useState`.
-
-7. **Add `'use client';`** directive when using Next.js app router.
-
-8. **Use the `to` prop** (not `href`) for client-side navigation after configuring the Link component in
-   theme.
-
-9. **Wrap unbounded `RowList`** with `<NegativeBox>` when placed inside `ResponsiveLayout`.
-
-10. **Use `small` prop on buttons** inside cards and `EmptyStateCard`.
-
-11. **Always set `font-family` on `body` using the correct font for the active skin.** Mistica does NOT inject
-    a font — without it browsers fall back to their default serif font (Times New Roman on desktop). Each skin
-    has a designated font:
-
-    | Skin                         | Font family         |
-    | ---------------------------- | ------------------- |
-    | `movistar-new` _(preferred)_ | `'Movistar Sans'`   |
-    | `movistar` _(legacy)_        | `'On Air'`          |
-    | `o2-new`, `o2`               | `'On Air'`          |
-    | `vivo-new` _(preferred)_     | `'Vivo Type'`       |
-    | `vivo` _(legacy)_            | `'Roboto'`          |
-    | `telefonica`, `tu`           | `'Telefonica Sans'` |
-    | `blau`                       | `'Roboto'`          |
-    | `esimflag`                   | `'On Air'`          |
-
-    Read `node_modules/@telefonica/mistica/doc/fonts.md` for `@font-face` declarations for each font.
-
-12. **Always set `body` background using `skinVars.colors.background`.** Without it the page background won't
-    match the theme, especially in dark mode. Set it inside a component rendered under `ThemeContextProvider`:
-
-    ```tsx
-    const GlobalStyles = () => <style>{`body { background-color: ${skinVars.colors.background}; }`}</style>;
-    ```
-
-13. **Do NOT wrap these components in `ResponsiveLayout`** — they already contain one internally:
-    `HeaderLayout`, `MainSectionHeaderLayout`, `Hero`, `CoverHero`, `MasterDetailLayout`,
-    `ButtonFixedFooterLayout`, `NavigationBar`, `MainNavigationBar`, `FunnelNavigationBar`, `Tabs`,
-    `SuccessFeedbackScreen`, `ErrorFeedbackScreen`, `InfoFeedbackScreen`, `LoadingScreen`,
-    `BrandLoadingScreen`. Place them at page level, side by side with `ResponsiveLayout` blocks.
-
-14. **Use carousels only for horizontal content.** `Carousel` and `CenteredCarousel` are horizontal-scroll
-    components — always place them **inside** `ResponsiveLayout`. `Slideshow` bleeds full-width automatically
-    and should be placed **outside** `ResponsiveLayout`.
-
-## Quick Reference
-
-### Standard page structure
-
-```tsx
-<ThemeContextProvider theme={misticaTheme}>
-  {/* GlobalStyles: set body font (see rule 11) and background (see rule 12) */}
-  <GlobalStyles />
-  {/* These components have their own internal ResponsiveLayout — place them at page level */}
-  <MainNavigationBar sections={[...]} />
-  <HeaderLayout header={<Header title="Page Title" />} />
-  {/* Slideshow goes outside ResponsiveLayout — it bleeds full-width automatically */}
-  <Slideshow items={[...]} />
-  <ResponsiveLayout>
-    <Box paddingY={24}>
-      <Stack space={32}>
-        <Stack space={16}>{/* section elements */}</Stack>
-        {/* Carousel and CenteredCarousel go INSIDE ResponsiveLayout */}
-        <Carousel itemsPerPage={{mobile: 1, tablet: 2, desktop: 3}} items={[...]} />
-      </Stack>
-    </Box>
-  </ResponsiveLayout>
-</ThemeContextProvider>
-```
-
-### Vertical rhythm: 24px container padding, 32px between sections, 16px between elements.
-
-### Card asset pattern
-
-```tsx
-<Circle backgroundColor={skinVars.colors.brandLow} size={40}>
-  <IconShopRegular color={skinVars.colors.brand} />
-</Circle>
-```
-
-### Color usage
+## Rules
 
-```tsx
-import {skinVars, applyAlpha} from '@telefonica/mistica';
-
-skinVars.colors.textPrimary; // text color
-skinVars.colors.brand; // brand color
-skinVars.colors.backgroundContainer; // container bg
-applyAlpha(skinVars.rawColors.brand, 0.5); // semi-transparent
-```
+Treat `node_modules/@telefonica/mistica/doc/llms.md` as the canonical source of truth for critical rules,
+page structure, and Mistica best practices. Do not rely on abbreviated rules here when `llms.md` is
+available.