1Arquitectura: shell + tokens

Dos piezas, ninguna es un selector de componente.

Un tema en @pi/ui no es un solo fichero que reescriba .pi-button, .pi-card o cualquier otro selector de componente. Es, exclusivamente, un bloque que redefine variables CSS (custom properties) bajo una clase contenedora. Los componentes ya están escritos para leer esas variables — cambiarlas es todo lo que hace falta.

La clase contenedora: .pi-shell

Todo tema se aplica añadiendo dos clases a un elemento raíz (normalmente <body>, porque los overlays de Material — diálogos, menús, snackbars — cuelgan de ahí y también deben heredar el tema):

<body class="pi-shell pi-shell__<nombre-del-tema>">

.pi-shell por sí sola ya aplica el contrato completo de tokens con sus valores por defecto (ver themes/_default.scss). .pi-shell__<nombre> se aplica a la vez, no en su lugar, y sobreescribe solo los tokens que ese tema quiere cambiar. Como ambas clases tienen la misma especificidad, gana la que se declaró más tarde en el CSS compilado — por eso el orden de @forward en themes/index.scss importa (ver §3).

Las dos familias de variables

Un tema puede tocar una familia, la otra, o ambas. _alternative.scss cambia las dos (repaleta primary/accent/highlighted y la forma). _minimal.scss y _gradient.scss solo tocan --pi-theme-* — la paleta de marca se queda igual a propósito.

El puente con Angular Material

Los componentes nativos de Material (slider, checkbox, radio…) no leen --pi-color-*: pintan con sus propios roles --mat-sys-*, que genera mat.theme(). El puente se declara una sola vez, en _default.scss, por indirección:

--mat-sys-primary: var(--pi-color-primary);
--mat-sys-primary-container: var(--pi-color-primary-100);
/* … */

Como es una indirección, cualquier tema que redefina --pi-color-primary arrastra automáticamente a Material sin tener que repetir el bloque del puente. Si tu tema no toca la paleta (como Minimal o Gradient), no necesitas tocar esto en absoluto.

2El contrato de tokens

Todo lo que un tema puede redefinir, con su valor en el tema por defecto y dónde se consume.

Botones

Campos de formulario

Superficies

Overlays (modal, notificación, tooltip, accordion)

Grupo añadido después de la primera versión de este contrato. Ningún tema salvo Minimal los redefine todavía: Default, Alternative y Gradient usan siempre el segundo argumento de var(), que reproduce exactamente la forma que tenía cada overlay antes de tokenizar.

3Crear un tema, paso a paso

Cuatro ficheros, ninguno toca un componente. Ejemplo con un tema ficticio brutalist.

@mixin brutalistThemeTokens {
  --pi-theme-button-radius: 0;
  --pi-theme-button-shadow: 4px 4px 0 var(--pi-color-black);
  --pi-theme-card-radius: 0;
  --pi-theme-card-shadow: none;
}

.pi-shell__brutalist {
  @include brutalistThemeTokens;
}

@forward 'default';
@forward 'alternative';
@forward 'minimal';
@forward 'gradient';
@forward 'brutalist'; // ← nuevo, al final

@use 'default' as *;
@use 'alternative' as *;
@use 'minimal' as *;
@use 'gradient' as *;
@use 'brutalist' as *; // ← nuevo, al final

export const ShellClass = {
  Default: shellTheming('default'),
  Alternative: shellTheming('alternative'),
  Minimal: shellTheming('minimal'),
  Gradient: shellTheming('gradient'),
  /* Bordes duros, sombra dura, sin medias tintas. */
  Brutalist: shellTheming('brutalist'),
};

import { inject } from '@angular/core';
import { PiThemeService } from '@pi/ui';

const themeService = inject(PiThemeService);
themeService.setTheme('brutalist');

import { ShellClass } from '@pi/ui';

document.body.className = ShellClass.Brutalist;

4Los cuatro temas del repo

Cuatro implementaciones reales del mismo contrato, en libs/ui/src/lib/styles/themes/.

Los cuatro comparten exactamente los mismos selectores de componente — la prueba de que el contrato de tokens funciona es que ninguno necesitó tocar un .component.ts ni un .component.html.

5Caso de estudio: anillo de foco en degradado

Qué hacer cuando el efecto que quieres no lo cubre ningún token existente.

El tema Gradient quería un borde en degradado al enfocar un campo. El problema: el borde de un <mat-form-field appearance="outline"> no es un border normal — es tres <div> (leading, notch, trailing) cada uno con su propio borde parcial, para dejar hueco a la etiqueta flotante. Un background en degradado ahí se vería cortado en cada unión.

La solución: un anillo aparte, no el borde del notch

En vez de pelear con los tres fragmentos, se añade un ::after sobre .mat-mdc-text-field-wrapper (la caja completa, sin partir) que pinta solo el borde gracias a mask-composite: se enmascara la copia padding-box (el interior) fuera de la copia border-box (el rectángulo completo), dejando visible únicamente el anillo:

.mat-mdc-text-field-wrapper { position: relative; }

&.mat-focused .mat-mdc-text-field-wrapper::after {
  content: '';
  position: absolute;
  inset: 0;
  z-index: 1;
  border-radius: var(--pi-theme-field-radius);
  padding: var(--pi-theme-field-border-width, 1px);
  background: var(--pi-theme-field-focus-gradient, none);
  -webkit-mask:
    linear-gradient(#fff 0 0) content-box,
    linear-gradient(#fff 0 0);
  -webkit-mask-composite: xor;
  mask-composite: exclude;
  pointer-events: none;
}

El token nuevo, --pi-theme-field-focus-gradient, se añadió al contrato compartido (consumido con fallback none) — así cualquier tema puede optar por él sin que los demás se vean afectados. Gradient además pone --pi-theme-field-border-color-focus: transparent para apagar el borde sólido del notch; si no, se vería el borde plano por debajo del anillo.

6Modo oscuro y temas

El modo oscuro del playground es ortogonal a los temas — conviven, no se solapan.

@pi/ui no trae un tema oscuro propio. El playground activa uno "best-effort" añadiendo la clase dark-mode al <html> (no al <body>, que es donde vive .pi-shell) — hoy vía PiThemeService.setDarkMode()/toggleDarkMode(), que hace ese toggle por ti (persistido en localStorage) en vez de que cada app repita el mismo effect() — y ahí reasigna solo los neutros (--pi-color-white, --pi-color-grey-*, --pi-color-black) — las paletas de marca (primary, accent…) se dejan igual:

html.dark-mode {
  --pi-color-white: #1c1f26;
  --pi-color-grey-100: #2a2e38;
  --pi-color-black: #f1f2f4;
  /* … solo neutros, la marca no cambia … */
}

Como es una clase distinta en un elemento distinto, cualquier combinación (tema × modo oscuro) funciona sin código extra — son dos cascadas independientes que solo coinciden en que ambas reasignan variables CSS. La única excepción real es cuando un tema usa un escalón de marca como si fuera superficie neutra (por ejemplo, --pi-color-primary-25 como fondo de campo en Alternative): ese caso puntual sí necesita un ajuste en modo oscuro, ya presente en styles.scss bajo html.dark-mode .pi-shell__alternative.

7Checklist

Antes de dar el tema por terminado

• Se creó con nx g @pi/ui:theme <nombre> — hace los tres puntos siguientes por ti.
• El fichero nuevo vive en themes/, exporta un mixin y una clase .pi-shell__<nombre>.
• Está en themes/index.scss, al final de ambos bloques (@forward y @use).
• Tiene entrada en ShellClass (configs.ts) y en PiThemeService (ThemeVariant/shellClassByVariant), con un comentario de una línea que resuma el aspecto.
• Solo declara los tokens que cambia — el resto hereda de _default.scss sin repetirlo.
• Si toca --pi-color-primary/accent/highlighted, revisado que el puente --mat-sys-* (declarado una vez en default) sigue coherente.
• Si toca overlays (modal/notificación/tooltip/accordion), revisado con las tres páginas de catálogo, no solo con un botón suelto.
• Si al tokenizar una superficie nueva tocaste un .component.scss, nx run ui:lint-styles no marca ese fichero (detecta --pi-color-* usado fuera de un fallback --pi-theme-*).
• Probado en el playground con las tres páginas de catálogo, no solo en un botón suelto.

Evita

• Añadir un selector de componente (.pi-button.mi-tema) dentro del fichero del tema — si hace falta, el token que falta va al contrato compartido, no aquí.
• Redeclarar tokens que no cambian "por si acaso" — genera ruido y dificulta ver qué es realmente distinto en ese tema.
• Tocar warn / success por estética — son colores semánticos; cambiarlos perjudica la lectura del estado (error/éxito).
• Asumir que --pi-theme-* alcanza a los controles nativos de Material (checkbox, radio, slider): esos usan tokens --mdc-* fijados en compilación, fuera de este contrato (ver §1).