@netzi/tokens 0.1.0-beta.10 → 0.1.0-beta.9

package/README.md

@@ -41,45 +41,38 @@ 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);
+  background: var(--netzi-blue);
+  color: var(--netzi-on-accent);
+  border-radius: var(--netzi-radius);
+  box-shadow: var(--netzi-shadow);
 }
 ```
 
-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.
+Escala de espaciado para gaps y paddings de layout (base 4px). Úsala en vez de
+píxeles/rem sueltos para mantener el ritmo del sistema de diseño.
+
+| Token             | Valor | Compacto |
+| ----------------- | ----- | -------- |
+| `--netzi-space-0` | 0     | 0        |
+| `--netzi-space-1` | 2px   | 2px      |
+| `--netzi-space-2` | 4px   | 4px      |
+| `--netzi-space-3` | 8px   | 8px      |
+| `--netzi-space-4` | 12px  | 10px     |
+| `--netzi-space-5` | 16px  | 12px     |
+| `--netzi-space-6` | 24px  | 20px     |
+| `--netzi-space-7` | 32px  | 28px     |
+| `--netzi-space-8` | 48px  | 40px     |
+
+Bajo `[data-density='compact']` los pasos medios/grandes se reducen (los finos no
+cambian), coherente con la densidad de los controles.
 
 ```css
 .tarjeta {
-  padding: var(--netzi-space-inset);
+  padding: var(--netzi-space-5);
   display: flex;
-  gap: var(--netzi-space-group);
+  gap: var(--netzi-space-3);
 }
 ```
 
@@ -96,312 +89,46 @@ Va aparte de `index.css`; impórtalo si tu app usa las fuentes de marca:
 ```
 
 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
+copian los woff2 al build. 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);
-}
-```
+## Tipografía (`--netzi-font-size-*`, `--netzi-line-height-*`, `--netzi-font-weight-*`)
+
+Escala de texto para todo lo que **no** es un control: líneas secundarias, pies,
+metadatos, títulos. Todos los tamaños escalan con `--netzi-font-scale` (el ajuste
+de accesibilidad del panel), igual que los controles. `md` = 14px es el 100 %.
+
+| Token                   | Valor  | Para qué                                |
+| ----------------------- | ------ | --------------------------------------- |
+| `--netzi-font-size-xs`  | 11px   | metadatos, etiquetas en mayúsculas      |
+| `--netzi-font-size-sm`  | 12.5px | líneas secundarias, pies, celdas densas |
+| `--netzi-font-size-md`  | 14px   | texto corriente                         |
+| `--netzi-font-size-lg`  | 16px   | texto destacado, títulos de tarjeta     |
+| `--netzi-font-size-xl`  | 18px   | títulos de sección                      |
+| `--netzi-font-size-2xl` | 22px   | títulos de página                       |
+| `--netzi-font-size-3xl` | 28px   | cifras grandes, portadas                |
+
+| Interlineado                  | Valor | Peso                            | Valor |
+| ----------------------------- | ----- | ------------------------------- | ----- |
+| `--netzi-line-height-none`    | 1     | `--netzi-font-weight-regular`   | 400   |
+| `--netzi-line-height-tight`   | 1.25  | `--netzi-font-weight-medium`    | 500   |
+| `--netzi-line-height-normal`  | 1.5   | `--netzi-font-weight-semibold`  | 600   |
+| `--netzi-line-height-relaxed` | 1.65  | `--netzi-font-weight-bold`      | 700   |
+|                               |       | `--netzi-font-weight-extrabold` | 800   |
 
 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
+ligada a la altura del control; no salen de esta escala. 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);
+  font-size: var(--netzi-font-size-xs);
+  line-height: var(--netzi-line-height-none);
+  font-weight: var(--netzi-font-weight-semibold);
   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>`):
@@ -412,36 +139,7 @@ El tema se controla con el atributo `data-theme` en un ancestro (normalmente `<h
 </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`.
+Sin el atributo, aplica el tema claro (`:root`).
 
 ## Overrides (white-label por app)
 
@@ -450,153 +148,22 @@ 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 */
+/* tema de la app "Acme": cambia el azul de marca y los radios */
 :root {
+  --netzi-blue: #6c3cff;
   --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;
+  --netzi-surface: #101522;
 }
 ```
 
-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                                                                                                                                              |
 | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Marca       | `--netzi-blue` `--netzi-blue-dark` `--netzi-green` `--netzi-purple` `--netzi-red` `--netzi-yellow`                                                  |
 | 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`                                                                                                                 |
@@ -604,21 +171,16 @@ alto contraste.
 | 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}`                                                                                                    |
+| Sombras     | `--netzi-shadow-sm` `--netzi-shadow` `--netzi-shadow-lg`                                                                                            |
 | 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»).
+| Forma       | `--netzi-radius` `--netzi-radius-lg`                                                                                                                |
+| Tipografía  | `--netzi-font-sans` `--netzi-font-mono` `--netzi-font-scale` `--netzi-font-size-{xs…3xl}` `--netzi-line-height-*` `--netzi-font-weight-*`           |
 
-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).
+Alias por **simetría**, para que el nombre que se da por hecho exista:
+`--netzi-surface-1`, `--netzi-text-1` y `--netzi-radius-md` apuntan a
+`--netzi-surface`, `--netzi-text` y `--netzi-radius`. 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.
 
 ### Un panel de cristal entra por transición, nunca por animación
 
@@ -660,18 +222,18 @@ 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-success` y compañía son **relleno** (un punto de estado, un fondo, una
+barra). 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).
+sobre fondo claro (`--netzi-blue` da 2.9:1; `--netzi-primary-dark`, 4.3:1). 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
@@ -680,70 +242,6 @@ misma `--netzi-on-primary` del reposo, y cada preset lo calibra para que no baje
 (`--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
@@ -754,8 +252,8 @@ en cada elemento con `data-theme` o `data-preset`, así que una sección oscura
 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).
+halos del tinte no cuentan: dan 1.1:1). Dos guardianes de `tokens-contrast.spec.ts` 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
@@ -779,14 +277,12 @@ 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.
+7.1:1 y `text-3` a 4.8: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.
+Los ratios están **medidos sobre este mismo `tokens.css`** por
+`tokens-contrast.spec.ts` en `@netzi/ui`: si cambias un valor y deja de cumplir, la
+suite se pone roja.
 
 ## Capas flotantes y superficies de cristal
 
@@ -810,8 +306,9 @@ 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.
+valor que en alto contraste, `#354049`);
+`tokens-contrast.spec.ts` exige que sobre el tinte más fuerte siga por encima de
+4.5:1 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
@@ -831,7 +328,7 @@ propósito: ahí el cristal solo resta legibilidad.
 
 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
+interruptor «Fondo ambiental» 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
@@ -859,149 +356,14 @@ 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.
+nunca; contra el fondo del kit y contra un gris medio, ambos pasan de 6:1. `tokens-contrast.spec.ts`
+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**