@higinio/design-mcp 0.1.0 → 0.1.1

package/assets/celeste/tailwind.css

@@ -114,4 +114,8 @@
   --color-accent-soft: var(--accent-soft);
   --color-accent-foreground: var(--text-on-primary);
   --color-link: var(--link);
+  --color-success: var(--success-500);
+  --color-warning: var(--warning-500);
+  --color-danger: var(--danger-500);
+  --color-info: var(--info-500);
 }

package/assets/nocturna/design-doc.md

@@ -48,8 +48,11 @@
 | `accent-300` | `#7dccf1` | Iconos activos, gráficas secundarias, código inline |
 | `accent-400` | `#52baed` | **Acento principal** — CTAs, links, focus, datos clave |
 | `accent-500` | `#2fa3dd` | Hover de botones de acento |
-| `accent-600` | `#1f87bb` | Pressed |
-| `accent-700` | `#186a94` | Bordes de elementos activos |
+| `accent-600` | `#1f87bb` | Pressed; en light, **solo UI** (focus, bordes, iconos) — 4.01:1 sobre blanco |
+| `accent-700` | `#186a94` | Bordes de elementos activos; en light, **texto de acción** — 5.95:1 sobre blanco |
+| `accent-800` | `#12506f` | Solo light: hover del texto de acción — 8.74:1 sobre blanco |
+
+> ⚠️ **Regla AA del acento en claro:** `accent-600` (`#1f87bb`) sobre blanco da **4.01:1**, no 4.5. Pasa el mínimo de **componentes UI** (3:1) pero **no el de texto** (4.5:1). Todo texto de acción sobre fondo claro usa `accent-700`; su hover, `accent-800`. `accent-400` jamás como texto en claro (2.19:1).
 
 ### 3.2 Secundario — Índigo Profundo (base `#353d7c`)
 
@@ -72,6 +75,7 @@
 | `night-700` | `#1e222d` | Superficie 3, hover de filas |
 | `night-600` | `#2a2f3d` | Bordes destacados (énfasis) |
 | `night-500` | `#3d4354` | Bordes por defecto |
+| `night-450` | `#5f6575` | Solo light: texto atenuado (`--text-muted`) — `night-400` caía a 4.27:1 sobre `--surface-3` |
 | `night-400` | `#6b7183` | Deshabilitado, placeholders |
 | `night-300` | `#9aa0b0` | Texto terciario, captions |
 | `night-200` | `#c5c9d4` | Texto secundario |
@@ -304,6 +308,7 @@ Indicador de carga circular; también sustituye el label del botón en estado lo
 
 - Fondo `night-800`, borde `1px night-500`, radius `sm`, altura 44px, padding `0 14px`, texto `night-100`.
 - **Label:** `text-sm` peso 500 `night-200`, margen inferior 6px. Siempre visible (nunca placeholder-como-label).
+- **Campo obligatorio (`.field--required`):** el label muestra un asterisco `danger-400` **decorativo** — pseudo-elemento (`aria-hidden` implícito), nunca un carácter que el lector anuncie. La obligatoriedad real se comunica en el control con `required` + `aria-required="true"`; el asterisco es solo un refuerzo visual (estado nunca solo por color). Contrapartida: marca lo **opcional** con "(opcional)" si el formulario tiene mayoría de campos obligatorios.
 - **Placeholder:** `night-400`.
 - **Hover:** borde `night-400`.
 - **Focus:** borde `accent-400` + `--ring`. Transición 150ms.
@@ -312,7 +317,7 @@ Indicador de carga circular; también sustituye el label del botón en estado lo
 - **Disabled:** fondo `night-900`, texto `night-400`, cursor `not-allowed`.
 - **Ayuda:** `text-sm` `night-300` debajo.
 - Icono leading: padding-left 40px, icono 18px `night-400`.
-- **`inputmode` según el dato** (`numeric`, `email`, `tel`, `decimal`) para el teclado correcto en móvil; `spellcheck="false"` en emails, códigos y usernames.
+- **`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).
 
@@ -349,6 +354,7 @@ Selector de valor único en un rango (`min`/`max`/`step`/`value`).
 
 - 20px, borde `2px night-500`, radius 4px / full.
 - Checked: fondo `accent-400`, check `night-950` animado (stroke-dashoffset, 200ms).
+- **Indeterminate (`input:indeterminate`):** tercer estado, no un "checked a medias" — un checkbox maestro cuyos hijos están parcialmente marcados. Se pinta con fondo `accent-400` y un **guion horizontal** `text-on-accent` (2px de alto), nunca el check. Solo puede activarse por JS (`el.indeterminate = true`); al marcarlo/desmarcarlo el maestro pasa a checked/unchecked normal.
 - Hover: borde `accent-300`. Focus: ring como inputs.
 - Label clicable, gap 10px.
 
@@ -422,9 +428,17 @@ Progreso **determinado** (para carga indeterminada usar `Skeleton`, no Progress)
 - Panel: fondo `night-800`, borde `night-600`, radius `lg`, sombra nivel 3, max-width 480/640px, padding 24px.
 - Entrada: fade + scale(0.96→1) 250ms. Salida 180ms.
 - Header `text-xl` + IconButton cerrar; footer con primaria al extremo derecho.
-- Esc y click en overlay cierran (excepto flujos destructivos).
+- Esc y click en overlay cierran (excepto flujos destructivos: marca el overlay con `data-modal-persistent` para exigir una elección explícita — ni Esc ni click fuera lo cierran).
 - `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 gestión de foco (obligatorias):**
+
+- El panel es `role="dialog"` + `aria-modal="true"` + `aria-labelledby` (id del `.modal__title`); si hay un párrafo de descripción, `aria-describedby` con su id.
+- **Al abrir:** guarda el elemento disparador y mueve el foco al panel (`tabindex="-1"`) o al primer control — así el lector anuncia el título; el panel no muestra anillo porque el foco es programático (`:focus-visible` no se dispara).
+- **Focus-trap:** Tab desde el último control vuelve al primero y Shift+Tab desde el primero salta al último; el foco nunca escapa al fondo mientras el modal está abierto.
+- **Al cerrar:** devuelve el foco al disparador que lo abrió (retorno de foco), venga el cierre de Esc, del overlay o de un botón `data-close-modal`.
+- Motion sin cambios: overlay fade+blur 200ms, panel fade + `scale(0.96→1)` 250ms; ambos respetan `prefers-reduced-motion` vía el piso global.
+
 ### 10.20 Menu
 
 Lista de acciones desplegable anclada a un trigger (acciones de fila, botón "más", menú de cuenta) — mismo patrón visual que el menú de `Select`, pero se abre desde cualquier trigger.
@@ -436,18 +450,21 @@ Lista de acciones desplegable anclada a un trigger (acciones de fila, botón "m
 
 ### 10.21 Tabla
 
-- Header: fondo `night-900`, `text-xs` uppercase `+0.08em` `night-300`, borde inferior `night-600`.
+- Header: fondo `night-900`, `text-xs` uppercase `+0.08em` `night-300`, borde inferior `night-600`. Siempre `scope="col"` en los `<th>`.
 - Filas: altura 52px, borde inferior `night-800`, hover fondo `night-700`.
 - Numéricos a la derecha con `tabular-nums`.
-- Fila seleccionada: fondo `--accent-selected` + borde izquierdo 2px `accent-400`.
+- **Zebra (`.table--zebra`):** filas pares en `--surface-2`; el hover (`--surface-3`) y la selección mandan sobre la banda. Úsala en tablas anchas y densas para seguir la fila; una tabla corta no la necesita.
+- **Sticky header (`.table--sticky`):** `thead` con `position: sticky; top: 0` para que los encabezados queden fijos al hacer scroll dentro de un contenedor con altura acotada (`overflow: auto`).
+- **Header ordenable:** el `<th>` contiene `<button class="th-sort">` con el label + `<svg class="sort-icon">`; el estado vive en `aria-sort` del `<th>` (`none` | `ascending` | `descending`). El icono está atenuado cuando la columna no ordena y se tiñe de `accent-400` (rotando 180° para descendente) cuando sí. Una sola columna ordenada a la vez.
+- **Selección (`.row--selected`):** columna con checkbox en el `<th>` (maestro, con `aria-label`) y en cada fila (checkbox con `aria-label` que describe la fila). La fila marcada usa `.row--selected`: fondo `--accent-selected` + borde izquierdo 2px `accent-400` — no depende solo del color, el checkbox marcado lo refuerza.
 
 ### 10.22 Stat
 
 - **Label** overline arriba: 12px, peso 500, uppercase, tracking `+0.08em`, `night-300`.
 - **Cifra:** JetBrains Mono 49px peso 500, line-height 1.05, color `accent-400`, `tabular-nums`, `white-space: nowrap`.
 - **Delta** opcional debajo: mono 14px — `success-400` / `danger-400` / `night-300` (neutral).
-- Gap vertical 6px. Formato numérico `es-ES`.
-- **Count-up** 600ms ease-out al montar; con `prefers-reduced-motion` muestra el valor directo.
+- Gap vertical 6px. Formato numérico con `Intl.NumberFormat` (`es-MX`).
+- **Count-up** 350ms ease-out al montar (techo `--duration-page`); con `prefers-reduced-motion` muestra el valor directo.
 
 ### 10.23 Pagination
 
@@ -478,6 +495,91 @@ Navegador de páginas 1-indexado, bajo tablas y listas largas.
 - **Link:** color `accent-400`; hover `accent-200` (150ms). Subrayado animado: línea 1px `currentColor` a -2px, `scaleX(0)→scaleX(1)` desde la izquierda, 200ms ease-out. Externo: `target="_blank" rel="noopener noreferrer"` + icono flecha 12px, gap 4px.
 - **Code (inline):** JetBrains Mono `0.9em`, texto `accent-300`, fondo `night-800`, borde `1px night-700`, radius 6px, padding `1px 6px`.
 
+### 10.27 AvatarGroup
+
+Pila de avatares solapados para representar un conjunto de colaboradores/participantes (complementa §10.12 Avatar).
+
+- **`.avatar-group`:** contenedor `inline-flex`; cada avatar reutiliza `.avatar` (cualquier tamaño) y se solapa 8px (`margin-left: -8px`, salvo el primero).
+- **Borde separador:** cada avatar del grupo lleva un borde `2px` **del color del fondo** — `--surface-1` sobre tarjetas, `--bg` sobre el lienzo — para recortarse del de atrás. Es el único caso donde el borde del avatar cambia de color respecto a §10.12.
+- **`.avatar-group__more`:** chip `+N` (modificador sobre `.avatar`) con fondo neutro `--surface-3` y texto `--text-secondary` en Manrope (sin uppercase ni tracking de display), para los avatares ocultos. Va siempre al final.
+- **Accesibilidad:** dale al grupo un nombre accesible (`aria-label="Equipo del proyecto"` o texto adyacente); los avatares con imagen conservan su `alt`. El `+N` no es interactivo por defecto; si abre una lista, conviértelo en `<button>` con `aria-label` ("Ver 3 personas más").
+
+### 10.28 Combobox / Autocomplete y Search
+
+Dos patrones de entrada con filtrado. Complementan al `Select` (§10.6): el combobox se escribe y filtra en vivo; el search recorre contenido.
+
+**Combobox (`.combobox`):**
+
+- `.combobox__input` reutiliza el `Input` (§10.4); `.combobox__list` es el desplegable sobre `--surface-2` (superficie de dropdowns), borde `--border-strong`, sombra nivel 3, radius `md`; `.combobox__option` es cada opción.
+- **Dos estados distintos, nunca solo por color:** `.is-active` = la opción resaltada por teclado (fondo `--surface-3`); `[aria-selected="true"]` = la opción ya elegida (fondo `--accent-selected` + texto `accent-300` + icono check en `accent-400`). La elegida se refuerza con el icono, no solo con el tinte.
+- **Accesibilidad:** el input es `role="combobox"` + `aria-expanded` + `aria-controls` (id de la lista) + `aria-autocomplete="list"` + `aria-activedescendant` (id de la opción activa). La lista es `role="listbox"` con id; cada opción `role="option"` + `aria-selected` + id. `autocomplete="off"` para no chocar con el autorrelleno del navegador.
+- **Teclado:** ↑/↓ mueven la opción activa, Enter la selecciona, Esc cierra. El foco nunca sale del input (patrón listbox); las opciones no son tabulables.
+
+**Search (`.search`):**
+
+- Wrapper `.search` con `.search__icon` (lupa, `aria-hidden`), `.search__input` (reutiliza el `Input`, con padding para el icono y el botón) y `.search__clear` (× con `aria-label="Limpiar"`, visible solo cuando hay texto).
+- El botón limpiar vacía el campo y devuelve el foco al input. Se oculta el botón nativo de `type="search"` de WebKit para no duplicar el affordance.
+
+### 10.29 Drawer / Sheet
+
+Panel que entra deslizándose desde un borde de la pantalla — filtros, detalle contextual, navegación en móvil. Mismo contrato de foco que el `Modal` (§10.19).
+
+- **`.drawer`** (contenedor `fixed`), **`.drawer__overlay`** (mismo `--overlay` del modal, **sin blur nuevo** — el blur solo existe en navbar y overlay de modal, §7), **`.drawer__panel`** sobre `--surface-2` con borde `--border-strong` y sombra nivel 3.
+- **Variantes:** `.drawer--right` (default), `.drawer--left`, `.drawer--bottom` (sheet, con radius superior).
+- **Accesibilidad y foco (obligatorios):** panel `role="dialog"` + `aria-modal="true"` + `aria-labelledby`; **focus-trap + retorno de foco** idénticos al Modal (guarda el disparador al abrir, lo restaura al cerrar); cierra con Esc y con clic en el overlay. `overscroll-behavior: contain` en el panel para que el scroll no se encadene a la página de atrás.
+- **Motion:** `transform: translateX(100%)→0` (translateY para `--bottom`) + fade del overlay, `--duration-slow`/`--ease-out`, dentro del techo (350ms). Entrada y salida interrumpibles vía la clase `.is-open` (`transition`, no keyframes); respetan `prefers-reduced-motion` por el piso global.
+
+### 10.30 Popover
+
+Panel flotante anclado a un disparador que se abre por **clic** — a diferencia del `Tooltip` (§10.15), que aparece por hover y solo informa. El popover puede contener controles (enlaces, botones, campos).
+
+- **`.popover`** (ancla `relative`), **`.popover__trigger`** (cualquier botón), **`.popover__panel`** sobre `--surface-2`, borde `--border-strong`, sombra nivel 3, radius `md`. Origin-aware: crece desde el `transform-origin` del disparador (`--end` lo alinea a la derecha).
+- **Accesibilidad:** trigger `aria-haspopup="dialog"` + `aria-expanded`; panel `role="dialog"` + `aria-label`. El foco entra al panel al abrir; cierra con Esc (devuelve el foco al trigger) y con clic fuera.
+- **Motion:** fade + `scale(0.96→1)` desde el origen, `--duration-base`/`--ease-out`. La visibilidad se retrasa hasta el final de la salida (`visibility`), así el panel cerrado no queda en el orden de tabulación.
+
+### 10.31 ButtonGroup
+
+Botones adyacentes que se leen como un control agrupado de acciones (no de selección — para selección excluyente usa `SegmentedControl`, §10.7).
+
+- **`.btn-group`** agrupa `.btn` existentes: el radius queda solo en los extremos y los bordes internos se colapsan (`margin-left: -1px`). El botón en hover/foco sube de `z-index` para que su borde no lo tape el vecino.
+- **Accesibilidad:** contenedor `role="group"` + `aria-label` que nombra el conjunto.
+- Funciona con cualquier variante de `.btn`; lo habitual es `outline` para que los bordes compartidos se lean.
+
+### 10.32 DatePicker
+
+Campo de fecha con calendario en popover: el input abre el calendario al hacer clic, se elige un día y el valor vuelve al campo.
+
+- **`.datepicker`** (ancla `relative`), **`.datepicker__input`** (reutiliza el `Input` §10.4, con icono de calendario leading vía `.input-wrap`), **`.datepicker__calendar`** = panel que reutiliza el look de `.popover__panel` sobre `--surface-2` (borde `--border-strong`, sombra nivel 3, radius `md`).
+- **Calendario:** `.calendar` contiene `.calendar__header` (mes y año + prev/next con los iconos chevron-left/chevron-right), `.calendar__weekdays` (iniciales L–D) y `.calendar__grid` con los `.calendar__day`.
+- **Estados del día:** `.calendar__day--today` (aro interior `accent-400` + texto `accent-300`), `.calendar__day--selected` (fondo `accent-400`, texto `--text-on-accent`, peso 600 — no depende solo del color), `.calendar__day--outside` (días del mes vecino, atenuados) y `[disabled]` (fuera de rango).
+- **Accesibilidad:** `.calendar__grid` es `role="grid"` con filas `role="row"` (`.calendar__week`, con `display: contents` para no romper el grid); los encabezados de día son `role="columnheader"` con `aria-label` del nombre completo (lunes…); cada día es un `<button role="gridcell">` con `aria-label` de la fecha completa ("10 de julio de 2026") y `aria-selected`. El día de hoy lleva `aria-current="date"`.
+- **Teclado:** el input abre el calendario (clic) y mueve el foco al día activo; las flechas mueven el día enfocado (±1 día, ±7 una semana) cruzando meses, Inicio/Fin saltan a los extremos de la semana, Enter/Espacio eligen y Esc cierra devolviendo el foco al input. Roving tabindex: solo el día activo es tabulable.
+
+### 10.33 FileUpload
+
+Zona de arrastre con lista de archivos.
+
+- **`.file-upload`** envuelve el `.file-upload__input` (file real, oculto accesiblemente con `.visually-hidden` — sigue en el orden de tabulación) y el `.file-upload__label` (zona clicable, borde discontinuo). Dentro del label, `.file-upload__button` resalta la palabra "explora" en `--link`, y `.file-upload__hint` da formatos y tamaño.
+- **`.file-upload.is-dragover`:** al arrastrar un archivo encima, el borde pasa a `accent-400` y el fondo a `--accent-ghost-hover`.
+- **Lista:** `.file-upload__list` con un `.file-upload__item` por archivo — icono + `.file-upload__name` + `.file-upload__size` (mono) + `.file-upload__remove` (× con `aria-label`). Un ítem subiendo incrusta el `.progress` (§10.18). El error usa `.file-upload__item--error`: borde y texto en `danger` **con icono de alerta + texto** ("Error: supera los 10 MB") — nunca solo por color.
+- **Accesibilidad:** el input file lleva label asociado (`for`/`id`) y `aria-describedby` que apunta a la ayuda de formatos/tamaño; el anillo de foco se pinta sobre el label (`:focus-visible` del input, oculto). El botón quitar nombra su archivo ("Quitar informe.pdf").
+
+### 10.34 Stepper / Wizard
+
+Indicador de progreso por pasos.
+
+- **`.stepper`** es un `<ol>`; cada `.step` tiene `.step__marker` (círculo con el número, o el icono check cuando está completo), `.step__label` y `.step__connector` (la línea al paso siguiente; el último paso no la lleva).
+- **Estados:** `.step--complete` (marcador con fondo `accent-400` + check en `--text-on-accent`; el conector se tiñe de `accent-400`), `.step--current` (marcador con borde `accent-400` y número en `accent-300`, label en `--text-primary` peso 600) y `.step--upcoming` (marcador y label atenuados).
+- **Variante `.stepper--vertical`:** apila los pasos; el marcador va a la izquierda y el conector es vertical.
+- **Accesibilidad:** al ser un `<ol>` el orden y el conteo se anuncian solos; el paso en curso lleva `aria-current="step"`; los pasos completos muestran el check (estado no solo por color) y refuerzan con texto oculto ("Completado:", "Paso actual:", "Pendiente:"). El conector es decorativo (`aria-hidden`).
+
+### 10.35 Kbd
+
+Tecla o atajo de teclado.
+
+- **`.kbd`** (sobre `<kbd>`): fondo `--surface-2`, borde `--border-strong`, sombra sutil (nivel 1), JetBrains Mono `text-xs`, radius 6px, alto y ancho mínimo 20px. Para combos se encadenan varias con un "+" literal entre ellas (`⌘ + K`).
+- Úsala en tooltips de atajos, menús y documentación; nunca como botón — es informativa, no interactiva.
+
 ---
 
 ## 11. Animaciones y motion
@@ -522,7 +624,7 @@ Antes de animar algo, pregúntate: ¿de dónde vino, qué cambió, a dónde se f
 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, shimmer).
 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 o segmented, reorder) → `--ease-in-out`, que acelera y frena en espejo; hover y cambios de color → `--ease-out` corto; loops de carga → `linear`.
+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
@@ -613,11 +715,13 @@ Regla: un gap en UI primaria (el flujo principal) es crítico; en UI secundaria,
 
 ## 12. Accesibilidad y contraste
 
-- `night-100` sobre `night-950`: **≈ 16:1** ✅ AAA.
-- `accent-400` sobre `night-950`: **≈ 8.5:1** ✅ — sirve como texto/link.
-- `night-950` sobre `accent-400` (CTAs): **≈ 8.5:1** ✅ — por eso el texto del CTA es oscuro.
-- `indigo-500` sobre `night-950`: **≈ 1.9:1** ⚠️ — solo fondo/decorativo, nunca texto.
-- `night-50` sobre `indigo-500`: **≈ 9:1** ✅ — texto sobre fondos índigo funciona.
+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.
+
+- `night-100` sobre `night-950`: **17.25:1** ✅ AAA.
+- `accent-400` sobre `night-950`: **9.50:1** ✅ — sirve como texto/link.
+- `night-950` sobre `accent-400` (CTAs): **9.50:1** ✅ — por eso el texto del CTA es oscuro.
+- `indigo-500` sobre `night-950`: **2.09:1** ⚠️ — solo fondo/decorativo, nunca texto.
+- `night-50` sobre `indigo-500`: **9.29:1** ✅ — texto sobre fondos índigo funciona.
 - Mínimos WCAG AA: 4.5:1 texto normal, 3:1 texto grande y UI.
 - Focus visible siempre (`:focus-visible` global, §6); estado nunca solo con color (color + icono + texto).
 - Touch targets 44×44px.
@@ -742,8 +846,8 @@ El sistema es **dark-first**, pero todo producto debe soportar light mode con lo
 ### 15.1 Filosofía de la inversión
 
 - Los fondos claros se tiñen levemente de azul (derivados del acento), nunca gris genérico ni blanco plano en toda la pantalla.
-- El celeste `#52baed` sobre blanco tiene contraste bajo (≈ 2.2:1): **no puede ser texto ni link en light**. Los links y textos de acción bajan a `accent-600 (#1f87bb)` y `accent-700 (#186a94)`.
-- El CTA conserva la firma de marca: **fondo `#52baed` con texto `#010203`** funciona igual sobre claro (contraste ≈ 8.5:1) — el botón se ve idéntico en ambos modos.
+- El celeste `#52baed` sobre blanco tiene contraste bajo (2.19:1): **no puede ser texto ni link en light**. El texto de acción baja a `accent-700 (#186a94)` (5.95:1) y su hover a `accent-800 (#12506f)` (8.74:1). `accent-600 (#1f87bb)` **no sirve como texto** —da 4.01:1, por debajo del 4.5 de AA— pero sí como UI (focus, bordes, iconos: mínimo 3:1), y ahí conserva la firma de marca.
+- El CTA conserva la firma de marca: **fondo `#52baed` con texto `#010203`** funciona igual sobre claro (9.50:1) — el botón se ve idéntico en ambos modos.
 - El índigo `#353d7c` gana protagonismo en light: aquí **sí** funciona como texto, headings de marca y fondos de sección con texto blanco.
 
 ### 15.2 Mapeo de tokens
@@ -758,18 +862,23 @@ El sistema es **dark-first**, pero todo producto debe soportar light mode con lo
 | `--border-strong` | `#2a2f3d` | `#b9c3d1` |
 | `--text-primary` | `#e8eaef` | `#14171f` |
 | `--text-secondary` | `#c5c9d4` | `#3d4354` |
-| `--text-muted` | `#9aa0b0` | `#6b7183` |
-| `--link` / texto de acción | `#52baed` | `#1f87bb` |
-| `--link-hover` | `#a8ddf6` | `#186a94` |
+| `--text-muted` | `#9aa0b0` | `#5f6575` (`night-450`) |
+| `--link` / texto de acción | `#52baed` | `#186a94` (`accent-700`) |
+| `--link-hover` | `#a8ddf6` | `#12506f` (`accent-800`) |
 | CTA primario (fondo/texto) | `#52baed` / `#010203` | `#52baed` / `#010203` (sin cambio) |
 | Secundario índigo | `#353d7c` fondo | `#353d7c` fondo, texto blanco |
-| `--success` | `#4ade80` | `#15803d` |
-| `--warning` | `#fbbf24` | `#a16207` |
-| `--danger` | `#f87171` | `#c03535` |
+| `--success` | `#4ade80` | `#166534` |
+| `--warning` | `#fbbf24` | `#854d0e` |
+| `--danger` | `#f87171` | `#b02c2c` |
+| `--info` | `#52baed` | `#186a94` |
 | `--ring` | `rgba(82,186,237,.2)` | `rgba(31,135,187,.25)` |
 
 Fondos suaves semánticos en light: `success #e3f5ea` · `warning #fbf3dd` · `danger #fbe7e7` · `info #e3f2fb`.
 
+> En light, el hover del texto de acción **oscurece** (`accent-700` → `accent-800`); en dark **aclara** (`accent-400` → `accent-200`). Es la misma intención —aumentar el contraste contra el fondo— aplicada a cada modo.
+>
+> Los semánticos de light son a la vez relleno y **texto sobre su propio `--*-bg` tintado**, así que se calibran contra ese fondo (no contra blanco): sobre blanco sobraría margen, pero sobre el fondo del badge se quedaban cortos. `--text-muted` no es `night-400` (`#6b7183`) porque ese caía a 4.27:1 sobre `--surface-3`.
+
 ### 15.3 Elevación en light
 
 Vuelven las sombras clásicas (teñidas de índigo, no negro puro); las superficies dejan de aclararse por nivel:
@@ -786,12 +895,14 @@ El glow de acento se mantiene como firma, pero más tenue: `0 0 0 1px rgba(82,18
 ### 15.4 Ajustes de componentes en light
 
 - **Botón primario:** idéntico al dark (fondo `#52baed`, texto `#010203`) — consistencia de marca entre modos.
-- **Botón secundario:** fondo `#353d7c`, texto blanco (contraste ≈ 9:1 ✅).
-- **Outline/Ghost:** borde `#b9c3d1`, texto `#14171f`; ghost con texto `#1f87bb` y hover `rgba(31,135,187,.08)`.
-- **Inputs:** fondo blanco, borde `#d8dfe8`; focus borde `#1f87bb` + ring.
-- **Tabla:** header `#eaf1f7`, hover de fila `#f5f8fb`, seleccionada `rgba(82,186,237,.12)` + borde izquierdo `#1f87bb`.
+- **Botón secundario:** fondo `#353d7c`, texto blanco (9.95:1 ✅).
+- **Outline/Ghost:** borde `#b9c3d1`, texto `#14171f`; ghost con texto `#186a94` (`accent-700`, 5.95:1) y hover `rgba(31,135,187,.08)`. El texto del ghost **no** es `#1f87bb`: como texto se queda en 4.01:1.
+- **Inputs:** fondo blanco, borde `#d8dfe8`; focus borde `#1f87bb` + ring (es UI, 4.01:1 ≥ 3 ✅).
+- **Tabla:** header `#eaf1f7`, hover de fila `#f5f8fb`, seleccionada `rgba(82,186,237,.12)` + borde izquierdo `#1f87bb` (borde = UI ✅).
 - **Navbar:** blanco 80% + blur, borde inferior `#d8dfe8`; link activo `#186a94`.
-- **Sidebar activo:** fondo `#e3f2fb`, texto `#14171f`, icono `#1f87bb`.
+- **Sidebar activo:** fondo `#e3f2fb`, texto `#14171f`, icono `#1f87bb` (icono = gráfico, mínimo 3:1 ✅).
+- **Cifras y `.progress__value`:** `#186a94` — son **texto**, no relleno; con `#1f87bb` se quedaban en 4.01:1.
+- **Badges de estado:** texto y punto en el semántico correspondiente sobre su `--*-bg`; ver §15.5.
 - **Tooltip:** fondo `#14171f`, texto `#f6f7f9` (se invierte).
 - **Toast:** fondo blanco, borde `#d8dfe8`, borde izquierdo semántico.
 - **Overlay de modal:** `rgba(20,23,31,.45)` + blur 4px.
@@ -800,10 +911,36 @@ El glow de acento se mantiene como firma, pero más tenue: `0 0 0 1px rgba(82,18
 
 ### 15.5 Contraste en light
 
-- `#14171f` sobre `#f5f8fb`: ≈ 16:1 ✅ AAA.
-- `#1f87bb` sobre blanco: ≈ 4.5:1 ✅ AA — link/texto de acción válido.
-- `#52baed` sobre blanco: ≈ 2.2:1 ❌ — **solo relleno decorativo o fondo de CTA con texto oscuro**.
-- Blanco sobre `#353d7c`: ≈ 9:1 ✅ AAA.
+Ratios calculados con la fórmula WCAG 2.x, no estimados a ojo. `mcp/test/contraste-tokens.test.ts` los recalcula desde `tokens.css` en cada corrida.
+
+**Texto (mínimo 4.5:1):**
+
+| Color | Sobre | Ratio | |
+|---|---|---|---|
+| `#14171f` (`--text-primary`) | `#f5f8fb` | **16.81:1** | ✅ AAA |
+| `#3d4354` (`--text-secondary`) | `#f5f8fb` | **9.25:1** | ✅ AAA |
+| `#5f6575` (`night-450`, `--text-muted`) | `#eaf1f7` (`--surface-3`) | **5.11:1** | ✅ AA |
+| `#186a94` (`accent-700`, `--link`) | blanco | **5.95:1** | ✅ AA |
+| `#186a94` | `#f5f8fb` (`--bg`) | **5.58:1** | ✅ AA |
+| `#12506f` (`accent-800`, `--link-hover`) | blanco | **8.74:1** | ✅ AAA |
+| Blanco | `#353d7c` (índigo) | **9.95:1** | ✅ AAA |
+| `#010203` | `#52baed` (CTA) | **9.50:1** | ✅ AAA |
+
+**Semánticos — sobre su propio fondo tintado, que es donde de verdad se leen:**
+
+| Token | Color | Sobre | Ratio | |
+|---|---|---|---|---|
+| `--success` | `#166534` | `#e3f5ea` | **6.29:1** | ✅ AA |
+| `--warning` | `#854d0e` | `#fbf3dd` | **6.19:1** | ✅ AA |
+| `--danger` | `#b02c2c` | `#fbe7e7` | **5.45:1** | ✅ AA |
+| `--info` | `#186a94` | `#e3f2fb` | **5.20:1** | ✅ AA |
+
+**No aptos como texto en claro:**
+
+- `#52baed` (`accent-400`) sobre blanco: **2.19:1** ❌ — solo relleno decorativo o fondo de CTA con texto oscuro.
+- `#1f87bb` (`accent-600`) sobre blanco: **4.01:1** ❌ como texto (AA pide 4.5) — ✅ como **componente UI** (AA pide 3): focus ring, bordes de input, borde de fila seleccionada, iconos. Ahí se queda, y conserva la firma de marca.
+
+> **Corrección (2026-07-14).** Este bloque afirmaba que `#1f87bb` sobre blanco daba 4.5:1. Da **4.01:1**: el número se estimó y nunca se calculó. Como `--link` y `--info` salían de ahí, el texto de acción y el badge de estado nacían fallando AA — un badge sobre `--info-bg` caía a **3.50:1**. Corregido bajando el texto de acción a `accent-700`, añadiendo `accent-800` para su hover y recalibrando los cuatro semánticos contra su fondo tintado. Amarrado con test para que no vuelva a pasar.
 
 ### 15.6 Implementación
 
@@ -817,13 +954,15 @@ El glow de acento se mantiene como firma, pero más tenue: `0 0 0 1px rgba(82,18
   --border-strong: #b9c3d1;
   --text-primary: #14171f;
   --text-secondary: #3d4354;
-  --text-muted: #6b7183;
-  --link: #1f87bb;
-  --link-hover: #186a94;
+  --text-muted: #5f6575;  /* night-450 — night-400 caía a 4.27:1 sobre --surface-3 */
+  --link: #186a94;        /* accent-700 · 5.95:1 — accent-600 solo da 4.01:1 */
+  --link-hover: #12506f;  /* accent-800 · en light el hover oscurece */
   --text-on-accent: #010203; /* CTA no cambia */
-  --success: #15803d;
-  --warning: #a16207;
-  --danger: #c03535;
+  /* Semánticos: son texto sobre su propio --*-bg tintado, no sobre blanco. */
+  --success: #166534;
+  --warning: #854d0e;
+  --danger: #b02c2c;
+  --info: #186a94;
   --ring: 0 0 0 3px rgba(31,135,187,.25);
   --shadow-1: 0 1px 3px rgba(53,61,124,.08);
   --shadow-2: 0 4px 10px rgba(53,61,124,.10);