@higinio/design-mcp 0.2.0 → 0.2.1

package/assets/salvia/design-doc.md

@@ -104,7 +104,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 |
@@ -119,26 +119,32 @@ Los componentes **nunca** usan los primitivos directamente: consumen esta capa.
 
 > ⚠️ **Regla de éxito:** el acento salvia **nunca comunica éxito**. Un resultado positivo usa `--success-*` (verde azulado) + icono ✓ (`check` o `circle-check`) + texto. La distancia de color entre `--accent` y `--success-500` es ΔE76 15.5 en claro y 16.2 en oscuro; el test de contraste exige al menos 15, así que esos dos hex no pueden acercarse más.
 
-### 3.5 Proporción de uso (regla 60-30-10)
+### 3.5 Uso del color y jerarquía
 
-- **60% — Lino y superficies** (`neutral-0/50/100`): fondos y superficies.
-- **30% — Tinta y estructura** (`neutral-600→900`, bordes): texto, iconos, divisores.
-- **10% — Salvia 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`, lino): sin gradientes, texturas de papel, granulado ni patrones; sin ilustraciones de hojas ni full-bleed decorativo — la superficie de trabajo (tarjetas de lino claro) es la protagonista.
-- Estado nunca solo con color: siempre color + icono + texto. El éxito, además, nunca con el salvia del acento.
+| 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 | **Lora** (600–700) | Georgia, serif | **Solo h1–h2**, cifras hero, títulos de marketing — nunca UI ni párrafos |
+| Display | **Lora** (600–700) | Georgia, serif | Marca y títulos editoriales, cifras hero, títulos de marketing — nunca UI ni párrafos |
 | Body/UI | **Nunito Sans** (400–700) | system-ui, sans-serif | Párrafos, botones, formularios, h3–h6 |
 | Mono | **Source Code Pro** (400–500) | ui-monospace, monospace | Datos numéricos, código, IDs, cantidades en tablas |
 
@@ -185,6 +191,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`
@@ -202,6 +216,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 | 32px | `--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 |
@@ -286,11 +334,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 `--border`, texto `--text-disabled` |
+| Primario | fondo `--action-bg`, texto `--text-on-action` | `--action-hover` | `--action-active`, sin sombra | fondo `--border`, texto `--text-disabled` |
 | Secundario | fondo `--surface`, borde `--border-strong`, texto `--text-primary` | fondo `--bg` | fondo `--surface-alt` | 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-600`) | fondo `--accent-soft` | fondo `--accent-soft-strong` | fondo `--border`, texto `--text-disabled` |
@@ -391,7 +439,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`, hover fondo `--bg`; chevron 18px `--text-muted` rota 180° (220ms). `aria-expanded`.
-- Panel: altura animada con `grid-template-rows` 0fr→1fr 280ms ease-out (sin reflow); contenido `text-sm --text-secondary`, padding `0 20px 16px`.
+- Panel: altura animada con `grid-template-rows` 0fr→1fr 280ms 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
@@ -618,7 +666,7 @@ Campo de fecha con un calendario en popover. Reusa el patrón visual del `Popove
 - **`.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__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 `--accent`, texto `--text-on-primary`), `.calendar__day--outside` (días de otro mes, `--text-muted`), `[disabled]` (no seleccionable). El hover usa `--accent-soft`.
+- **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`.
 
@@ -690,7 +738,7 @@ Las duraciones de entrada son algo más largas que en un sistema utilitario, por
 ### 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 `--stagger-step` (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?
@@ -730,26 +778,21 @@ Las duraciones de entrada son algo más largas que en un sistema utilitario, por
 
 ### 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
 
@@ -783,7 +826,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.
 
 ---
 
@@ -815,6 +858,16 @@ Ratios calculados con la fórmula WCAG 2.x (no estimados). El test `mcp/test/con
 ## 13. Tokens CSS consolidados
 
 ```css
+/* ============================================================
+   Salvia Serena — Design Tokens v1.0
+   Sistema de diseño de Higinio Sosa · light-first
+   Fuente de verdad: DESIGN-salvia-serena.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=Lora:ital,wght@0,600;0,700;1,600&family=Nunito+Sans:ital,wght@0,400;0,500;0,600;0,700;1,400&family=Source+Code+Pro:wght@400;500&display=swap");
+
 :root {
   /* == Primitivos: primario (Salvia) == */
   --primary-50: #e2eadf; --primary-100: #d4e0d1; --primary-200: #b8cbb7;
@@ -902,6 +955,107 @@ Ratios calculados con la fórmula WCAG 2.x (no estimados). El test `mcp/test/con
   --stagger-step: 30ms;
 
   color-scheme: light;
+
+  --overlay: rgba(44, 54, 48, .5);
+  --tooltip-bg: var(--neutral-900);
+  --tooltip-text: var(--neutral-0);
+  --focus-color: var(--accent);
+  --text-on-danger: var(--neutral-0);
+  --border-hover: var(--neutral-500);
+  --ring-danger: 0 0 0 3px rgba(181,82,63,.22);
+
+  --action-bg: var(--accent);
+  --action-hover: var(--accent-hover);
+  --action-active: var(--accent-active);
+  --text-on-action: var(--text-on-primary);
+  --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;
+  --touch-target: 44px;
+  --text-display-fluid: clamp(2.5rem, 1.8rem + 2.4vw, 4.5rem);
+
+  /* Series categóricas: orden estable; acompañar con etiqueta o forma. */
+  --chart-1: #549864;
+  --chart-2: #8d4226;
+  --chart-3: #179a8e;
+  --chart-4: #81416d;
+  --chart-5: #8a8b39;
+  --chart-6: #195f91;
+  --chart-7: #996f18;
+  /* 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-8);
+
+}
+
+/* == Modo oscuro (variante) — alternar data-theme en <html> ==
+   Casi sin sombras: las capas se separan por superficie y borde, y solo
+   los overlays (lg/xl) conservan una sombra tenue. */
+[data-theme="dark"] {
+  --bg: #151a17;
+  --surface: #1d231f;
+  --surface-alt: #252c27;
+  --border: #2d3530;
+  --border-strong: #6f7b72;
+  --text-primary: #e3e8e2;
+  --text-secondary: #c4ccc5;
+  --text-muted: #a6b0a8;
+  --text-disabled: #79837b;
+  --accent: #9fc2a8;
+  --accent-hover: #b5d2bc;
+  --accent-active: #8ab295;
+  --accent-soft: #26332b;
+  --accent-soft-strong: #2f4035;
+  --text-on-primary: #151a17;
+  --text-on-primary-solid: #b5d2bc;
+  --link: #b5d2bc;
+  --success-500: #6cc3ac; --success-100: #14271f; --success-text: #8ad3bf;
+  --warning-500: #d9a94f; --warning-100: #2a2213; --warning-text: #e6c17e;
+  --danger-500: #d9806d;  --danger-100: #2c1814;  --danger-text: #e9a597;
+  --info-500: #8fb0c9;    --info-100: #18222b;    --info-text: #a9c4d8;
+  --ring: 0 0 0 3px rgba(159,194,168,.3);
+  --ring-color: rgba(159,194,168,.3);
+  --shadow-xs: none;
+  --shadow-sm: none;
+  --shadow-md: none;
+  --shadow-lg: 0 8px 24px rgba(8,10,9,.3);
+  --shadow-xl: 0 16px 32px rgba(8,10,9,.35);
+  color-scheme: dark;
+
+  --overlay: rgba(0, 0, 0, .6);
+  --tooltip-bg: #e3e8e2;
+  --tooltip-text: #2c3630;
+  --focus-color: var(--accent);
+  --text-on-danger: #151a17;
+  --border-hover: #a6b0a8;
+  --ring-danger: 0 0 0 3px rgba(217,128,109,.25);
+
+  --selection-bg: var(--action-bg);
+  --selection-text: var(--text-on-action);
+
+  /* Series categóricas: orden estable; acompañar con etiqueta o forma. */
+  --chart-1: #60a46f;
+  --chart-2: #a85a3f;
+  --chart-3: #2da79b;
+  --chart-4: #9b5986;
+  --chart-5: #818230;
+  --chart-6: #3678ac;
+  --chart-7: #946b10;
+}
+
+/* == 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;
+  }
 }
 ```
 
@@ -928,6 +1082,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 — del lino al sol a un verde bosque al anochecer.
@@ -1037,6 +1202,26 @@ Ratios calculados, no estimados (mismo test que §12).
   --shadow-lg: 0 8px 24px rgba(8,10,9,.3);
   --shadow-xl: 0 16px 32px rgba(8,10,9,.35);
   color-scheme: dark;
+
+  --overlay: rgba(0, 0, 0, .6);
+  --tooltip-bg: #e3e8e2;
+  --tooltip-text: #2c3630;
+  --focus-color: var(--accent);
+  --text-on-danger: #151a17;
+  --border-hover: #a6b0a8;
+  --ring-danger: 0 0 0 3px rgba(217,128,109,.25);
+
+  --selection-bg: var(--action-bg);
+  --selection-text: var(--text-on-action);
+
+  /* Series categóricas: orden estable; acompañar con etiqueta o forma. */
+  --chart-1: #60a46f;
+  --chart-2: #a85a3f;
+  --chart-3: #2da79b;
+  --chart-4: #9b5986;
+  --chart-5: #818230;
+  --chart-6: #3678ac;
+  --chart-7: #946b10;
 }
 ```
 
@@ -1065,3 +1250,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="#f3f2ec">` (el `--bg` claro, lino); con el tema oscuro activo, actualizarlo a `#151a17` 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/salvia-serena/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.