@higinio/design-mcp 0.1.0 → 0.1.1

package/README.md

@@ -47,7 +47,7 @@ VS Code usa la clave `servers`, no `mcpServers`:
 
 En los tres casos, reemplaza `ABS/RUTA/mcp/dist/index.js` por la ruta absoluta real al archivo compilado (por ejemplo `C:/Users/higinio/Documents/Proyectos/Diseño/mcp/dist/index.js`), usando `/` en vez de `\` para evitar problemas de escape en JSON.
 
-**Nota:** una vez publicado el paquete en npm, la config se simplifica y deja de depender de una ruta local:
+**Nota:** el paquete ya está publicado en npm como [`@higinio/design-mcp`](https://www.npmjs.com/package/@higinio/design-mcp), así que la config puede usar `npx` directamente y deja de depender de una ruta local:
 
 ```json
 { "command": "npx", "args": ["-y", "@higinio/design-mcp"] }
@@ -107,12 +107,15 @@ Para desplegarlo en **Dokploy** y conectarlo desde Claude Code (local o remoto),
 
 ## CLI / pre-commit
 
-Los cuatro validadores puros (`validate_code`, `validate_motion`, `check_slop`, `checklist_preflight`) también se pueden correr sobre archivos locales sin pasar por MCP, con el binario `design-lint` (compilado en `dist/cli.js`):
+Los cuatro validadores puros (`validate_code`, `validate_motion`, `check_slop`, `checklist_preflight`) también se pueden correr sobre archivos locales sin pasar por MCP, con el binario `design-lint`. Como el paquete está publicado en npm, en otro proyecto lo ejecutas con `npx` sin instalar nada; dentro de este repo apuntas a `dist/cli.js`:
 
 ```
 design-lint --system celeste|nocturna [--lang css|html|js] [--json] <archivos o globs...>
 
-# ejemplos
+# desde cualquier proyecto (paquete publicado)
+npx @higinio/design-mcp design-lint --system celeste "src/**/*.css"
+
+# dentro de este repo (binario compilado)
 node dist/cli.js --system celeste src/styles/*.css
 node dist/cli.js --system nocturna --json "src/**/*.html"
 node dist/cli.js --system celeste --lang css tokens.txt   # fuerza el lenguaje

package/assets/celeste/design-doc.md

@@ -306,9 +306,10 @@ Export propio (extraído del estado loading de Button). SVG 16px default: círcu
 - **Disabled:** fondo `neutral-100`, 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.
+- **`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-500`, 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
 
@@ -326,7 +327,7 @@ Mismos estados que input. Min-height 96px, `resize: vertical`, padding 12px 14px
 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.
-- Indicador blanco (`--surface`) deslizante, radius `calc(radius-md - 3px)`, `shadow-xs`; **desliza left/width 200ms ease-out**.
+- Opción activa: fondo blanco (`--surface`), radius `calc(radius-md - 3px)`, `shadow-xs`; **transición de fondo y color 200ms `--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
@@ -344,6 +345,7 @@ Rango de valor único.
 - Checked: fondo `--accent`, check blanco animado (stroke-dashoffset, 200ms).
 - 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
 
@@ -409,9 +411,17 @@ Progreso **determinado** (para carga indeterminada usar `Skeleton`, no Progress)
 - Panel: fondo blanco, radius `lg`, `shadow-xl`, max-width 480px (confirm) / 640px (formulario), padding 24px.
 - Entrada: fade + scale(0.96→1), 250ms. Salida: 180ms.
 - 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).
+- 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).
@@ -424,11 +434,20 @@ Lista de acciones desplegable anclada a un trigger (acciones de fila, botones "m
 
 ### 10.21 Tabla
 
-- Header: fondo `neutral-50`, `text-xs` uppercase `--tracking-label`, `--text-muted`, borde inferior `--border`.
+- Header: fondo `neutral-50`, `text-xs` uppercase `--tracking-label`, `--text-muted`, borde inferior `--border`. Cada `<th>` lleva `scope="col"`.
 - Filas: altura 52px, borde inferior `neutral-100`, hover fondo `neutral-50`.
 - Celdas numéricas alineadas a la derecha con `tabular-nums`.
 - 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).
@@ -462,9 +481,100 @@ Navegador de páginas 1-indexado, bajo una `Table`.
 
 - **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 200ms (`--duration-base`) ease-out. Sin glow: en light-first la elevación es sombra + desplazamiento, nunca brillo.
-- **Link:** color `--link` (primary-700, AA ≈6:1); subrayado animado 1px `currentColor` que crece de 0%→100% del ancho desde la izquierda (`background-size`, 200ms ease-out). Externo: `target="_blank" rel="noopener noreferrer"` + icono flecha 12px, gap 4px.
+- **Link:** color `--link` (primary-700, AA 5.94:1); subrayado animado 1px `currentColor` que crece de 0%→100% del ancho desde la izquierda (`background-size`, 200ms ease-out). Externo: `target="_blank" rel="noopener noreferrer"` + icono flecha 12px, gap 4px.
 - **Code (inline):** IBM Plex Mono `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`, `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.
+
+### 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-expanded` + `aria-controls`; un `.datepicker__icon` de calendario 18px a la derecha (decorativo, `aria-hidden`).
+- **`.datepicker__calendar`** — panel flotante `role="dialog"` con `aria-label`, mismo patrón que `.popover__panel`. Variante `.datepicker--right` ancla a la derecha.
+- **`.calendar`** — dentro del panel: `.calendar__header` (mes/año en `.calendar__title` + botones prev/next con `#i-chevron-left/right`), `.calendar__weekdays` (7 encabezados `role="columnheader"` con `aria-label` completo: "lunes"…), `.calendar__grid` (`role="grid"`), y `.calendar__day` (botón `role="gridcell"`, `aria-label` de la fecha completa vía `Intl.DateTimeFormat` y `aria-selected`). Semana empieza en lunes.
+- **Estados de día:** `.calendar__day--today` (semibold + anillo interior `--border-strong`), `.calendar__day--selected` (fondo `--accent`, texto `--text-on-primary`), `.calendar__day--outside` (días de otro mes, `--text-disabled`), `[disabled]` (no seleccionable). El hover usa `--accent-soft`.
+- **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 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`** blanco, 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**.
+- **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 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
@@ -509,7 +619,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
@@ -523,7 +633,7 @@ Antes de animar algo, pregúntate: ¿de dónde vino, qué cambió, a dónde se f
 | Input | focus | ring que aparece con fade 150ms |
 | Checkbox | check | trazo del check dibujándose 200ms `ease-spring` |
 | Toggle | cambio | thumb desliza 200ms `ease-spring` |
-| SegmentedControl | cambio | indicador desliza left/width 200ms `--ease-in-out` |
+| SegmentedControl | cambio | la opción activa toma fondo blanco 200ms `--ease-out` |
 | Slider | press | thumb escala 1.15, 100ms |
 | Acordeón | abrir | `grid-template-rows` (0fr→1fr) 250ms + fade del contenido |
 | Dropdown / Menu | abrir | fade + translateY(-4px→0) 160–180ms |
@@ -601,11 +711,13 @@ Regla: un gap en UI primaria (el flujo principal) es crítico; en UI secundaria,
 
 ## 12. Accesibilidad y contraste
 
-- `neutral-800` sobre blanco: **≈ 10.4:1** ✅ AAA.
-- Blanco sobre `primary-500`: **≈ 3.4:1** ⚠️ solo texto ≥18px/bold o componentes UI; para texto normal usar fondo `primary-700`.
-- `--link` (`primary-700`) sobre blanco: **≈ 6:1** ✅ AA — por eso links y ghost usan `--link`, no `primary-500`.
+Ratios calculados con la fórmula WCAG 2.x (no estimados). El test `mcp/test/contraste-tokens.test.ts` los recalcula desde `tokens.css` en cada corrida: si alguien retoca la paleta y rompe un mínimo, la suite falla.
+
+- `neutral-800` sobre blanco: **12.42:1** ✅ AAA.
+- Blanco sobre `primary-500`: **3.22:1** ⚠️ solo texto ≥18px/bold o componentes UI; para texto normal usar fondo `primary-700`.
+- `--link` (`primary-700`) sobre blanco: **5.94:1** ✅ AA — por eso links y ghost usan `--link`, no `primary-500`.
 - `primary-300` (#a0c0d4) **nunca como texto sobre blanco** — solo decorativo.
-- Tonos `--*-text` garantizan AA sobre los fondos suaves `*-100`.
+- Tonos `--*-text` garantizan AA sobre los fondos suaves `*-100`: success **5.30:1** · warning **4.72:1** · danger **6.60:1** · info **4.83:1**.
 - 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.
@@ -772,7 +884,7 @@ Fondos suaves semánticos en dark: `success #12291f` · `warning #2b2210` · `da
 
 ### 15.4 Ajustes de componentes en dark
 
-- **Botón primario:** fondo `#87a8c7`, texto `#16181e` (contraste ≈ 7:1 ✅). Hover `#a0c0d4`.
+- **Botón primario:** fondo `#87a8c7`, texto `#16181e` (7.14:1 ✅). Hover `#a0c0d4`.
 - **Inputs:** fondo `#252935`, borde `#3a3f4d`, placeholder `#8b91a0`; focus borde `#a0c0d4` + ring.
 - **Tabla:** header `#1d2028`, hover de fila `#252935`, seleccionada `rgba(160,192,212,.1)`.
 - **Sidebar activo:** fondo `rgba(113,146,186,.15)`, texto `#e6e9ee`, icono `#a0c0d4`.
@@ -783,9 +895,12 @@ Fondos suaves semánticos en dark: `success #12291f` · `warning #2b2210` · `da
 
 ### 15.5 Contraste en dark
 
-- `#e6e9ee` sobre `#16181e`: ≈ 13:1 ✅ AAA.
-- `#a0c0d4` sobre `#16181e`: ≈ 8:1 ✅ — en dark el celeste **sí** puede ser texto/link (al revés que en light).
-- `#7192ba` sobre `#16181e`: ≈ 4.6:1 ✅ AA — usable en texto normal.
+Ratios calculados, no estimados (mismo test que §12).
+
+- `#e6e9ee` sobre `#16181e`: **14.58:1** ✅ AAA.
+- `#a0c0d4` sobre `#16181e`: **9.28:1** ✅ — en dark el celeste **sí** puede ser texto/link (al revés que en light).
+- `#7192ba` sobre `#16181e`: **5.51:1** ✅ AA — usable en texto normal.
+- Tonos `--*-text` sobre sus `*-100` en dark: success **8.76:1** · warning **9.60:1** · danger **8.03:1** · info **8.20:1**.
 
 ### 15.6 Implementación
 

package/assets/celeste/framework.css

@@ -304,6 +304,8 @@
 .field__help { font-size: var(--text-sm); color: var(--text-muted); }
 .field__error { font-size: var(--text-sm); color: var(--danger-500); display: inline-flex; align-items: center; gap: 6px; }
 .field__error svg { width: 14px; height: 14px; flex: none; }
+/* Campo obligatorio (§10.4): asterisco decorativo; el input lleva required/aria-required */
+.field--required .field__label::after { content: " *"; color: var(--danger-500); }
 
 .input, .textarea, .select {
   width: 100%; font-family: var(--font-body); font-size: var(--text-base);
@@ -421,6 +423,15 @@
 .checkbox input:checked ~ .checkbox__box svg { stroke-dashoffset: 0; }
 .checkbox input:focus-visible ~ .checkbox__box { box-shadow: var(--ring); }
 .checkbox input:disabled ~ * { opacity: .5; cursor: not-allowed; }
+/* Estado indeterminate (§10.9): guion horizontal para "seleccionar todo" parcial */
+.checkbox__box { position: relative; }
+.checkbox input:indeterminate ~ .checkbox__box { background: var(--accent); border-color: var(--accent); }
+.checkbox input:indeterminate ~ .checkbox__box svg { visibility: hidden; }
+.checkbox input:indeterminate ~ .checkbox__box::after {
+  content: ""; position: absolute; top: 50%; left: 50%;
+  width: 10px; height: 2px;
+  background: var(--text-on-primary); transform: translate(-50%, -50%);
+}
 
 .radio__dot {
   width: 20px; height: 20px; flex: none; display: grid; place-items: center;
@@ -526,6 +537,19 @@
 .avatar__dot--busy   { background: var(--danger-500); }
 .avatar__dot--away   { background: var(--warning-500); }
 
+/* AvatarGroup (§10.27): stack solapado con anillo de superficie */
+.avatar-group { display: inline-flex; align-items: center; }
+.avatar-group .avatar { border: 2px solid var(--surface); border-radius: var(--radius-full); }
+.avatar-group .avatar + .avatar,
+.avatar-group .avatar-group__more { margin-left: -8px; }
+.avatar-group__more {
+  display: grid; place-items: center; flex: none;
+  width: 36px; height: 36px; border-radius: var(--radius-full);
+  border: 2px solid var(--surface);
+  background: var(--accent-soft-strong); color: var(--text-on-primary-solid);
+  font-family: var(--font-body); font-size: var(--text-xs); font-weight: var(--weight-semibold);
+}
+
 .divider { border: 0; border-top: var(--border-width) solid var(--border); margin: var(--space-4) 0; }
 .divider--label {
   display: flex; align-items: center; gap: 12px; border: 0; margin: var(--space-4) 0;
@@ -787,6 +811,30 @@
 .table tbody tr.is-selected { background: var(--accent-soft); }
 .table .num, .table td.num, .table th.num { text-align: right; font-family: var(--font-mono); }
 
+/* Variantes de tabla (§10.21): zebra, sticky header, orden y selección */
+.table--zebra tbody tr:nth-child(even) { background: var(--surface-alt); }
+.table--zebra tbody tr:nth-child(even):hover { background: var(--bg); }
+.table--sticky thead th { position: sticky; top: 0; z-index: 1; }
+.table tbody tr.row--selected,
+.table tbody tr.row--selected:hover { background: var(--accent-soft); }
+.table .col-select { width: 44px; text-align: center; }
+.table .col-select .checkbox { display: inline-flex; justify-content: center; gap: 0; }
+
+.th-sort {
+  display: inline-flex; align-items: center; gap: 6px; width: 100%;
+  border: 0; background: transparent; cursor: pointer;
+  font: inherit; letter-spacing: inherit; text-transform: inherit; color: inherit; text-align: left;
+}
+.th-sort--num { justify-content: flex-end; }
+.th-sort .sort-icon {
+  width: 14px; height: 14px; flex: none; opacity: .35;
+  transition: opacity var(--duration-fast) var(--ease-out),
+              transform var(--duration-base) var(--ease-out);
+}
+.table th[aria-sort="ascending"] .sort-icon,
+.table th[aria-sort="descending"] .sort-icon { opacity: 1; color: var(--accent); }
+.table th[aria-sort="descending"] .sort-icon { transform: rotate(180deg); }
+
 .stat__label {
   display: inline-flex; align-items: center; gap: 8px; margin-bottom: 8px;
   font-size: var(--text-sm); color: var(--text-muted);
@@ -902,6 +950,306 @@
   border-radius: var(--radius-sm); padding: 1px 6px;
 }
 
+/* --------------------------------------------------------------------------
+   13b. COMBOBOX · BÚSQUEDA · DRAWER · POPOVER · BUTTONGROUP (§10.28–10.31)
+   -------------------------------------------------------------------------- */
+
+/* Combobox / Autocomplete (§10.28) */
+.combobox { position: relative; }
+.combobox__input {
+  width: 100%; height: var(--control-height-md); padding: 0 14px;
+  font-family: var(--font-body); font-size: var(--text-base);
+  color: var(--text-primary); background: var(--surface);
+  border: var(--border-width) solid var(--border-strong); border-radius: var(--radius-sm);
+  transition: border-color var(--duration-fast) var(--ease-out),
+              box-shadow var(--duration-fast) var(--ease-out);
+}
+.combobox__input:hover:not(:disabled):not(:focus) { border-color: var(--text-disabled); }
+.combobox__input:focus { outline: none; border-color: var(--accent); box-shadow: var(--ring); }
+.combobox__input:disabled { background: var(--surface-alt); color: var(--text-disabled); cursor: not-allowed; }
+.combobox__list {
+  position: absolute; top: calc(100% + 6px); left: 0; right: 0; z-index: 50;
+  max-height: 264px; overflow-y: auto; margin: 0; padding: 6px; list-style: none;
+  background: var(--surface); border: var(--border-width) solid var(--border);
+  border-radius: var(--radius-md); box-shadow: var(--shadow-lg);
+  opacity: 0; transform: translateY(-4px); pointer-events: none;
+  transition: opacity var(--duration-base) var(--ease-out),
+              transform var(--duration-base) var(--ease-out);
+}
+.combobox.is-open .combobox__list { opacity: 1; transform: none; pointer-events: auto; }
+.combobox__option {
+  display: flex; align-items: center; gap: 8px;
+  padding: 10px 12px; border-radius: var(--radius-sm);
+  font-size: var(--text-sm); color: var(--text-primary); cursor: pointer;
+  transition: background-color var(--duration-fast) var(--ease-out);
+}
+.combobox__option .combobox__check {
+  width: 16px; height: 16px; margin-left: auto; flex: none;
+  color: var(--accent); opacity: 0;
+}
+.combobox__option.is-active { background: var(--accent-soft); }
+.combobox__option[aria-selected="true"] { color: var(--link); font-weight: var(--weight-medium); }
+.combobox__option[aria-selected="true"] .combobox__check { opacity: 1; }
+.combobox__empty { padding: 10px 12px; font-size: var(--text-sm); color: var(--text-muted); }
+
+/* Búsqueda (§10.28) */
+.search { position: relative; display: flex; align-items: center; }
+.search__icon {
+  position: absolute; left: 12px; top: 50%; transform: translateY(-50%);
+  width: 18px; height: 18px; color: var(--text-disabled); pointer-events: none;
+}
+.search__input {
+  width: 100%; height: var(--control-height-md); padding: 0 40px;
+  font-family: var(--font-body); font-size: var(--text-base);
+  color: var(--text-primary); background: var(--surface);
+  border: var(--border-width) solid var(--border-strong); border-radius: var(--radius-sm);
+  transition: border-color var(--duration-fast) var(--ease-out),
+              box-shadow var(--duration-fast) var(--ease-out);
+}
+.search__input::-webkit-search-cancel-button { -webkit-appearance: none; appearance: none; }
+.search__input:hover:not(:focus) { border-color: var(--text-disabled); }
+.search__input:focus { outline: none; border-color: var(--accent); box-shadow: var(--ring); }
+.search__clear {
+  position: absolute; right: 6px; top: 50%; transform: translateY(-50%);
+  display: none; width: 32px; height: 32px; align-items: center; justify-content: center;
+  border: 0; border-radius: var(--radius-full); background: transparent;
+  color: var(--text-muted); cursor: pointer;
+  transition: background-color var(--duration-fast) var(--ease-out),
+              color var(--duration-fast) var(--ease-out);
+}
+.search__clear:hover { background: var(--surface-alt); color: var(--text-primary); }
+.search__clear svg { width: 16px; height: 16px; }
+.search__input:not(:placeholder-shown) ~ .search__clear { display: inline-flex; }
+
+/* Drawer / Sheet (§10.29) */
+.drawer {
+  position: fixed; inset: 0; z-index: 100;
+  visibility: hidden; pointer-events: none;
+  transition: visibility 0s linear var(--duration-base);
+}
+.drawer.is-open { visibility: visible; pointer-events: auto; transition-delay: 0s; }
+.drawer__overlay {
+  position: absolute; inset: 0; background: var(--overlay);
+  opacity: 0; transition: opacity var(--duration-base) var(--ease-out);
+}
+.drawer.is-open .drawer__overlay { opacity: 1; }
+.drawer__panel {
+  position: absolute; inset: 0 0 0 auto; width: min(400px, 100%);
+  display: flex; flex-direction: column; gap: var(--space-5);
+  padding: var(--card-padding); background: var(--surface);
+  box-shadow: var(--shadow-xl); overflow-y: auto; overscroll-behavior: contain;
+  transform: translateX(100%);
+  transition: transform var(--duration-base) var(--ease-in);
+}
+.drawer.is-open .drawer__panel {
+  transform: none;
+  transition: transform var(--duration-slow) var(--ease-out);
+}
+.drawer--right .drawer__panel { inset: 0 0 0 auto; transform: translateX(100%); }
+.drawer--left .drawer__panel { inset: 0 auto 0 0; transform: translateX(-100%); }
+.drawer--bottom .drawer__panel {
+  inset: auto 0 0 0; width: 100%; max-height: 85vh;
+  border-radius: var(--radius-lg) var(--radius-lg) 0 0; transform: translateY(100%);
+}
+.drawer__header {
+  display: flex; align-items: center; justify-content: space-between; gap: var(--space-4);
+}
+.drawer__title { font-size: var(--text-lg); font-weight: var(--weight-semibold); margin: 0; }
+.drawer__body { flex: 1; }
+.drawer__footer {
+  display: flex; justify-content: flex-end; gap: var(--space-3); margin-top: auto;
+}
+
+/* Popover (§10.30) */
+.popover { position: relative; display: inline-block; }
+.popover__panel {
+  position: absolute; top: calc(100% + 8px); left: 0; z-index: 60;
+  width: max-content; max-width: 300px; padding: var(--space-4);
+  background: var(--surface); border: var(--border-width) solid var(--border);
+  border-radius: var(--radius-md); box-shadow: var(--shadow-lg);
+  transform-origin: top left; opacity: 0; transform: scale(.96); pointer-events: none;
+  transition: opacity var(--duration-base) var(--ease-out),
+              transform var(--duration-base) var(--ease-out);
+}
+.popover.is-open .popover__panel { opacity: 1; transform: none; pointer-events: auto; }
+.popover--right .popover__panel { left: auto; right: 0; transform-origin: top right; }
+
+/* ButtonGroup (§10.31) */
+.btn-group { display: inline-flex; }
+.btn-group .btn { border-radius: 0; }
+.btn-group .btn:first-child {
+  border-top-left-radius: var(--radius-md); border-bottom-left-radius: var(--radius-md);
+}
+.btn-group .btn:last-child {
+  border-top-right-radius: var(--radius-md); border-bottom-right-radius: var(--radius-md);
+}
+.btn-group .btn:not(:first-child) { margin-left: calc(var(--border-width) * -1); }
+.btn-group .btn:hover, .btn-group .btn:focus-visible { z-index: 1; }
+
+/* --------------------------------------------------------------------------
+   13c. DATEPICKER · FILEUPLOAD · STEPPER · KBD (§10.32–10.35)
+   -------------------------------------------------------------------------- */
+
+/* DatePicker (§10.32) */
+.datepicker { position: relative; display: inline-block; }
+.datepicker__input {
+  width: 100%; height: var(--control-height-md); padding: 0 40px 0 14px;
+  font-family: var(--font-body); font-size: var(--text-base);
+  color: var(--text-primary); background: var(--surface);
+  border: var(--border-width) solid var(--border-strong); border-radius: var(--radius-sm);
+  transition: border-color var(--duration-fast) var(--ease-out),
+              box-shadow var(--duration-fast) var(--ease-out);
+}
+.datepicker__input:hover:not(:disabled):not(:focus) { border-color: var(--text-disabled); }
+.datepicker__input:focus { outline: none; border-color: var(--accent); box-shadow: var(--ring); }
+.datepicker__input:disabled { background: var(--surface-alt); color: var(--text-disabled); cursor: not-allowed; }
+.datepicker__icon {
+  position: absolute; right: 12px; top: calc(var(--control-height-md) / 2); transform: translateY(-50%);
+  width: 18px; height: 18px; color: var(--text-muted); pointer-events: none;
+}
+.datepicker__calendar {
+  position: absolute; top: calc(100% + 8px); left: 0; z-index: 60;
+  width: max-content; padding: var(--space-4);
+  background: var(--surface); border: var(--border-width) solid var(--border);
+  border-radius: var(--radius-md); box-shadow: var(--shadow-lg);
+  transform-origin: top left; opacity: 0; transform: scale(.96); pointer-events: none;
+  transition: opacity var(--duration-base) var(--ease-out),
+              transform var(--duration-base) var(--ease-out);
+}
+.datepicker.is-open .datepicker__calendar { opacity: 1; transform: none; pointer-events: auto; }
+.datepicker--right .datepicker__calendar { left: auto; right: 0; transform-origin: top right; }
+
+.calendar { width: 15.75rem; }
+.calendar__header {
+  display: flex; align-items: center; justify-content: space-between;
+  gap: var(--space-2); margin-bottom: var(--space-3);
+}
+.calendar__title { font-size: var(--text-sm); font-weight: var(--weight-semibold); color: var(--text-primary); }
+.calendar__weekdays,
+.calendar__grid { display: grid; grid-template-columns: repeat(7, 1fr); gap: 2px; }
+.calendar__weekdays { margin-bottom: 4px; }
+.calendar__weekday {
+  display: flex; align-items: center; justify-content: center; height: 28px;
+  font-size: var(--text-xs); font-weight: var(--weight-medium); color: var(--text-muted);
+}
+.calendar__day {
+  display: flex; align-items: center; justify-content: center;
+  width: 34px; height: 34px; margin: 0 auto; padding: 0;
+  border: 0; border-radius: var(--radius-sm); background: transparent;
+  font-family: var(--font-body); font-size: var(--text-sm); color: var(--text-primary);
+  cursor: pointer;
+  transition: background-color var(--duration-fast) var(--ease-out),
+              color var(--duration-fast) var(--ease-out);
+}
+.calendar__day:hover:not(:disabled):not(.calendar__day--selected) { background: var(--accent-soft); }
+.calendar__day--outside { color: var(--text-disabled); }
+.calendar__day--today { font-weight: var(--weight-semibold); box-shadow: inset 0 0 0 1px var(--border-strong); }
+.calendar__day--selected { background: var(--accent); color: var(--text-on-primary); font-weight: var(--weight-semibold); }
+.calendar__day:disabled { color: var(--text-disabled); cursor: not-allowed; }
+
+/* FileUpload (§10.33) */
+.file-upload {
+  border: 2px dashed var(--border-strong); border-radius: var(--radius-lg);
+  background: var(--surface);
+  transition: border-color var(--duration-fast) var(--ease-out),
+              background-color var(--duration-fast) var(--ease-out);
+}
+.file-upload.is-dragover { border-color: var(--accent); background: var(--accent-soft); }
+.file-upload__input {
+  position: absolute; width: 1px; height: 1px; margin: -1px;
+  clip-path: inset(50%); overflow: hidden; white-space: nowrap;
+}
+.file-upload__label {
+  display: flex; flex-direction: column; align-items: center; text-align: center;
+  gap: var(--space-2); padding: var(--space-8) var(--space-6); cursor: pointer;
+}
+.file-upload__label > svg { width: 32px; height: 32px; color: var(--text-muted); }
+.file-upload__title { font-size: var(--text-sm); color: var(--text-secondary); }
+.file-upload__hint { font-size: var(--text-xs); color: var(--text-muted); }
+.file-upload__button {
+  display: inline-flex; align-items: center; justify-content: center;
+  height: var(--control-height-sm); padding: 0 16px; margin-top: var(--space-1);
+  border: var(--border-width) solid var(--border-strong); border-radius: var(--radius-md);
+  font-size: var(--text-sm); font-weight: var(--weight-semibold); color: var(--text-primary);
+  background: var(--surface);
+  transition: background-color var(--duration-fast) var(--ease-out);
+}
+.file-upload__label:hover .file-upload__button { background: var(--bg); }
+.file-upload__list { list-style: none; margin: var(--space-4) 0 0; padding: 0; display: flex; flex-direction: column; gap: var(--space-2); }
+.file-upload__item {
+  display: flex; align-items: center; gap: var(--space-3);
+  padding: var(--space-3); border: var(--border-width) solid var(--border);
+  border-radius: var(--radius-md); background: var(--surface);
+}
+.file-upload__icon { width: 20px; height: 20px; color: var(--text-muted); flex: none; }
+.file-upload__meta { display: flex; flex-direction: column; gap: 4px; min-width: 0; flex: 1; }
+.file-upload__name {
+  font-size: var(--text-sm); font-weight: var(--weight-medium); color: var(--text-primary);
+  white-space: nowrap; overflow: hidden; text-overflow: ellipsis;
+}
+.file-upload__size { display: inline-flex; align-items: center; gap: 6px; font-size: var(--text-xs); color: var(--text-muted); }
+.file-upload__size svg { width: 12px; height: 12px; flex: none; }
+.file-upload__meta .progress { margin-top: 2px; }
+.file-upload__remove {
+  display: inline-flex; align-items: center; justify-content: center;
+  width: 32px; height: 32px; flex: none; border: 0; border-radius: var(--radius-full);
+  background: transparent; color: var(--text-muted); cursor: pointer;
+  transition: background-color var(--duration-fast) var(--ease-out),
+              color var(--duration-fast) var(--ease-out);
+}
+.file-upload__remove:hover { background: var(--surface-alt); color: var(--text-primary); }
+.file-upload__remove svg { width: 16px; height: 16px; }
+.file-upload__item--error { border-color: var(--danger-500); }
+.file-upload__item--error .file-upload__icon,
+.file-upload__item--error .file-upload__size { color: var(--danger-text); }
+
+/* Stepper / Wizard (§10.34) */
+.stepper { display: flex; list-style: none; margin: 0; padding: 0; }
+.step {
+  position: relative; flex: 1;
+  display: flex; flex-direction: column; align-items: center; text-align: center; gap: var(--space-2);
+}
+.step__marker {
+  position: relative; z-index: 1;
+  display: inline-flex; align-items: center; justify-content: center;
+  width: 32px; height: 32px; flex: none; border-radius: var(--radius-full);
+  border: 2px solid var(--border-strong); background: var(--surface);
+  font-size: var(--text-sm); font-weight: var(--weight-semibold); color: var(--text-muted);
+}
+.step__marker svg { width: 16px; height: 16px; }
+.step__label { font-size: var(--text-sm); color: var(--text-secondary); }
+.step__connector {
+  position: absolute; top: 16px; z-index: 0; left: 50%; right: -50%;
+  height: 2px; margin: 0 20px; background: var(--border);
+}
+.step--complete .step__marker { background: var(--accent); border-color: var(--accent); color: var(--text-on-primary); }
+.step--complete .step__label { color: var(--text-primary); }
+.step--complete .step__connector { background: var(--accent); }
+.step--current .step__marker { border-color: var(--accent); color: var(--accent); }
+.step--current .step__label { color: var(--text-primary); font-weight: var(--weight-semibold); }
+.stepper--vertical { flex-direction: column; align-items: stretch; }
+.stepper--vertical .step {
+  flex-direction: row; align-items: flex-start; text-align: left;
+  gap: var(--space-3); padding-bottom: var(--space-6);
+}
+.stepper--vertical .step:last-child { padding-bottom: 0; }
+.stepper--vertical .step__connector {
+  top: 36px; bottom: -4px; left: 15px; right: auto;
+  width: 2px; height: auto; margin: 0;
+}
+.stepper--vertical .step__label { padding-top: 5px; }
+
+/* Kbd (§10.35) */
+.kbd {
+  display: inline-flex; align-items: center; justify-content: center;
+  min-width: 20px; height: 20px; padding: 0 6px;
+  font-family: var(--font-mono); font-size: var(--text-xs); line-height: 1;
+  color: var(--text-secondary); background: var(--surface);
+  border: var(--border-width) solid var(--border-strong);
+  border-radius: var(--radius-sm); box-shadow: var(--shadow-xs);
+}
+.kbd-combo { display: inline-flex; align-items: center; gap: 4px; color: var(--text-muted); font-size: var(--text-xs); }
+
 /* --------------------------------------------------------------------------
    14. UTILIDADES MÍNIMAS
    -------------------------------------------------------------------------- */