@higinio/design-mcp 0.1.1 → 0.2.1

package/assets/salvia/design-doc.md

@@ -0,0 +1,1260 @@
+# DESIGN.md — Sistema de Diseño "Salvia Serena"
+
+> Sistema de marca **light-first**, natural y relajante, de **Higinio Sosa** para sus productos de bienestar, hábitos y salud (web, móvil, dashboards, landing pages).
+> Paleta base: `#f3f2ec` (lino, fondo) · `#4f6b58` (salvia, primario) · `#2c3630` (tinta verde)
+>
+> **Versión 1.0**.
+> Entregables: `salvia-serena.html` (style guide), `dist/salvia-serena/` (tokens CSS · framework · Tailwind v4 · DTCG JSON), skill `~/.claude/skills/salvia-serena-design/`.
+
+---
+
+## 1. Identidad y principios
+
+**Personalidad de marca:** natural, relajante y cálida, sin ser rústica. Transmite confort y control sin presión; la calma viene del color, del aire y de un ritmo pausado, no de la decoración. Vibe: *«Lino al sol y hojas de salvia; nada urge»*.
+
+1. **Calma antes que urgencia** — Nada parpadea, nada apremia. El sistema acompaña; nunca presiona ni cuenta hacia atrás.
+2. **Claridad primero** — El contenido siempre por encima de la decoración.
+3. **Un acento a la vez** — El salvia `#4f6b58` guía la acción; nunca compite consigo mismo y **nunca comunica éxito**.
+4. **La naturalidad la ponen el color y la tipografía** — Lino, salvia y una serif cálida (Lora). Sin hojas dibujadas, sin texturas de papel, sin motivos botánicos de adorno.
+5. **Movimiento pausado y con propósito** — Algo más lento que lo habitual, porque relaja; la animación explica (aparece, cambia, desaparece), nunca decora sola.
+
+**Reglas duras propias:**
+
+- **El acento salvia nunca comunica éxito.** El éxito es verde azulado (`--success-500` `#2f7d6a`) y **siempre va con icono ✓** y texto. Un botón salvia y una comida «completada» no pueden verse iguales.
+- **Nada de ilustraciones de hojas ni texturas de papel.** Ni granulado, ni fondos con fibra, ni ramitas en los encabezados: la naturalidad la dan el color y la tipografía.
+
+**Regla de oro de implementación:** los componentes consumen **solo tokens semánticos** (`--surface`, `--accent`, `--text-primary`, `--link`…), nunca hex directos. El theme switch es un cambio de atributo, no un refactor.
+
+---
+
+## 2. Voz y contenido
+
+- **Idioma:** español (México/LatAm neutro) — "tú", nunca "usted".
+- **Tono:** sereno, cercano y natural. Frases cortas y amables; cálido sin ser empalagoso, natural sin ser rústico (nada de "cosecha", "huertito" ni diminutivos). **Cero signos de exclamación** y cero jerga de marketing.
+- **Sin urgencia:** nunca "¡Rápido!", "Última oportunidad", "No te quedes atrás" ni contadores que presionan. Si algo tiene plazo, se dice con calma: "Puedes registrarlo hasta las 23:00".
+- **Sin culpa:** el progreso se cuenta por lo hecho, no por lo que falta. "3 de 8 vasos", no "Te faltan 5". Un día sin registros no se reprocha.
+- **Voz:** segunda persona ("tu comida", "tus hábitos"), nunca primera persona del producto ("nosotros").
+- **Casing:** sentence case en todo — botones, headings, labels. Nunca Title Case ni ALL CAPS, salvo labels uppercase muy puntuales (`+0.04em` tracking) para eyebrows/headers de tabla.
+- **Botones:** 1–3 palabras, imperativos y tranquilos ("Guardar", "Registrar comida", "Más tarde").
+- **Errores:** explican qué falló **y qué hacer**, sin dramatizar: "No se pudo guardar. Revisa tu conexión e inténtalo de nuevo."
+- **Estados vacíos:** invitan a una acción concreta, sin presionar — "Aún no registras comidas hoy. Añade la primera cuando quieras." Nunca un simple "No hay datos".
+- **Logros:** se confirman con sobriedad ("Meta del día cumplida"), con el tono de éxito y su ✓; sin euforia, sin confeti.
+- **Emoji:** no se usan. El estado se comunica con color + icono + texto.
+- **Fechas y números:** siempre con `Intl.DateTimeFormat` / `Intl.NumberFormat` (`es-MX`), nunca formatos hardcodeados ("12/07/2026" a mano se rompe al cambiar de locale).
+- **`translate="no"`** en nombres de marca y tokens de código, para que la traducción automática no los corrompa.
+- **Numerales para conteos:** "8 vasos", no "ocho vasos" — se escanean más rápido.
+
+---
+
+## 3. Paleta de colores
+
+### 3.1 Primario — Salvia (base `#4f6b58`)
+
+| Token | Hex | Uso |
+|---|---|---|
+| `primary-50` | `#e2eadf` | **Acento suave** — hover de ghost/outline, fila seleccionada, chips |
+| `primary-100` | `#d4e0d1` | Seleccionados suaves, ítem activo del sidebar, chip de avatar |
+| `primary-200` | `#b8cbb7` | Bordes activos suaves, divisores destacados |
+| `primary-300` | `#97b09e` | Decorativo — iconos de empty state, gráficas. **Nunca texto** (2.23:1) |
+| `primary-400` | `#73907c` | Iconos secundarios, hover de checkbox/radio (solo UI) |
+| `primary-500` | `#4f6b58` | **Primario** — fondo de botones, bordes activos, focus, rellenos de gráficas |
+| `primary-600` | `#435c4b` | Hover de botones primarios, **`--link`: texto de links y botones ghost** |
+| `primary-700` | `#384d3f` | Pressed/active, tabs y navbar activos, texto sobre `primary-100` |
+| `primary-800` | `#304236` | Texto de marca con alto contraste |
+| `primary-900` | `#2c3630` | **Tinta de marca** — headings, texto principal |
+
+### 3.2 Neutrales — Lino (derivados de `#2c3630`)
+
+| Token | Hex | Uso |
+|---|---|---|
+| `neutral-0` | `#fbfaf6` | Superficie de tarjetas (lino claro, no blanco puro) |
+| `neutral-50` | `#f3f2ec` | **Lino** — fondo general de la app |
+| `neutral-100` | `#eae9e1` | Fondos alternos, filas zebra, tracks |
+| `neutral-200` | `#dfe0d6` | Bordes y divisores por defecto |
+| `neutral-300` | `#b9beb4` | Iconos deshabilitados, presencia "offline" |
+| `neutral-400` | `#858d84` | Bordes de inputs y botones secundarios, placeholder, texto deshabilitado |
+| `neutral-500` | `#5c675f` | Texto terciario, captions |
+| `neutral-600` | `#47524b` | Texto secundario |
+| `neutral-700` | `#38423b` | Párrafos largos |
+| `neutral-800` | `#2c3630` | Texto principal, headings |
+| `neutral-900` | `#1f2622` | Texto de máximo énfasis, fondo de tooltip |
+
+### 3.3 Semánticos (ramp de 3 tonos por estado)
+
+Cada estado tiene tres tokens: el sólido (`-500`), el fondo suave (`-100`) y **el tono de texto AA sobre el fondo suave (`-text`)**. Atención y error son tonos tierra; info es un azul pizarra propio, para no diluir el acento.
+
+| Estado | Sólido `-500` | Fondo `-100` | Texto `-text` | Uso |
+|---|---|---|---|---|
+| `success` | `#2f7d6a` | `#dcefe8` | `#22604f` | Verde azulado — confirmaciones, metas cumplidas, siempre con ✓ |
+| `warning` | `#b8862f` | `#f6ecd8` | `#7e5a17` | Ámbar tierra — avisos, pendientes |
+| `danger` | `#b5523f` | `#f6e4df` | `#8a3a2b` | Rojo arcilla — errores, acciones destructivas |
+| `info` | `#5b7891` | `#e3eaf0` | `#3f5a70` | Azul pizarra — informativos |
+
+### 3.4 Capa de aliases semánticos
+
+Los componentes **nunca** usan los primitivos directamente: consumen esta capa.
+
+| Alias | Valor | Rol |
+|---|---|---|
+| `--bg` | `neutral-50` | Fondo de la app (lino) |
+| `--surface` | `neutral-0` | Tarjetas, paneles |
+| `--surface-alt` | `neutral-100` | Fondos alternos, zebra, tracks |
+| `--border` | `neutral-200` | Borde por defecto |
+| `--border-strong` | `neutral-400` | Bordes de inputs y botones secundarios (3.27:1) |
+| `--text-primary` | `neutral-800` | Texto principal |
+| `--text-secondary` | `neutral-600` | Texto secundario |
+| `--text-muted` | `neutral-500` | Terciario, captions |
+| `--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 |
+| `--accent-hover` | `primary-600` | Hover del primario |
+| `--accent-active` | `primary-700` | Pressed |
+| `--accent-soft` | `primary-50` | Hover de ghost, fondos sutiles |
+| `--accent-soft-strong` | `primary-100` | Seleccionados suaves |
+| `--link` | `primary-600` | **Texto de links y botones ghost (AA 7.00:1)** |
+| `--ring` | `0 0 0 3px rgba(79,107,88,.25)` | Focus ring de inputs |
+
+> ⚠️ **Regla AA de acento:** `primary-500` sobre `--surface` da 5.62:1, pero el texto de links y ghost usa siempre `--link` (`primary-600`, 7.00:1) para que cada rol tenga su token. `primary-400` (3.35:1) solo en iconos y UI; `primary-300` (2.23:1) jamás como texto.
+
+> ⚠️ **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 Uso del color y jerarquía
+
+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.
+
+| 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 y funciones
+
+| Rol | Fuente | Fallback | Uso |
+|---|---|---|---|
+| 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 |
+
+Lora aporta la calidez de una serif caligráfica contenida; Nunito Sans, de terminales suaves, mantiene la UI amable y legible. La itálica de Lora (600) queda para un énfasis editorial puntual en display —una cita, un subtítulo de portada o el descriptor del wordmark (§9)—, nunca en UI ni en párrafos.
+
+Carga vía Google Fonts CDN (familias exactas del brief, no sustitutas — si llegan binarios licenciados, sustituir por `@font-face` con los mismos `font-family`, cero cambios downstream):
+
+```css
+@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");
+```
+
+### 4.2 Escala (ratio 1.25 — tercera mayor, base 16px, en `rem`)
+
+| Token | Tamaño | Line-height (token) | Peso | Uso |
+|---|---|---|---|---|
+| `text-xs` | 12px | 1.5 `--leading-xs` | 400–500 | Captions, labels |
+| `text-sm` | 14px | 1.5 `--leading-sm` | 400 | Texto secundario, tablas |
+| `text-base` | 16px | 1.6 `--leading-base` | 400 | Párrafos, inputs |
+| `text-lg` | 18px | 1.55 `--leading-lg` | 500 | Lead, subtítulos |
+| `text-xl` | 20px | 1.4 `--leading-xl` | 600 | h4 |
+| `text-2xl` | 25px | 1.3 `--leading-2xl` | 600 | h3 (Nunito Sans) |
+| `text-3xl` | 31px | 1.25 `--leading-3xl` | 600 | h2 (Lora) |
+| `text-4xl` | 39px | 1.15 `--leading-4xl` | 700 | h1 (Lora) |
+| `text-5xl` | 49px | 1.1 `--leading-5xl` | 700 | Display/hero |
+
+Pesos tokenizados: `--weight-regular 400` · `--weight-medium 500` · `--weight-semibold 600` · `--weight-bold 700`.
+
+### 4.3 Reglas
+
+- Letter-spacing tokenizado: `--tracking-display: -0.02em` (display ≥31px), `--tracking-body: 0`, `--tracking-label: +0.04em` (labels uppercase).
+- Longitud de línea: `--measure: 65ch` (60–75 caracteres).
+- Números en tablas: `font-variant-numeric: tabular-nums` o Source Code Pro.
+- Mínimo absoluto: 12px con line-height 1.5.
+
+### 4.4 Jerarquía y craft (Butterick)
+
+- **Máx. 3 niveles de heading visualmente distintos por vista.** La escala define tamaños para h1–h4, pero en una misma pantalla no uses más de tres niveles claramente diferenciados; el exceso aplana la jerarquía.
+- **Jerarquía por espacio y peso, no solo por tamaño.** Deja más espacio arriba de un heading que abajo (lo ata a su contenido). Distingue niveles con espacio y peso, no solo con puntos de tamaño.
+- **Comillas y apóstrofos curvos** (« », " ", ' '), nunca rectos (`"`, `'`). Un solo espacio tras el punto seguido (nunca doble, herencia de máquina de escribir).
+- **Interlineado generoso en cuerpo de texto: 150–160%** (ya son los tokens `--leading-base`/`--leading-sm`, §4.2); no bajes de 130% ni en texto denso (tablas, captions).
+- **En dash (–) para rangos y series** ("10–20 minutos", "lun–vie"); **em dash (—) solo para incisos**, con moderación (la skill `anti-slop-diseno` marca >2 por bloque como cliché de IA).
+- **Kerning activado** (`font-kerning: normal`); ligaduras por defecto.
+- En JSX/TSX y en strings usa el carácter UTF-8 real (`'`, `"`), no escapes ni entidades (`’`, `’`), que no se decodifican igual en todos los contextos.
+
+---
+
+### 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`
+
+Aliases de uso (consumir estos, no números sueltos):
+
+| Alias | Valor | Uso |
+|---|---|---|
+| `--card-padding` | 24px (`--space-6`) | Padding de tarjetas (`--card-padding-mobile: 16px`) |
+| `--section-gap` | 64px (`--space-16`) | Separación entre secciones (48–64px) |
+| `--form-gap` | 20px (`--space-5`) | Gap entre campos de formulario |
+| `--button-padding-md` | 12px 20px | Botón md (`--button-padding-sm: 8px 14px`) |
+| `--control-height-sm/md/lg` | 36 / 44 / 52px | Alturas de controles |
+| `--gutter` | 24px | Gutter del grid (`--gutter-mobile: 16px`) |
+
+---
+
+### 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 |
+|---|---|---|
+| `radius-sm` | 8px | Inputs, chips, badges |
+| `radius-md` | 12px | Botones, dropdowns, menús |
+| `radius-lg` | 16px | Tarjetas, modales, accordion |
+| `radius-xl` | 24px | Hero, imágenes destacadas |
+| `radius-full` | 9999px | Avatares, pills, toggles |
+
+Los radios son amplios a propósito: las esquinas suaves bajan la tensión visual sin volver la UI infantil.
+
+- Borde por defecto: `var(--border-width, 1px) solid var(--border)`.
+- **Focus ring global de teclado** (en el framework, especificidad cero vía `:where()` — funciona aunque no uses el reset):
+
+```css
+:where(a, button, [role="button"], input, select, textarea, summary, [tabindex]):focus-visible {
+  outline: 2px solid var(--focus-color);
+  outline-offset: 2px;
+  border-radius: 2px;
+}
+```
+
+Solo lo dispara el teclado (`:focus-visible`), nunca el click de ratón. `--focus-color` es un token del framework que vale `var(--accent)` en los dos modos, así que el contorno sigue al acento: `#4f6b58` en claro (5.62:1 sobre `--surface`) y `#9fc2a8` en oscuro (8.20:1). El SegmentedControl y el chip de métrica usan el mismo token para su foco.
+
+**Transparencia y blur:** únicos usos permitidos — overlay de modal `rgba(44,54,48,.5)` y ring de focus. **No hay glassmorphism ni blur en Salvia Serena**; las superficies son opacas y planas.
+
+---
+
+## 7. Elevación
+
+Sombras suaves teñidas con la tinta verde `#2c3630`, nunca negro puro. Máximo **3 niveles visibles por pantalla**. **Sin resplandor de acento (glow):** la elevación es sombra y borde, nunca brillo.
+
+### Niveles
+
+| Nivel | Superficie | Sombra | Uso |
+|---|---|---|---|
+| 0 | `--bg`, sin sombra, borde discontinuo | — | Reposo del lienzo |
+| 1 | `--surface` + borde `--border` | `--shadow-xs` / `--shadow-sm` | Inputs, tarjetas en reposo |
+| 2 | `--surface` + borde `--border` | `--shadow-md` | Hover, dropdowns |
+| 3 | `--surface` + borde `--border-strong` | `--shadow-lg` / `--shadow-xl` | Modales, popovers, diálogos críticos |
+
+### Sombras
+
+| Token | Valor | Uso |
+|---|---|---|
+| `shadow-xs` | `0 1px 2px rgba(44,54,48,.06)` | Inputs, indicador de SegmentedControl |
+| `shadow-sm` | `0 1px 3px rgba(44,54,48,.08), 0 1px 2px rgba(44,54,48,.05)` | Tarjetas en reposo |
+| `shadow-md` | `0 4px 8px rgba(44,54,48,.09), 0 2px 4px rgba(44,54,48,.05)` | Hover, dropdowns |
+| `shadow-lg` | `0 12px 24px rgba(44,54,48,.12), 0 4px 8px rgba(44,54,48,.06)` | Modales, popovers, menús |
+| `shadow-xl` | `0 24px 48px rgba(44,54,48,.16)` | Diálogos críticos |
+
+---
+
+## 8. Iconografía
+
+- **Set:** [Lucide](https://lucide.dev) como sustituto *(flagged: no hay set propio de marca — si existe, reemplazar)*. Trazo 1.5–2px, esquinas redondeadas — casa con las formas suaves y el ritmo tranquilo de la marca.
+- **Componente `Icon`:** inserta el SVG **inline** para heredar `currentColor` (un componente sirve para cualquier tono) y sobrevivir impresión/exportación. Acepta nombres kebab-case de Lucide; los nombres clásicos pre-renombre (`home`, `alert-circle`, `check-circle`, `alert-triangle`, `more-horizontal`…) se traducen automáticamente.
+- **Tamaños:** 14px inline con texto pequeño · 16–18px inputs/chevrons · 20px botones/toolbars · 40px empty states (en `primary-300` decorativo).
+- **El ✓ es del éxito:** `check` / `circle-check` acompañan siempre a un estado de éxito, en el tono `--success-*`.
+- **Iconos botánicos** (`leaf`, `sprout`…) solo cuando representan un dato real —una categoría «verduras», por ejemplo—, nunca como adorno de marca.
+- **Alineación óptica:** los iconos asimétricos (play, flechas, chevrons) se centran a ojo, no geométricamente — el centro matemático engaña con formas que pesan hacia un lado. Ajustar 1–2px a mano hasta que se vea centrado.
+- Sin emoji; sin Unicode-como-icono (excepto el `/` tipográfico de breadcrumbs).
+
+---
+
+## 9. Marca / Wordmark
+
+No hay logo ni imágenes de marca — el wordmark es puramente tipográfico. Donde un mockup necesite logotipo, se renderiza **"Higinio"** (o el nombre del producto) en `--font-display` — nunca se dibuja un logo aproximado.
+
+- **"Higinio"** en Lora peso 600 (`--weight-semibold`), tracking `--tracking-display` (`-0.02em`), color `--text-primary` (tinta verde). Tamaño de referencia: 31px (`--text-3xl`). El 600 deja ver el trazo caligráfico de Lora sin endurecerlo; el 700 queda para titulares grandes. El `.navbar__brand` del framework usa el mismo peso (`--weight-semibold`) a `text-lg`.
+- **Variante con descriptor:** debajo del nombre, el producto o el lema en Lora 600 itálica, `text-lg`, `--text-secondary`. Dentro de la marca es el único lugar con itálica; en el contenido, §4.1 la admite además en citas y subtítulos de portada.
+- **Variante badge:** mismo texto/tamaño dentro de caja con fondo `--surface`, borde `1px --border`, radius `md` (12px), `shadow-sm`, padding `14px 22px`.
+- El wordmark es texto, no un icono: Lora 600–700, nunca en UI ni párrafos.
+- **Sentence case siempre:** "Higinio", nunca "HIGINIO" ni "higinio".
+- Color `--text-primary`; `primary-300` jamás como texto, tampoco en el wordmark.
+- Sin hojas, ramas ni isotipo botánico junto al nombre. No se genera ilustración para no inventar assets: usar placeholders y pedir los materiales reales.
+
+---
+
+## 10. Biblioteca de componentes
+
+### 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`. 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 `--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` |
+| Destructivo | fondo `danger-500`, texto `--text-on-danger` | oscurecer 8% | oscurecer 14% | opacidad 50% |
+
+- `--text-on-danger` es un token del framework: `neutral-0` en claro (4.74:1 sobre `danger-500`) y la tinta oscura `#151a17` en oscuro (6.09:1), donde el rojo arcilla se aclara y el texto claro ya no alcanza AA. Los oscurecidos de hover y active (`color-mix` con negro al 92% y 86%) se mantienen por encima de 4.5:1 en los dos modos.
+- Con icono: gap 8px, icono 20px.
+- Loading: spinner 16px reemplaza el texto (el botón conserva su ancho — fijar `min-width`).
+- Confirmar es una acción y va en salvia; el éxito es su resultado y se muestra después, en el tono de éxito con ✓. Ningún botón se pinta de `--success-500`.
+
+### 10.2 IconButton
+
+Botón cuadrado solo-icono para toolbars, acciones de fila y chrome. **Requiere `label` accesible** (`aria-label` + `title`). Radius `md`.
+
+- Tamaños: sm 32px (icono 16) · md 44px, `--control-height-md` (icono 18) · lg 48px (icono 20). md y lg cumplen el objetivo táctil de 44×44px (§12); sm queda para chrome denso de escritorio, nunca como único destino táctil, así que el cierre de Toast, Modal y Drawer usa md.
+- Variantes espejo de Button: `primary` (fondo `--accent`, icono `--text-on-primary`; hover `--accent-hover`), `secondary` (fondo `--surface`, borde `--border-strong`; hover `--bg`), `ghost` (transparente, icono `--text-secondary`; hover fondo `--surface-alt`) — **default `ghost`** porque vive en chrome denso, no como CTA.
+- Disabled: opacidad 0.5. Transición de fondo 150ms.
+
+### 10.3 Spinner
+
+Export propio (extraído del estado loading de Button). SVG 16px default: círculo al 25% de opacidad + arco de ¼ sólido, stroke 2.5, rotación 0.8s linear infinita. Color default `--accent`; `--text-on-primary` dentro de botones primary/destructive.
+
+### 10.4 Input
+
+- Fondo `--surface`, borde `1px --border-strong`, radius `sm`, altura `--control-height-md`, padding `0 14px`, `text-base`.
+- **Label:** `text-sm`, peso 500, `--text-secondary`, separado 6px del control. Siempre visible (no usar placeholder como label).
+- **Placeholder:** `--text-disabled`.
+- **Hover:** borde `--border-hover`, un paso más oscuro que el reposo: `neutral-500` en claro (5.65:1 sobre `--surface`) y `#a6b0a8` en oscuro (7.16:1). Lo comparten Textarea, Select, Combobox, Search y DatePicker.
+- **Focus:** borde `--accent` + `--ring`. Transición 150ms.
+- **Error:** borde `danger-500` + `--ring-danger` (ring arcilla suave); mensaje `text-sm` `--danger-text` con icono, 6px debajo (el borde y el ring siguen en `danger-500`, que como texto no llega a 4.5:1 sobre `--bg`).
+- **Éxito (validación):** borde `success-500` + icono ✓ dentro del input.
+- **Disabled:** fondo `--surface-alt`, texto `--text-disabled`, cursor `not-allowed`.
+- **Texto de ayuda:** `text-sm` `--text-muted` debajo del input.
+- Con icono leading: padding-left 40px, icono 18px `--text-disabled`.
+- **`inputmode` según el dato** (`numeric`, `email`, `tel`, `decimal`) para el teclado correcto en móvil; `spellcheck="false"` en emails, códigos y usernames; **`autocomplete` apropiado** (`email`, `current-password`, `one-time-code`, `name`…) para el autorrelleno del navegador.
+- **Nunca bloquear el pegado** (`onpaste`): rompe gestores de contraseñas y códigos de verificación.
+- **Al enviar con errores,** mover el foco al primer campo inválido (no solo pintarlo de rojo).
+- **Campo obligatorio (`.field--required`):** el `.field__label` muestra un asterisco decorativo vía `::after` en color `--danger-text`, y el `<input>` lleva `required` + `aria-required="true"` como señal accesible real (el asterisco es cromo, no el mecanismo). No marques campos "opcionales" con asterisco: el asterisco significa obligatorio.
+
+### 10.5 Textarea
+
+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
+
+- Trigger: igual que input + chevron 16px `--text-muted` (rota 180° al abrir, 220ms).
+- Menú: fondo `--surface`, radius `md`, `shadow-lg`, padding 6px, max-height 320px con scroll.
+- Opción: padding `10px 12px`, radius `sm`, hover fondo `--bg`, seleccionada fondo `--accent-soft` + texto `--link` + check.
+- Entrada del menú: fade + translateY(-4px→0), 220ms (`--duration-base`).
+
+### 10.7 SegmentedControl
+
+Pill compacta de **2–4 opciones mutuamente excluyentes** (switches de vista, filtros rápidos). Para >4 opciones o labels largos, usar `Select`.
+
+- Contenedor: fondo `--surface-alt`, radius `md`, padding 3px. Altura 40px (md) / 32px (sm); segmentos = altura − 6px, padding horizontal 16px.
+- Opción activa: fondo `--surface`, radius `calc(radius-md - 3px)`, `shadow-xs`; **transición de fondo y color 220ms `--ease-out`** (swap de color, nunca animando `left`/`width`).
+- Segmento activo: `--text-primary` semibold; inactivo: `--text-secondary` medium; transición de color 150ms. Texto `text-sm`.
+
+### 10.8 Slider
+
+Rango de valor único.
+
+- Track: 6px de alto, radius full; porción rellena `--accent`, resto `--border` (gradiente vivo, sin elementos extra).
+- Thumb: círculo `--surface` 18px, borde `2px --accent`, `shadow-sm`; **al presionar escala 1.15** (100ms).
+- Label opcional `text-sm --text-secondary` arriba-izquierda; valor en `--font-mono --text-muted` arriba-derecha (`showValue`).
+- Disabled: opacidad 0.5. Props: `min/max/step/value/onChange`.
+
+### 10.9 Checkbox y Radio
+
+- Tamaño 20px, fondo `--surface`, borde `2px --border-strong`, radius 4px (checkbox) / full (radio).
+- Checked: fondo `--accent`, check `--text-on-primary` animado (stroke-dashoffset, 220ms). Marcar es seleccionar, no un estado de éxito.
+- Hover: borde `primary-400`. Focus: ring como inputs.
+- Label clicable, gap 10px, `text-base`. `RadioGroup` agrupa con `role="radiogroup"`.
+- **Indeterminate (`input:indeterminate`):** fondo `--accent` con un guion horizontal (10×2px, `--text-on-primary`) en vez del check. Es el estado de un checkbox "seleccionar todo" cuando la selección es parcial. Es una **propiedad del DOM** (`checkbox.indeterminate = true`), no un atributo HTML: se fija por JS y se sincroniza con las filas seleccionadas (ver §10.21).
+
+### 10.10 Switch
+
+- Track 44×24px, radius full. Off: fondo `--border-strong`. On: fondo `--accent`.
+- Thumb 20px `neutral-0` con `shadow-xs`; desliza 20px en 220ms `ease-spring`.
+
+### 10.11 Badge y Tag
+
+- Badge: `text-xs` peso 500, padding `2px 8px`, radius full. Neutro: fondo `--surface-alt` + texto `--text-secondary`. Semántico: fondo suave (`*-100`) + **texto `--*-text`** del mismo tono. El badge de éxito lleva su icono ✓ de 12px.
+- Tag removible: fondo `--surface-alt`, borde `--border`, incluye botón × de 16px a la vista y 44px de área de toque (`::before` invisible centrado en la ×, como el cierre del Alert); hover del × fondo `--border`.
+
+### 10.12 Avatar
+
+- Imagen de usuario con fallback automático a iniciales (máx. 2, del nombre) sobre chip `--accent-soft-strong` con texto `--text-on-primary-solid` semibold (6.68:1). Si la imagen falla, cae a iniciales.
+- Tamaños: sm 28px (fuente 12) · md 36px (14) · lg 48px (18) · xl 64px (24), o px directo. Radius full.
+- Dot de presencia opcional: 28% del diámetro (mín. 8px), anillo `0 0 0 2px var(--surface)`: online `success-500` · busy `danger-500` · away `warning-500` · offline `neutral-300`.
+
+### 10.13 Divider
+
+- Regla hairline `1px --border`. `role="separator"`.
+- Horizontal (default) · horizontal con label centrado (`text-xs` uppercase, `--tracking-label`, `--text-muted`, medium; líneas flexibles a los lados, gap 12px — patrón "o continúa con") · vertical (se estira al alto del padre flex).
+
+### 10.14 Accordion
+
+- 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 (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
+
+Fondo `--tooltip-bg` (`neutral-900`), texto `--tooltip-text` (`neutral-0`, 14.80:1) `text-xs`, padding `6px 10px`, radius `sm`, flecha 6px. Delay de aparición 400ms, fade + translateY(4px→0) en 150ms. Máximo 1 línea de ayuda; si necesita más, usar popover.
+
+**Skip-delay:** solo el primer tooltip del grupo espera los 400ms; mientras haya un tooltip visible, los hermanos aparecen al instante y sin animación de entrada. El usuario ya está explorando — repetirle el delay y el fade en cada icono estorba.
+
+### 10.16 Alert
+
+Banner de estado **inline y persistente** (vs Toast, transitorio): errores de formulario, avisos de plan.
+
+- 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`. En éxito el ✓ no es opcional.
+- 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, caja visual de 24px) vía `onDismiss`; un `::before` invisible centrado lleva su área de toque a 44px (§12). `role="status"`.
+
+### 10.17 Toast
+
+- Posición: top-right (desktop), top-center (móvil). Ancho 360px. `ToastStack` los apila (gap 12px, máximo 3).
+- Fondo `--surface`, borde izquierdo 3px semántico, `shadow-lg`, radius `md`, padding 14px 16px, icono semántico 20px (✓ en éxito).
+- Entrada: slide-in desde la derecha + fade, 280ms. Salida: fade + translateX, 220ms.
+- Auto-dismiss 5s (pausable con hover).
+- Botón cerrar: IconButton ghost md (44px, §10.2).
+- **Accesibilidad:** el contenedor lleva `role="status"` + `aria-live="polite"`; los toasts de error usan `role="alert"` para anunciarse de inmediato.
+
+### 10.18 Progress y ProgressRing
+
+Progreso **determinado** (para carga indeterminada usar `Skeleton`, no Progress).
+
+- **Lineal:** track 8px radius full fondo `--surface-alt`; relleno en tono (`--accent`/`success-500`/`warning-500`/`danger-500`), width anima 280ms ease-out; label `text-sm --text-secondary` + porcentaje en `--font-mono --text-muted` opcionales. `role="progressbar"` + `aria-valuenow`.
+- **ProgressRing:** SVG rotado -90°, track `--surface-alt`, arco en tono con `strokeLinecap: round`, `stroke-dashoffset` anima 280ms; tamaño default 56px, stroke 5; porcentaje centrado en mono (24% del tamaño).
+- **Avance frente a meta:** mientras se avanza, el relleno es `--accent`; solo al cumplir la meta pasa a `success-500`, con ✓ y el texto que lo dice ("Meta cumplida").
+
+### 10.19 Modal
+
+- Overlay: `--overlay` (`rgba(44,54,48,.5)`), fade 220ms.
+- Panel: fondo `--surface`, radius `lg`, `shadow-xl`, max-width 480px (confirm) / 640px (formulario), padding 24px.
+- Entrada: fade + scale(0.96→1), 280ms. Salida: la misma transición en sentido inverso (280ms, `--duration-slow`).
+- Header con título `text-xl` + IconButton cerrar; footer con acciones alineadas a la derecha (primaria al extremo).
+- Cerrar con Esc y click en overlay (excepto flujos destructivos: el overlay no cierra para evitar descartes accidentales; Esc y los botones sí).
+- `overscroll-behavior: contain` en el panel scrolleable — al llegar al fondo, el scroll no se encadena a la página de atrás.
+
+**Accesibilidad y foco (obligatorio):**
+
+- **Roles y etiquetado:** el contenedor lleva `role="dialog"`, `aria-modal="true"` y `aria-labelledby` apuntando al id del título (`.modal__title`). Si hay texto descriptivo, `aria-describedby` con el id de ese párrafo.
+- **Foco al abrir:** el foco entra al panel (`.modal__panel` con `tabindex="-1"`) o al primer control enfocable del modal.
+- **Focus-trap:** mientras está abierto, Tab y Shift+Tab ciclan solo entre los elementos enfocables del modal; el foco nunca escapa al contenido de atrás (que además está inerte por el overlay).
+- **Retorno de foco:** al cerrar (Esc, botón ×, Cancelar o click en overlay), el foco vuelve al elemento que abrió el modal.
+- El panel se marca con `tabindex="-1"` para poder recibir foco programático sin quedar en el orden de tabulación.
+
+### 10.20 Menu
+
+Lista de acciones desplegable anclada a un trigger (acciones de fila, botones "más", menú de cuenta).
+
+- Panel: fondo `--surface`, borde `--border`, radius `md`, `shadow-lg`, padding 6px, min-width 190px, offset 6px bajo el trigger, `align` left/right.
+- Entrada: fade + translateY(-4px→0) 160ms ease-out.
+- Ítem: `role="menuitem"`, padding `9px 12px`, radius `sm`, `text-sm --text-primary`, icono opcional 16px `--text-muted`, gap 10px; hover fondo `--bg`.
+- Ítem `danger`: texto e icono `--danger-text`, hover fondo `danger-100` (6.28:1).
+- Separador: 1px `--border`, margen `6px 4px`. Cierra con click fuera, Esc o al seleccionar.
+
+### 10.21 Tabla
+
+- Header: fondo `--bg`, `text-xs` uppercase `--tracking-label`, `--text-muted`, borde inferior `--border`. Cada `<th>` lleva `scope="col"`.
+- Filas: altura 52px, borde inferior `--surface-alt`, hover fondo `--bg`.
+- Celdas numéricas alineadas a la derecha con `tabular-nums` en `--font-mono`.
+- Fila seleccionada: fondo `--accent-soft`.
+
+**Variantes (clases del framework):**
+
+- **`.table--zebra`** — filas alternas (`tr:nth-child(even)`) con fondo `--surface-alt`; el hover sigue ganando.
+- **`.table--sticky`** — `thead th` con `position: sticky; top: 0` (fondo opaco del header + `z-index`). El contenedor scrolleable acota la altura para que el header quede fijo.
+- **Header ordenable** — dentro del `<th>` un `<button class="th-sort">` (o `.th-sort--num` para columnas numéricas) con el texto + `.sort-icon`. El `<th>` declara `aria-sort="none|ascending|descending"`; el JS alterna el valor y reordena el `tbody`. El icono se atenúa en `none` y toma `--accent` (rotado 180° en `descending`) al ordenar.
+- **Columna de selección** — `.col-select` (44px, centrada) con un `.checkbox` por fila (`aria-label` describiendo la fila) y un checkbox "seleccionar todo" en el `<th>`. La fila marcada lleva `.row--selected` (fondo `--accent-soft`); el checkbox del header pasa a `indeterminate` cuando la selección es parcial (ver §10.9).
+
+**Accesibilidad:** `scope="col"` en headers; `aria-sort` en la columna ordenable; el `.sort-icon` es `aria-hidden` (el estado real lo da `aria-sort` + el texto del header); cada checkbox de fila con `aria-label` propio.
+
+### 10.22 Stat
+
+Tile de KPI único (componer dentro de `Card` para métricas de dashboard).
+
+- Label `text-sm --text-muted` con icono opcional 16px (gap 8px, margen inferior 8px).
+- 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`). **El delta indica tendencia, no éxito ni fracaso:** la flecha sigue al signo y el tono por defecto es neutro (`--text-secondary`). En métricas de bienestar subir no siempre es bueno, y teñir una bajada de rojo choca con la voz «sin culpa» (§2).
+- `deltaTone` (clases `.stat__delta--up` / `.stat__delta--down`, en `--success-text` / `--danger-text`) solo cuando el producto decide qué sentido es bueno. Aun así no sustituye al ✓: un logro se comunica con el tono de éxito, su icono y texto.
+
+#### 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` (7.00:1 sobre `--surface`) 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 anillo propio (outline 2px `--focus-color`, offset 2px).
+- **Meta cumplida:** el salvia del valor no comunica el logro. Si la métrica llega a su meta, el chip lo dice con un icono ✓ en `--success-500` (modificador `.metric-chip--met`) y con texto en su nombre accesible («Agua: 8 de 8 vasos, meta cumplida»).
+
+```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`.
+
+- Flechas prev/next (chevron 16px) + lista de páginas que **trunca con elipsis a partir de 7 páginas** (patrones `1…n`, ventana `page±1`).
+- Celdas: min-width 36px, altura 36px, radius `sm`, `text-sm` medium `--text-secondary`; hover fondo `--surface-alt`.
+- Página activa: chip sólido `--accent` texto `--text-on-primary` semibold, `aria-current="page"`.
+- Flechas deshabilitadas en extremos (`--text-disabled`); elipsis no clicable.
+
+### 10.24 Navegación
+
+- **Navbar:** altura 64px, fondo `--surface`, borde inferior `--border`. Link `text-sm` medium `--text-secondary`; activo: texto `--accent-active` + indicador inferior 2px `--accent`.
+- **Sidebar:** ancho 260px, fondo `--bg`, borde derecho `--border`. Ítem: radius `md`, padding `10px 12px`, `text-sm` medium `--text-secondary`; hover fondo `--surface-alt`; activo: fondo `--accent-soft-strong`, texto `--link` (5.36:1), icono `--accent`.
+- **Tabs:** borde inferior `--border`; tab activa con texto `--accent-active` e indicador 2px `--accent` que se desliza entre tabs (280ms).
+- **Breadcrumbs:** `text-sm` `--text-muted`, separador `/` (tipográfico), último ítem `--text-primary`; hover de los enlaces en `--link`.
+
+#### 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: bloque plano `--surface-alt` que pulsa en opacidad (`@keyframes ss-pulse`, de 1 a 0.5 y vuelta, 1.36s por tramo = 4 × `--duration-page`, `linear`, loop alternado). Sin degradado: solo cambia la `opacity` del bloque entero. Con `prefers-reduced-motion`, el reset global (§11.5) lo deja quieto y opaco. Radius igual al contenido que reemplaza.
+- Estado vacío (`EmptyState`): icono 40px en `primary-300` decorativo, título `text-lg`, descripción `text-sm` `--text-muted`, CTA claro. Un estado vacío siempre invita a actuar, sin presionar ("Añade la primera cuando quieras").
+
+### 10.26 Card, Link y Code
+
+- **Card:** fondo `--surface`, borde `1px --border`, radius `lg`, padding 24px (16px en móvil), `shadow-sm`.
+- **Card interactiva:** cursor pointer; hover eleva — `translateY(-2px)` + `shadow-md`; transición de transform/sombra 220ms (`--duration-base`) ease-out. Sin glow: en light-first la elevación es sombra + desplazamiento, nunca brillo.
+- **Link:** color `--link` (`primary-600`, AA 7.00:1 sobre `--surface`); subrayado animado 1px `currentColor` que crece de 0%→100% del ancho desde la izquierda (`background-size`, 220ms ease-out). Externo: `target="_blank" rel="noopener noreferrer"` + icono flecha 12px, gap 4px.
+- **Code (inline):** Source Code Pro `0.9em`, texto `--text-primary`, fondo `--surface-alt`, borde `1px --border`, radius `sm`, padding `1px 6px`.
+
+### 10.27 AvatarGroup
+
+Stack de avatares solapados para representar participantes de un proyecto, miembros de un equipo o asignados de una tarea. Complementa al `Avatar` (§10.12).
+
+- **`.avatar-group`** — contenedor `inline-flex`; cada `.avatar` (y el `.avatar-group__more`) se solapa con `margin-left: -8px`.
+- **Anillo de separación** — cada avatar del grupo lleva un borde `2px solid var(--surface)` (radius full) que lo recorta del de atrás; en dark hereda el `--surface` oscuro. El orden de pintado deja el último encima.
+- **`.avatar-group__more`** — chip circular del mismo tamaño (36px) para el `+N` de overflow: fondo `--accent-soft-strong`, texto `--text-on-primary-solid` semibold `text-xs`, mismo anillo y solapamiento. Va al final del grupo.
+- Para más de ~5 avatares, corta la lista y muestra el resto como `+N` (evita filas larguísimas).
+
+### 10.28 Combobox / Autocomplete y Búsqueda
+
+Campo de texto con lista de opciones filtrable (Combobox) y su primo especializado para búsqueda (Search). Para una lista fija sin filtrado, usar `Select` (§10.6); para texto libre sin sugerencias, `Input` (§10.4).
+
+**Combobox (`.combobox`):**
+
+- **`.combobox__input`** — input `role="combobox"` con `aria-expanded`, `aria-controls` (id de la lista), `aria-autocomplete="list"` y `aria-activedescendant` apuntando a la opción activa. Mismo look que `Input` (borde `--border-strong`, focus `--accent` + `--ring`).
+- **`.combobox__list`** — dropdown `role="listbox"` con id; fondo `--surface`, borde `--border`, `shadow-lg`, radius `md`, max-height 264px con scroll. Entra con fade + translateY(-4px→0), `--duration-base` `--ease-out`.
+- **`.combobox__option`** — `role="option"` + `aria-selected`. `.is-active` = resaltado de teclado (fondo `--accent-soft`); `[aria-selected="true"]` = elegida (texto `--link`, medium, check `--accent` a la derecha — el estado no se comunica solo por color).
+- **Teclado:** ↑/↓ mueven la opción activa **sin mover el foco** (que se queda en el input); Enter selecciona, Esc cierra, Home/End saltan a los extremos. La opción activa se señala con `aria-activedescendant`, no con foco real.
+
+**Búsqueda (`.search`):**
+
+- **`.search__icon`** — lupa 18px a la izquierda, `aria-hidden` (decorativa).
+- **`.search__input`** — input con padding lateral 40px para dejar sitio al icono y a la ×.
+- **`.search__clear`** — botón × que aparece solo cuando hay texto (`:not(:placeholder-shown)`), `aria-label="Limpiar"`; al pulsarlo vacía el campo y le devuelve el foco. Mide 32px a la vista y 44px de área de toque (`::before` invisible, como el cierre del Alert).
+
+### 10.29 Drawer / Sheet
+
+Panel que entra deslizando desde un borde para tareas contextuales (filtros, detalle, formulario lateral) sin sacar al usuario de la vista. Modal en comportamiento, lateral en forma.
+
+- **`.drawer`** — contenedor/estado a pantalla completa (`position: fixed`), oculto hasta `.is-open`.
+- **`.drawer__overlay`** — capa `--overlay` que atenúa el fondo; cierra al hacer click.
+- **`.drawer__panel`** — panel `--surface` con `shadow-xl`; `overscroll-behavior: contain` para que el scroll no se encadene a la página. El contenedor lleva `role="dialog"` + `aria-modal="true"` + `aria-labelledby`.
+- **Variantes:** `.drawer--right` (default), `.drawer--left`, `.drawer--bottom` (esta última full-width, con radius superior `lg`).
+- **Foco (igual que Modal, §10.19):** al abrir, el foco entra al panel (`tabindex="-1"`), queda atrapado (Tab/Shift+Tab ciclan) y vuelve al disparador al cerrar. Esc y click en overlay cierran.
+- **Motion:** entra con `translateX(100%)→0` (o `translateY` en la variante bottom) + fade del overlay, `--duration-slow` `--ease-out`; la salida es más corta (`--duration-base`, `--ease-in`). Solo `transform`/`opacity`, bajo el techo `--duration-page`.
+
+### 10.30 Popover
+
+Contenedor flotante con **contenido interactivo** anclado a un disparador. A diferencia del Tooltip (§10.15, solo texto y aparición en hover), el Popover se abre por **click** y puede llevar enlaces, botones o campos.
+
+- **`.popover`** — contenedor relativo (`.is-open` lo abre).
+- **`.popover__trigger`** — disparador con `aria-haspopup="dialog"` + `aria-expanded`.
+- **`.popover__panel`** — `role="dialog"` + `aria-label`/`aria-labelledby`; fondo `--surface`, borde `--border`, `shadow-lg`, radius `md`. El foco entra al panel al abrir; cierra con Esc y click fuera.
+- **Motion:** aparece desde el `transform-origin` del trigger (fade + `scale(0.96→1)`), `--duration-base` `--ease-out` — sin rebote (es un utilitario). Variante `.popover--right` ancla el panel a la derecha.
+
+### 10.31 ButtonGroup
+
+Botones adyacentes con bordes compartidos para acciones relacionadas (barra de fechas, alineación, cambio de vista). Para un único-seleccionado mutuamente excluyente, usar `SegmentedControl` (§10.7).
+
+- **`.btn-group`** — contenedor `inline-flex` con `role="group"` + `aria-label`. Usa los `.btn`/`.btn--secondary` existentes dentro.
+- **Bordes:** radius solo en los extremos (el primer hijo redondea la izquierda, el último la derecha); los bordes internos se colapsan con `margin-left: -1px` para no duplicar la línea. En hover/focus el botón sube en `z-index` para que su borde y su ring queden por encima del vecino.
+
+### 10.32 DatePicker
+
+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-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 `--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`.
+
+### 10.33 FileUpload
+
+Zona de arrastre (dropzone) + lista de archivos.
+
+- **`.file-upload`** — dropzone: borde `2px dashed --border-strong`, radius `lg`, fondo `--surface`. Estado **`.file-upload.is-dragover`** (borde `--accent` + fondo `--accent-soft`) mientras se arrastra un archivo encima.
+- **`.file-upload__input`** — el `<input type="file">` real, oculto de forma accesible (no `display:none`), con **label asociado** (`.file-upload__label for=…`) y `aria-describedby` que apunta al hint de formatos/tamaño. La zona describe la acción ("Arrastra archivos o elige").
+- **`.file-upload__label`** — área central con icono de subida (`#i-upload`), `.file-upload__title` (instrucción), `.file-upload__button` (pseudo-botón "Elegir archivos" — no un `<button>` real, para no anidar interactivos dentro del label) y `.file-upload__hint` (formatos y tamaño máximo).
+- **`.file-upload__list`** / **`.file-upload__item`** — la lista de subidas. Cada item: `.file-upload__icon` (`#i-file`, o `#i-circle-alert` en error), `.file-upload__name` (trunca con ellipsis), `.file-upload__size` (metadatos/estado) y `.file-upload__remove` (× 32px a la vista y 44px de área de toque, con `aria-label` que nombra el archivo). Un item que sube incluye la barra `.progress` (§10.18) dentro de su meta.
+- **Error (`.file-upload__item--error`):** borde `--danger-500`, icono y texto de estado en `--danger-text`; **el estado no se comunica solo por color** — el item lleva icono de alerta + texto que explica qué pasó y qué hacer ("Formato no admitido · elige PDF, PNG o JPG").
+- **JS mínimo:** `is-dragover` en dragenter/dragover, se quita en dragleave/drop; el × elimina su item. La subida real y su validación son responsabilidad de la app.
+
+### 10.34 Stepper / Wizard
+
+Indicador de progreso multipaso.
+
+- **`.stepper`** — un **`<ol>`** horizontal; `.stepper--vertical` lo apila. Cada **`.step`** contiene `.step__marker` (círculo 32px), `.step__label` y, salvo el último, un `.step__connector` (línea de 2px hacia el siguiente paso).
+- **Estados:** `.step--complete` (marcador `--accent` con **`#i-check`** en `--text-on-primary`, conector `--accent`), `.step--current` (marcador con borde e ícono/número `--accent`, label semibold `--text-primary`, `aria-current="step"`), `.step--upcoming` (marcador neutro con su **número**). El completo muestra check y el próximo muestra número: **el estado no depende solo del color**.
+- **Progreso, no éxito:** un paso completo marca avance dentro de un flujo y va en salvia. El resultado del flujo completo ("Plan guardado") se confirma aparte, con el tono de éxito y su ✓.
+- **Conector:** hereda el color de su paso — se pinta `--accent` solo tras un paso completo, marcando hasta dónde llegó el progreso; el marcador va en `z-index` superior para que el círculo tape la línea.
+- a11y: lista ordenada real (`<ol>`), `aria-current="step"` en el actual, iconos decorativos (`aria-hidden`); el número/label textual da la señal no cromática.
+
+### 10.35 Kbd
+
+Tecla del teclado para atajos y ayuda contextual.
+
+- **`.kbd`** (para `<kbd>`) — tecla con fondo `--surface`, borde `--border-strong`, radius `sm`, **sombra sutil de tinta** (`--shadow-xs`), tipografía `--font-mono` `text-xs`, color `--text-secondary`, **mínimo 20px** de ancho/alto. Funciona inline en el texto o suelta.
+- **Combos:** varias `.kbd` con el signo **"+" literal** entre teclas (envueltas en `.kbd-combo` para alinear el "+" en `--text-muted`). Ejemplos: `⌘ + K`, `Ctrl + S`, `Esc`.
+
+---
+
+## 11. Animaciones y motion
+
+### 11.0 Cuándo animar (frequency gate)
+
+La frecuencia de una acción decide su intensidad de movimiento:
+
+| Frecuencia de la acción | Motion |
+|---|---|
+| Rara / memorable (primer uso, meta cumplida) | Puede deleitar con calma: un fundido o un trazo, nunca confeti |
+| Ocasional (abrir un panel, un modal) | Transición clara y pausada |
+| Diaria / repetida (navegar, registrar, alternar) | Sutil y rápida, casi imperceptible |
+| Muy frecuente (100+/día) o de teclado | Sin animación; el movimiento estorbaría |
+
+Antes de animar algo, pregúntate: ¿de dónde vino, qué cambió, a dónde se fue? Si no hay respuesta, no lo animes.
+
+### 11.1 Tokens
+
+Las duraciones de entrada son algo más largas que en un sistema utilitario, porque un ritmo pausado relaja; el feedback táctil (`instant`, `fast`) sigue siendo inmediato.
+
+```css
+:root {
+  --duration-instant: 100ms;  /* feedback táctil: press, toggle */
+  --duration-fast: 150ms;     /* hover, focus, color */
+  --duration-base: 220ms;     /* dropdowns, tooltips, switches */
+  --duration-slow: 280ms;     /* modales, toasts, drawers */
+  --duration-page: 340ms;     /* transiciones de página/vista (techo) */
+
+  --ease-out: cubic-bezier(0.2, 0, 0, 1);      /* entradas (default) */
+  --ease-in: cubic-bezier(0.4, 0, 1, 1);        /* salidas */
+  --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); /* toggles, checks (rebote sutil) */
+  --stagger-step: 30ms;       /* paso entre ítems de una lista con stagger */
+}
+```
+
+### 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. **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?
+6. **Origen consciente** — Popovers, menús y dropdowns aparecen desde el `transform-origin` de su disparador; los modales, desde el centro. Nunca un origen arbitrario.
+7. **Interrumpible** — Toda animación puede invertirse desde su valor visible actual, sin saltar al destino y reanimar. Clave en hover y gestos. En la práctica: para UI que se dispara con frecuencia (toasts, dropdowns, hover) usa `transition` — con `@starting-style` para la entrada al montar —, no `@keyframes`: un keyframe no puede invertirse a mitad de camino. Los `@keyframes` quedan para loops de carga (spinner, pulso del skeleton).
+8. **La salida es más discreta que la entrada** — Además de ~20% más corta, atenúa: menor desplazamiento y menor opacidad. Entrar se nota; salir se difumina.
+9. **El easing según el trabajo** — Entrar → `--ease-out`; salir → `--ease-in`; un elemento que se mueve de un punto a otro de la pantalla (indicador de tabs que se desliza, reorder) → `--ease-in-out`, que acelera y frena en espejo; hover y cambios de color → `--ease-out` corto; loops de carga → `linear`.
+10. **`will-change` solo mientras anima** — Se pone justo antes de animar y se quita al terminar; nunca permanente en el CSS. Presupuesto de capas GPU: menos de 10 elementos promovidos a la vez.
+
+### 11.3 Micro-interacciones por componente
+
+| Elemento | Trigger | Animación |
+|---|---|---|
+| Botón | hover | color de fondo 150ms + `shadow-sm` |
+| Botón | press | `scale(0.98)` 100ms |
+| Link | hover | color 150ms + subrayado que crece de 0 a 100% (220ms) |
+| Tarjeta interactiva | hover | `translateY(-2px)` + `shadow-md`, 220ms |
+| Input | focus | ring que aparece con fade 150ms |
+| Checkbox | check | trazo del check dibujándose 220ms `ease-spring` |
+| Toggle | cambio | thumb desliza 220ms `ease-spring` |
+| SegmentedControl | cambio | la opción activa toma fondo `--surface` 220ms `--ease-out` |
+| Slider | press | thumb escala 1.15, 100ms |
+| Acordeón | abrir | `grid-template-rows` (0fr→1fr) 280ms + fade del contenido |
+| Dropdown / Menu | abrir | fade + translateY(-4px→0) 160–220ms |
+| Modal | abrir | overlay fade 220ms; panel fade + scale(0.96→1) 280ms |
+| Toast | entrar | slide-in + fade 280ms `ease-out` |
+| Icon swap (p. ej. copiar→check) | cambio | cross-fade: opacity + scale(0.9→1), 150ms; nunca blur |
+| Progress | cambio | width / stroke-dashoffset 280ms `ease-out` |
+| Página/vista | cambio | fade + translateY(8px→0) 340ms |
+
+### 11.4 Loading
+
+- Spinner: ver §10.3.
+- Progress: ver §10.18.
+- Skeleton: pulso de opacidad de 1.36s por tramo, en loop alternado (ver §10.25).
+- Si la carga dura <300ms, **no mostrar spinner** (evita parpadeo).
+
+### 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) {
+  :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; }
+}
+```
+
+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
+
+Tells de motion genérico (a menudo generado por IA). La tool `validate_motion` del MCP los detecta con estos umbrales:
+
+| Anti-patrón | Umbral / detección | En su lugar |
+|---|---|---|
+| `transition: all` | cualquier uso | Enumera: `transition: transform 220ms, opacity 220ms` |
+| `ease-in` en entradas | `ease-in` en una entrada de UI | `--ease-out`; reserva `ease-in` para salidas |
+| Animar propiedades de layout | `width/height/top/left/right/bottom/margin/padding` | `transform`/`opacity`. Excepciones: `width` de Progress, `grid-template-rows` del Accordion |
+| Blur como recurso | `filter`/`backdrop-filter: blur()` | Elimínalo; fondos planos de lino, sombras teñidas de tinta |
+| Duración excesiva | > el techo del sistema (`--duration-page`, 340ms) fuera de un loop de carga | Recorta a ≤ `--duration-page` |
+| `scale(0)` | arrancar desde escala 0 | `scale(0.9–0.98)` + `opacity: 0` |
+| Rebote en utilitarios | spring/overshoot en dropdown, menú, modal, tooltip, popover, select | `--ease-out`; el spring sutil se reserva a check y toggle |
+| Overshoot excesivo | curva con y1 > 1.6 | Rebote apenas perceptible (y1 ≤ ~1.4) |
+| blur-everywhere | ≥3 elementos con blur | Rediseña sin blur |
+| hover-scale-en-todo | ≥3 elementos que escalan en hover | Reserva el scale para 1–2 acciones clave |
+| stagger-spam | ≥2 listas con stagger en una vista | Una lista con stagger por vista (máx. 6 ítems) |
+| uniform-fade | ≥4 entradas idénticas | Varía duración/origen o justifícalo |
+| pulsing | indicadores que laten en loop (pulse/ping/glow) | Estado estático claro; spinner o pulso del skeleton solo en carga real. Un latido en un indicador de estado sugiere urgencia, y aquí nada urge |
+| motion-on-mount-for-static | contenido estático que se anima al montar sin razón — no lo detecta la tool; juicio manual | Nada: aplica el frequency gate (§11.0) — si no responde de dónde/qué/adónde, no se anima |
+
+### 11.7 Motion gap
+
+Un "motion gap" es UI que aparece o desaparece sin transición y debería tenerla. Zonas donde suele faltar:
+
+- Render condicional (`{cond && <X/>}`) y ternarios que cambian de vista.
+- Tabs, secciones colapsables y acordeones.
+- Campos condicionales de formularios.
+- Toasts y notificaciones.
+- Estados de carga y de error.
+- Paneles de settings / inspector.
+
+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.
+
+---
+
+## 12. Accesibilidad y contraste
+
+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.
+
+- `--text-primary` (`neutral-800`) sobre `--surface`: **11.99:1** ✅ AAA (sobre `--bg` 11.16 · sobre `--surface-alt` 10.28).
+- `--text-secondary` (`neutral-600`): **7.80:1** sobre `--surface` · 7.27 sobre `--bg` · 6.69 sobre `--surface-alt` ✅ AA.
+- `--text-muted` (`neutral-500`): **5.65:1** sobre `--surface` · 5.26 sobre `--bg` · 4.84 sobre `--surface-alt` ✅ AA.
+- `--link` (`primary-600`) sobre `--surface`: **7.00:1** ✅ AA (sobre `--bg` 6.52 · sobre `--surface-alt` 6.01) — por eso links y ghost usan `--link`.
+- Blanco (`--text-on-primary`) sobre `primary-500`: **5.87:1** ✅ AA para texto normal (hover 7.31 · active 9.12).
+- `--accent` sobre `--surface`: **5.62:1** ✅ (mínimo de UI 3:1).
+- `--border-strong` (`neutral-400`) sobre `--surface`: **3.27:1** ✅ (mínimo de UI 3:1; sobre `--bg` 3.05).
+- `primary-300` (`#97b09e`) sobre `--surface`: **2.23:1** — **nunca como texto**, solo decorativo. `primary-400`: 3.35:1, solo iconos y UI.
+- Tonos `--*-text` garantizan AA sobre los fondos suaves `*-100`: success **6.15:1** · warning **5.33:1** · danger **6.28:1** · info **5.95:1**.
+- Sólidos `-500` sobre `--surface`: success 4.72 · warning 3.10 · danger 4.74 · info 4.43. El texto de estado usa siempre `--*-text`; los `-500` quedan para iconos, bordes y rellenos.
+- `--danger-text` como texto de error (mensaje de campo, ítem destructivo del menú, asterisco de obligatorio): **6.88:1** sobre `--bg` · 7.39 sobre `--surface` · 6.28 sobre `danger-100`. `danger-500` daría 4.41 sobre `--bg` y 4.03 sobre `danger-100`.
+- **Éxito frente a acento:** ΔE76 entre `--accent` y `--success-500` = **15.5** (mínimo 15 en el test). El éxito, además, siempre lleva ✓.
+- Tokens de componente del framework (los fija el mismo test): contorno de foco `--focus-color` sobre `--surface` **5.62:1** · `--text-on-danger` sobre `danger-500` **4.74:1** (hover 5.42 · active 5.97) · `--border-hover` sobre `--surface` **5.65:1**.
+- Otros pares de componentes: avatar (`--text-on-primary-solid` sobre `--accent-soft-strong`) 6.68 · sidebar activo (`--link` sobre `--accent-soft-strong`) 5.36 · tooltip (`neutral-0` sobre `neutral-900`) 14.80.
+- Mínimos WCAG AA: 4.5:1 texto normal, 3:1 texto grande y UI.
+- Focus visible siempre (ring global `:focus-visible`, §6); estado nunca comunicado solo con color (icono + texto).
+- Touch targets mínimos: 44×44px.
+- IconButton siempre con `aria-label`; Progress con `role="progressbar"`; Alert con `role="status"`; Divider con `role="separator"`; Pagination con `aria-current="page"`.
+
+---
+
+## 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;
+  --primary-300: #97b09e; --primary-400: #73907c; --primary-500: #4f6b58;
+  --primary-600: #435c4b; --primary-700: #384d3f; --primary-800: #304236;
+  --primary-900: #2c3630;
+
+  /* == Primitivos: neutrales (Lino) == */
+  --neutral-0: #fbfaf6; --neutral-50: #f3f2ec; --neutral-100: #eae9e1;
+  --neutral-200: #dfe0d6; --neutral-300: #b9beb4; --neutral-400: #858d84;
+  --neutral-500: #5c675f; --neutral-600: #47524b; --neutral-700: #38423b;
+  --neutral-800: #2c3630; --neutral-900: #1f2622;
+
+  /* == Primitivos: semánticos (ramp de 3: sólido / fondo / texto AA) ==
+     El éxito es verde azulado, lejos del acento salvia: el acento nunca comunica éxito. */
+  --success-500: #2f7d6a; --success-100: #dcefe8; --success-text: #22604f;
+  --warning-500: #b8862f; --warning-100: #f6ecd8; --warning-text: #7e5a17;
+  --danger-500: #b5523f;  --danger-100: #f6e4df;  --danger-text: #8a3a2b;
+  --info-500: #5b7891;    --info-100: #e3eaf0;    --info-text: #3f5a70;
+
+  /* == Aliases semánticos (los componentes consumen SOLO esto) == */
+  --bg: var(--neutral-50);
+  --surface: var(--neutral-0);
+  --surface-alt: var(--neutral-100);
+  --border: var(--neutral-200);
+  --border-strong: var(--neutral-400);
+  --text-primary: var(--neutral-800);
+  --text-secondary: var(--neutral-600);
+  --text-muted: var(--neutral-500);
+  --text-disabled: var(--neutral-400);
+  --text-on-primary: #ffffff;
+  --text-on-primary-solid: var(--primary-700);
+  --accent: var(--primary-500);
+  --accent-hover: var(--primary-600);
+  --accent-active: var(--primary-700);
+  --accent-soft: var(--primary-50);
+  --accent-soft-strong: var(--primary-100);
+  --link: var(--primary-600); /* AA 7.00:1 sobre --surface — texto de links y ghost */
+
+  /* == Tipografía == */
+  --font-display: "Lora", Georgia, serif;
+  --font-body: "Nunito Sans", system-ui, -apple-system, sans-serif;
+  --font-mono: "Source Code Pro", ui-monospace, monospace;
+  --text-xs: .75rem; --text-sm: .875rem; --text-base: 1rem; --text-lg: 1.125rem;
+  --text-xl: 1.25rem; --text-2xl: 1.5625rem; --text-3xl: 1.9375rem;
+  --text-4xl: 2.4375rem; --text-5xl: 3.0625rem;
+  --leading-xs: 1.5; --leading-sm: 1.5; --leading-base: 1.6; --leading-lg: 1.55;
+  --leading-xl: 1.4; --leading-2xl: 1.3; --leading-3xl: 1.25;
+  --leading-4xl: 1.15; --leading-5xl: 1.1;
+  --tracking-display: -0.02em; --tracking-body: 0; --tracking-label: 0.04em;
+  --weight-regular: 400; --weight-medium: 500; --weight-semibold: 600; --weight-bold: 700;
+  --measure: 65ch;
+
+  /* == 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;
+  --card-padding: var(--space-6); --card-padding-mobile: var(--space-4);
+  --section-gap: var(--space-16); --form-gap: var(--space-5);
+  --button-padding-md: 12px 20px; --button-padding-sm: 8px 14px;
+  --control-height-sm: 36px; --control-height-md: 44px; --control-height-lg: 52px;
+  --gutter: 24px; --gutter-mobile: 16px;
+
+  /* == Radios, bordes y sombras (teñidas de tinta verde, nunca negro puro) == */
+  --radius-sm: 8px; --radius-md: 12px; --radius-lg: 16px;
+  --radius-xl: 24px; --radius-full: 9999px;
+  --border-width: 1px;
+  --shadow-xs: 0 1px 2px rgba(44,54,48,.06);
+  --shadow-sm: 0 1px 3px rgba(44,54,48,.08), 0 1px 2px rgba(44,54,48,.05);
+  --shadow-md: 0 4px 8px rgba(44,54,48,.09), 0 2px 4px rgba(44,54,48,.05);
+  --shadow-lg: 0 12px 24px rgba(44,54,48,.12), 0 4px 8px rgba(44,54,48,.06);
+  --shadow-xl: 0 24px 48px rgba(44,54,48,.16);
+
+  /* == Focus == */
+  --ring: 0 0 0 3px rgba(79,107,88,.25);
+  --ring-color: rgba(79,107,88,.25);
+
+  /* == Motion (pausado: nada urge) == */
+  --duration-instant: 100ms; --duration-fast: 150ms; --duration-base: 220ms;
+  --duration-slow: 280ms; --duration-page: 340ms;
+  --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); /* 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(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;
+  }
+}
+```
+
+Estilos base (extracto del framework — clase `.salvia-reset` aplicable a `body` o contenedor): fondo `--bg`, color `--text-primary`, `--font-body`/`--text-base`/`--leading-base`, antialiased; **h1 en display bold y h2 en display semibold**, con tracking display; **h3–h6 en body semibold**; `p { max-width: var(--measure) }`; `table { font-variant-numeric: tabular-nums }`; + focus ring global (§6).
+
+---
+
+## 14. Breakpoints y grid
+
+| Token | Ancho | Contenedor |
+|---|---|---|
+| `sm` | 640px | 100% - 32px |
+| `md` | 768px | 720px |
+| `lg` | 1024px | 960px |
+| `xl` | 1280px | 1200px |
+
+Grid de 12 columnas, gutter 24px (16px móvil). Mobile-first. Navbar fija de 64px; sidebar de 260px cuando aplica (riel de 64px si es contraíble, §10.24).
+
+**Touch y viewport:**
+
+- `touch-action: manipulation` en botones y links — elimina el delay de double-tap en móvil.
+- Alturas de viewport con `100dvh`, no `100vh` (la barra de iOS cambia el alto visible).
+- **Receta de overflow:** `min-width: 0` en los hijos flex que deben truncar; texto largo con `text-overflow: ellipsis` o `line-clamp`, siempre con `title` o tooltip que exponga el contenido completo.
+
+---
+
+### 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.
+
+### 15.1 Filosofía de la inversión
+
+- Los fondos se derivan de la tinta verde `#2c3630` (nunca negro puro ni gris genérico): `#151a17` hereda el matiz salvia de la marca.
+- El acento se **aclara**: sobre fondo oscuro, `#4f6b58` pierde fuerza, así que el rol de acento pasa a un salvia claro `#9fc2a8` y el texto sobre él se vuelve oscuro (`#151a17`). El éxito también se aclara (`#6cc3ac`) y conserva su distancia con el acento (ΔE76 16.2).
+- Casi sin sombras: la elevación se apoya en superficies más claras + bordes, y solo los overlays (`--shadow-lg`/`--shadow-xl`) conservan una sombra tenue.
+
+### 15.2 Mapeo de tokens
+
+| Token semántico | Light | Dark |
+|---|---|---|
+| `--bg` | `#f3f2ec` | `#151a17` |
+| `--surface` | `#fbfaf6` | `#1d231f` |
+| `--surface-alt` | `#eae9e1` | `#252c27` |
+| `--border` | `#dfe0d6` | `#2d3530` |
+| `--border-strong` | `#858d84` | `#6f7b72` |
+| `--text-primary` | `#2c3630` | `#e3e8e2` |
+| `--text-secondary` | `#47524b` | `#c4ccc5` |
+| `--text-muted` | `#5c675f` | `#a6b0a8` |
+| `--text-disabled` | `#858d84` | `#79837b` |
+| `--accent` (botones, focus) | `#4f6b58` | `#9fc2a8` |
+| `--accent-hover` | `#435c4b` | `#b5d2bc` |
+| `--accent-active` | `#384d3f` | `#8ab295` |
+| `--accent-soft` | `#e2eadf` | `#26332b` |
+| `--accent-soft-strong` | `#d4e0d1` | `#2f4035` |
+| `--text-on-primary` | `#ffffff` | `#151a17` |
+| `--text-on-primary-solid` | `#384d3f` | `#b5d2bc` |
+| `--link` | `#435c4b` | `#b5d2bc` |
+| `--success` | `#2f7d6a` | `#6cc3ac` |
+| `--warning` | `#b8862f` | `#d9a94f` |
+| `--danger` | `#b5523f` | `#d9806d` |
+| `--info` | `#5b7891` | `#8fb0c9` |
+| `--ring` | `rgba(79,107,88,.25)` | `rgba(159,194,168,.3)` |
+
+Fondos suaves semánticos en dark: `success #14271f` · `warning #2a2213` · `danger #2c1814` · `info #18222b`.
+
+### 15.3 Elevación en dark
+
+| Nivel | Superficie | Sombra |
+|---|---|---|
+| 0 | `#151a17` | — |
+| 1 | `#1d231f` + borde `#2d3530` | ninguna (`--shadow-xs`/`--shadow-sm`: `none`) |
+| 2 | `#1d231f` + borde `#2d3530`; hover sobre `#252c27` | ninguna (`--shadow-md`: `none`) |
+| 3 | `#1d231f` + borde `#6f7b72` | `0 8px 24px rgba(8,10,9,.3)` (`lg`) · `0 16px 32px rgba(8,10,9,.35)` (`xl`) |
+
+### 15.4 Ajustes de componentes en dark
+
+- **Botón primario:** fondo `#9fc2a8`, texto `#151a17` (9.02:1 ✅). Hover `#b5d2bc` (10.83:1), active `#8ab295` (7.45:1).
+- **Inputs:** fondo `--surface` `#1d231f`, borde `#6f7b72` (3.62:1), hover `#a6b0a8` (`--border-hover`), placeholder `#79837b`; focus borde `#9fc2a8` + ring.
+- **Botón destructivo:** fondo `#d9806d`, texto `#151a17` (`--text-on-danger`, 6.09:1).
+- **Foco de teclado:** contorno `#9fc2a8` (`--focus-color`, 8.20:1 sobre `--surface`).
+- **Tabla:** header y hover de fila `#151a17` (`--bg`), seleccionada `#26332b` (`--accent-soft`).
+- **Sidebar activo:** fondo `#2f4035`, texto `#b5d2bc` (6.77:1), icono `#9fc2a8`.
+- **Tooltip:** se invierte — fondo `#e3e8e2`, texto `#2c3630` (10.08:1).
+- **Overlay de modal:** `rgba(0,0,0,.6)`.
+- **Card interactiva:** sin sombras intermedias, el hover se lee por el desplazamiento de 2px y el borde.
+- **Skeleton:** base `#252c27`, con el mismo pulso de opacidad que en claro.
+- Texto claro sobre oscuro "engorda": bajar un peso donde sea posible (500→400).
+
+### 15.5 Contraste en dark
+
+Ratios calculados, no estimados (mismo test que §12).
+
+- `--text-primary` `#e3e8e2` sobre `#151a17`: **14.18:1** ✅ AAA (sobre `--surface` 12.88 · sobre `--surface-alt` 11.52).
+- `--text-secondary` `#c4ccc5`: 10.73 / 9.75 / 8.71 · `--text-muted` `#a6b0a8`: 7.88 / 7.16 / 6.40 (sobre `--bg` / `--surface` / `--surface-alt`) ✅.
+- `--link` `#b5d2bc` sobre `#151a17`: **10.83:1** ✅ (sobre `--surface` 9.84 · sobre `--surface-alt` 8.79).
+- `--text-on-primary` `#151a17` sobre `--accent` `#9fc2a8`: **9.02:1** ✅.
+- `--accent` sobre `--surface`: **8.20:1** · `--border-strong` sobre `--surface`: **3.62:1** ✅ (mínimo de UI 3:1).
+- Tokens de componente: `--focus-color` sobre `--surface` **8.20:1** · `--text-on-danger` sobre `danger-500` **6.09:1** (hover 5.23 · active 4.62) · `--border-hover` sobre `--surface` **7.16:1**.
+- Tonos `--*-text` sobre sus `*-100` en dark: success **9.07:1** · warning **9.20:1** · danger **8.25:1** · info **8.89:1**. `--danger-text` sobre `--bg`: **8.64:1** · sobre `--surface`: 7.84.
+- `--text-on-primary-solid` `#b5d2bc` sobre `--accent-soft-strong` `#2f4035` (iniciales del avatar, `+N` del AvatarGroup): **6.77:1**.
+- **Éxito frente a acento:** ΔE76 = **16.2** (mínimo 15).
+
+### 15.6 Implementación
+
+```css
+[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;
+}
+```
+
+---
+
+## 16. Distribución y consumo
+
+El sistema se distribuye en varios formatos para poder usarlo desde cualquier stack:
+
+| Entregable | Ubicación | Uso |
+|---|---|---|
+| **Este documento** | `DESIGN-salvia-serena.md` | Fuente de verdad legible |
+| **Style guide interactivo** | `salvia-serena.html` | Referencia visual siempre disponible (abrir en navegador) |
+| **Tokens CSS** | `dist/salvia-serena/tokens.css` | Drop-in para cualquier proyecto (vanilla, React, Angular, Vue) |
+| **Framework CSS** | `dist/salvia-serena/salvia-serena.css` | Tokens + clases de componentes (`.btn`, `.card`, `.sidebar`…) y la clase `.salvia-reset` |
+| **Tailwind v4** | `dist/salvia-serena/tailwind.css` | Bloque `@theme` — genera utilidades `bg-primary-500`, `text-neutral-800`, etc. |
+| **DTCG JSON** | `dist/salvia-serena/tokens.json` | Formato estándar W3C DTCG 2025.10 — interoperable con Figma/Tokens Studio/Style Dictionary |
+| **Paquete npm** | `@higinio/design-css/salvia/…` | Subrutas `salvia/tokens.css`, `salvia/framework.css`, `salvia/tailwind.css` y `salvia/tokens.json` |
+| **MCP** | `system="salvia"` | Tokens, specs de componentes y validación desde el servidor MCP (`get_token(system="salvia", name="--accent")`) |
+| **Skill de Claude** | `~/.claude/skills/salvia-serena-design/` | Invocable desde cualquier sesión de Claude Code |
+
+**Cómo consumirlo en un proyecto nuevo:**
+
+1. Copiar `dist/salvia-serena/tokens.css` (o importar `@higinio/design-css/salvia/tokens.css`) antes que cualquier estilo propio, **o** pegar el bloque `@theme` en el CSS de Tailwind v4 (`@higinio/design-css/salvia/tailwind.css`). Para tener también las clases de componentes, `@higinio/design-css/salvia/framework.css`.
+2. Aplicar la clase `.salvia-reset` al `body` (o usar los estilos base equivalentes).
+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.