@higinio/design-mcp 0.1.1 → 0.2.1

package/assets/celeste/design-doc.md

@@ -96,7 +96,7 @@ Los componentes **nunca** usan los primitivos directamente: consumen esta capa.
 | `--text-primary` | `neutral-800` | Texto principal |
 | `--text-secondary` | `neutral-600` | Texto secundario |
 | `--text-muted` | `neutral-500` | Terciario, captions |
-| `--text-disabled` | `neutral-400` | Deshabilitado, placeholder |
+| `--text-disabled` | `neutral-400` | Solo controles deshabilitados |
 | `--text-on-primary` | `#ffffff` | Texto sobre botón primario |
 | `--text-on-primary-solid` | `primary-700` | Texto de peso normal sobre `primary-100` |
 | `--accent` | `primary-500` | Rellenos de acción, bordes activos, focus |
@@ -109,26 +109,32 @@ Los componentes **nunca** usan los primitivos directamente: consumen esta capa.
 
 > ⚠️ **Regla AA de acento:** `primary-500` sobre blanco da ~3:1 — válido solo para **componentes UI** (rellenos, bordes, focus). Para **texto** (links, ghost) usar `--link` (`primary-700`, ~6:1). `primary-300` jamás como texto.
 
-### 3.5 Proporción de uso (regla 60-30-10)
+### 3.5 Uso del color y jerarquía
 
-- **60% — Neutrales claros** (`neutral-0/50/100`): fondos y superficies.
-- **30% — Tinta y estructura** (`neutral-600→900`, bordes): texto, iconos, divisores.
-- **10% — Primario y semánticos**: botones, links, estados, gráficas. **El acento pierde poder si supera el 10%.** (Excepción: una visualización de datos multiserie usa la paleta categórica validada de la skill `dataviz-marca`, exenta de este techo — son datos, no cromo decorativo.)
+El primitivo de marca expresa identidad; el rol de acción asegura legibilidad. Una acción dominante por contexto de decisión: un formulario, un diálogo o una región independiente pueden tener su propia acción. Evita competir dentro del mismo grupo. La proporción de acento se decide por jerarquía y contenido; 60/30/10 es una orientación visual, no una cuota ni un criterio de conformidad.
 
-Reglas prácticas:
-- **Un solo botón primario visible por pantalla**; el resto secundarios o ghost.
-- **Fondos siempre planos** (`--bg`): sin gradientes, texturas ni patrones; sin full-bleed decorativo — la superficie de trabajo (tarjetas blancas) es la protagonista.
-- Estado nunca solo con color: siempre color + icono + texto.
+| Rol semántico | Uso |
+|---|---|
+| `--action-bg`, `--action-hover`, `--action-active` | Relleno de acciones sólidas y selección con texto |
+| `--text-on-action` | Texto e iconos sobre los tres fondos de acción; ≥4.5:1 |
+| `--control-border` | Contorno necesario para reconocer campos, checkbox y radio; ≥3:1 |
+| `--focus-color` | Contorno sólido de teclado, distinto del halo decorativo |
+| `--placeholder` | Ayuda legible dentro de campos; nunca sustituye al label |
+| `--selection-bg`, `--selection-text` | Selección nativa de texto, con contraste propio |
+
+`--accent` conserva la firma cromática y no garantiza contraste como relleno de texto normal. No lo intercambies con `--action-bg`. Los separadores decorativos usan `--border`; los controles usan `--control-border`.
+
+Para datos categóricos consulta `.claude/skills/dataviz-marca/references/paletas-graficas.md`: allí se declara la validación de cada paleta, sus límites y los fallbacks. La identidad de serie también necesita etiqueta, forma o patrón; un cambio de tendencia no significa éxito por defecto.
 
 ---
 
 ## 4. Tipografía
 
-### 4.1 Familias (roles estrictos)
+### 4.1 Familias y funciones
 
 | Rol | Fuente | Fallback | Uso |
 |---|---|---|---|
-| Display | **Fraunces** (600–700) | Georgia, serif | **Solo h1–h2**, cifras hero, títulos de marketing — nunca UI ni párrafos |
+| Display | **Fraunces** (600–700) | Georgia, serif | Marca y títulos editoriales, cifras hero, títulos de marketing — nunca UI ni párrafos |
 | Body/UI | **Public Sans** (400–600) | system-ui, sans-serif | Párrafos, botones, formularios, h3–h6 |
 | Mono | **IBM Plex Mono** (400–500) | ui-monospace, monospace | Datos numéricos, código, IDs, montos en tablas |
 
@@ -173,6 +179,14 @@ Pesos tokenizados: `--weight-regular 400` · `--weight-medium 500` · `--weight-
 
 ---
 
+### Roles tipográficos por tarea
+
+La etiqueta HTML expresa estructura, no una familia tipográfica. En **Operate** (formularios, datos, ajustes), usa `data-mode="operate"` en la región: la familia de UI lleva h1–h3, con una escala fija en rem de 32/20/18px. `.ui-title` permite aplicarla de forma local. Conserva un solo h1 de página y el orden de encabezados.
+
+En **Read**, la familia display puede abrir una página editorial; `.reading-title` y `.display` consumen `--text-display-fluid`, con límites en rem y `text-wrap: balance`. El cuerpo mantiene 65–75ch y tamaños en rem. **Persuade** prioriza una decisión y **Experience** deja protagonismo a la obra: no copies la composición de un dashboard a una landing. Las cifras de tablas usan `tabular-nums`; reserva la mono para código, IDs o mediciones que lo necesiten.
+
+---
+
 ## 5. Espaciado
 
 Escala base 4px — tokens `--space-1…24` (número = px/4): `4 · 8 · 12 · 16 · 20 · 24 · 32 · 40 · 48 · 64 · 80 · 96`
@@ -190,6 +204,40 @@ Aliases de uso (consumir estos, no números sueltos):
 
 ---
 
+### Ritmo entre textos, controles y tarjetas
+
+| Relación | Separación | Token |
+|---|---:|---|
+| Etiqueta → control; control → ayuda/error | 6px | `--field-gap` |
+| Título → descripción del mismo grupo | 8px | `--heading-gap` |
+| Párrafos o bloques relacionados | 16px | `--content-gap` |
+| Bloques directos dentro de una tarjeta | 16px | `--card-content-gap` |
+| Campos consecutivos y pie del formulario | 20px | `--form-gap` |
+| Tarjetas consecutivas | 24px | `--card-group-gap` |
+| Secciones independientes | 64px | `--section-gap` |
+
+El padding protege el borde; el gap separa contenido. `.card` organiza sus hijos directos con `--card-content-gap`. Para anidar contenido usa `.card__content` o `.stack`; `.text-group` agrupa título y descripción a 8px. `.form-stack` separa campos a 20px; `.cluster` agrupa acciones con 12px y permite envolver. `.stack--cards` consume la separación de tarjetas de esta marca.
+
+Un contenedor es dueño de la separación: dentro de stacks y grids se neutralizan los márgenes de sus hijos para no sumar margen y gap. Los `.field` consecutivos también se separan en flujo normal. Evita repartir márgenes manuales entre cada div; aplica el contenedor al grupo. Las alturas de control son mínimas: permiten crecer cuando aumenta el tamaño del texto.
+
+```html
+<div class="stack stack--cards">
+  <section class="card" data-mode="operate">
+    <header class="text-group"><h2>Datos de contacto</h2><p>Usaremos estos datos para responder.</p></header>
+    <form class="form-stack">
+      <div class="field"><label class="field__label" for="nombre">Nombre</label><input class="input" id="nombre" autocomplete="name"></div>
+      <div class="field"><label class="field__label" for="correo">Correo</label><input class="input" id="correo" type="email" autocomplete="email"></div>
+      <div class="cluster"><button class="btn btn--primary" type="submit">Guardar</button><button class="btn btn--secondary" type="button">Cancelar</button></div>
+    </form>
+  </section>
+  <section class="card"><h2 class="ui-title">Otra sección</h2><p>El contenedor mantiene su distancia respecto a la tarjeta anterior.</p></section>
+</div>
+```
+
+Verifica la composición con ayuda/error multilínea, textos largos, 320px y texto al 200%. El texto debe envolver y los controles crecer; no reduzcas gaps para hacer caber contenido.
+
+---
+
 ## 6. Bordes, radios y focus
 
 | Token | Valor | Uso |
@@ -205,7 +253,7 @@ Aliases de uso (consumir estos, no números sueltos):
 
 ```css
 :where(a, button, [role="button"], input, select, textarea, summary, [tabindex]):focus-visible {
-  outline: 2px solid var(--primary-500);
+  outline: 2px solid var(--focus-color);
   outline-offset: 2px;
   border-radius: 2px;
 }
@@ -269,11 +317,11 @@ No hay logo ni imágenes de marca — el wordmark es puramente tipográfico. Don
 
 ### 10.1 Botones
 
-Alturas: 36 (sm) / 44 (md) / 52px (lg). Radius `md`. Peso 600, `text-sm`/`text-base`; lg usa padding `14px 24px` y `text-lg`. Un solo primario visible por pantalla; ghost y outline usan `--link` (AA), no `primary-500`.
+Alturas: 36 (sm) / 44 (md) / 52px (lg). Radius `md`. Peso 600, `text-sm`/`text-base`; lg usa padding `14px 24px` y `text-lg`. Una acción dominante por contexto de decisión; ghost y outline usan `--link` (AA), no `primary-500`.
 
 | Variante | Reposo | Hover | Active | Disabled |
 |---|---|---|---|---|
-| Primario | fondo `--accent`, texto `--text-on-primary` | `--accent-hover` + `shadow-sm` | `--accent-active`, sin sombra | fondo `neutral-200`, texto `--text-disabled` |
+| Primario | fondo `--action-bg`, texto `--text-on-action` | `--action-hover` | `--action-active`, sin sombra | fondo `neutral-200`, texto `--text-disabled` |
 | Secundario | fondo `--surface`, borde `--border-strong`, texto `neutral-800` | fondo `neutral-50` | fondo `neutral-100` | opacidad 50% |
 | Outline | fondo transparente, borde `--accent`, **texto `--link`** | fondo `--accent-soft`, borde `--accent-hover` | fondo `--accent-soft-strong` | opacidad 50% |
 | Ghost | **texto `--link`** (`primary-700`) | fondo `--accent-soft` | fondo `--accent-soft-strong` | fondo `neutral-200`, texto `--text-disabled` |
@@ -313,7 +361,7 @@ Export propio (extraído del estado loading de Button). SVG 16px default: círcu
 
 ### 10.5 Textarea
 
-Mismos estados que input. Min-height 96px, `resize: vertical`, padding 12px 14px. Contador de caracteres `text-xs` `--text-disabled` alineado a la derecha.
+Mismos estados que input. Min-height 96px, `resize: vertical`, padding 12px 14px. Contador de caracteres (`.textarea-counter`) `text-xs` `--text-muted` alineado a la derecha.
 
 ### 10.6 Select
 
@@ -372,7 +420,7 @@ Rango de valor único.
 
 - Contenedor: borde `--border`, radius `lg`, fondo `--surface`, ítems separados por borde interno.
 - Header: botón full-width, padding `16px 20px`, `text-base` medium `--text-primary`; chevron 18px `--text-muted` rota 180° (200ms). `aria-expanded`.
-- Panel: altura animada con `grid-template-rows` 0fr→1fr 250ms ease-out (sin reflow); contenido `text-sm --text-secondary`, padding `0 20px 16px`.
+- Panel: altura animada con `grid-template-rows` 0fr→1fr 250ms ease-out (con layout local controlado); contenido `text-sm --text-secondary`, padding `0 20px 16px`.
 - Un panel abierto a la vez salvo `allowMultiple`; `defaultOpen` por ids.
 
 ### 10.15 Tooltip
@@ -387,7 +435,7 @@ Banner de estado **inline y persistente** (vs Toast, transitorio): errores de fo
 
 - 4 tonos: fondo suave semántico (`*-100`), radius `md`, padding `14px 16px`.
 - Icono semántico 20px en `*-500`: info→`info` · success→`circle-check` · warning→`triangle-alert` · danger→`circle-alert`.
-- Título `text-sm` semibold y cuerpo `text-sm` en `--*-text` (cuerpo con opacidad 0.92).
+- Título `text-sm` semibold y cuerpo `text-sm` en `--*-text`, a contraste completo (sin opacidad).
 - Botón cerrar opcional (× 16px en el color del tono) vía `onDismiss`. `role="status"`.
 
 ### 10.17 Toast
@@ -456,6 +504,26 @@ Tile de KPI único (componer dentro de `Card` para métricas de dashboard).
 - Valor grande en `--font-mono text-3xl` semibold `--text-primary` (tracking -0.01em, line-height 1).
 - Delta opcional en baseline (gap 10px): `text-sm` semibold con flecha 14px (`trending-up`/`trending-down`/`minus`). Tono derivado del signo (− → danger, resto success) u override `deltaTone`; colores del delta en `--*-text` (no los `-500`).
 
+#### Chip de métrica
+
+Pastilla de una línea con rótulo y valor —por ejemplo, «Agua **3 de 8**»— para métricas secundarias que no merecen un Stat completo.
+
+- **`.metric-chip`:** radius `full`, borde `1px --border`, fondo `--surface`, padding `4px 12px`, `text-sm` `--text-secondary`; icono opcional de 16px en `--text-muted`.
+- **Contenido:** `.metric-chip__label` y `.metric-chip__value`; el valor va semibold en `--link` con `tabular-nums`.
+- **Fila:** `.metric-chips` agrupa los chips con `display: flex; flex-wrap: wrap; gap: var(--space-2)`, así que saltan de línea en móvil.
+- **Interactivo** (por ejemplo, «sumar un vaso»): `button.metric-chip`, con `min-height: var(--control-height-md)` (44px) y padding horizontal de 16px. Hover: fondo `--accent-soft` y borde `--accent`. Active: fondo `--accent-soft-strong` y `scale(.98)`. Foco de teclado con el anillo del sistema (outline 2px `--accent`, offset 2px).
+
+```html
+<div class="metric-chips">
+  <span class="metric-chip"><span class="metric-chip__label">Pasos</span> <span class="metric-chip__value">6,240</span></span>
+  <button class="metric-chip" type="button" aria-label="Agua: 3 de 8 vasos. Sumar un vaso">
+    <span class="metric-chip__label">Agua</span> <span class="metric-chip__value">3 de 8</span>
+  </button>
+</div>
+```
+
+**Accesibilidad:** el chip interactivo es un `<button>` con nombre accesible completo, no solo la cifra («Agua: 3 de 8 vasos. Sumar un vaso»); el nombre empieza por el texto visible (WCAG 2.5.3) y se actualiza con el valor. El chip informativo es texto: no lleva rol ni foco.
+
 ### 10.23 Pagination
 
 Navegador de páginas 1-indexado, bajo una `Table`.
@@ -472,6 +540,37 @@ Navegador de páginas 1-indexado, bajo una `Table`.
 - **Tabs:** borde inferior `--border`; tab activa con indicador 2px `--accent` que se desliza entre tabs (250ms).
 - **Breadcrumbs:** `text-sm` `--text-muted`, separador `/` (tipográfico), último ítem `--text-primary`.
 
+#### Sidebar contraíble
+
+Variante del Sidebar para apps con muchas secciones: alterna entre la lista con rótulos y un riel de iconos que deja más ancho al contenido.
+
+- **Estados:** expandido, 260px (el ancho del Sidebar), y contraído, riel de iconos de 64px. Clases: `.sidebar.sidebar--collapsible` y, contraído, `.is-collapsed`. Cada ítem lleva su icono de 18px y el nombre en `.sidebar__label`.
+- **Grupos con rótulo:** `.sidebar__group` con un `.sidebar__group-label` (`text-xs` semibold en mayúsculas, tracking `--tracking-label`, `--text-muted`); 16px entre grupos. En el riel, cada rótulo se convierte en un separador de 1px `--border` y el del primer grupo se oculta.
+- **Ítem activo:** `.is-active` (fondo `--accent-soft-strong`, texto `--link`) más `aria-current="page"`.
+- **Botón de contraer:** `.sidebar__item.sidebar__toggle` al pie (`margin-top: auto`), con un chevron que apunta hacia donde se moverá el borde (rota 180° en el riel) y el texto «Contraer» / «Expandir» en su `.sidebar__label`.
+- **Tooltip en el riel:** el `.sidebar__label` queda oculto a la vista pero accesible (patrón de `.u-visually-hidden`) y aparece a la derecha del ítem como tooltip (`--tooltip-bg`, `text-xs`, radius `sm`, delay 400ms) al pasar el cursor —solo con puntero real, §11.5— y al enfocar el ítem con teclado (`:focus-visible`). No es un `title`: el nombre sigue en el árbol de accesibilidad. El riel no recorta su contenido (sin `overflow`) para que el tooltip pueda salir de él.
+- **Por debajo de 768px** (`md`), `.sidebar--collapsible` no se muestra fijo: lo sustituye un botón ☰ `.icon-btn.sidebar-trigger` que abre un Drawer `.drawer--left` (§10.29) con los mismos grupos e ítems. El framework muestra `.sidebar-trigger` solo por debajo de 768px y lo oculta (`display: none`) desde 768px, el mismo breakpoint en el que aparece el sidebar fijo; así el ☰ y el sidebar nunca conviven. El botón lleva `aria-label="Abrir navegación"`, `aria-controls` con el id del drawer y `aria-expanded` (`false` cerrado, `true` abierto).
+- **Motion:** el ancho cambia sin transición —el layout usa `grid-template-columns: auto 1fr` y el contenido sigue al sidebar al instante—; nunca se anima `width`. Solo los rótulos se funden al expandir: `opacity` 0→1 y `translateX(-4px)`→0 en `--duration-fast` `--ease-out`. Con `prefers-reduced-motion`, sin animación (reset global, §11.5).
+
+```html
+<nav class="sidebar sidebar--collapsible" id="appNav" aria-label="Principal">
+  <div class="sidebar__group" role="group" aria-labelledby="navHoy">
+    <span class="sidebar__group-label" id="navHoy">Hoy</span>
+    <a class="sidebar__item is-active" href="/" aria-current="page"><svg aria-hidden="true">…</svg><span class="sidebar__label">Inicio</span></a>
+  </div>
+  <button class="sidebar__item sidebar__toggle" type="button" aria-expanded="true" aria-controls="appNav">
+    <svg aria-hidden="true">…</svg><span class="sidebar__label">Contraer</span>
+  </button>
+</nav>
+
+<!-- Solo por debajo de 768px -->
+<button class="icon-btn sidebar-trigger" type="button" aria-label="Abrir navegación"
+        aria-expanded="false" aria-controls="navDrawer">…menu…</button>
+<div class="drawer drawer--left" id="navDrawer">…los mismos grupos e ítems…</div>
+```
+
+**Accesibilidad:** el contenedor es un `<nav>` con `aria-label`; el ítem de la página actual lleva `aria-current="page"` además de `.is-active`. El toggle es un `<button>` real con `aria-expanded` (`true` expandido, `false` en el riel) y `aria-controls` con el id del sidebar; al alternar, su texto cambia entre «Contraer» y «Expandir». El ☰ `.sidebar-trigger` también es un `<button>` con `aria-expanded` y `aria-controls` hacia el drawer, y el drawer sigue el contrato de foco del Modal. Los grupos se declaran con `role="group"` y `aria-labelledby` apuntando a su rótulo, que en el riel sigue siendo legible para el lector aunque se vea como una línea.
+
 ### 10.25 Skeleton y EmptyState
 
 - Skeleton: fondo `--surface-alt` con shimmer (gradiente que barre en 1.4s, loop). Radius igual al contenido que reemplaza.
@@ -541,10 +640,10 @@ Botones adyacentes con bordes compartidos para acciones relacionadas (barra de f
 
 Campo de fecha con un calendario en popover. Reusa el patrón visual del `Popover` (§10.30, panel `--surface` + `shadow-lg`, aparición desde el `transform-origin` del disparador) y la navegación por teclado del `Combobox` (§10.28).
 
-- **`.datepicker`** — contenedor relativo (`.is-open` lo abre). **`.datepicker__input`** con el look de `Input` (borde `--border-strong`, focus `--accent` + `--ring`), `readonly` + `aria-haspopup="dialog"` + `aria-expanded` + `aria-controls`; un `.datepicker__icon` de calendario 18px a la derecha (decorativo, `aria-hidden`).
+- **`.datepicker`** — contenedor relativo (`.is-open` lo abre). **`.datepicker__input`** con el look de `Input` (borde `--border-strong`, focus `--accent` + `--ring`), `readonly` + `aria-haspopup="dialog"` + `aria-controls` (sin `aria-expanded`, que no es válido en un `input` de texto; el estado abierto lo da `.is-open`); un `.datepicker__icon` de calendario 18px a la derecha (decorativo, `aria-hidden`).
 - **`.datepicker__calendar`** — panel flotante `role="dialog"` con `aria-label`, mismo patrón que `.popover__panel`. Variante `.datepicker--right` ancla a la derecha.
-- **`.calendar`** — dentro del panel: `.calendar__header` (mes/año en `.calendar__title` + botones prev/next con `#i-chevron-left/right`), `.calendar__weekdays` (7 encabezados `role="columnheader"` con `aria-label` completo: "lunes"…), `.calendar__grid` (`role="grid"`), y `.calendar__day` (botón `role="gridcell"`, `aria-label` de la fecha completa vía `Intl.DateTimeFormat` y `aria-selected`). Semana empieza en lunes.
-- **Estados de día:** `.calendar__day--today` (semibold + anillo interior `--border-strong`), `.calendar__day--selected` (fondo `--accent`, texto `--text-on-primary`), `.calendar__day--outside` (días de otro mes, `--text-disabled`), `[disabled]` (no seleccionable). El hover usa `--accent-soft`.
+- **`.calendar`** — dentro del panel: `.calendar__header` (mes/año en `.calendar__title` + botones prev/next con `#i-chevron-left/right`), `.calendar__table` (`role="grid"`) que envuelve la fila de cabeceras `.calendar__weekdays` (`role="row"`, 7 encabezados `role="columnheader"` con `aria-label` completo: "lunes"…) y `.calendar__grid` (`role="rowgroup"`) con una `.calendar__week` (`role="row"`, `display: contents` para no romper la rejilla) por semana, y `.calendar__day` (botón `role="gridcell"`, `aria-label` de la fecha completa vía `Intl.DateTimeFormat` y `aria-selected`). Semana empieza en lunes.
+- **Estados de día:** `.calendar__day--today` (semibold + anillo interior `--border-strong`), `.calendar__day--selected` (fondo `--action-bg`, texto `--text-on-action`), `.calendar__day--outside` (días de otro mes, `--text-muted`), `[disabled]` (no seleccionable). El hover usa `--accent-soft`.
 - **Teclado y foco (como Popover):** el input abre por click (o Enter/Espacio/↓); al abrir, el foco entra al calendario (día enfocado). Dentro de la rejilla las **flechas** mueven el foco entre días (roving `tabindex`, cambiando de mes al cruzar el borde), Home/End saltan a los extremos de la semana, PageUp/PageDown cambian de mes, Enter/Espacio selecciona; **Esc** cierra y devuelve el foco al input. La fecha se formatea con `Intl` (`es-MX`), nunca a mano.
 - **Motion:** el panel aparece con fade + `scale(0.96→1)`, `--duration-base` `--ease-out`, bajo el techo `--duration-page`. Solo `transform`/`opacity`.
 
@@ -612,7 +711,7 @@ Antes de animar algo, pregúntate: ¿de dónde vino, qué cambió, a dónde se f
 ### 11.2 Principios de movimiento
 
 1. **Entra rápido, sale más rápido** — La salida siempre es ~20% más corta que la entrada.
-2. **Solo `transform` y `opacity`** — Nunca animar `width/height/top/left` (evita reflow). Excepciones controladas: width de Progress y `grid-template-rows` del Accordion.
+2. **Propiedades según coste y propósito** — Prefiere `transform` y `opacity` para desplazamiento y aparición. Color y sombra pueden acompañar un estado. Width de Progress y `grid-template-rows` del Accordion recalculan layout: mantenlos locales, cortos y medidos; no son animaciones gratis.
 3. **Distancias cortas** — Desplazamientos de entrada de 4–8px; nada "vuela" por la pantalla.
 4. **Jerarquía temporal** — En listas, stagger de 30ms por ítem (máximo 6 ítems con stagger).
 5. **La animación explica** — Todo movimiento responde a: ¿de dónde vino, qué cambió, a dónde se fue?
@@ -652,26 +751,21 @@ Antes de animar algo, pregúntate: ¿de dónde vino, qué cambió, a dónde se f
 
 ### 11.5 Accesibilidad del movimiento
 
+La preferencia reducida cambia los tokens de duración propios a 0ms y detiene spinner y skeleton. Los estados finales siguen visibles; el feedback de color de botones puede durar 80ms. No se acortan con un selector universal las animaciones de otras librerías. No uses eventos de animación como única condición para completar una operación o retirar un elemento.
+
 ```css
 @media (prefers-reduced-motion: reduce) {
-  *, *::before, *::after {
-    animation-duration: 0.01ms !important;
-    animation-iteration-count: 1 !important;
-    transition-duration: 0.01ms !important;
-    scroll-behavior: auto !important;
+  :root {
+    --duration-instant: 0ms; --duration-fast: 0ms; --duration-base: 0ms;
+    --duration-slow: 0ms; --duration-page: 0ms; --stagger-step: 0ms;
   }
+  html { scroll-behavior: auto; }
+  .spinner, .skeleton, .skeleton::after { animation: none; }
+  .btn, .icon-btn { transform: none; transition: background-color 80ms linear, color 80ms linear; }
 }
 ```
 
-Este reset con `*` es el **piso de seguridad**: garantiza que ningún motion sobreviva si el usuario pide reducirlo, incluso en componentes que no se revisaron a mano. Donde el movimiento comunica información real (progreso, un check, un conteo) y eliminarlo del todo perjudicaría la comprensión, un componente puede sobrescribir el reset con un selector más específico y una duración corta (p. ej. `transition-duration: 80ms`) en vez de colapsar a 0.01ms — hoy ningún componente del sistema ejerce esta excepción; todos usan el piso global.
-
-**Gating de hover:** los efectos de hover que mueven o elevan (transform, box-shadow) van dentro de `@media (hover: hover) and (pointer: fine)` — en touch no hay hover real y el tap dispara hovers falsos que se quedan pegados hasta el siguiente toque. Los hover de solo color/fondo pueden quedar fuera: un cambio de color pegado no estorba.
-
-```css
-@media (hover: hover) and (pointer: fine) {
-  .card--interactive:hover { transform: translateY(-2px); box-shadow: var(--shadow-md); }
-}
-```
+Los hover que desplazan o elevan solo se aplican con `(hover: hover) and (pointer: fine)`. Verifica la alternativa reducida con el mismo contenido y flujo, incluidos abrir, cerrar, cargar y confirmar. Los datos llegan con su valor final desde HTML: no hay valor final visible desde la carga.
 
 ### 11.6 Anti-patrones de motion
 
@@ -705,7 +799,7 @@ Un "motion gap" es UI que aparece o desaparece sin transición y debería tenerl
 - Estados de carga y de error.
 - Paneles de settings / inspector.
 
-Regla: un gap en UI primaria (el flujo principal) es crítico; en UI secundaria, medio. Toda entrada/salida condicional necesita su transición de `opacity`/`transform`, con su contraparte de salida más discreta.
+La ausencia de transición no es un defecto por sí sola. Evalúa si el cambio se entiende y mantiene el foco. En tareas frecuentes, teclado o movimiento reducido, una actualización instantánea puede ser la respuesta correcta.
 
 ---
 
@@ -714,7 +808,7 @@ Regla: un gap en UI primaria (el flujo principal) es crítico; en UI secundaria,
 Ratios calculados con la fórmula WCAG 2.x (no estimados). El test `mcp/test/contraste-tokens.test.ts` los recalcula desde `tokens.css` en cada corrida: si alguien retoca la paleta y rompe un mínimo, la suite falla.
 
 - `neutral-800` sobre blanco: **12.42:1** ✅ AAA.
-- Blanco sobre `primary-500`: **3.22:1** ⚠️ solo texto ≥18px/bold o componentes UI; para texto normal usar fondo `primary-700`.
+- Blanco sobre `primary-500`: **3.22:1** ⚠️ no apto para el texto normal de un botón; el rol `--action-bg` usa `primary-700` en claro.
 - `--link` (`primary-700`) sobre blanco: **5.94:1** ✅ AA — por eso links y ghost usan `--link`, no `primary-500`.
 - `primary-300` (#a0c0d4) **nunca como texto sobre blanco** — solo decorativo.
 - Tonos `--*-text` garantizan AA sobre los fondos suaves `*-100`: success **5.30:1** · warning **4.72:1** · danger **6.60:1** · info **4.83:1**.
@@ -728,20 +822,30 @@ Ratios calculados con la fórmula WCAG 2.x (no estimados). El test `mcp/test/con
 ## 13. Tokens CSS consolidados
 
 ```css
+/* ============================================================
+   Celeste Clásica — Design Tokens v2.0
+   Sistema de diseño de Higinio Sosa · light-first
+   Fuente de verdad: DESIGN-celeste-clasica.md
+   Uso: importar ANTES de cualquier estilo propio.
+   Los componentes consumen SOLO aliases semánticos, nunca hex.
+   ============================================================ */
+
+@import url("https://fonts.googleapis.com/css2?family=Fraunces:ital,opsz,wght@0,9..144,600;0,9..144,700;1,9..144,600&family=Public+Sans:ital,wght@0,400;0,500;0,600;0,700;1,400&family=IBM+Plex+Mono:wght@400;500&display=swap");
+
 :root {
-  /* == Primitivos: primario == */
+  /* == Primitivos: primario (Azul Acero) == */
   --primary-50: #f2f6fa; --primary-100: #dfe9f2; --primary-200: #c3d5e6;
   --primary-300: #a0c0d4; --primary-400: #87a8c7; --primary-500: #7192ba;
   --primary-600: #5d7ba3; --primary-700: #4d6588; --primary-800: #40536e;
   --primary-900: #31343e;
 
-  /* == Primitivos: neutrales == */
+  /* == Primitivos: neutrales (Gris Azulado) == */
   --neutral-0: #ffffff; --neutral-50: #f7f8fa; --neutral-100: #eef0f3;
   --neutral-200: #dcdfe5; --neutral-300: #b8bdc7; --neutral-400: #8a8f9c;
   --neutral-500: #666b78; --neutral-600: #4d5160; --neutral-700: #3d414e;
   --neutral-800: #31343e; --neutral-900: #22242b;
 
-  /* == Primitivos: semánticos (ramp de 3) == */
+  /* == Primitivos: semánticos (ramp de 3: sólido / fondo / texto AA) == */
   --success-500: #3d9970; --success-100: #e2f3ec; --success-text: #2b6e50;
   --warning-500: #c9922e; --warning-100: #faf1de; --warning-text: #8a651c;
   --danger-500: #c04d4d;  --danger-100: #f9e7e7;  --danger-text: #8f3232;
@@ -764,7 +868,7 @@ Ratios calculados con la fórmula WCAG 2.x (no estimados). El test `mcp/test/con
   --accent-active: var(--primary-700);
   --accent-soft: var(--primary-50);
   --accent-soft-strong: var(--primary-100);
-  --link: var(--primary-700);
+  --link: var(--primary-700); /* AA ~6:1 — texto de links y ghost; primary-500 solo para UI */
 
   /* == Tipografía == */
   --font-display: "Fraunces", Georgia, serif;
@@ -780,7 +884,7 @@ Ratios calculados con la fórmula WCAG 2.x (no estimados). El test `mcp/test/con
   --weight-regular: 400; --weight-medium: 500; --weight-semibold: 600; --weight-bold: 700;
   --measure: 65ch;
 
-  /* == Espaciado == */
+  /* == Espaciado (escala base 4px) == */
   --space-1: 4px; --space-2: 8px; --space-3: 12px; --space-4: 16px;
   --space-5: 20px; --space-6: 24px; --space-8: 32px; --space-10: 40px;
   --space-12: 48px; --space-16: 64px; --space-20: 80px; --space-24: 96px;
@@ -790,7 +894,7 @@ Ratios calculados con la fórmula WCAG 2.x (no estimados). El test `mcp/test/con
   --control-height-sm: 36px; --control-height-md: 44px; --control-height-lg: 52px;
   --gutter: 24px; --gutter-mobile: 16px;
 
-  /* == Radios, bordes y sombras == */
+  /* == Radios, bordes y sombras (teñidas de tinta, nunca negro puro) == */
   --radius-sm: 6px; --radius-md: 10px; --radius-lg: 14px;
   --radius-xl: 20px; --radius-full: 9999px;
   --border-width: 1px;
@@ -809,10 +913,112 @@ Ratios calculados con la fórmula WCAG 2.x (no estimados). El test `mcp/test/con
   --duration-slow: 250ms; --duration-page: 320ms;
   --ease-out: cubic-bezier(0.2, 0, 0, 1);
   --ease-in: cubic-bezier(0.4, 0, 1, 1);
-  --ease-in-out: cubic-bezier(0.65, 0, 0.35, 1);
+  --ease-in-out: cubic-bezier(0.65, 0, 0.35, 1); /* moverse de A a B en pantalla */
   --ease-spring: cubic-bezier(0.34, 1.4, 0.64, 1);
+  --stagger-step: 30ms;
 
   color-scheme: light;
+
+  --overlay: rgba(49, 52, 62, .5);
+  --tooltip-bg: var(--neutral-900);
+  --tooltip-text: #ffffff;
+  --ring-danger: 0 0 0 3px rgba(192,77,77,.22);
+
+  --action-bg: var(--primary-700);
+  --action-hover: var(--primary-800);
+  --action-active: var(--primary-900);
+  --text-on-action: var(--text-on-primary);
+  --control-border: var(--neutral-400);
+  --placeholder: var(--text-muted);
+  --selection-bg: var(--action-bg);
+  --selection-text: var(--text-on-action);
+  --font-ui-heading: var(--font-body);
+  --text-ui-title: 2rem;
+  --touch-target: 44px;
+  --focus-color: var(--accent);
+  --text-display-fluid: clamp(2.75rem, 1.7rem + 3vw, 4.75rem);
+  --border-hover: var(--neutral-500);
+  --text-on-danger: #ffffff;
+
+  /* Series categóricas: orden estable; acompañar con etiqueta o forma. */
+  --chart-1: #4a8cc1;
+  --chart-2: #853f63;
+  --chart-3: #129a92;
+  --chart-4: #8e4031;
+  --chart-5: #5b975e;
+  --chart-6: #8a600a;
+  --chart-7: #857bc1;
+  /* Ritmo de contenido y formularios. */
+  --field-gap: 6px;
+  --heading-gap: var(--space-2);
+  --content-gap: var(--space-4);
+  --card-content-gap: var(--space-4);
+  --card-group-gap: var(--space-6);
+
+}
+
+/* == Modo oscuro (variante) — alternar data-theme en <html> == */
+[data-theme="dark"] {
+  --bg: #16181e;
+  --surface: #1d2028;
+  --surface-alt: #252935;
+  --border: #3a3f4d;
+  --border-strong: #4a5060;
+  --text-primary: #e6e9ee;
+  --text-secondary: #b9bfcb;
+  --text-muted: #8b91a0;
+  --text-disabled: #6f7585;
+  --accent: #87a8c7;
+  --accent-hover: #a0c0d4;
+  --accent-active: #7192ba;
+  --accent-soft: rgba(113,146,186,.12);
+  --accent-soft-strong: rgba(113,146,186,.18);
+  --text-on-primary: #16181e;
+  --link: #a0c0d4;
+  --success-500: #5cbf93; --success-100: #12291f; --success-text: #7fd4ae;
+  --warning-500: #e0ad4d; --warning-100: #2b2210; --warning-text: #ecc57e;
+  --danger-500: #e07777;  --danger-100: #2e1515;  --danger-text: #eb9e9e;
+  --info-500: #87a8c7;    --info-100: #1a2430;    --info-text: #a0c0d4;
+  --ring: 0 0 0 3px rgba(160,192,212,.3);
+  --ring-color: rgba(160,192,212,.3);
+  --shadow-sm: 0 1px 2px rgba(0,0,0,.35);
+  --shadow-md: 0 4px 12px rgba(0,0,0,.45);
+  --shadow-lg: 0 12px 32px rgba(0,0,0,.55);
+  color-scheme: dark;
+
+  --text-on-primary-solid: #a0c0d4;
+  --overlay: rgba(0, 0, 0, .6);
+  --tooltip-bg: #e6e9ee;
+  --tooltip-text: #31343e;
+  --ring-danger: 0 0 0 3px rgba(224,119,119,.25);
+
+  --selection-bg: var(--action-bg);
+  --selection-text: var(--text-on-action);
+  --action-bg: var(--accent);
+  --action-hover: var(--accent-hover);
+  --action-active: var(--accent-active);
+  --control-border: var(--text-muted);
+  --border-hover: var(--text-secondary);
+  --text-on-danger: #16181e;
+  --focus-color: var(--accent);
+
+  /* Series categóricas: orden estable; acompañar con etiqueta o forma. */
+  --chart-1: #5798ce;
+  --chart-2: #a0587c;
+  --chart-3: #2aa79e;
+  --chart-4: #aa5849;
+  --chart-5: #67a369;
+  --chart-6: #946a1c;
+  --chart-7: #877cc3;
+}
+
+/* == Accesibilidad del movimiento == */
+
+@media (prefers-reduced-motion: reduce) {
+  :root {
+    --duration-instant: 0ms; --duration-fast: 0ms; --duration-base: 0ms;
+    --duration-slow: 0ms; --duration-page: 0ms; --stagger-step: 0ms;
+  }
 }
 ```
 
@@ -839,6 +1045,17 @@ Grid de 12 columnas, gutter 24px (16px móvil). Mobile-first. Navbar fija de 64p
 
 ---
 
+### Adaptación de los componentes
+
+- Reflow a 320 CSS px sin recortar contenido ni ocultar el desbordamiento del documento. Revisa también texto al 200% y zoom al 400%.
+- Acciones de formularios se apilan cuando no caben; el primario puede ocupar el ancho disponible en móvil. Las etiquetas largas pueden envolver sin quedar cortadas.
+- La navegación lateral se convierte en disclosure o drawer con estado accesible, cierre con Escape, devolución de foco y contenido cerrado fuera del orden de tabulación. Tabs largas conservan desplazamiento horizontal local.
+- Una tabla ancha usa `.table-scroll`, con nombre accesible y región enfocables si el scroll necesita teclado; prioriza columnas o una vista de detalle sin retirar datos necesarios.
+- Calendarios y grupos compactos mantienen objetivos de al menos 24×24px o espaciado equivalente; 44×44px es la preferencia de comodidad táctil, no el mínimo AA universal. El tamaño visible del icono puede ser menor que su zona activa.
+- Popovers, combobox y calendarios respetan el viewport y se reposicionan cerca de sus bordes. En producción usa top layer, portal o posicionamiento con detección de colisiones para escapar de ancestros con overflow. El framework CSS por sí solo no gestiona colisiones ni foco.
+
+---
+
 ## 15. Modo oscuro (variante)
 
 El sistema es **light-first**, pero todo producto debe soportar dark mode con los mismos tokens semánticos. La marca no cambia: cambia el escenario.
@@ -918,6 +1135,8 @@ Ratios calculados, no estimados (mismo test que §12).
   --accent: #87a8c7;
   --accent-hover: #a0c0d4;
   --accent-active: #7192ba;
+  --accent-soft: rgba(113,146,186,.12);
+  --accent-soft-strong: rgba(113,146,186,.18);
   --text-on-primary: #16181e;
   --link: #a0c0d4;
   --success-500: #5cbf93; --success-100: #12291f; --success-text: #7fd4ae;
@@ -925,10 +1144,36 @@ Ratios calculados, no estimados (mismo test que §12).
   --danger-500: #e07777;  --danger-100: #2e1515;  --danger-text: #eb9e9e;
   --info-500: #87a8c7;    --info-100: #1a2430;    --info-text: #a0c0d4;
   --ring: 0 0 0 3px rgba(160,192,212,.3);
+  --ring-color: rgba(160,192,212,.3);
   --shadow-sm: 0 1px 2px rgba(0,0,0,.35);
   --shadow-md: 0 4px 12px rgba(0,0,0,.45);
   --shadow-lg: 0 12px 32px rgba(0,0,0,.55);
   color-scheme: dark;
+
+  --text-on-primary-solid: #a0c0d4;
+  --overlay: rgba(0, 0, 0, .6);
+  --tooltip-bg: #e6e9ee;
+  --tooltip-text: #31343e;
+  --ring-danger: 0 0 0 3px rgba(224,119,119,.25);
+
+  --selection-bg: var(--action-bg);
+  --selection-text: var(--text-on-action);
+  --action-bg: var(--accent);
+  --action-hover: var(--accent-hover);
+  --action-active: var(--accent-active);
+  --control-border: var(--text-muted);
+  --border-hover: var(--text-secondary);
+  --text-on-danger: #16181e;
+  --focus-color: var(--accent);
+
+  /* Series categóricas: orden estable; acompañar con etiqueta o forma. */
+  --chart-1: #5798ce;
+  --chart-2: #a0587c;
+  --chart-3: #2aa79e;
+  --chart-4: #aa5849;
+  --chart-5: #67a369;
+  --chart-6: #946a1c;
+  --chart-7: #877cc3;
 }
 ```
 
@@ -955,3 +1200,11 @@ El sistema se distribuye en varios formatos para poder usarlo desde cualquier st
 3. Los componentes consumen solo aliases semánticos (§3.4) — nunca hex.
 4. Para light/dark: alternar `data-theme` en `<html>`; los tokens hacen el resto.
 5. En el `<head>`: `<meta name="theme-color" content="#f7f8fa">` (el `--bg` claro); con el tema oscuro activo, actualizarlo a `#16181e` para que la barra del navegador acompañe al fondo.
+
+### Mantenimiento de las distribuciones
+
+Los contratos se definen en esta especificación y sus valores ejecutables en `dist/celeste-clasica/tokens.css`. Los ajustes comunes de componentes están en `web/component-contracts.css`; la presentación compartida de las guías, en `web/styleguide.css`. Tras editar, ejecuta `node scripts/build-design-assets.mjs`: regenera el prefijo de tokens del framework, el CSS embebido de las guías y los roles semánticos de Tailwind/DTCG. Los componentes propios del framework se conservan. Luego sincroniza skills, paquete CSS y MCP. Las guías siguen siendo HTML autocontenido, excepto la carga externa de fuentes.
+
+### Series categóricas
+
+`--chart-1` a `--chart-7` mantienen su orden y cambian de paso con el tema. La prueba `mcp/test/chart-palettes.test.ts` verifica contraste ≥3:1 contra la superficie y separación entre colores adyacentes en OKLab: ≥15 en visión normal y ≥8 bajo simulaciones Machado de protanopía, deuteranopía y tritanopía. Son umbrales internos, no certificación WCAG ni garantía para todos los pares o personas; usa etiquetas, formas o patrones y tabla equivalente.