314 lines
18 KiB
Markdown
314 lines
18 KiB
Markdown
# Tokens de `@pi/ui`
|
||
|
||
Todo el aspecto visual de la librería (color, forma, sombra, tipografía de
|
||
controles) se resuelve en **custom properties de CSS**, nunca en valores
|
||
hardcodeados dentro de un componente. Hay dos familias con propósitos
|
||
distintos, más un puñado de primitivas base:
|
||
|
||
| Familia | Dónde vive | Qué representa | Cuántos temas la redefinen |
|
||
| --------------- | ---------------------------------------- | ------------------------------------------------------------------------------ | --------------------------- |
|
||
| `--pi-color-*` | `:root` (`_pi-color-variables.scss`) | Paleta de marca (primary/accent/highlighted/warn/success/grey/white/black/background) | Todos excepto Minimal |
|
||
| `--pi-theme-*` | `.pi-shell` (`themes/_*.scss`) | Forma y comportamiento por superficie: botón, campo, card, panel, chip, overlay | Todos |
|
||
| Primitivas base | `:root` (`_pi-global-variables.scss`, `_pi-font-sizes-variables.scss`, `_pi-public-variables.scss`) | Espaciado, radios, sombras, tamaños de fuente, animaciones — sin tematizar | Ninguno |
|
||
|
||
Los componentes de `common/` (botón, campo, card, panel, chip, modal,
|
||
snackbar, tooltip, accordion…) **no leen la paleta ni la forma directamente**:
|
||
consumen `--pi-theme-*`, y son los ficheros de `styles/themes/` los que deciden
|
||
qué valor tiene cada token. Así, un tema nuevo no toca un solo selector de
|
||
componente — solo redefine tokens (ver `_alternative.scss`, `_minimal.scss`,
|
||
`_gradient.scss` como ejemplo).
|
||
|
||
## Cómo se aplica un tema
|
||
|
||
La forma recomendada es `PiThemeService` — inyectable, con persistencia en
|
||
`localStorage` y sin tener que tocar el DOM a mano:
|
||
|
||
```ts
|
||
import { inject } from '@angular/core';
|
||
import { PiThemeService } from '@pi/ui';
|
||
|
||
const themeService = inject(PiThemeService);
|
||
|
||
themeService.setTheme('alternative'); // pinta pi-shell pi-shell__alternative en <body>
|
||
themeService.toggleDarkMode(); // pinta/quita dark-mode en <html>
|
||
```
|
||
|
||
`theme`/`darkMode` son señales normales: también se pueden mutar con un
|
||
`[(value)]`/`[(checked)]` dos vías directo sobre la señal (ver el uso real en
|
||
`apps/playground/src/app/app.ts`/`app.html`). Por debajo, cada cambio dispara
|
||
un `effect()` que aplica la clase y persiste — cualquier camino de escritura
|
||
queda cubierto por igual, no solo los setters.
|
||
|
||
Si no quieres el servicio (p. ej. fuera de un contexto de inyección), el
|
||
mecanismo de bajo nivel sigue disponible:
|
||
|
||
```ts
|
||
import { ShellClass } from '@pi/ui';
|
||
|
||
document.body.className = ShellClass.Alternative; // 'pi-shell pi-shell__alternative'
|
||
```
|
||
|
||
`ShellClass` expone `Default`, `Alternative`, `Minimal` y `Gradient`
|
||
(`libs/ui/src/lib/styles/configs.ts`). Cada uno corresponde a un mixin en
|
||
`libs/ui/src/lib/styles/themes/_<nombre>.scss`, incluido desde
|
||
`themes/index.scss`. Dentro de un shell se puede forzar el aspecto contrario en
|
||
un subárbol con `.is-private`/`.is-public` (p. ej. el input `context` de
|
||
`pi-card`).
|
||
|
||
### El patrón de fallback
|
||
|
||
Un token puede consumirse de dos formas, según si el tema por defecto lo
|
||
declara o no:
|
||
|
||
```scss
|
||
// El tema Default declara este token → todos los temas lo tienen.
|
||
border-radius: var(--pi-theme-card-radius);
|
||
|
||
// El tema Default NO lo declara → el segundo argumento de var() reproduce
|
||
// el valor original hardcodeado. Solo Minimal (u otro tema futuro) lo pisa.
|
||
border-radius: var(--pi-theme-chip-radius, #{$chip-border-radius});
|
||
```
|
||
|
||
Esto es intencional: los tokens que **todos** los temas existentes necesitan
|
||
personalizar (radio/altura/tipografía de botón, forma de campo) se declaran en
|
||
`_default.scss`. Los que solo un tema concreto toca (radio de overlays en
|
||
Minimal, degradado de foco en Gradient) se dejan sin declarar en Default —así
|
||
su valor por defecto es exactamente el que tenía el componente antes de
|
||
tokenizar, byte a byte, y ningún tema existente cambia de aspecto sin querer.
|
||
|
||
## `--pi-theme-*`: tabla completa
|
||
|
||
**D** = Default · **A** = Alternative · **M** = Minimal · **G** = Gradient.
|
||
Una celda vacía significa "no lo redefine, hereda el valor de la fila D (o el
|
||
fallback de `var()` si D tampoco lo declara, marcado como *(fallback)*)".
|
||
|
||
### Botón (`pi-button/_pi-button.scss`, `_pi-button-theme.scss`, `menu/dynamic-menu`)
|
||
|
||
| Token | D | A | M | G |
|
||
| --- | --- | --- | --- | --- |
|
||
| `--pi-theme-button-height` | `var(--pi-spacing-xxx-large)` (2.5rem) | `2.875rem` | `2.5rem` | — |
|
||
| `--pi-theme-button-radius` | `var(--pi-border-radius-medium)` | `999px` (píldora) | `var(--pi-border-radius-xx-small)` | — |
|
||
| `--pi-theme-button-font-weight` | `600` | `700` | `500` | — |
|
||
| `--pi-theme-button-letter-spacing` | `normal` | `0.04em` | `normal` | — |
|
||
| `--pi-theme-button-text-transform` | `none` | `uppercase` | `none` | — |
|
||
| `--pi-theme-button-shadow` | `none` | `0 6px 16px -6px rgba(106,63,212,.55)` | `none` | — |
|
||
| `--pi-theme-button-transition` | `background-color .16s ease-in` | `all .2s ease-out` | `background-color .12s ease-out, border-color .12s ease-out` | — |
|
||
| `--pi-theme-button-fill-primary` | `none` (relleno plano) | degradado `primary-900→primary-400` | `none` | degradado `primary-400→primary-900` |
|
||
| `--pi-theme-button-fill-accent` | `none` | degradado `accent-900→accent-400` | `none` | degradado `accent-400→accent-900` |
|
||
| `--pi-theme-button-fill-warn` | `none` | — | `none` | — |
|
||
| `--pi-theme-button-fill-success` | `none` | — | `none` | — |
|
||
| `--pi-theme-button-fill-highlighted` | `none` | degradado `highlighted→highlighted-300` | `none` | degradado `highlighted-300→highlighted` |
|
||
|
||
`--pi-theme-button-fill-#{$color}` se interpola por nombre de color en
|
||
`_pi-button-theme.scss:47` (`background-image: var(--pi-theme-button-fill-#{$color}, none)`),
|
||
así que un tema nuevo que quiera degradado en un color que no sea
|
||
primary/accent/highlighted solo tiene que declarar
|
||
`--pi-theme-button-fill-<color>`.
|
||
|
||
### Campos de formulario (`_mat-form-field.scss`, `file-upload`, `_mat-datepicker.scss`, `_mat-select.scss`)
|
||
|
||
| Token | D | A | M | G |
|
||
| --- | --- | --- | --- | --- |
|
||
| `--pi-theme-field-radius` | `0.875rem` | `999px` | `var(--pi-border-radius-xx-small)` | — |
|
||
| `--pi-theme-field-border-width` | `1px` | `2px` | `1px` | — |
|
||
| `--pi-theme-field-border-color` | `var(--pi-color-grey-200)` | `var(--pi-color-primary-100)` | `var(--pi-color-grey-200)` | — |
|
||
| `--pi-theme-field-border-color-hover` | `var(--pi-color-grey-300)` | `var(--pi-color-primary-300)` | `var(--pi-color-grey-400)` | — |
|
||
| `--pi-theme-field-border-color-focus` | `var(--pi-color-primary)` | `var(--pi-color-primary)` | `var(--pi-color-black)` | `transparent` (deja ver el degradado) |
|
||
| `--pi-theme-field-surface` | `var(--pi-color-white)` | `var(--pi-color-primary-25)` | `var(--pi-color-white)` | — |
|
||
| `--pi-theme-field-label-color` | `var(--pi-color-grey-300)` | `var(--pi-color-primary-900)` | `var(--pi-color-grey-400)` | — |
|
||
| `--pi-theme-field-label-transform` *(fallback: `none`)* | — | `uppercase` | `none` | — |
|
||
| `--pi-theme-field-label-letter-spacing` *(fallback: `normal`)* | — | `0.08em` | `normal` | — |
|
||
| `--pi-theme-field-label-weight` *(fallback: `inherit`)* | — | `700` | `500` | — |
|
||
| `--pi-theme-field-focus-gradient` *(fallback: `none`)* | — | — | — | `linear-gradient(120deg, primary, accent, highlighted)` |
|
||
|
||
### Superficies: card / panel / chip
|
||
|
||
| Token | D | A | M | G | Consumidores |
|
||
| --- | --- | --- | --- | --- | --- |
|
||
| `--pi-theme-card-radius` | `var(--pi-border-radius-large)` | `1.5rem` | `var(--pi-border-radius-xx-small)` | — | `_pi-card.scss`, `skeleton.component.scss` |
|
||
| `--pi-theme-card-shadow` | `var(--pi-box-shadow-panel)` | `0 10px 30px -12px rgba(59,13,107,.28)` | `none` | — | `_pi-card.scss` |
|
||
| `--pi-theme-panel-radius` | `var(--pi-border-radius-large)` | `1.5rem` | `var(--pi-border-radius-xx-small)` | — | `panel.component.scss`, `_mat-datepicker.scss`, `_mat-select.scss`, `dynamic-menu` |
|
||
| `--pi-theme-chip-radius` *(fallback: radio original por tamaño)* | — | `0.25rem` | `0` | — | `chip/styles/_size.scss` (×3, por tamaño y por affix) |
|
||
|
||
### Overlays: modal / notification / tooltip / accordion
|
||
|
||
Ningún tema salvo Minimal los redefine — Default/Alternative/Gradient usan
|
||
siempre el *fallback* de `var()` (el valor que tenían antes de tokenizar).
|
||
|
||
| Token | Fallback (D/A/G) | M | Consumidores |
|
||
| --- | --- | --- | --- |
|
||
| `--pi-theme-modal-radius` | `var(--pi-border-radius-medium)` (panel completo) / `var(--pi-border-radius-large)` (`.pi-modal__panel--full`) | `var(--pi-border-radius-xx-small)` | `_mat-dialog.scss` (×2) |
|
||
| `--pi-theme-notification-radius` | `var(--pi-border-radius-large)` | `var(--pi-border-radius-xx-small)` | `snack-bar.component.scss`, `_mat-snackbar.scss` (×2) |
|
||
| `--pi-theme-notification-shadow` | `var(--pi-box-shadow)` | `none` | `_mat-snackbar.scss` |
|
||
| `--pi-theme-tooltip-radius` | `var(--pi-border-radius-medium)` | `var(--pi-border-radius-xx-small)` | `_mat-tooltip.scss` |
|
||
| `--pi-theme-tooltip-shadow` | `var(--pi-box-shadow-panel-double)` | `none` | `_mat-tooltip.scss` |
|
||
| `--pi-theme-accordion-radius` | `var(--pi-border-radius-large)` | `var(--pi-border-radius-xx-small)` | `accordion.component.scss`, `_horizontal-accordion.scss`, `_vertical-accordion.scss` (×6, incluye un `calc(... - 0.0625rem)`) |
|
||
| `--pi-theme-overlay-divider-color` | `var(--pi-color-grey-100)` | — | `drawer.component.scss`, `hub.component.scss` (borde bajo la cabecera) |
|
||
| `--pi-theme-hub-grabber-color` | `var(--pi-color-grey-100)` | — | `hub.component.scss` (el asa superior) |
|
||
|
||
### Puente con Angular Material (`--mat-sys-*`)
|
||
|
||
Los componentes de Material (slider, checkbox, radio, progress…) no leen
|
||
`--pi-color-*`: pintan con sus propios roles `--mat-sys-*`, generados por
|
||
`mat.theme()` a partir de una paleta separada. `_default.scss` reengancha una
|
||
cosa con otra **una sola vez**, por indirección:
|
||
|
||
```scss
|
||
--mat-sys-primary: var(--pi-color-primary);
|
||
--mat-sys-on-primary: var(--pi-color-white);
|
||
--mat-sys-primary-container: var(--pi-color-primary-100);
|
||
--mat-sys-on-primary-container: var(--pi-color-primary-900);
|
||
--mat-sys-secondary: var(--pi-color-accent);
|
||
--mat-sys-on-secondary: var(--pi-color-white);
|
||
--mat-sys-secondary-container: var(--pi-color-accent-100);
|
||
--mat-sys-on-secondary-container: var(--pi-color-accent-900);
|
||
--mat-sys-tertiary: var(--pi-color-highlighted);
|
||
--mat-sys-on-tertiary: var(--pi-color-white);
|
||
--mat-sys-error: var(--pi-color-warn);
|
||
--mat-sys-on-error: var(--pi-color-white);
|
||
```
|
||
|
||
Como es indirección (`var(--pi-color-*)`, no un valor literal), un tema que
|
||
redefina `--pi-color-primary` etc. (como Alternative) tiñe también los
|
||
controles de Material sin tener que repetir este bloque.
|
||
|
||
## `--pi-color-*`: paleta de marca
|
||
|
||
Declarada una vez en `:root` (`_pi-color-variables.scss`) con los valores
|
||
Default, y redeclarada completa dentro de `.pi-shell__alternative` (Minimal y
|
||
Gradient **no** tocan la paleta — ver comentario en `_minimal.scss`: "minimalista
|
||
aquí es una cuestión de forma, no de color"). Se consume **directamente por
|
||
nombre** (no hay indirección `--pi-theme-*` de por medio) en ~100 ficheros de
|
||
la librería: bordes, fondos, texto, iconos, estados de badge/chip/status, etc.
|
||
|
||
Cada paleta (`primary`, `accent`, `highlighted`, `warn`, `success`) sigue la
|
||
misma escala de 10 pasos + variante rgba del tono 200:
|
||
|
||
`10 → 25 → 50 → 75 → 100 → 200 → 200-rgba → 300 → 400 → (base) → 900`
|
||
|
||
| Escala | primary (D) | accent (D) | highlighted (D) | warn (D) | success (D) |
|
||
| --- | --- | --- | --- | --- | --- |
|
||
| 10 | `#fdfdff` | `#fffdf9` | `#f9fbff` | `#fff9fa` | `#f7fcf9` |
|
||
| 25 | `#fafbff` | `#fffaed` | `#f2f5ff` | `#ffedf0` | `#e6f6ed` |
|
||
| 50 | `#f0f4ff` | `#fdf5e5` | `#e9eeff` | `#fcebeb` | `#def5e8` |
|
||
| 75 | `#eaefff` | `#fae5bf` | `#dae2ff` | `#ffe7ea` | `#c7ebdc` |
|
||
| 100 | `#d7e2fb` | `#fce0ad` | `#bccdfa` | `#f7cdcd` | `#bbe8d5` |
|
||
| 200 | `#c3d5ff` | `#f6d495` | `#6482d7` | `#f2acac` | `#83dbb6` |
|
||
| 200-rgba | `rgba(196,213,255,.15)` | `rgba(252,224,173,.15)` | `rgba(168,193,255,.15)` | `rgba(237,129,129,.15)` | *(no tiene)* |
|
||
| 300 | `#a3c0ff` | `#f2c26a` | `#436ac1` | `#ec8b8b` | `#60c99d` |
|
||
| 400 | `#8cacf2` | `#f6bc63` | `#1d3f8a` | `#e87272` | `#3ebe88` |
|
||
| base | `#799ef0` | `#eda82a` | `#0d2a6b` | `#e45959` | `#1cb273` |
|
||
| 900 | `#5772d4` | `#d78f0f` | `#030f3c` | `#c13737` | `#009758` |
|
||
|
||
**Neutros y utilidad**, sin escala de tema (no cambian entre Default/Alternative):
|
||
|
||
| Token | Valor | Uso |
|
||
| --- | --- | --- |
|
||
| `--pi-color-white` | `#ffffff` | — |
|
||
| `--pi-color-white-900` | `#f4f4f4` | — |
|
||
| `--pi-color-white-rgba-03/05/06/09` | blanco a 33/50/66/88% opacidad | overlays, disabled |
|
||
| `--pi-color-black-200` | `#323748` | — |
|
||
| `--pi-color-black` | `#1a1a1a` | texto, foco (Minimal) |
|
||
| `--pi-color-grey-10…900` | escala de 10 pasos, `#fcfcfd → #3d3d3d` | bordes, texto secundario |
|
||
| `--pi-color-background-300/400/500` | `#aeaeb6` / `#fcfcfc` / `#f7f7f7` | fondos de página |
|
||
|
||
En `_alternative.scss` la paleta completa (`primary`, `accent`, `highlighted`)
|
||
se redeclara con una gama azul→violeta / turquesa / violeta oscuro,
|
||
respectivamente. `warn` y `success` se dejan intactos a propósito en todos los
|
||
temas: son colores semánticos y cambiarlos perjudicaría la lectura del estado.
|
||
|
||
> Nota: `_pi-color-variables.scss` declara `--pi-color-grey-200` dos veces
|
||
> (líneas 328-329) y `--pi-color-white`/`--pi-color-background-400` con el
|
||
> mismo patrón en otro punto del fichero — inofensivo (la segunda declaración
|
||
> gana y tiene el mismo valor) pero es limpieza pendiente si se retoca el
|
||
> fichero.
|
||
|
||
## Primitivas base (sin tematizar)
|
||
|
||
Estas variables no cambian entre temas — son la escala de espaciado/forma/sombra
|
||
de toda la librería, y los tokens `--pi-theme-*` casi siempre se expresan en
|
||
función de ellas (`var(--pi-border-radius-large)`, `var(--pi-spacing-xxx-large)`…).
|
||
|
||
| Familia | Tokens | Rango |
|
||
| --- | --- | --- |
|
||
| Espaciado | `--pi-spacing-xxxxx-small` … `--pi-spacing-xxxx-large` | `0.0625rem` (1px) … `3rem` (48px), 11 pasos |
|
||
| Radio | `--pi-border-radius-xx-small` … `--pi-border-radius-x-large` | `0.125rem` (2px) … `1.375rem` (22px), 5 pasos |
|
||
| Sombra | `--pi-box-shadow`, `-hover`, `-double`, `-panel`, `-panel-double`, `-panel-disabled`, `-top`, `-inset` | valores `rgba` fijos, ver `_pi-global-variables.scss` |
|
||
| Animación | `--pi-animation`, `-fast`, `-slow` | `all .16s/.25s/.4s ease-out` |
|
||
| Tamaño de fuente | `--pi-font-size-xxx-small` … `-xxx-large` | `0.5rem` (8px) … `2.875rem` (46px), 9 pasos |
|
||
| Layout (header/footer/navbar/aside/card) | `--pi-height-*`, `--pi-width-*` | ver `_pi-global-variables.scss` |
|
||
| Landing/marketing | `--pi-public-font-size-*`, `--pi-public-height-*`, `--pi-public-width-*` | ver `_pi-public-variables.scss` |
|
||
|
||
`_pi-gradient-variables.scss` (`$pi-gradient-primary-light`, etc.) son
|
||
variables **Sass**, no custom properties de CSS — se resuelven en tiempo de
|
||
compilación y no forman parte del contrato de theming en runtime.
|
||
|
||
## Cómo tokenizar una superficie nueva
|
||
|
||
1. En el consumidor, cambia el valor hardcodeado por
|
||
`var(--pi-theme-<superficie>-<propiedad>, <valor-original>)`. El fallback
|
||
garantiza que ningún tema existente cambia de aspecto hasta que decida
|
||
redefinir el token.
|
||
2. Si **todos** los temas van a necesitar tocarlo pronto, decláralo también en
|
||
`defaultThemeTokens` (`_default.scss`) con el valor original — así queda
|
||
documentado como parte del contrato en vez de vivir solo como fallback
|
||
disperso en el CSS.
|
||
3. Añade el override en el/los temas que lo necesiten
|
||
(`_alternative.scss`, `_minimal.scss`, `_gradient.scss`).
|
||
4. Actualiza este documento.
|
||
|
||
## Cómo añadir un tema nuevo
|
||
|
||
La forma recomendada es el generador:
|
||
|
||
```bash
|
||
nx g @pi/ui:theme mi-marca
|
||
```
|
||
|
||
Crea `libs/ui/src/lib/styles/themes/_mi-marca.scss` (en blanco, con los
|
||
grupos de tokens más habituales comentados a modo de chuleta), lo registra en
|
||
`themes/index.scss`, añade la entrada a `ShellClass` en `styles/configs.ts` y
|
||
extiende `ThemeVariant`/`PiThemeService` — el tema queda seleccionable con
|
||
`themeService.setTheme('mi-marca')` sin ningún paso manual más. Solo falta
|
||
descomentar y ajustar los tokens que definen el aspecto, y (si tu app expone un
|
||
selector de tema) añadirlo a esa lista.
|
||
|
||
Estos son los pasos que da por ti, si prefieres hacerlo a mano o entender qué
|
||
toca:
|
||
|
||
1. Crea `libs/ui/src/lib/styles/themes/_<nombre>.scss` con un mixin
|
||
`<nombre>ThemeTokens` que redefina solo los tokens `--pi-theme-*` (y, si
|
||
aplica, `--pi-color-*`) que cambian respecto a Default.
|
||
2. Aplícalo a `.pi-shell__<nombre>`.
|
||
3. Impórtalo desde `themes/index.scss`.
|
||
4. Añade la entrada a `ShellClass` en `styles/configs.ts`.
|
||
5. Añade `'<nombre>'` a `ThemeVariant` y una entrada a `shellClassByVariant`
|
||
en `util/theme/theme.service.ts`.
|
||
|
||
No hace falta tocar ningún componente: si consumen los tokens en vez de
|
||
valores literales, el tema nuevo se propaga solo.
|
||
|
||
## Lint de tokens: evitar que un color de marca se filtre sin querer
|
||
|
||
El bug que motivó tokenizar accordion/tab/select-option/drawer/hub esta misma
|
||
sesión (un `var(--pi-color-*)` a pelo en el componente, así que ningún tema ni
|
||
el modo oscuro puede redefinir esa superficie) tiene ahora una regla de
|
||
stylelint que lo detecta automáticamente: `pi/no-raw-color-token`
|
||
(`tools/stylelint-plugin-pi-theme/`).
|
||
|
||
```bash
|
||
nx run ui:lint-styles
|
||
```
|
||
|
||
Marca cualquier `--pi-color-*` que aparezca fuera del *fallback* de un
|
||
`var(--pi-theme-*, ...)` — es decir, exactamente el patrón contrario al de
|
||
["El patrón de fallback"](#el-patrón-de-fallback). Están exentos
|
||
`styles/themes/**` (ahí `--pi-color-*` es legítimo: son las definiciones) y
|
||
`styles/common/abstracts/**` (donde se declaran las primitivas de la paleta).
|
||
|
||
**Estado actual: es un target aparte, no está enganchado a `nx lint` ni a CI.**
|
||
Al escribirse, señala ~500 usos preexistentes repartidos por componentes que
|
||
esta sesión no llegó a tokenizar — adoptarlo como gate exige ir migrándolos
|
||
primero (mismo patrón que en "Cómo tokenizar una superficie nueva"). Úsalo para
|
||
no introducir *más* mientras se migra el resto.
|