@higinio/design-mcp 0.2.0 → 0.2.1

package/assets/nocturna/design-doc.md

@@ -29,7 +29,7 @@
 - **Casing:** sentence case en headings y botones ("Crear proyecto", no "Crear Proyecto" ni "CREAR PROYECTO"). Overlines/labels en uppercase con tracking `+0.08em`.
 - **Copy de botones:** verbo + objeto, corto: "Guardar cambios", "Ver informe".
 - **Mensajes de estado:** concretos y accionables — el error dice qué pasó **y qué hacer**.
-- **Números y datos:** protagonistas — siempre en JetBrains Mono o `tabular-nums`, grandes en dashboards, con count-up al montar.
+- **Números y datos:** protagonistas — siempre en JetBrains Mono o `tabular-nums`, grandes en dashboards, con valor final visible desde la carga.
 - **Fechas y números formateados:** siempre con `Intl.DateTimeFormat` / `Intl.NumberFormat` (`es-MX`), nunca formatos hardcodeados — un "12/07/2026" a mano se rompe al cambiar de locale.
 - **`translate="no"`** en nombres de marca y tokens de código (IDs, comandos, rutas), para que la traducción automática no los corrompa.
 - **Numerales para conteos:** "8 despliegues", no "ocho despliegues" — en un dashboard el dígito se escanea más rápido.
@@ -76,7 +76,7 @@
 | `night-600` | `#2a2f3d` | Superficie de separadores sutiles |
 | `night-500` | `#3d4354` | Bordes por defecto |
 | `night-450` | `#5f6575` | Solo light: texto atenuado (`--text-muted`) — `night-400` caía a 4.27:1 sobre `--surface-3` |
-| `night-400` | `#6b7183` | Deshabilitado, placeholders |
+| `night-400` | `#6b7183` | Solo controles deshabilitadoss |
 | `night-300` | `#9aa0b0` | Texto terciario, captions |
 | `night-200` | `#c5c9d4` | Texto secundario |
 | `night-100` | `#e8eaef` | Texto principal |
@@ -106,7 +106,7 @@ Los componentes **nunca** usan los primitivos de arriba directamente: consumen e
 | `--text-primary` | `night-100` | Texto principal |
 | `--text-secondary` | `night-200` | Texto secundario |
 | `--text-muted` | `night-300` | Terciario, captions |
-| `--text-disabled` | `night-400` | Deshabilitado, placeholder |
+| `--text-disabled` | `night-400` | Solo controles deshabilitados |
 | `--text-heading` | `night-50` | Headings, máximo énfasis |
 | `--text-on-accent` | `night-950` | Texto sobre CTAs de acento (**oscuro, nunca blanco**) |
 | `--accent-ghost-hover` | `rgba(82,186,237,.08)` | Hover de botones ghost |
@@ -115,17 +115,22 @@ Los componentes **nunca** usan los primitivos de arriba directamente: consumen e
 | `--overlay` | `rgba(1,2,3,.7)` | Overlay de modal |
 | `--success/--warning/--danger/--info` | sus `-400` | Estados semánticos |
 
-### 3.6 Proporción de uso (regla 60-30-10 adaptada a dark)
+### 3.6 Uso del color y jerarquía
 
-- **60% — Fondos nocturnos** (`night-950/900/800`): el escenario oscuro.
-- **30% — Texto y estructura** (`night-50→300`, bordes, índigo en fondos de sección).
-- **10% — Acento eléctrico y semánticos**: CTAs, links, cifras clave, gráficas. (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:
-- El celeste `accent-400` es **el único color que grita**: un CTA primario por pantalla.
-- El índigo es el "30% de marca": fondos de hero, sidebars, estados seleccionados — nunca compite con el acento y **nunca es texto sobre negro** (contraste 1.9:1).
-- Evitar blanco puro `#ffffff` en texto masivo; usar `night-100`.
-- **Fondos siempre planos:** sin imágenes de fondo, sin texturas, sin gradientes decorativos. El único "brillo" permitido es el glow de acento (§7).
+| 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.
 
 ---
 
@@ -135,7 +140,7 @@ Reglas prácticas:
 
 | Rol | Fuente | Fallback | Uso |
 |---|---|---|---|
-| Display | **Space Grotesk** (500–700) | system-ui, sans-serif | **Solo h1–h3**, cifras hero, navegación, wordmark |
+| Display | **Space Grotesk** (500–700) | system-ui, sans-serif | Marca y títulos editoriales, cifras hero, navegación, wordmark |
 | Body/UI | **Manrope** (400–700) | system-ui, sans-serif | Párrafos, formularios, tablas, **h4 en adelante** |
 | Mono | **JetBrains Mono** (400–500) | monospace | Datos numéricos, código, IDs |
 
@@ -179,6 +184,14 @@ Carga vía Google Fonts CDN (sin binarios adjuntos — si hay licencias locales,
 
 ---
 
+### 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`: `4 · 8 · 12 · 16 · 20 · 24 · 32 · 40 · 48 · 64 · 80 · 96`
@@ -196,6 +209,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 |
@@ -464,7 +511,7 @@ Lista de acciones desplegable anclada a un trigger (acciones de fila, botón "m
 - **Cifra:** JetBrains Mono 49px peso 500, line-height 1.05, color `accent-400`, `tabular-nums`, `white-space: nowrap`.
 - **Delta** opcional debajo: mono 14px — `success-400` / `danger-400` / `night-300` (neutral).
 - Gap vertical 6px. Formato numérico con `Intl.NumberFormat` (`es-MX`).
-- **Count-up** 350ms ease-out al montar (techo `--duration-page`); con `prefers-reduced-motion` muestra el valor directo.
+- **valor final visible desde la carga.
 
 #### Chip de métrica
 
@@ -668,7 +715,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** — Salida ~20% más corta que la entrada.
-2. **Solo `transform` y `opacity`** — Nunca animar propiedades de layout.
+2. **Propiedades según coste y propósito** — Prefiere `transform` y `opacity` para desplazamiento. Color y sombra pueden comunicar estados; las excepciones de layout son locales, cortas y medidas.
 3. **Distancias cortas** — Entradas de 4–8px.
 4. **Stagger en listas** — 30ms por ítem, máximo 6 ítems.
 5. **Firma de marca:** los elementos con acento entran con fade + glow (opacidad del glow 0→1 en 220ms). Usar solo en el elemento hero/CTA.
@@ -696,7 +743,7 @@ Antes de animar algo, pregúntate: ¿de dónde vino, qué cambió, a dónde se f
 | Toast | entrar | slide-in + fade 250ms |
 | Icon swap (p. ej. copiar→check) | cambio | cross-fade: opacity + scale(0.9→1), 150ms; nunca blur |
 | Página/vista | cambio | fade + translateY(8px→0) 350ms |
-| Cifra/dato clave | montar | count-up numérico 350ms `ease-out` (solo dashboards; techo `--duration-page`) |
+| Cifra/dato clave | montar | valor final visible desde la carga|
 
 ### 11.4 Loading
 
@@ -707,26 +754,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, glow) 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-2); }
-}
-```
+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
 
@@ -760,7 +802,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.
 
 ---
 
@@ -783,22 +825,36 @@ Ratios calculados con la fórmula WCAG 2.x (no estimados). El test `mcp/test/con
 ## 13. Tokens CSS consolidados
 
 ```css
+/* ============================================================
+   Nocturna Eléctrica — Design Tokens v2.0
+   Sistema de diseño de Higinio Sosa · dark-first
+   Fuente de verdad: DESIGN-nocturna-electrica.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=Space+Grotesk:wght@500;600;700&family=Manrope:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap');
+
 :root {
-  /* == Primitivos: acento == */
+  /* == Primitivos: acento (Celeste Eléctrico) ==
+     accent-600 sobre blanco da 4.01:1 — vale como UI (≥3) pero NO como texto (<4.5).
+     Para texto sobre claro se usa accent-700 (5.95:1) y accent-800 (8.74:1). */
   --accent-100: #d9f0fb; --accent-200: #a8ddf6; --accent-300: #7dccf1;
   --accent-400: #52baed; --accent-500: #2fa3dd; --accent-600: #1f87bb; --accent-700: #186a94;
+  --accent-800: #12506f;
 
-  /* == Primitivos: índigo == */
+  /* == Primitivos: índigo (Índigo Profundo) — nunca texto sobre negro == */
   --indigo-300: #7a83c4; --indigo-400: #565fa3; --indigo-500: #353d7c;
   --indigo-600: #2b3264; --indigo-700: #22284f; --indigo-800: #1a1e3b;
 
   /* == Primitivos: escala nocturna == */
   --night-950: #010203; --night-900: #0b0d12; --night-800: #14171f;
   --night-700: #1e222d; --night-600: #2a2f3d; --night-500: #3d4354;
+  --night-450: #5f6575; /* texto atenuado en light: night-400 caía a 4.27:1 sobre --surface-3 */
   --night-400: #6b7183; --night-300: #9aa0b0; --night-200: #c5c9d4;
   --night-100: #e8eaef; --night-50: #f6f7f9;
 
-  /* == Primitivos: semánticos == */
+  /* == Primitivos: semánticos (calibrados para dark) == */
   --success-400: #4ade80; --success-bg: #0a2617;
   --warning-400: #fbbf24; --warning-bg: #2a2005;
   --danger-400: #f87171;  --danger-bg: #2c0f0f;
@@ -806,13 +862,24 @@ Ratios calculados con la fórmula WCAG 2.x (no estimados). El test `mcp/test/con
 
   /* == Aliases semánticos (los componentes consumen SOLO esto) == */
   --bg: var(--night-950);
-  --surface-1: var(--night-900); --surface-2: var(--night-800); --surface-3: var(--night-700);
-  --border: var(--night-500); --border-strong: var(--night-400);
-  --text-primary: var(--night-100); --text-secondary: var(--night-200);
-  --text-muted: var(--night-300); --text-disabled: var(--night-400);
-  --text-heading: var(--night-50); --text-on-accent: var(--night-950);
+  --surface-1: var(--night-900);
+  --surface-2: var(--night-800);
+  --surface-3: var(--night-700);
+  --border: var(--night-500);
+  /* night-400, no night-600: en dark, oscurecer un borde lo DEBILITA (principio 2:
+     la elevación se comunica aclarando). n600 daba 1.46:1 vs los 1.97:1 del borde
+     normal — el énfasis se veía más flojo. n400 = 3.99:1 sobre surface-1. */
+  --border-strong: var(--night-400);
+  --text-primary: var(--night-100);
+  --text-secondary: var(--night-200);
+  --text-muted: var(--night-300);
+  --text-disabled: var(--night-400);
+  --text-heading: var(--night-50);
+  --text-on-accent: var(--night-950); /* texto de CTA oscuro, nunca blanco */
   --success: var(--success-400); --warning: var(--warning-400);
   --danger: var(--danger-400); --info: var(--info-400);
+  --link: var(--accent-400);
+  --link-hover: var(--accent-200);
   --accent-ghost-hover: rgba(82,186,237,.08);
   --accent-ghost-active: rgba(82,186,237,.14);
   --accent-selected: rgba(82,186,237,.12);
@@ -830,7 +897,7 @@ Ratios calculados con la fórmula WCAG 2.x (no estimados). El test `mcp/test/con
   --tracking-display: -0.02em; --tracking-overline: 0.08em;
   --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;
@@ -843,15 +910,15 @@ Ratios calculados con la fórmula WCAG 2.x (no estimados). El test `mcp/test/con
   --radius-sm: 8px; --radius-md: 12px; --radius-lg: 16px;
   --radius-xl: 24px; --radius-full: 9999px;
   --border-default: 1px solid var(--night-500);
-  --border-emphasis: 1px solid var(--night-400);
-  --focus-ring: 2px solid var(--accent-400);
+  --border-emphasis: 1px solid var(--night-400); /* ver --border-strong */
+  --focus-ring: 2px solid var(--focus-color);
   --focus-ring-offset: 2px;
 
-  /* == Elevación == */
+  /* == Elevación (superficie + sombra + borde) == */
   --shadow-1: 0 1px 2px rgba(0,0,0,.4);
   --shadow-2: 0 4px 12px rgba(0,0,0,.5);
   --shadow-3: 0 12px 32px rgba(0,0,0,.6);
-  --glow-accent: 0 0 0 1px rgba(82,186,237,.35), 0 4px 20px rgba(82,186,237,.18);
+  --glow-accent: 0 0 0 1px rgba(82,186,237,.35), 0 4px 20px rgba(82,186,237,.18); /* máx. uno por pantalla */
   --ring: 0 0 0 3px rgba(82,186,237,.2);
   --ring-danger: 0 0 0 3px rgba(248,113,113,.2);
 
@@ -860,10 +927,168 @@ Ratios calculados con la fórmula WCAG 2.x (no estimados). El test `mcp/test/con
   --duration-slow: 250ms; --duration-page: 350ms;
   --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: dark;
+
+  --focus-color: var(--accent-400);
+  --border-hover: var(--night-400);
+  --outline-hover-bg: var(--surface-2);
+  --outline-active-bg: var(--surface-3);
+  --text-on-danger: var(--night-950);
+  --data-color: var(--accent-400);
+  --elevated-border: var(--night-600);
+  --card-border: var(--night-600);
+  --code-color: var(--accent-300);
+  --code-border: var(--night-700);
+  --table-header-bg: var(--night-900);
+  --row-border: var(--night-800);
+  --row-hover: var(--night-700);
+  --navbar-bg: rgba(1,2,3,.8);
+  --nav-active: var(--accent-400);
+  --sidebar-bg: var(--night-900);
+  --sidebar-active-bg: var(--indigo-800);
+  --sidebar-active-text: var(--night-50);
+  --sidebar-active-icon: var(--accent-400);
+  --switch-off: var(--night-600);
+  --tooltip-bg: var(--night-700);
+  --tooltip-border: var(--night-600);
+  --tooltip-text: var(--night-100);
+  --skeleton-base: var(--night-800);
+  --skeleton-sheen: var(--night-700);
+  --empty-icon: var(--indigo-400);
+
+  --action-bg: var(--accent);
+  --action-hover: var(--accent-hover);
+  --action-active: var(--accent-active);
+  --text-on-action: var(--text-on-accent);
+  --control-border: var(--border-strong);
+  --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;
+  --control-height-md: 44px;
+  --button-padding-md: 12px 20px;
+  --surface: var(--surface-1);
+  --surface-alt: var(--surface-2);
+  --accent: var(--accent-400);
+  --accent-hover: var(--accent-300);
+  --accent-active: var(--accent-500);
+  --text-display-fluid: clamp(2.5rem, 1.5rem + 3.4vw, 5rem);
+  --text-on-primary-solid: var(--link);
+  --weight-regular: 400;
+  --weight-medium: 500;
+  --weight-semibold: 600;
+  --weight-bold: 700;
+  --leading-base: 1.6;
+  --leading-lg: 1.55;
+  --gutter: 24px;
+  --gutter-mobile: 16px;
+
+  /* Series categóricas: orden estable; acompañar con etiqueta o forma. */
+  --chart-1: #52baed;
+  --chart-2: #a0587c;
+  --chart-3: #2aa79e;
+  --chart-4: #aa5849;
+  --chart-5: #67a369;
+  --chart-6: #946a1c;
+  --chart-7: #877cc3;
+  /* 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 claro (variante) — alternar data-theme en <html> == */
+[data-theme="light"] {
+  --bg: #f5f8fb;
+  --surface-1: #ffffff;
+  --surface-2: #ffffff;
+  --surface-3: #eaf1f7;
+  --border: #d8dfe8;
+  /* border-strong NO se redefine en claro: night-400 (:root) cumple 1.4.11 en
+     AMBOS temas (3.26-3.99:1 en dark, 4.27-4.87:1 en light). #b9c3d1 daba
+     1.53-1.78:1, bajo el mínimo de 3:1 para UI. */
+  --text-primary: #14171f;
+  --text-secondary: #3d4354;
+  --text-muted: var(--night-450); /* no night-400: ese caía a 4.27:1 sobre --surface-3 */
+  --text-disabled: #9aa0b0;
+  --text-heading: #14171f;
+  --link: #186a94; /* accent-700 · 5.95:1 sobre blanco — accent-600 solo daba 4.01:1 */
+  --link-hover: #12506f; /* accent-800 · en light el hover OSCURECE (en dark aclara) */
+  --text-on-accent: #010203; /* CTA no cambia entre modos */
+  /* Semánticos de light: son a la vez relleno y TEXTO sobre su propio --*-bg tintado,
+     así que se calibran contra ese fondo, no contra blanco. */
+  --success: #166534;
+  --warning: #854d0e;
+  --danger: #b02c2c;
+  --info: #186a94;
+  --success-bg: #e3f5ea; --warning-bg: #fbf3dd;
+  --danger-bg: #fbe7e7;  --info-bg: #e3f2fb;
+  --accent-ghost-hover: rgba(31,135,187,.08);
+  --accent-ghost-active: rgba(31,135,187,.14);
+  --accent-selected: rgba(82,186,237,.12);
+  --overlay: rgba(20,23,31,.45);
+  --ring: 0 0 0 3px rgba(31,135,187,.25);
+  --shadow-1: 0 1px 3px rgba(53,61,124,.08);
+  --shadow-2: 0 4px 10px rgba(53,61,124,.10);
+  --shadow-3: 0 12px 28px rgba(53,61,124,.14);
+  --glow-accent: 0 0 0 1px rgba(82,186,237,.4), 0 4px 16px rgba(82,186,237,.25);
+  color-scheme: light;
+
+  --focus-color: #186a94;
+  --border-hover: #5f6575;
+  --outline-hover-bg: #eaf1f7;
+  --outline-active-bg: #d8dfe8;
+  --text-on-danger: #ffffff;
+  --data-color: #186a94;
+  --elevated-border: #d8dfe8;
+  --card-border: #d8dfe8;
+  --code-color: #186a94;
+  --code-border: #d8dfe8;
+  --table-header-bg: #eaf1f7;
+  --row-border: #eaf1f7;
+  --row-hover: #f5f8fb;
+  --navbar-bg: rgba(255,255,255,.8);
+  --nav-active: #186a94;
+  --sidebar-bg: #ffffff;
+  --sidebar-active-bg: #e3f2fb;
+  --sidebar-active-text: #14171f;
+  --sidebar-active-icon: #1f87bb;
+  --switch-off: var(--control-border);
+  --tooltip-bg: #14171f;
+  --tooltip-border: #14171f;
+  --tooltip-text: #f6f7f9;
+  --skeleton-base: #eaf1f7;
+  --skeleton-sheen: #f5f8fb;
+  --ring-danger: 0 0 0 3px rgba(192,53,53,.2);
+
+  --selection-bg: var(--action-bg);
+  --selection-text: var(--text-on-action);
+
+  /* Series categóricas: orden estable; acompañar con etiqueta o forma. */
+  --chart-1: #186a94;
+  --chart-2: #853f63;
+  --chart-3: #129a92;
+  --chart-4: #8e4031;
+  --chart-5: #5b975e;
+  --chart-6: #8a600a;
+  --chart-7: #857bc1;
+}
+
+/* == 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;
+  }
 }
 ```
 
@@ -890,6 +1115,17 @@ Grid de 12 columnas, gutter 24px (16px móvil). Mobile-first.
 
 ---
 
+### 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 claro (variante)
 
 El sistema es **dark-first**, pero todo producto debe soportar light mode con los mismos tokens semánticos. La energía de la marca se conserva; solo se invierte el escenario.
@@ -958,7 +1194,7 @@ El glow de acento se mantiene como firma, pero más tenue: `0 0 0 1px rgba(82,18
 - **Toast:** fondo blanco, borde `#d8dfe8`, borde izquierdo semántico.
 - **Overlay de modal:** `rgba(20,23,31,.45)` + blur 4px.
 - **Skeleton:** base `#eaf1f7`, shimmer hacia `#f5f8fb`.
-- **Count-up y motion:** sin cambios; el glow de entrada baja su opacidad máxima a 0.6.
+- **valor final visible desde la carga.6.
 
 ### 15.5 Contraste en light
 
@@ -1002,24 +1238,74 @@ Ratios calculados con la fórmula WCAG 2.x, no estimados a ojo. `mcp/test/contra
   --surface-2: #ffffff;
   --surface-3: #eaf1f7;
   --border: #d8dfe8;
-  /* --border-strong no se redefine: night-400 (:root) cumple 1.4.11 en los dos temas */
+  /* border-strong NO se redefine en claro: night-400 (:root) cumple 1.4.11 en
+     AMBOS temas (3.26-3.99:1 en dark, 4.27-4.87:1 en light). #b9c3d1 daba
+     1.53-1.78:1, bajo el mínimo de 3:1 para UI. */
   --text-primary: #14171f;
   --text-secondary: #3d4354;
-  --text-muted: #5f6575;  /* night-450 — night-400 caía a 4.27:1 sobre --surface-3 */
-  --link: #186a94;        /* accent-700 · 5.95:1 — accent-600 solo da 4.01:1 */
-  --link-hover: #12506f;  /* accent-800 · en light el hover oscurece */
-  --text-on-accent: #010203; /* CTA no cambia */
-  /* Semánticos: son texto sobre su propio --*-bg tintado, no sobre blanco. */
+  --text-muted: var(--night-450); /* no night-400: ese caía a 4.27:1 sobre --surface-3 */
+  --text-disabled: #9aa0b0;
+  --text-heading: #14171f;
+  --link: #186a94; /* accent-700 · 5.95:1 sobre blanco — accent-600 solo daba 4.01:1 */
+  --link-hover: #12506f; /* accent-800 · en light el hover OSCURECE (en dark aclara) */
+  --text-on-accent: #010203; /* CTA no cambia entre modos */
+  /* Semánticos de light: son a la vez relleno y TEXTO sobre su propio --*-bg tintado,
+     así que se calibran contra ese fondo, no contra blanco. */
   --success: #166534;
   --warning: #854d0e;
   --danger: #b02c2c;
   --info: #186a94;
+  --success-bg: #e3f5ea; --warning-bg: #fbf3dd;
+  --danger-bg: #fbe7e7;  --info-bg: #e3f2fb;
+  --accent-ghost-hover: rgba(31,135,187,.08);
+  --accent-ghost-active: rgba(31,135,187,.14);
+  --accent-selected: rgba(82,186,237,.12);
+  --overlay: rgba(20,23,31,.45);
   --ring: 0 0 0 3px rgba(31,135,187,.25);
   --shadow-1: 0 1px 3px rgba(53,61,124,.08);
   --shadow-2: 0 4px 10px rgba(53,61,124,.10);
   --shadow-3: 0 12px 28px rgba(53,61,124,.14);
   --glow-accent: 0 0 0 1px rgba(82,186,237,.4), 0 4px 16px rgba(82,186,237,.25);
   color-scheme: light;
+
+  --focus-color: #186a94;
+  --border-hover: #5f6575;
+  --outline-hover-bg: #eaf1f7;
+  --outline-active-bg: #d8dfe8;
+  --text-on-danger: #ffffff;
+  --data-color: #186a94;
+  --elevated-border: #d8dfe8;
+  --card-border: #d8dfe8;
+  --code-color: #186a94;
+  --code-border: #d8dfe8;
+  --table-header-bg: #eaf1f7;
+  --row-border: #eaf1f7;
+  --row-hover: #f5f8fb;
+  --navbar-bg: rgba(255,255,255,.8);
+  --nav-active: #186a94;
+  --sidebar-bg: #ffffff;
+  --sidebar-active-bg: #e3f2fb;
+  --sidebar-active-text: #14171f;
+  --sidebar-active-icon: #1f87bb;
+  --switch-off: var(--control-border);
+  --tooltip-bg: #14171f;
+  --tooltip-border: #14171f;
+  --tooltip-text: #f6f7f9;
+  --skeleton-base: #eaf1f7;
+  --skeleton-sheen: #f5f8fb;
+  --ring-danger: 0 0 0 3px rgba(192,53,53,.2);
+
+  --selection-bg: var(--action-bg);
+  --selection-text: var(--text-on-action);
+
+  /* Series categóricas: orden estable; acompañar con etiqueta o forma. */
+  --chart-1: #186a94;
+  --chart-2: #853f63;
+  --chart-3: #129a92;
+  --chart-4: #8e4031;
+  --chart-5: #5b975e;
+  --chart-6: #8a600a;
+  --chart-7: #857bc1;
 }
 ```
 
@@ -1045,3 +1331,11 @@ El sistema se distribuye en varios formatos para poder usarlo desde cualquier st
 2. Los componentes consumen solo aliases semánticos (§3.5) — nunca hex.
 3. Para dark/light: alternar `data-theme` en `<html>`; los tokens hacen el resto.
 4. En el `<head>`: `<meta name="theme-color" content="#010203">` (el `--bg` nocturno) — sin él, la barra del navegador queda clara sobre la app oscura. Con el tema claro activo, actualizarlo a `#f5f8fb`.
+
+### Mantenimiento de las distribuciones
+
+Los contratos se definen en esta especificación y sus valores ejecutables en `dist/nocturna-electrica/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.