@netzi/tokens 0.1.0-beta.10

package/README.md

@@ -0,0 +1,1008 @@
+# @netzi/tokens
+
+Design tokens de Netzi como **CSS custom properties**. Agnóstico de framework
+(sirve para Angular, React, HTML plano, Tailwind, etc.). Es la base sobre la que
+se construyen `@netzi/ui` y cualquier app de Netzi Tech.
+
+- Tema **claro** (`:root`, tema claro) y **oscuro** (`[data-theme="dark"]`, Netzi navy).
+- Acentos de marca constantes en ambos temas.
+- Todos los tokens usan el prefijo `--netzi-*` para evitar colisiones.
+
+## Instalación
+
+En el **npm público**, bajo el scope `@netzi` de Netzi Tech: sin registry especial ni
+token. Mientras el kit esté en beta, cada versión nueva es una beta y es la que se
+instala por defecto:
+
+```bash
+pnpm add @netzi/tokens
+```
+
+Licencia de uso libre con código privado: ver `LICENSE.md` dentro del paquete. Las
+tipografías incluidas van bajo la SIL Open Font License 1.1.
+
+## Uso
+
+Importa la entrada por defecto (tokens + reset base):
+
+```css
+@import '@netzi/tokens';
+```
+
+O por partes:
+
+```css
+@import '@netzi/tokens/tokens.css'; /* solo las variables (sin reset) */
+@import '@netzi/tokens/base.css'; /* reset + tipografía base + scrollbar */
+@import '@netzi/tokens/fonts.css'; /* opcional: fuentes de marca, autoalojadas */
+```
+
+En tu CSS, consume los tokens:
+
+```css
+.boton {
+  background: var(--netzi-primary);
+  color: var(--netzi-on-primary);
+  border-radius: var(--netzi-radius-control);
+  box-shadow: var(--netzi-elevation-floating);
+}
+```
+
+Usa los tokens por **papel** (superficie, texto, espaciado de grupo, radio de control,
+estilo de título), no los pasos de una escala: el papel dice para qué es y la escala de
+debajo puede cambiar sin tocar tu app. Las escalas con nombre de paso (`--netzi-space-4`,
+`--netzi-radius-sm`, `--netzi-font-size-md`…) están en desuso para las apps (ver
+«Escalas que pasan a internas»).
+
+## Espaciado (`--netzi-space-*`)
+
+Espaciado por **papel**, de lo más cercano a lo más lejano: cuanto más relacionadas están
+dos cosas, menos aire hay entre ellas (proximidad). Úsalo en vez de píxeles o `rem` sueltos
+para mantener el ritmo del sistema; detrás hay una escala de base 4px que es de la fuente.
+
+| Token                    | Valor | Compacto | Para qué                                                                      |
+| ------------------------ | ----- | -------- | ----------------------------------------------------------------------------- |
+| `--netzi-space-related`  | 4px   | 4px      | piezas de un mismo elemento: icono y texto, chips de una lista, campo y ayuda |
+| `--netzi-space-group`    | 8px   | 8px      | elementos hermanos de un grupo: botones de una barra, cabecera y contenido    |
+| `--netzi-space-stack`    | 12px  | 10px     | grupos apilados en un panel o un formulario: campos, filas, columnas          |
+| `--netzi-space-inset-sm` | 12px  | 10px     | relleno de un contenedor compacto: panel flotante, aviso                      |
+| `--netzi-space-inset`    | 16px  | 12px     | relleno de una tarjeta o un panel                                             |
+| `--netzi-space-inset-lg` | 24px  | 20px     | relleno de un diálogo, un panel lateral o una tarjeta grande                  |
+| `--netzi-space-section`  | 32px  | 28px     | entre secciones de una página                                                 |
+| `--netzi-space-page`     | 48px  | 40px     | entre regiones grandes de una página y su margen en pantallas anchas          |
+
+Bajo `[data-density='compact']` se reducen desde `stack` hacia arriba (los finos no
+cambian), coherente con la densidad de los controles, también en una sección con su propia
+densidad.
+
+```css
+.tarjeta {
+  padding: var(--netzi-space-inset);
+  display: flex;
+  gap: var(--netzi-space-group);
+}
+```
+
+## Fuentes de marca (`fonts.css`)
+
+`fonts.css` trae **Plus Jakarta Sans** (texto) y **Fira Code** (monoespaciada) como
+fuentes variables woff2 **dentro del paquete** (~95 KB en total, en dos subconjuntos
+`latin` y `latin-ext` que el navegador descarga según haga falta). No se pide nada
+a Google: política 14 (autoalojar) y 08b (sin terceros antes del consentimiento).
+Va aparte de `index.css`; impórtalo si tu app usa las fuentes de marca:
+
+```css
+@import '@netzi/tokens/fonts.css';
+```
+
+Las rutas son relativas al paquete y las reescriben Vite y el CLI de Angular, que
+copian los woff2 al build.
+
+Mientras llegan, el texto se pinta con un **respaldo del sistema con las métricas
+ajustadas** (Arial o Liberation Sans, y Courier New o Liberation Mono, con `size-adjust`,
+`ascent-override`, `descent-override` y `line-gap-override`): ocupa casi lo mismo que la
+fuente de marca y la página no salta al cambiar. Los tokens `--netzi-font-sans` y
+`--netzi-font-mono` ya lo nombran detrás de la de marca; si cambias la familia en línea,
+deja `'Plus Jakarta Sans Fallback'` (o `'Fira Code Fallback'`) justo detrás. De dónde
+salen los números está en el propio `fonts.css`. Licencia OFL-1.1, adjunta en `styles/fonts/`. Ninguna hoja
+publicada carga nada desde fuera: todo viaja dentro del paquete.
+
+## Tipografía (`--netzi-typography-*`)
+
+Un **estilo de texto** por papel (título, cuerpo, metadato), con familia, tamaño, peso,
+interlineado y espaciado entre letras juntos: es lo que usa una app. Todos escalan con
+`--netzi-font-scale` (el ajuste de accesibilidad del panel), igual que los controles; `body-ui`
+(14px) es el 100 %. El texto corrido (`body`) mide 16px desde la #219 (ADR 0015). Las familias son `--netzi-font-sans` (texto) y `--netzi-font-mono`
+(código y cifras en columna).
+
+**Medida legible** (`--netzi-measure`, `33em`, #213): el ancho máximo del texto corrido, para
+que cada línea se quede en unos 40 a 75 caracteres (64 de mediana) en cualquier ventana (criterio
+C.9). Va en el párrafo (`max-inline-size`), nunca en la página ni en la sección: el ancho que
+sobra lo ocupan el contenido auxiliar, las acciones, otro panel, la rejilla o la prosa en columnas entre párrafos; un párrafo no se parte en columnas, y una descripción corta puede dejar hueco. Va en `em` y
+no en `ch`: el `ch` es el ancho del cero de la fuente que pinta en ese momento, y al llegar la
+fuente de marca cambiaría el ancho de cada párrafo y lo haría saltar (criterio C.12).
+
+```css
+.descripcion {
+  max-inline-size: var(--netzi-measure);
+}
+```
+
+Los tamaños de los **controles** (`--netzi-control-fs-sm/md/lg`) son otra familia,
+ligada a la altura del control; no salen de la escala de texto. La densidad compacta no
+cambia el texto (encoge el aire, no la letra).
+
+### Estilos de texto
+
+En CSS cada estilo es el atajo `font` (tokens `typography` de DTCG) y su espaciado entre letras
+va aparte, porque `font` no lo incluye. El tamaño solo sale también aparte
+(`--netzi-typography-body-font-size`, #155), para la hoja que pone el peso y el interlineado
+por su cuenta y no quiere que el atajo se los pise:
+
+| Estilo                        | Tamaño | Peso | Interlineado | Espaciado | Para qué                                  |
+| ----------------------------- | ------ | ---- | ------------ | --------- | ----------------------------------------- |
+| `--netzi-typography-display`  | 28px   | 800  | 1.25         | -0.5px    | cifras grandes, portadas                  |
+| `--netzi-typography-headline` | 22px   | 700  | 1.25         | -0.2px    | títulos de página                         |
+| `--netzi-typography-title`    | 18px   | 700  | 1.25         | 0         | títulos de sección                        |
+| `--netzi-typography-title-sm` | 16px   | 600  | 1.25         | 0         | texto destacado, títulos de tarjeta       |
+| `--netzi-typography-body`     | 16px   | 400  | 1.5          | 0         | texto corrido: párrafos, descripciones    |
+| `--netzi-typography-body-ui`  | 14px   | 400  | 1.5          | 0         | interfaz: opciones, pestañas, celdas      |
+| `--netzi-typography-body-sm`  | 12.5px | 400  | 1.5          | 0         | líneas secundarias, pistas, pies          |
+| `--netzi-typography-caption`  | 11px   | 600  | 1.25         | 0.5px     | metadatos, etiquetas cortas en mayúsculas |
+
+```css
+.titulo-de-seccion {
+  font: var(--netzi-typography-title);
+  letter-spacing: var(--netzi-typography-title-letter-spacing);
+}
+.meta {
+  font: var(--netzi-typography-caption);
+  letter-spacing: var(--netzi-typography-caption-letter-spacing);
+  text-transform: uppercase;
+}
+.celda {
+  font-size: var(--netzi-typography-body-ui-font-size);
+}
+```
+
+Siguen a `--netzi-font-sans` si la app la cambia. El atajo `font` reinicia también el
+interlineado y el peso: ponlo primero y cambia después lo que quieras (una familia mono para
+un código, por ejemplo). Las mayúsculas de `caption` las pone quien lo usa (`text-transform`),
+no el estilo. Detrás hay una escala de tamaños, pesos e interlineados que es de la fuente: sus
+tokens (`--netzi-font-size-*`, `--netzi-font-weight-*`, `--netzi-line-height-*`) están en
+desuso para las apps.
+
+## Movimiento (`--netzi-duration-*`, `--netzi-ease-*`)
+
+Duraciones y curvas con **nombre de intención**, no de valor: el componente dice qué hace
+(un hover, un panel que entra) y el token decide cuánto dura. Así el ritmo del kit se
+cambia en un sitio y el movimiento reducido también.
+
+| Duración                   | Valor | Para qué                                              |
+| -------------------------- | ----- | ----------------------------------------------------- |
+| `--netzi-duration-instant` | 100ms | la respuesta a una pulsación                          |
+| `--netzi-duration-fast`    | 150ms | hover, foco, cambios de color; lo pequeño que aparece |
+| `--netzi-duration-base`    | 200ms | lo que se despliega o gira (flechas, acordeón)        |
+| `--netzi-duration-slow`    | 280ms | los paneles y capas que entran (modal, drawer)        |
+
+| Curva                   | Valor                              | Para qué                                   |
+| ----------------------- | ---------------------------------- | ------------------------------------------ |
+| `--netzi-ease-standard` | `cubic-bezier(0.25, 0.1, 0.25, 1)` | lo que cambia sin entrar ni salir (`ease`) |
+| `--netzi-ease-enter`    | `cubic-bezier(0.16, 1, 0.3, 1)`    | lo que aparece: frena al llegar            |
+| `--netzi-ease-exit`     | `cubic-bezier(0.4, 0, 1, 1)`       | lo que se va: acelera al irse              |
+| `--netzi-ease-settle`   | `cubic-bezier(0.34, 1.45, 0.5, 1)` | lo que llega, se pasa un poco y se asienta |
+
+### Bucles y destello
+
+Lo que se repite sin fin no es un cambio de estado: su token da la duración de **una vuelta**
+y queda fuera de la escala de arriba (que no pasa de 300 ms). El destello es un aviso que se
+apaga solo, largo a propósito para que dé tiempo a verlo.
+
+| Duración                      | Valor  | Para qué                                                          |
+| ----------------------------- | ------ | ----------------------------------------------------------------- |
+| `--netzi-duration-loop-spin`  | 700ms  | el giro de un indicador de carga                                  |
+| `--netzi-duration-loop-orbit` | 1100ms | el anillo que recorre el borde de un ítem o una pestaña           |
+| `--netzi-duration-loop-pulse` | 1200ms | el latido de opacidad que sustituye al giro (movimiento reducido) |
+| `--netzi-duration-loop-sweep` | 1200ms | la barra de progreso indeterminada                                |
+| `--netzi-duration-loop-shine` | 1300ms | el brillo del skeleton                                            |
+| `--netzi-duration-flash`      | 1400ms | un aviso que se enciende, se deja ver y se apaga solo             |
+
+| Curva                | Valor                            | Para qué                                                       |
+| -------------------- | -------------------------------- | -------------------------------------------------------------- |
+| `--netzi-ease-swing` | `cubic-bezier(0.42, 0, 0.58, 1)` | lo que va y vuelve: latidos, barridos, brillos (`ease-in-out`) |
+| `--netzi-ease-spin`  | `cubic-bezier(0, 0, 1, 1)`       | lo que gira sin fin a velocidad constante (`linear`)           |
+
+Los bucles **no cambian** con `prefers-reduced-motion`: una duración de bucle no para una
+animación infinita. Cada componente quita su bucle o lo cambia por un latido de opacidad en
+su propia regla reducida:
+
+```css
+.cargando {
+  animation: giro var(--netzi-duration-loop-spin) var(--netzi-ease-spin) infinite;
+}
+@media (prefers-reduced-motion: reduce) {
+  .cargando {
+    animation: latido var(--netzi-duration-loop-pulse) var(--netzi-ease-swing) infinite;
+  }
+}
+```
+
+### Desplazamiento y fundido: dos familias, un solo sitio para el movimiento reducido
+
+Con `prefers-reduced-motion: reduce` lo que **se desplaza, gira, escala o cambia de
+geometría** no debe moverse (WCAG 2.3.3), pero un cambio de color o de opacidad no es
+movimiento y puede seguir suavizándose. Por eso hay dos familias:
+
+- `--netzi-duration-{instant,fast,base,slow}` son las de los **fundidos** (color, fondo,
+  borde, sombra, opacidad). No cambian con la preferencia.
+- `--netzi-duration-move-{fast,base,slow}` son las del **desplazamiento** (`transform`,
+  `translate`, `rotate`, `scale`, `top`/`left`, alturas, filas de rejilla, márgenes). Valen
+  lo mismo que su fundido, y bajo `@media (prefers-reduced-motion: reduce)` `tokens.css` las
+  pone a `0.01ms` **en un solo bloque**: todo lo que las usa salta a su estado final.
+
+Van a `0.01ms` y no a `0` para que `transitionend` y `animationend` sigan llegando a quien
+los espera (con duración cero no hay transición y el evento no se dispara nunca).
+
+```css
+.panel {
+  transition:
+    transform var(--netzi-duration-move-slow) var(--netzi-ease-enter),
+    opacity var(--netzi-duration-slow) var(--netzi-ease-enter);
+}
+/* Con reduce, el panel ya no se desliza (salta) pero sigue apareciendo con un fundido:
+   no hace falta escribir ninguna regla @media. */
+```
+
+Para cambiar el ritmo en tu app, redefine `--netzi-duration-{fast,base,slow}`: las `move`
+apuntan a ellas y las siguen, y el bloque de movimiento reducido las sigue anulando. Si
+redefines un token `move` directamente, tu regla de `:root` gana a la de `tokens.css` también
+con la preferencia, así que repite la anulación en tu propio `@media`:
+
+```css
+:root {
+  --netzi-duration-move-slow: 320ms;
+}
+@media (prefers-reduced-motion: reduce) {
+  :root {
+    --netzi-duration-move-slow: 0.01ms;
+  }
+}
+```
+
+Una transición que mueve con una duración de **fundido** sí sigue moviéndose con la
+preferencia: elige la familia por lo que anima, no por cuánto dura. Si una capa mezcla
+las dos (`transition: 0.15s`, que es `all`), necesita su propia regla reducida. Las
+**animaciones** con `@keyframes` también: la duración de una animación infinita no la para.
+En `@netzi/ui` lo vigilan dos guardianes: el de movimiento reducido entiende estos tokens
+(una transición que solo mueve con `move` ya está reducida) y otro falla con cualquier
+duración o curva literal en las hojas del kit, también en los bucles (solo pasan `0s` y el
+`0.01ms` de la regla reducida).
+
+La salida DTCG resuelta publica la escala sin la preferencia (tipos `duration` y
+`cubicBezier`): cada plataforma nativa lee el ajuste de movimiento reducido de su sistema.
+
+## Tamaños de ventana (`--netzi-window-*`)
+
+El diseño cambia en cinco **tamaños de ventana con nombre** (ADR 0016 del repo), siempre en
+los mismos cortes. Cada token es el ancho en el que **empieza** ese tamaño:
+
+| Token                        | Valor  | Tamaño      | Ancho        | Paneles |
+| ---------------------------- | ------ | ----------- | ------------ | ------- |
+| (ninguno)                    | 0      | compacto    | < 600 px     | 1       |
+| `--netzi-window-medium`      | 600px  | medio       | 600–839 px   | 1 o 2   |
+| `--netzi-window-expanded`    | 840px  | expandido   | 840–1199 px  | 2       |
+| `--netzi-window-large`       | 1200px | grande      | 1200–1599 px | 2       |
+| `--netzi-window-extra-large` | 1600px | extragrande | ≥ 1600 px    | hasta 3 |
+
+`--netzi-window-reflow` (375px) no es un tamaño: es el corte de **reflujo** dentro de
+compacto. Por debajo (teléfonos de 320 y 360 y el zoom al 400 %, WCAG 1.4.10) lo que va en
+fila dentro de un panel flotante se apila.
+
+Una `var()` no vale dentro de `@media`, así que en una hoja se escribe el número del token,
+siempre en forma de rango y con el mismo sentido:
+
+```css
+/* Compacto: por debajo del medio. */
+@media (width < 600px) {
+}
+/* Del expandido hacia arriba. */
+@media (width >= 840px) {
+}
+```
+
+En `@netzi/ui` un guardián falla con cualquier otro corte de ventana en las hojas del kit.
+Lo que depende de su **propia caja** y no de la ventana (una rejilla que cabe o no en su
+columna) usa una consulta de contenedor con nombre, `@container <nombre> (…)`. En el código,
+`@netzi/ui` exporta los mismos cortes (`NETZI_WINDOW_BREAKPOINTS`) y una señal con el tamaño
+actual (`NetziWindowSizeService`). La salida DTCG resuelta los publica como `dimension` en px.
+
+## Capas (`--netzi-layer-*`)
+
+El orden de apilamiento (`z-index`) sale de una escala con **nombre de intención**: quien
+pinta algo encima dice qué es (un desplegable, un aviso) y la escala decide qué tapa a qué.
+De abajo arriba:
+
+| Token                    | Valor | Para qué                                                                    |
+| ------------------------ | ----- | --------------------------------------------------------------------------- |
+| `--netzi-layer-content`  | 0     | el contenido de la página: el punto de partida                              |
+| `--netzi-layer-sticky`   | 2     | encabezados y columnas fijas (la tabla de datos)                            |
+| `--netzi-layer-bar`      | 20    | lo del marco que pasa sobre el contenido: plegar el menú, la barra de carga |
+| `--netzi-layer-flyout`   | 50    | submenús del menú plegado y menús contextuales anclados al contenido        |
+| `--netzi-layer-scrim`    | 80    | el velo de un panel lateral que se abre encima (el menú en el móvil)        |
+| `--netzi-layer-modal`    | 100   | diálogos y paneles laterales, con su velo dentro                            |
+| `--netzi-layer-dropdown` | 120   | paneles anclados a un control y la paleta de comandos                       |
+| `--netzi-layer-toast`    | 200   | el aviso, que se ve aunque haya un modal o un desplegable abiertos          |
+| `--netzi-layer-tooltip`  | 300   | la etiqueta de lo que tiene el puntero o el foco                            |
+| `--netzi-layer-blocking` | 1000  | la pantalla que bloquea la app hasta resolver algo (sin conexión)           |
+| `--netzi-layer-top`      | 10000 | lo que nunca puede quedar tapado: el enlace «Ir al contenido» con foco      |
+
+Reglas, las mismas que sigue `@netzi/ui` (un guardián falla con cualquier número suelto en
+sus hojas):
+
+- Dentro de la capa de un componente, el orden local va con `-1`, `0` o `1` (la capa de
+  cristal detrás de su panel, una celda fijada sobre las demás).
+- Lo que tiene que quedar justo encima o debajo de otra cosa de su misma capa va un escalón
+  más allá: `calc(var(--netzi-layer-dropdown) + 1)`. Nunca más de uno: si hace falta más,
+  falta una capa en la escala.
+- En `@netzi/ui` cada uso lleva el valor del token como respaldo
+  (`var(--netzi-layer-dropdown, 120)`): sin `tokens.css` el kit apila igual, y el guardián
+  comprueba que el número coincide con el token.
+- Un desplegable dentro de un modal no necesita nada: el modal abre su propio contexto de
+  apilamiento y lo que lleva dentro va en su capa.
+
+```css
+.mi-barra-fija {
+  position: sticky;
+  top: 0;
+  z-index: var(--netzi-layer-bar); /* por encima de los encabezados fijos de la tabla */
+}
+```
+
+Los huecos entre valores dejan sitio a la app: una capa propia entre dos del kit se escribe
+con `calc()` sobre la de debajo. La salida DTCG publica la escala como `number`; en móvil el
+orden lo da la composición, y la escala sirve de referencia si una pieza tiene que ordenar.
+
+## Forma y elevación (`--netzi-radius-*`, `--netzi-elevation-*`)
+
+Radios por **papel**:
+
+| Token                       | Valor  | Compacto | Para qué                                                                    |
+| --------------------------- | ------ | -------- | --------------------------------------------------------------------------- |
+| `--netzi-radius-control`    | 6px    | 5px      | controles y piezas pequeñas: botones, campos, ítems de menú, iconos en caja |
+| `--netzi-radius-surface-sm` | 8px    | 6px      | superficies pequeñas o pegadas a un control: el panel de un select, avisos  |
+| `--netzi-radius-surface`    | 10px   | 8px      | superficies: tarjetas, diálogos, popovers, paneles                          |
+| `--netzi-radius-pill`       | 9999px | 9999px   | lo del todo redondeado: píldoras, puntos, avatares, interruptores           |
+
+En una pieza cuadrada, `pill` es un círculo; en una alargada, una píldora. Sustituye a los
+`999px` y `50%` sueltos, y la densidad no lo toca.
+
+La elevación dice **cuánto se despega** una pieza de lo que tiene debajo, con nombre de
+intención y de menos a más:
+
+| Token                        | Para qué                                                                         |
+| ---------------------------- | -------------------------------------------------------------------------------- |
+| `--netzi-elevation-base`     | pegado a su superficie, sin sombra: para devolver a cero lo que la hereda        |
+| `--netzi-elevation-raised`   | levantado sobre su superficie: el pulgar de un interruptor, una tecla            |
+| `--netzi-elevation-floating` | pequeño y suelto sobre el contenido: el tooltip, la etiqueta de una gráfica      |
+| `--netzi-elevation-modal`    | lo que se abre encima y lo aparta: desplegables, menús, aviso, diálogos, paneles |
+
+```css
+.mi-tarjeta-flotante {
+  border: 1px solid var(--netzi-border);
+  border-radius: var(--netzi-radius-surface);
+  box-shadow: var(--netzi-elevation-floating);
+}
+.mi-punto {
+  border-radius: var(--netzi-radius-pill);
+}
+```
+
+Una sombra **nunca es lo único** que separa una capa: lleva su borde. En oscuro las sombras son
+más densas, en contraste alto `raised` se marca más y en papel no hay ninguna. La salida DTCG
+publica los mismos niveles (tipo `shadow`): en móvil cada plataforma pinta el nivel a su
+manera.
+
+## Tema claro / oscuro
+
+El tema se controla con el atributo `data-theme` en un ancestro (normalmente `<html>`):
+
+```html
+<html data-theme="dark">
+  ...
+</html>
+```
+
+Sin el atributo, aplica el tema claro (`:root`). Con `data-theme="light"`, una sección vuelve
+al claro dentro de una página oscura (#237): pinta lo mismo que una página clara con el preset,
+el contraste y el cristal de la página. Si tu app redefine tokens en `:root` para el claro,
+ponlos también en `[data-theme='light']`, como haces en `[data-theme='dark']` para el oscuro.
+
+## Impresión
+
+Al imprimir, el papel sale claro, opaco y quieto sin que la app haga nada:
+
+- Los bloques que fijan `data-theme`, `data-glass` o `data-ambient` van en
+  `@media not print`: en papel no aplican y sale el tema claro y opaco, con el preset, el
+  contraste alto y la densidad intactos.
+- En `@media print`, la raíz pierde las sombras y el desenfoque del velo, y cada duración
+  baja a `0.01ms`.
+- El bloque de papel se declara en la raíz y en `[data-contrast='high']`, que redefine la
+  sombra pequeña: una sección con su propio contraste alto tampoco imprime sombras.
+- El contrato de contraste se comprueba también en papel: un color que el contexto de
+  impresión redefina y no llegue a su mínimo rompe el build.
+- `base.css` pone el papel en blanco, subraya los enlaces (en blanco y negro el color no los
+  distingue) y quita animaciones y transiciones a medio camino.
+- Con el atributo `data-print-urls` en un enlace o en un contenedor, cada enlace externo
+  imprime su dirección detrás. Es opcional: en toda la página llenaría de direcciones el menú.
+
+En `@netzi/ui`, el marco de `netzi-layout` y las capas flotantes no se imprimen. Un modal o
+un drawer abierto sí: una vez, sin el velo y en el flujo de la página, donde está el
+componente, sin tapar nada. Fijo, el navegador lo repetiría encima de cada hoja, y puede ser
+justo lo que se quiere en papel (un recibo).
+
+Lo propio de la app que no va en papel se oculta con su regla `@media print`. Si redefines
+un token del tema oscuro en tu hoja, envuélvelo también en `@media not print`.
+
+## Overrides (white-label por app)
+
+El mecanismo de personalización **sobrevive a las actualizaciones**: redefine los
+tokens que quieras en tu propio scope. Las nuevas versiones de `@netzi/tokens`
+cambian solo los _defaults_; nunca pisan lo que tu app sobreescribe.
+
+```css
+/* tema de la app "Acme": radios propios */
+:root {
+  --netzi-radius: 8px;
+  --netzi-radius-lg: 14px;
+}
+```
+
+El movimiento se personaliza por las duraciones de fundido (`--netzi-duration-{fast,base,slow}`),
+que arrastran a las de desplazamiento. Redefinir un `--netzi-duration-move-*` obliga a repetir
+su `0.01ms` dentro de tu `@media (prefers-reduced-motion: reduce)`: ver «Movimiento».
+
+Los colores no se cambian de uno en uno: cada token de color se pinta encima o
+debajo de otro, y cambiar solo uno rompe el par. Para poner el color de tu marca,
+sigue el contrato de la sección siguiente.
+
+## Estados de interacción
+
+Hover, foco, presionado, arrastrado, seleccionado y deshabilitado son un solo sistema (#156).
+Cada estado es una **capa** translúcida del color del texto que se pinta encima del fondo del
+control, sin cambiarlo; la opacidad va aparte para quien pinte la capa con su propio color:
+
+| Token                            | Opacidad | Para qué                                             |
+| -------------------------------- | -------- | ---------------------------------------------------- |
+| `--netzi-state-hover`            | 0.08     | El puntero encima                                    |
+| `--netzi-state-focus`            | 0.12     | Lo enfocado dentro de un compuesto (más su anillo)   |
+| `--netzi-state-pressed`          | 0.12     | Mientras se pulsa, con el ratón o con el dedo        |
+| `--netzi-state-dragged`          | 0.16     | La pieza que se lleva con el puntero                 |
+| `--netzi-state-selected`         | —        | Lo seleccionado: el tinte del primario               |
+| `--netzi-state-disabled-opacity` | 0.6      | Lo deshabilitado, sobre el control entero            |
+| `--netzi-primary-pressed`        | —        | El relleno de marca presionado (cada preset el suyo) |
+
+```css
+.mi-control:active:not(:disabled) {
+  background-image: linear-gradient(var(--netzi-state-pressed), var(--netzi-state-pressed));
+}
+```
+
+Como imagen de fondo la capa no se interpola: aparece al instante, también con movimiento
+reducido. El build comprueba que `--netzi-text` llega a 4.5:1 sobre cada superficie con
+cualquier capa encima y que el texto deshabilitado se queda a 3:1. Un relleno de marca no lleva
+la capa (acercaría el fondo a su tinta): usa `--netzi-primary-pressed`.
+
+## Marca propia (`@netzi/tokens/brand`)
+
+La marca va en el **primario**, no en `--netzi-blue`. `--netzi-blue` es un acento de
+Netzi y además el color de estado `--netzi-info`, y `--netzi-on-accent` (la tinta de
+los contadores y de los rellenos de acento) se mide sobre él: cambiarlo a un morado
+deja esa tinta en 3.35:1. Si aun así lo cambias, redefine con él `--netzi-blue-text`,
+`--netzi-blue-dark` y `--netzi-on-accent`, y comprueba el contraste de los tres.
+
+### El contrato: ocho tokens que se redefinen juntos
+
+| Token                     | Papel                                         | Se mide sobre                                   | Mínimo |
+| ------------------------- | --------------------------------------------- | ----------------------------------------------- | ------ |
+| `--netzi-primary`         | Relleno de marca: botón, interruptor, barra   | (fondo de `on-primary`)                         | —      |
+| `--netzi-primary-hover`   | El relleno al pasar el puntero                | (fondo de `on-primary`)                         | —      |
+| `--netzi-primary-pressed` | El relleno presionado (#156)                  | (fondo de `on-primary`)                         | —      |
+| `--netzi-on-primary`      | Tinta sobre el relleno, su hover y presionado | `primary`, `primary-hover`, `primary-pressed`   | 4.5:1  |
+| `--netzi-primary-dark`    | Relleno de lo marcado (checkbox, radio)       | cada superficie                                 | 3:1    |
+| `--netzi-on-primary-dark` | Tinta sobre el primario oscuro (blanco)       | `primary-dark`                                  | 3:1    |
+| `--netzi-primary-text`    | El primario que se lee (enlaces, ítem activo) | cada superficie y `primary-tint` sobre cada una | 4.5:1  |
+| `--netzi-primary-graphic` | Lo no textual que comunica (progreso, anillo) | cada superficie y `primary-tint` sobre cada una | 3:1    |
+
+Lo demás sale solo del primario: los tintes (`--netzi-primary-tint`, 10 % en claro y
+15 % en oscuro; `--netzi-primary-tint-strong`, 22 % y 28 %), el anillo de foco
+(`--netzi-focus-ring` es `--netzi-primary-text`) y el fondo ambiental. Pero el
+relleno también se mide por ellos: `--netzi-text` tiene que llegar a 4.5:1 sobre el
+tinte marcado y el pulgar de las barras de desplazamiento (`--netzi-text-2`) a 3:1
+sobre el suave. Todo en claro y en oscuro, sobre `bg`, `surface`, `surface-2` y
+`surface-3`; el alto contraste no cambia el primario y solo sube los textos.
+
+### Derivarlo de un color
+
+`deriveBrand` devuelve los ocho tokens de cada modo ya calibrados. El relleno es tu
+color tal cual mientras alguna de las dos tintas del kit (`#04121f` o blanco) llegue a
+4.5:1 encima; en los tonos medios no llega ninguna, y entonces se mueve al tono más
+cercano que sí (`adjusted: true`). El texto, el gráfico y el primario oscuro son el
+tono más cercano al relleno que llega a su mínimo en cada modo; el hover oscurece lo
+justo para notarse sin perder la tinta, y el presionado es el hover con la capa de
+presionado (12 %) del extremo contrario a la tinta, que la aleja en vez de acercarla.
+
+```js
+import { brandVariables, deriveBrand, validateBrand } from '@netzi/tokens/brand';
+
+const marca = deriveBrand('#6c3cff'); // { color, adjusted, light, dark }
+validateBrand(marca).ok; // true
+brandVariables(marca.dark); // { '--netzi-primary': '#6c3cff', '--netzi-primary-text': '#9f80ff', … }
+```
+
+En CSS, el resultado para el morado de «Acme». Carga esta hoja **después** de
+`@netzi/tokens` y no pongas `data-preset`, que redefine el primario:
+
+<!-- ejemplo-marca -->
+
+```css
+/* Marca "Acme": deriveBrand('#6c3cff') de @netzi/tokens/brand */
+[data-theme='light'],
+:root {
+  --netzi-primary: #6c3cff;
+  --netzi-primary-hover: #5f35e0;
+  --netzi-primary-pressed: #542fc5;
+  --netzi-primary-dark: #6c3cff;
+  --netzi-primary-text: #693af7;
+  --netzi-primary-graphic: #6c3cff;
+  --netzi-on-primary: #ffffff;
+  --netzi-on-primary-dark: #ffffff;
+}
+
+[data-theme='dark'] {
+  --netzi-primary: #6c3cff;
+  --netzi-primary-hover: #5f35e0;
+  --netzi-primary-pressed: #542fc5;
+  --netzi-primary-dark: #764aff;
+  --netzi-primary-text: #9f80ff;
+  --netzi-primary-graphic: #7f55ff;
+  --netzi-on-primary: #ffffff;
+  --netzi-on-primary-dark: #ffffff;
+}
+```
+
+La regla clara va también en `[data-theme='light']`: el paquete vuelve a declarar ahí los
+valores claros de las capas para una sección clara dentro de una página oscura (#237), y sin
+ella la sección perdería la marca. Un test del paquete lee este bloque: si deja de cumplir, o
+de ser lo que da `deriveBrand('#6c3cff')`, la suite se pone roja.
+
+### Validar una marca hecha a mano
+
+`validateBrand({ light, dark })` mide cada par del contrato y devuelve
+`{ ok, checks, failures }`; cada fallo dice el modo, la tinta, el fondo, el ratio y el
+mínimo. Lanza `TypeError` si falta un modo o un token no es `#rgb` o `#rrggbb`. Mide contra las
+superficies del tema por defecto: si tu app redefine también las superficies, ya no
+es este contrato, y conviene medir el resultado en la página. Sobre las capas de
+**cristal** el texto se lee contra lo que haya detrás; el kit lo comprueba para sus
+presets, no para una marca propia.
+
+En Angular, `@netzi/ui` lo hace por ti: `provideNetziBrand('#6c3cff')` (o
+`NetziThemeService.setBrand`) deriva la marca, la escribe en una hoja propia por encima
+del preset (en claro, en cada sección clara y en cada sección oscura) y, en desarrollo, avisa en la consola si el color no cumple tal cual.
+
+El contrato no es una copia: un test del paquete mete lo que deriva `deriveBrand` en la
+fuente DTCG y le pasa el mismo contrato de contraste que el build, en claro, oscuro y
+alto contraste.
+
+## Catálogo de tokens
+
+| Grupo       | Tokens                                                                                                                                              |
+| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Estado      | `--netzi-info` `--netzi-success` `--netzi-warning` `--netzi-danger` (+ su `-text`)                                                                  |
+| Superficies | `--netzi-bg` `--netzi-surface` `--netzi-surface-2` `--netzi-surface-3`                                                                              |
+| Bordes      | `--netzi-border` `--netzi-border-2`                                                                                                                 |
+| Flotantes   | `--netzi-float-bg` `--netzi-float-border` `--netzi-float-border-2` `--netzi-float-surface` (`-2`, `-3`) `--netzi-float-filter` `--netzi-float-glow` |
+| Velo modal  | `--netzi-scrim` `--netzi-scrim-filter`                                                                                                              |
+| Lente       | `--netzi-float-lens` `--netzi-float-lens-size` (opt-in, ver abajo)                                                                                  |
+| Texto       | `--netzi-text` `--netzi-text-2` `--netzi-text-3` `--netzi-on-accent`                                                                                |
+| Elevación   | `--netzi-elevation-{base,raised,floating,modal}`                                                                                                    |
+| Acento      | `--netzi-tint` `--netzi-primary-tint` `--netzi-primary-tint-strong`                                                                                 |
+| Forma       | `--netzi-radius-control` `--netzi-radius-surface` `--netzi-radius-surface-sm` `--netzi-radius-pill`                                                 |
+| Controles   | `--netzi-control-h-{sm,md,lg}` `--netzi-control-px-*` `--netzi-control-fs-*` `--netzi-touch-target` `--netzi-touch-gap`                             |
+| Tipografía  | `--netzi-font-sans` `--netzi-font-mono` `--netzi-font-scale` `--netzi-typography-*` `--netzi-measure`                                               |
+| Espaciado   | `--netzi-space-{related,group,stack,section,page}` `--netzi-space-inset` (`-sm`, `-lg`)                                                             |
+| Movimiento  | `--netzi-duration-{instant,fast,base,slow}` `--netzi-duration-move-{fast,base,slow}` `--netzi-ease-{standard,enter,exit}`                           |
+| Capas       | `--netzi-layer-{content,sticky,bar,flyout,scrim,modal,dropdown,toast,tooltip,blocking,top}`                                                         |
+
+El catálogo son los tokens **públicos**: los que puedes usar y redefinir. La lista exacta va
+en el paquete (`public-tokens.json`, ver «Públicos e internos»).
+
+Un token que **no** existe no da error: la declaración entera se descarta y el elemento se
+queda sin fondo, sin color o sin radio, sin aviso en build ni en consola. Por eso cada papel
+tiene **un solo nombre**: los sinónimos que había están en desuso (ver abajo).
+
+### Un panel de cristal entra por transición, nunca por animación
+
+Una animación CSS terminada se queda retenida en el elemento y, si animó
+`opacity`, Chromium deja el panel compuesto como su propia raíz de fondo: el
+`backdrop-filter` de su capa de cristal solo ve el fondo del propio panel y la
+página se lee nítida a través de él. Por eso todos los paneles del kit entran con
+`transition` + `@starting-style`, y un guardián de la suite lo vigila. Si añades
+una capa de cristal nueva, no le pongas `@keyframes` de entrada.
+
+### La lente del canto, y por qué es opt-in
+
+Con `data-glass-lens="on"` en la raíz, el borde de las capas modales (modal,
+drawer, paleta ⌘K) lleva **su propio desenfoque**, más fuerte que el del interior:
+es lo que da sensación de espesor.
+
+No es refracción de verdad —el fondo no se curva— y **hoy no puede serlo**:
+Chromium acepta `backdrop-filter: url(#filtro-svg)` y luego lo ignora (el mismo
+filtro como `filter` normal sí deforma, así que el problema es el
+`backdrop-filter`, no el filtro), y Safari ni lo acepta.
+
+Es opt-in porque **cuesta**: es una segunda capa de `backdrop-filter`. Medido con
+el fondo en movimiento:
+
+| escenario                            | fps   |
+| ------------------------------------ | ----- |
+| una capa con cristal                 | 60    |
+| una capa con cristal **+ lente**     | 60    |
+| tres capas apiladas                  | 30-38 |
+| tres capas apiladas **+ lente**      | 26    |
+| capa con lente, con el shell apagado | 51    |
+
+Con una sola capa en pantalla sale gratis; apilada, se nota. La última fila es
+un experimento **descartado**: apagar el filtro del topbar y del sidebar bajo una
+capa modal daba esos frames, pero el velo es translúcido y el salto de tono del
+shell se veía al abrir. `NetziOverlayService` y su marca `data-netzi-overlay="open"`
+se quedan para que la app reaccione a «hay algo encima» (pausar una animación
+cara, un vídeo de fondo).
+
+### Estados y tintes: relleno o texto, nunca los dos
+
+`--netzi-success` y compañía son **relleno** (un punto de estado, un fondo). Para texto va su
+`-text`, que es la versión que llega a 4.5:1. Con los tintes del primario pasa lo mismo por otro
+lado: `--netzi-primary-tint` (10 %) es para superficies grandes y aguanta `--netzi-primary-text`
+justo; en una pieza pequeña se pierde contra el fondo, y para eso está
+`--netzi-primary-tint-strong` (22 %), cuya tinta es `--netzi-text`.
+
+Lo mismo vale para el primario y los acentos a secas: `--netzi-primary`,
+`--netzi-blue`, `--netzi-green`… son **relleno** y no llegan a 4.5:1 como texto
+sobre fondo claro (`--netzi-blue` da 2.54:1 sobre el fondo y 2.68:1 sobre blanco;
+`--netzi-primary-dark` baja a 4.23:1 en `surface-3`). Si se lee, va
+`--netzi-primary-text` o el `-text` del color, que están calibrados por tema y por
+preset. Es lo que le pasó al botón `soft` (#56).
+
+Y un relleno del primario tiene **dos fondos oscuros** según lo que lleve encima.
+`--netzi-primary-hover` es el del estado hover de un botón relleno: su tinta es la
+misma `--netzi-on-primary` del reposo, y cada preset lo calibra para que no baje de
+4.5:1 (5.4:1 en azul). `--netzi-primary-dark` es el fondo de lo que lleva **blanco**
+(`--netzi-on-primary-dark`): la pista de un interruptor encendido, la marca de un
+checkbox. Si se cruzan, la tinta oscura sobre el azul oscuro se queda en 3.9:1 (#68).
+
+### Lo no textual que comunica: `--netzi-primary-graphic`
+
+El relleno de una barra de progreso, un anillo de carga, una barra de navegación: no son
+texto, pero dicen algo, y WCAG 1.4.11 les pide **3:1** frente a lo que tienen al lado. El
+primario crudo no llega en claro con azul (2.15:1 en el peor fondo), verde (1.36), naranja
+(1.78), rojo (2.51) ni cian (1.92). `--netzi-primary-graphic` es el tono más cercano al
+primario que llega a 3:1 sobre cada superficie y sobre `--netzi-primary-tint` (el fondo de un
+ítem activo), calibrado por preset y por tema; su contrato `non-text` lo comprueba el build en
+las 24 combinaciones (#140). `--netzi-primary-text` también cumple, pero se aleja más del
+color de marca.
+
+Dos casos en que no basta:
+
+- **Lo que late en opacidad.** En el valle del latido el color se mezcla con el fondo y
+  baja; con el valle de `netzi-progress` (0,75) `--netzi-primary-graphic` se queda por debajo de
+  3:1. Lo que late va con `--netzi-primary-text`, que deja margen.
+- **Los colores de estado.** Una barra de éxito, aviso o error va con su `-text`
+  (`--netzi-success-text`…) o con su `-graphic` (abajo): el crudo da 1.43:1 (verde) o
+  1.50:1 (amarillo) en claro.
+
+Un degradado cuenta en cada punto que se ve: si se desvanece hasta transparente, su cola
+baja de cualquier mínimo. El del kit va de un primario que cumple a otro que cumple.
+
+### Lo no textual de un estado: `--netzi-*-graphic` y `--netzi-*-veil`
+
+La estrella marcada, el punto de presencia de un avatar, el borde de un campo inválido o el
+icono de un resultado también son no textuales que comunican, y el crudo del estado no llega
+en claro: azul 2.08:1, verde 1.33, amarillo 1.41 y rojo 2.15 en el peor fondo (#189). Cada
+estado tiene su gráfico, el tono más cercano al crudo que llega a **3:1** sobre cada superficie
+y sobre su propio velo. En oscuro el crudo ya cumple y es su valor.
+
+| Token                     | Claro     | Oscuro    | Velo (14 %)            |
+| ------------------------- | --------- | --------- | ---------------------- |
+| `--netzi-info-graphic`    | `#0e84cd` | `#0ba5ff` | `--netzi-info-veil`    |
+| `--netzi-success-graphic` | `#069047` | `#0ae972` | `--netzi-success-veil` |
+| `--netzi-warning-graphic` | `#9d7a0c` | `#f0c040` | `--netzi-warning-veil` |
+| `--netzi-danger-graphic`  | `#df464b` | `#ff6b6b` | `--netzi-danger-veil`  |
+
+Los alias de estado apuntan a los de marca (`--netzi-blue-graphic`, `--netzi-green-graphic`,
+`--netzi-yellow-graphic`, `--netzi-red-graphic`), como los `-text`. El velo es el fondo redondo
+de un icono de estado: el contrato `non-text` de cada gráfico lo mide compuesto sobre cada
+superficie, en las 24 combinaciones de modo, contraste y preset. Si pones un icono sobre una
+mezcla más opaca, ya no está medido.
+
+### Con el dedo, objetivos de 44 px (`--netzi-touch-target`)
+
+Con puntero táctil (`@media (pointer: coarse)`) nada de lo que se toca en un campo baja de
+`--netzi-touch-target` (44 px, WCAG 2.5.5). Los tokens suben `--netzi-control-h-sm` y
+`--netzi-control-h-md` a 46 px también con la densidad compacta (el borde de 1 px del
+contenedor no le quita al input), y cada componente agranda lo suyo: filas de casillas y
+radios, opciones, días del calendario, chips, estrellas, la franja de los sliders… Los
+iconos pequeños (las × de los chips, la flecha de un desplegable) amplían solo su zona de toque, sin mover
+el dibujo. Con ratón no cambia nada. Una app que ponga controles propios puede usar el
+mismo token en su `@media (pointer: coarse)`.
+
+Entre dos objetivos vecinos queda además `--netzi-touch-gap` (8 px, criterio A.5 de la
+política 17), medido entre zonas de toque y no entre dibujos: botones de la paginación,
+estrellas, pestañas, chips, celdas, días del calendario, ítems de un menú, la barra del
+editor… Las piezas de un control segmentado se tocan a propósito y quedan fuera, como pide
+la política. También quedan fuera, mientras la política no las recoja (#226), las piezas de
+un campo de una línea (el input y su botón: −/+, el ojo, la flecha del desplegable) y las
+opciones de una lista. El token es para usarlo en un `@media (pointer: coarse)` propio; con
+ratón, cada componente conserva su hueco.
+
+### El foco va con `--netzi-focus-ring`, no con el primario
+
+Un indicador de foco, contorno o borde, tiene que llegar a **3:1** sobre el fondo (WCAG
+1.4.11). El primario no llega en claro con azul (2.7:1), verde (1.6), naranja (2.2) ni cian
+(2.4). `--netzi-focus-ring` se apoya en `--netzi-primary-text`, que cada preset y cada tema
+calibran a 4.5:1 sobre las superficies, también en alto contraste. Se declara en la raíz y
+en cada elemento con `data-theme` o `data-preset`, así que una sección oscura dentro de una
+página clara tiene su propio anillo.
+
+Todo `:focus`, `:focus-visible` y `:focus-within` del kit lo usa como contorno o borde (los
+halos del tinte no cuentan: dan 1.1:1). Dos guardianes de la suite del kit impiden volver
+al primario y quitar el contorno sin poner otro indicador (#76).
+
+Sobre una capa de **cristal** el anillo se ve contra lo que haya detrás: sobre el fondo del
+kit cumple, pero con una imagen muy oscura (en claro) o muy clara (en oscuro) debajo puede
+bajar de 3:1. Si la app pone cristal sobre fondos así, conviene darle a esa capa un tinte
+más opaco.
+
+## Los tres niveles de texto
+
+Tienen **papeles distintos**, no son tres grados de gris intercambiables. El ratio
+es el peor de las cuatro superficies del tema (`bg`, `surface`, `surface-2`,
+`surface-3`); `surface-3` es siempre el caso malo.
+
+| Token            | Claro  | Oscuro | Para qué                                                                           |
+| ---------------- | ------ | ------ | ---------------------------------------------------------------------------------- |
+| `--netzi-text`   | 13.7:1 | 15.2:1 | Títulos, valores y cuerpo.                                                         |
+| `--netzi-text-2` | 4.8:1  | 5.0:1  | **Cualquier** texto secundario: rótulos, ayudas, pies, metadatos, placeholders.    |
+| `--netzi-text-3` | 3.2:1  | 3.3:1  | **No textual**: iconos decorativos, chevrons, separadores, líneas, deshabilitados. |
+
+WCAG 2.1 pide **4.5:1** para texto normal (SC 1.4.3) y **3:1** para lo no textual
+con significado (SC 1.4.11). Por eso `--netzi-text-3` **no vale para texto**: si
+lo que pintas se lee, va `--netzi-text-2`.
+
+Con `data-contrast='high'` cada nivel toma el valor del de encima: `text-2` sube a
+11.3:1 en claro y 7.2:1 en oscuro, y `text-3` a 4.8:1 y 5.0:1, así que el modo cumple
+incluso donde alguien haya usado `text-3` para un rótulo.
+
+Los ratios no son una promesa del README: cada token que se pinta sobre algo declara en
+la fuente su **contrato de contraste** (texto, 4.5:1; no textual, 3:1; y sobre qué fondos),
+y el build lo comprueba en las 24 combinaciones de modo, contraste y preset antes de
+generar `tokens.css`. Si un valor deja de cumplir, el paquete no se construye. Ver
+«Cómo se genera» al final.
+
+## Capas flotantes y superficies de cristal
+
+Las capas que se pintan **encima** del contenido —topbar, sidebar, paneles
+anclados, modal, drawer, menús y toasts— no usan `--netzi-surface` directamente,
+sino su propio juego de tokens:
+
+| Token                     | Para qué                                        |
+| ------------------------- | ----------------------------------------------- |
+| `--netzi-float-bg`        | Fondo de la capa                                |
+| `--netzi-float-border`    | Su borde                                        |
+| `--netzi-float-border-2`  | Su borde marcado                                |
+| `--netzi-float-surface`   | Lo ANIDADO dentro de la capa: la lámina misma   |
+| `--netzi-float-surface-2` | … a un paso de la lámina (tarjetas, hovers)     |
+| `--netzi-float-surface-3` | … a dos pasos                                   |
+| `--netzi-float-filter`    | Valor de `backdrop-filter` (por defecto `none`) |
+
+Cada capa re-escopa `--netzi-surface`, `-2` y `-3` a los tres `float-surface`, así
+que **todo lo que va dentro** (una tarjeta, la burbuja de un comentario, el hover
+de un botón) hereda el vidrio sin saber que está en una capa. Con cristal son
+tintes translúcidos **oscuros** que se alejan de la lámina un paso, dos y tres
+(una tarjeta es más gris que la lámina, como en opaco). En claro eso resta
+contraste, y por eso `--netzi-text-2` con cristal baja dos niveles (el mismo
+valor que en alto contraste, `#2a333c`); el test de contraste del paquete exige que
+sobre el tinte más fuerte siga por encima de su suelo incluso con negro puro debajo.
+
+Con el cristal apagado valen exactamente lo mismo que los tokens de siempre, así
+que no cambia nada. Con `data-glass="on"` en un ancestro (lo pone
+`NetziThemeService` en `<html>`, y también vale en un scope acotado) esas capas
+pasan a ser translúcidas con el fondo desenfocado y saturado:
+
+```html
+<html data-theme="dark" data-glass="on">
+  ...
+</html>
+```
+
+Las superficies de **contenido** (tarjetas, secciones, tablas) siguen opacas a
+propósito: ahí el cristal solo resta legibilidad.
+
+### Fondo ambiental: darle al cristal algo que desenfocar
+
+Un cristal sobre un fondo liso se ve como una placa gris: no hay nada detrás
+que atravesar. Con `data-ambient="on"` en la raíz (`NetziThemeService.setAmbient`,
+interruptor «Fondo con color» en `netzi-settings`) el layout pinta bajo
+`--netzi-bg` unas manchas de color suaves —el primario del preset, morado y
+verde— que se ven a través del topbar, del sidebar y de cualquier capa que pase
+por encima. Token: `--netzi-ambient` (`none` sin el eje). Los porcentajes son
+bajos y el texto se sigue leyendo encima (`--netzi-text-3` sobre la mancha más
+fuerte: 4.4:1 en claro, 4.6:1 en oscuro). En alto contraste se apaga solo.
+
+```html
+<html data-theme="dark" data-glass="on" data-ambient="on"></html>
+```
+
+**El suelo de contraste no lo pone solo el alfa.** Sobre cristal el texto se lee
+contra lo que haya debajo, que cambia al scrollear, así que el caso a cumplir es
+el fondo más contrario posible. Taparlo con opacidad exige un alfa de 0.82, y a
+0.82 esto ya no parece cristal; por eso el filtro **acota el fondo** antes de
+componerlo:
+
+| función          | qué hace                                                       |
+| ---------------- | -------------------------------------------------------------- |
+| `saturate(180%)` | aviva el color de debajo al difuminarse (lo vistoso)           |
+| `contrast(0.6)`  | comprime el rango del fondo hacia el gris medio                |
+| `brightness()`   | lo empuja al tono de la capa: `1.5` en claro, `0.66` en oscuro |
+| `blur(28px)`     | lo difumina; cuanto más ancho, más vidrio esmerilado           |
+
+Bastan **0.44** de alfa y brillo 1.25 en claro,
+**0.12** y brillo 0.56 en oscuro, 10 px de desenfoque en los dos. El precio es
+el plano contrario puro debajo (negro en claro, blanco en oscuro): ahí el texto
+secundario se queda en **4.1-4.2:1**, y el primario no baja de 4.5:1
+nunca; contra el fondo del kit y contra un gris medio, ambos pasan de 6:1. El test de
+contraste del paquete modela la cadena entera, no solo el alfa: tocar cualquiera de sus
+funciones mueve el veredicto.
+
+Degradación automática, sin JS y sin polyfill: con
+`prefers-reduced-transparency: reduce` y donde no haya `backdrop-filter`, la
+superficie opaca de siempre.
+
+## Públicos e internos
+
+`tokens.css` declara todo lo que el kit necesita, pero no todo es para las apps. Cada token de
+la fuente dice si es **público** (el contrato: lo puedes usar y redefinir, y cambiarlo de
+forma incompatible sigue el procedimiento de desuso) o **interno** (materia prima de la fuente
+o pieza del kit: puede cambiar o desaparecer en cualquier versión).
+
+- La capa **semántica** es pública entera: superficies, texto, bordes, primario, estados,
+  elevación, capas, espaciado y radios por papel, estilos de texto, familias, duraciones y
+  curvas.
+- Las **primitivas** son internas: son la materia prima de la fuente (política 17). Los colores
+  de marca crudos (`blue`, `green`, `yellow`, `red`, `purple` y `blue-dark`) se usan por el
+  primario y los estados, que siguen al preset y al contraste alto, y `radius-full` por
+  `radius-pill`. Las escalas con nombre de paso (espacio, radios, tamaños, pesos e
+  interlineados) siguen públicas **en desuso** mientras convive su retirada (ver abajo).
+- Las de **componente** son internas salvo las que el kit ofrece: capas flotantes, velo,
+  controles, objetivo táctil, anillo de foco, paleta de gráficas y fondo ambiental. Quedan
+  internos los pulgares de los interruptores y de las barras de desplazamiento.
+
+La lista va en el paquete, generada por el build en el orden de la fuente:
+
+```js
+import publicos from '@netzi/tokens/public-tokens.json' with { type: 'json' };
+
+// [{ name: '--netzi-primary-text', path: 'primary.text', layer: 'semantic' }, …]
+const nombres = new Set(publicos.tokens.map((t) => t.name));
+```
+
+Cada entrada lleva su custom property, su ruta en la fuente (el nombre canónico), su capa
+(`theme` si solo existe en un tema, como la lente del cristal) y, si está en desuso, el
+aviso. La salida DTCG resuelta marca lo mismo en `$extensions["tech.netzi"].visibility`. Un
+test del paquete falla si este README, el contrato de marca o el sustituto de un token en
+desuso dependen de un nombre que no sea público.
+
+## En desuso
+
+Un token en desuso sigue saliendo en `tokens.css` con el mismo valor que su sustituto
+(apunta a él), así que nada se rompe al actualizar; convive al menos una beta publicada y se
+retira en un cambio incompatible propio, con su guía de migración (ADR 0012). Mientras
+tanto lo marcan:
+
+- `$deprecated` en la fuente DTCG y en la salida resuelta, con el sustituto y la versión;
+- un comentario `/* deprecated: … */` encima de su declaración en `tokens.css`;
+- el build, que los lista cada vez que corre;
+- y esta tabla.
+
+Cuando el paquete llega a la versión de retirada (o la pasa), el build **avisa sin fallar**:
+«el token X debía retirarse en @netzi/tokens 0.1.0-beta.11; retíralo o mueve la versión». Es
+el recordatorio de que el sinónimo ya ha convivido lo que tocaba; retirarlo es un cambio
+incompatible propio, y el momento lo decide quien corta la release.
+
+| En desuso           | Usa                          | Deprecado en                  | Se retira, como pronto        |
+| ------------------- | ---------------------------- | ----------------------------- | ----------------------------- |
+| `--netzi-surface-1` | `--netzi-surface`            | `@netzi/tokens 0.1.0-beta.10` | `@netzi/tokens 0.1.0-beta.11` |
+| `--netzi-text-1`    | `--netzi-text`               | `@netzi/tokens 0.1.0-beta.10` | `@netzi/tokens 0.1.0-beta.11` |
+| `--netzi-radius-md` | `--netzi-radius-surface-sm`  | `@netzi/tokens 0.1.0-beta.10` | `@netzi/tokens 0.1.0-beta.11` |
+| `--netzi-shadow-sm` | `--netzi-elevation-raised`   | `@netzi/tokens 0.1.0-beta.10` | `@netzi/tokens 0.1.0-beta.11` |
+| `--netzi-shadow`    | `--netzi-elevation-floating` | `@netzi/tokens 0.1.0-beta.10` | `@netzi/tokens 0.1.0-beta.11` |
+| `--netzi-shadow-lg` | `--netzi-elevation-modal`    | `@netzi/tokens 0.1.0-beta.10` | `@netzi/tokens 0.1.0-beta.11` |
+
+El nombre canónico de cada papel es la raíz de su grupo (`surface`, `text`), que es el que usa
+la política de diseño como nombre de ruta; el radio medio es el de una superficie pequeña. Para migrar basta con buscar y
+sustituir: `var(--netzi-surface-1)` por `var(--netzi-surface)`, y lo mismo con los demás.
+`@netzi/ui` y el playground ya solo usan los canónicos, y un guardián lo vigila.
+
+Las sombras de antes (`shadow-sm`, `shadow`, `shadow-lg`) pasan a la escala de elevación
+(#220): mismo valor en cada tema, con nombre de intención. Como el anillo de foco, se vuelven a
+declarar en cada sección con su propio tema o contraste, así que siguen al tema igual que
+antes. Lo mismo hacen los otros tres sinónimos.
+
+### Escalas que pasan a internas
+
+La política de diseño reserva las primitivas a la fuente: una app usa papeles. Las escalas con
+nombre de paso eran públicas porque este README las enseñaba; desde `@netzi/tokens`
+`0.1.0-beta.10` cada una tiene su papel y la escala está en desuso para las apps (#228). No
+desaparecen: los papeles se apoyan en ellas, así que siguen en `tokens.css` con su valor y, al
+retirarse, **pasan a internas** (salen de `public-tokens.json` y pueden cambiar sin aviso). Se
+marcan igual que un sinónimo (`$deprecated`, el comentario en `tokens.css`, el build, esta
+tabla), y el build avisa cuando el paquete llega a la versión:
+
+| En desuso                    | Usa                                                                    | Deprecado en                  | Pasa a interna, como pronto   |
+| ---------------------------- | ---------------------------------------------------------------------- | ----------------------------- | ----------------------------- |
+| `--netzi-space-0`            | `0`                                                                    | `@netzi/tokens 0.1.0-beta.10` | `@netzi/tokens 0.1.0-beta.11` |
+| `--netzi-space-1`            | `--netzi-space-related` (cambia el valor: 2px no es un paso del ritmo) | `@netzi/tokens 0.1.0-beta.10` | `@netzi/tokens 0.1.0-beta.11` |
+| `--netzi-space-2`            | `--netzi-space-related`                                                | `@netzi/tokens 0.1.0-beta.10` | `@netzi/tokens 0.1.0-beta.11` |
+| `--netzi-space-3`            | `--netzi-space-group`                                                  | `@netzi/tokens 0.1.0-beta.10` | `@netzi/tokens 0.1.0-beta.11` |
+| `--netzi-space-4`            | `--netzi-space-stack` o `--netzi-space-inset-sm`                       | `@netzi/tokens 0.1.0-beta.10` | `@netzi/tokens 0.1.0-beta.11` |
+| `--netzi-space-5`            | `--netzi-space-inset`                                                  | `@netzi/tokens 0.1.0-beta.10` | `@netzi/tokens 0.1.0-beta.11` |
+| `--netzi-space-6`            | `--netzi-space-inset-lg`                                               | `@netzi/tokens 0.1.0-beta.10` | `@netzi/tokens 0.1.0-beta.11` |
+| `--netzi-space-7`            | `--netzi-space-section`                                                | `@netzi/tokens 0.1.0-beta.10` | `@netzi/tokens 0.1.0-beta.11` |
+| `--netzi-space-8`            | `--netzi-space-page`                                                   | `@netzi/tokens 0.1.0-beta.10` | `@netzi/tokens 0.1.0-beta.11` |
+| `--netzi-radius-sm`          | `--netzi-radius-control`                                               | `@netzi/tokens 0.1.0-beta.10` | `@netzi/tokens 0.1.0-beta.11` |
+| `--netzi-radius`             | `--netzi-radius-surface-sm`                                            | `@netzi/tokens 0.1.0-beta.10` | `@netzi/tokens 0.1.0-beta.11` |
+| `--netzi-radius-lg`          | `--netzi-radius-surface`                                               | `@netzi/tokens 0.1.0-beta.10` | `@netzi/tokens 0.1.0-beta.11` |
+| `--netzi-font-size-{xs…3xl}` | el estilo de su papel (`caption` … `display`, arriba)                  | `@netzi/tokens 0.1.0-beta.10` | `@netzi/tokens 0.1.0-beta.11` |
+| `--netzi-font-weight-*`      | el estilo de su papel (`medium` no tiene: `body` cambia el valor)      | `@netzi/tokens 0.1.0-beta.10` | `@netzi/tokens 0.1.0-beta.11` |
+| `--netzi-line-height-*`      | el estilo de su papel (`none` y `relaxed` no tienen: cambia el valor)  | `@netzi/tokens 0.1.0-beta.10` | `@netzi/tokens 0.1.0-beta.11` |
+
+Para migrar el espaciado y los radios basta con buscar y sustituir por el papel de cada uso
+(`var(--netzi-space-3)` por `var(--netzi-space-group)`; el `4` tiene dos papeles, y el que
+toca lo dice el sitio: aire entre grupos o relleno). Para el texto, cambia el trío
+`font-size` + `font-weight` + `line-height` por el atajo del estilo:
+
+```css
+/* Antes */
+.meta {
+  font-size: var(--netzi-font-size-xs);
+  font-weight: var(--netzi-font-weight-semibold);
+  line-height: var(--netzi-line-height-tight);
+}
+/* Después */
+.meta {
+  font: var(--netzi-typography-caption);
+  letter-spacing: var(--netzi-typography-caption-letter-spacing);
+}
+```
+
+Las duraciones, las curvas y las familias no cambian: ya tenían nombre de intención y pasan a
+la capa semántica con el mismo nombre. `@netzi/ui` y el playground ya solo usan los papeles, y
+el mismo guardián de los sinónimos lo vigila.
+
+## Cómo se genera
+
+`tokens.css` **no se escribe a mano**: sale de una fuente única en JSON con el formato del
+W3C Design Tokens Community Group (DTCG 2025.10), con Style Dictionary. La fuente tiene
+tres capas —primitivos (marca y escalas), semánticos (papeles: superficie, texto, borde,
+primario, estado) y de componente (controles, capas flotantes, foco)— y un archivo por eje
+de tema (modo, preset, contraste, cristal, fondo ambiental, densidad, puntero táctil y
+movimiento reducido).
+
+La misma fuente sirve a quien no lee CSS: una salida DTCG ya resuelta, un archivo por
+combinación de modo, contraste y preset, pensada para librerías nativas (Compose,
+SwiftUI). En CSS, las referencias entre tokens se mantienen como `var()`, así que un
+override en tu scope sigue arrastrando a los tokens que se apoyan en el tuyo.
+
+## Versionado
+
+SemVer. Cambiar el **valor** de un token es `minor`/`patch`; **renombrar o quitar**
+un token es `major` (rompe la API pública).