@higinio/design-mcp 0.1.1 → 0.2.0

package/assets/bruma/design-doc.md

@@ -0,0 +1,1083 @@
+# DESIGN.md — Sistema de Diseño "Bruma Lavanda"
+
+> Sistema de marca **light-first**, calmo y preciso, de **Higinio Sosa** para sus productos de seguimiento, datos personales y lectura larga (web, móvil, dashboards, landing pages).
+> Paleta base: `#f2f1f6` (niebla, fondo) · `#5b578a` (lavanda, primario) · `#2c2b38` (tinta)
+>
+> **Versión 1.0**.
+> Entregables: `bruma-lavanda.html` (style guide), `dist/bruma-lavanda/` (tokens CSS · framework · Tailwind v4 · DTCG JSON), skill `~/.claude/skills/bruma-lavanda-design/`.
+
+---
+
+## 1. Identidad y principios
+
+**Personalidad de marca:** calma, precisa y legible. Es la que transmite control: cada dato está donde se espera, se lee a la primera y nada compite por la atención. La calma viene del orden, no de la suavidad; la bruma es el escenario, nunca el contenido. Vibe: *«Una mañana de niebla en orden; todo en su sitio»*.
+
+1. **Orden antes que adorno** — Todo tiene su sitio. La jerarquía la ponen el espacio, el borde y el peso tipográfico, no la decoración.
+2. **Legibilidad primero** — Una tipografía de UI pensada para baja visión (Atkinson Hyperlegible Next) y contrastes holgados en los dos modos. Si un dato no se lee a la primera, el diseño falló.
+3. **Un acento a la vez, y pequeño** — La lavanda `#5b578a` marca la acción, el estado activo y el foco. Nunca rellena áreas grandes ni compite consigo misma.
+4. **La niebla es el fondo, no el texto** — Fondos planos y fríos, superficies opacas. Nada difuminado: sin blur, sin degradados, sin texto sobre veladuras.
+5. **Movimiento corto y preciso** — La animación confirma lo que pasó y se aparta. Es breve porque el control no espera.
+
+**Reglas duras propias:**
+
+- **Prohibido el violeta saturado.** La lavanda es apagada y grisácea: el `--accent` claro tiene una saturación HSL de 22.7% y un croma C\*ab de 31.3 (26.2 en oscuro); el test `slop-sistemas.test.ts` exige saturación ≤ 25% en claro y croma ≤ 40 en los dos modos. Nada de morados eléctricos, fucsias ni el violeta de las plantillas de IA.
+- **Prohibidos los degradados de cualquier tipo.** Ni en fondos, ni en botones, ni en textos, ni en bordes, ni en overlays o imágenes de cabecera. El color es siempre plano: en el sistema no hay ningún degradado, tampoco en los estados de carga (el Skeleton pulsa en opacidad, §10.25). El test `slop-sistemas.test.ts` lo comprueba sobre el framework: ni `radial-gradient` ni `conic-gradient`, y `linear-gradient` solo como técnica de relleno sin transición de color en el track del Slider (§10.8) y en el subrayado del Link (§10.26).
+- **El acento lavanda no se usa como fondo de áreas grandes.** `--accent` sólido solo en controles (botón primario, checkbox, switch, paso del stepper, página activa, día elegido), estados activos e indicadores, y anillos de foco. Nunca en el fondo de un hero, una sección, una tarjeta, un banner, el navbar o el sidebar. Los tintes `--accent-soft` / `--accent-soft-strong` quedan para estados de selección y hover (fila seleccionada, ítem activo, opción resaltada), no para colorear secciones.
+
+**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, preciso y directo. Frases cortas que informan; el dato antes que el adjetivo. Claro sin ser seco, amable sin ser meloso. **Cero signos de exclamación** y cero jerga de marketing.
+- **Precisión:** di exactamente qué pasó y con qué cifra. "Guardado a las 14:32", no "¡Listo!"; "3 registros sin categoría", no "Hay algunos pendientes".
+- **Sin urgencia:** nunca "¡Rápido!", "Última oportunidad" ni contadores que presionan. Si algo tiene plazo, se dice con calma y con el dato: "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 registro", "tus datos"), 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 concretos ("Guardar", "Registrar", "Exportar datos").
+- **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:** dicen qué falta y cómo empezar — "Aún no hay registros esta semana. Añade el primero desde «Registrar»." Nunca un simple "No hay datos".
+- **Logros:** se confirman con sobriedad y con el dato ("Meta del día cumplida: 8 de 8"), 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 — Lavanda (base `#5b578a`)
+
+| Token | Hex | Uso |
+|---|---|---|
+| `primary-50` | `#e5e3f1` | **Acento suave** — hover de ghost/outline, fila seleccionada, opción resaltada |
+| `primary-100` | `#d8d5ea` | Seleccionados suaves, ítem activo del sidebar, chip de avatar |
+| `primary-200` | `#bdb9da` | Bordes activos suaves, divisores destacados |
+| `primary-300` | `#9d99c4` | Decorativo — iconos de empty state, gráficas. **Nunca texto** (2.61:1) |
+| `primary-400` | `#7c78a8` | Iconos secundarios, hover de checkbox/radio (solo UI) |
+| `primary-500` | `#5b578a` | **Primario** — fondo de botones, bordes activos, focus, rellenos de gráficas |
+| `primary-600` | `#4d4979` | Hover de botones primarios, **`--link`: texto de links y botones ghost** |
+| `primary-700` | `#403d66` | Pressed/active, tabs y navbar activos, texto sobre `primary-100` |
+| `primary-800` | `#35334f` | Texto de marca con alto contraste |
+| `primary-900` | `#2c2b38` | **Tinta de marca** — headings, texto principal |
+
+### 3.2 Neutrales — Niebla (derivados de `#2c2b38`)
+
+| Token | Hex | Uso |
+|---|---|---|
+| `neutral-0` | `#fbfbfd` | Superficie de tarjetas (niebla clara, no blanco puro) |
+| `neutral-50` | `#f2f1f6` | **Niebla** — fondo general de la app |
+| `neutral-100` | `#e9e8f0` | Fondos alternos, filas zebra, tracks |
+| `neutral-200` | `#dedce8` | Bordes y divisores por defecto |
+| `neutral-300` | `#b8b6c8` | Iconos deshabilitados, presencia "offline" |
+| `neutral-400` | `#86849a` | Bordes de inputs y botones secundarios, placeholder, texto deshabilitado |
+| `neutral-500` | `#5d5b6e` | Texto terciario, captions |
+| `neutral-600` | `#48475a` | Texto secundario |
+| `neutral-700` | `#393846` | Párrafos largos |
+| `neutral-800` | `#2c2b38` | Texto principal, headings |
+| `neutral-900` | `#1f1e28` | 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`)**. Los cuatro van algo desaturados para convivir con la niebla; info es un azul pizarra propio, para no diluir el acento.
+
+| Estado | Sólido `-500` | Fondo `-100` | Texto `-text` | Uso |
+|---|---|---|---|---|
+| `success` | `#2f7a68` | `#dcefe9` | `#235e50` | Verde azulado — confirmaciones, metas cumplidas, siempre con ✓ |
+| `warning` | `#b07f2a` | `#f5ecd9` | `#7a5716` | Ámbar apagado — avisos, pendientes |
+| `danger` | `#b24c55` | `#f6e3e5` | `#8b3540` | Rojo rosado frío — errores, acciones destructivas |
+| `info` | `#4f7896` | `#e1eaf1` | `#3a5b74` | 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 (niebla) |
+| `--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.51:1) |
+| `--text-primary` | `neutral-800` | Texto principal |
+| `--text-secondary` | `neutral-600` | Texto secundario |
+| `--text-muted` | `neutral-500` | Terciario, captions |
+| `--text-disabled` | `neutral-400` | Deshabilitado, placeholder |
+| `--text-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 controles, bordes activos, focus |
+| `--accent-hover` | `primary-600` | Hover del primario |
+| `--accent-active` | `primary-700` | Pressed |
+| `--accent-soft` | `primary-50` | Hover de ghost, selección sutil |
+| `--accent-soft-strong` | `primary-100` | Seleccionados suaves |
+| `--link` | `primary-600` | **Texto de links y botones ghost (AA 7.98:1)** |
+| `--ring` | `0 0 0 3px rgba(91,87,138,.25)` | Focus ring de inputs |
+
+> ⚠️ **Regla AA de acento:** `primary-500` sobre `--surface` da 6.40:1, pero el texto de links y ghost usa siempre `--link` (`primary-600`, 7.98:1) para que cada rol tenga su token. `primary-400` (3.98:1) solo en iconos y UI; `primary-300` (2.61:1) jamás como texto.
+
+> ⚠️ **Regla de área del acento:** `--accent` es un color de control, no de superficie. Si una pieza mide más que un botón grande, no va en lavanda sólida: una tarjeta destacada se marca con borde `--border-strong` o con un indicador de 2–3px en `--accent`, nunca con fondo lavanda. El éxito, por su parte, es verde azulado (`--success-500`), lejos del acento (ΔE76 52.6 en claro y 49.2 en oscuro), y siempre lleva ✓.
+
+### 3.5 Proporción de uso (regla 60-30-10)
+
+- **60% — Niebla y superficies** (`neutral-0/50/100`): fondos y superficies.
+- **30% — Tinta y estructura** (`neutral-600→900`, bordes): texto, iconos, divisores.
+- **10% — Lavanda y semánticos**: botones, links, estados activos, foco, gráficas. **El acento pierde poder si supera el 10%**, y en Bruma además no puede concentrarse en una sola área grande (§1). (Excepción: una visualización de datos multiserie usa la paleta categórica validada de la skill `dataviz-marca`, exenta de este techo — son datos, no cromo decorativo.)
+
+Reglas prácticas:
+- **Un solo botón primario visible por pantalla**; el resto secundarios o ghost.
+- **Fondos siempre planos** (`--bg`, niebla): sin degradados de ningún tipo, sin texturas, granulado ni patrones, sin veladuras ni full-bleed decorativo — la superficie de trabajo (tarjetas de niebla clara con su borde) es la protagonista.
+- Estado nunca solo con color: siempre color + icono + texto.
+
+---
+
+## 4. Tipografía
+
+### 4.1 Familias (roles estrictos)
+
+| Rol | Fuente | Fallback | Uso |
+|---|---|---|---|
+| Display | **Bricolage Grotesque** (600–700) | system-ui, sans-serif | **Solo h1–h2**, cifras hero, títulos de marketing — nunca UI ni párrafos |
+| Body/UI | **Atkinson Hyperlegible Next** (400–700) | system-ui, sans-serif | Párrafos, botones, formularios, h3–h6 |
+| Mono | **Atkinson Hyperlegible Mono** (400–500) | ui-monospace, monospace | Datos numéricos, código, IDs, cantidades en tablas |
+
+**Atkinson Hyperlegible Next** es una tipografía diseñada por el Braille Institute para lectores con baja visión: cada carácter tiene una forma inconfundible (la `I` mayúscula, la `l` y el `1` no se parecen; el `0` y la `O` tampoco), con aperturas amplias y terminales que no se cierran. Es la versión con pesos de 200 a 800 de la Atkinson Hyperlegible original, que solo trae 400 y 700; el framework usa 500 y 600 en botones, ítems, tabs, labels y stats, y por eso se carga Next. Su hermana **Atkinson Hyperlegible Mono** comparte esas formas, así que las cifras de una tabla se leen igual que las del texto.
+
+**Bricolage Grotesque** pone el carácter en los titulares: una grotesca con algo de tensión en las curvas, más expresiva que la UI, que mantiene el orden y evita la frialdad de una sans genérica. Sus 600 y 700 bastan para dos niveles de display.
+
+La itálica cargada es la de Atkinson Hyperlegible Next 400, para el énfasis (`<em>`) y las citas dentro del texto corrido. El display no lleva itálica: Bricolage se carga sin ella y el navegador la falsearía inclinando el romano.
+
+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=Bricolage+Grotesque:wght@600;700&family=Atkinson+Hyperlegible+Next:ital,wght@0,400;0,500;0,600;0,700;1,400&family=Atkinson+Hyperlegible+Mono: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 (Atkinson Hyperlegible Next) |
+| `text-3xl` | 31px | 1.25 `--leading-3xl` | 600 | h2 (Bricolage Grotesque) |
+| `text-4xl` | 39px | 1.15 `--leading-4xl` | 700 | h1 (Bricolage Grotesque) |
+| `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). Es el sistema de la lectura larga: respeta la medida también en paneles anchos.
+- Números en tablas: `font-variant-numeric: tabular-nums` o Atkinson Hyperlegible Mono.
+- 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 (`’`, `&rsquo;`), que no se decodifican igual en todos los contextos.
+
+---
+
+## 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`
+
+La densidad es algo compacta: tarjetas y secciones respiran menos que en un sistema editorial, para que una pantalla de seguimiento muestre más datos sin parecer apretada. Los controles conservan sus alturas de 44px.
+
+Aliases de uso (consumir estos, no números sueltos):
+
+| Alias | Valor | Uso |
+|---|---|---|
+| `--card-padding` | 20px (`--space-5`) | Padding de tarjetas, modales y drawers (`--card-padding-mobile: 16px`) |
+| `--section-gap` | 48px (`--space-12`) | Separación entre secciones (40–48px) |
+| `--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`) |
+
+---
+
+## 6. Bordes, radios y focus
+
+| Token | Valor | Uso |
+|---|---|---|
+| `radius-sm` | 6px | Inputs, chips, badges |
+| `radius-md` | 8px | Botones, dropdowns, menús |
+| `radius-lg` | 12px | Tarjetas, modales, accordion |
+| `radius-xl` | 16px | Hero, imágenes destacadas |
+| `radius-full` | 9999px | Avatares, pills, toggles |
+
+Los radios son contenidos a propósito: las formas más rectas ordenan la pantalla y alinean mejor en rejilla, sin llegar a la esquina viva.
+
+- 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: `#5b578a` en claro (6.40:1 sobre `--surface`) y `#b0acdc` en oscuro (7.68:1). El SegmentedControl y el chip de métrica usan el mismo token para su foco. El anillo de foco es uno de los tres usos legítimos del lavanda (§1).
+
+**Transparencia y blur:** únicos usos permitidos — overlay de modal `rgba(31,30,40,.5)` y ring de focus. **No hay glassmorphism ni blur en Bruma Lavanda**: la niebla es un color de fondo, no un efecto; las superficies son opacas y planas.
+
+---
+
+## 7. Elevación
+
+La elevación **se apoya en el borde más que en la sombra**: cada capa se separa por su superficie y su contorno, y la sombra, mínima y teñida con la tinta `#2c2b38` (nunca negro puro), solo confirma lo que el borde ya dice. Máximo **3 niveles visibles por pantalla**. **Sin resplandor de acento (glow):** la elevación es borde y sombra, 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-strong` | — | Hover de la tarjeta interactiva: sube por el borde, no por la sombra |
+| 3 | `--surface` + borde `--border` (menús, popovers) | `--shadow-lg` / `--shadow-xl` | Menús, dropdowns, popovers, toasts, modales, drawers |
+
+En hover, una tarjeta interactiva no se eleva: su borde pasa de `--border` a `--border-strong` (§10.26).
+
+### Sombras
+
+| Token | Valor | Uso |
+|---|---|---|
+| `shadow-xs` | `0 1px 1px rgba(44,43,56,.04)` | Inputs, indicador de SegmentedControl, Kbd |
+| `shadow-sm` | `0 1px 2px rgba(44,43,56,.06)` | Tarjetas en reposo, hover del botón primario |
+| `shadow-md` | `0 2px 6px rgba(44,43,56,.07), 0 1px 2px rgba(44,43,56,.04)` | Elevación intermedia para piezas propias; ningún componente del framework la usa |
+| `shadow-lg` | `0 8px 20px rgba(44,43,56,.09), 0 2px 6px rgba(44,43,56,.05)` | Menús, dropdowns, popovers, toasts |
+| `shadow-xl` | `0 16px 36px rgba(44,43,56,.12)` | Modales, drawers, 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 los radios contenidos y la lectura limpia 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 atmosféricos** (`cloud-fog`, `moon`, `sparkles`…) solo cuando representan un dato real —el clima de un registro, 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 Bricolage Grotesque peso 600 (`--weight-semibold`), tracking `--tracking-display` (`-0.02em`), color `--text-primary` (tinta). Tamaño de referencia: 31px (`--text-3xl`). El 600 mantiene la grotesca firme sin volverla pesada; 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 Atkinson Hyperlegible Next 500, `text-lg`, `--text-secondary`. La marca no lleva itálica: el display se carga sin ella (§4.1).
+- **Variante badge:** mismo texto/tamaño dentro de caja con fondo `--surface`, borde `1px --border`, radius `md` (8px), `shadow-sm`, padding `14px 22px`.
+- El wordmark es texto, no un icono: Bricolage Grotesque 600–700, nunca en UI ni párrafos.
+- **Sentence case siempre:** "Higinio", nunca "HIGINIO" ni "higinio".
+- Color `--text-primary`; ni lavanda sólida ni degradado en el nombre, y `primary-300` jamás como texto, tampoco en el wordmark.
+- Sin nubes, brumas ni isotipo 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`. Un solo primario visible por pantalla; ghost y outline usan `--link` (AA), no `primary-500`.
+
+| Variante | Reposo | Hover | Active | Disabled |
+|---|---|---|---|---|
+| Primario | fondo `--accent`, texto `--text-on-primary` | `--accent-hover` + `shadow-sm` | `--accent-active`, sin sombra | fondo `--border`, texto `--text-disabled` |
+| 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 (5.01:1 sobre `danger-500`) y la tinta oscura `#16151c` en oscuro (6.99:1), donde el rojo 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`).
+- El botón es el control por excelencia del lavanda, y no se estira hasta el ancho de una sección: un botón así sería un área de color (§3.4). Si el layout pide un bloque de llamada, el bloque va en `--surface` con borde y el botón dentro, a su tamaño.
+
+### 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 140ms.
+
+### 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 (6.38:1 sobre `--surface`) y `#aaa8bb` en oscuro (7.09:1). Lo comparten Textarea, Select, Combobox, Search y DatePicker.
+- **Focus:** borde `--accent` + `--ring`. Transición 140ms.
+- **Error:** borde `danger-500` + `--ring-danger` (ring rojo suave); mensaje `text-sm` `--danger-text` con icono, 6px debajo (el borde y el ring siguen en `danger-500`, que como texto queda en 4.61:1 sobre `--bg`, sin margen, y en 4.20:1 sobre `danger-100`).
+- **É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, 180ms).
+- 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), 180ms (`--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 180ms `--ease-out`** (swap de color, nunca animando `left`/`width`).
+- Segmento activo: `--text-primary` semibold; inactivo: `--text-secondary` medium; transición de color 140ms. Texto `text-sm`.
+
+### 10.8 Slider
+
+Rango de valor único.
+
+- Track: 6px de alto, radius full; porción rellena `--accent`, resto `--border`. Es una técnica de relleno sin transición de color: un `linear-gradient` cuyas dos paradas caen en el mismo punto (`--slider-fill`) pinta dos tramos planos con un corte duro, 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, 180ms). 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 180ms `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 (7.04: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° (180ms). `aria-expanded`.
+- Panel: altura animada con `grid-template-rows` 0fr→1fr 240ms ease-out (sin reflow); 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`, 15.94:1) `text-xs`, padding `6px 10px`, radius `sm`, flecha 6px. Delay de aparición 400ms, fade + translateY(4px→0) en 140ms. 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, 240ms. Salida: fade + translateX, 180ms.
+- 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 240ms 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 240ms; 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(31,30,40,.5)`), fade 180ms.
+- Panel: fondo `--surface`, radius `lg`, `shadow-xl`, max-width 480px (confirm) / 640px (formulario), padding 20px (`--card-padding`).
+- Entrada: fade + scale(0.96→1), 240ms. Salida: la misma transición en sentido inverso (240ms, `--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.35: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 datos personales 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.98: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 lavanda 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.75:1), icono `--accent`. El sidebar en sí nunca va en lavanda: el tinte se limita al ítem activo.
+- **Tabs:** borde inferior `--border`; tab activa con texto `--accent-active` e indicador 2px `--accent` que se desliza entre tabs (240ms).
+- **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 bl-pulse`, de 1 a 0.5 y vuelta, 1.2s 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 dice qué falta y cómo empezar ("Añade el primero desde «Registrar»").
+
+### 10.26 Card, Link y Code
+
+- **Card:** fondo `--surface`, borde `1px --border`, radius `lg`, padding 20px (`--card-padding`; 16px en móvil), `shadow-sm`.
+- **Card interactiva:** cursor pointer; en hover el borde pasa de `--border` a `--border-strong`, con transición de `border-color` 180ms (`--duration-base`) ease-out. No se desplaza ni gana sombra: en Bruma la elevación se lee en el borde, y la tarjeta no "flota" fuera de su sitio.
+- **Link:** color `--link` (`primary-600`, AA 7.98:1 sobre `--surface`); subrayado animado 1px `currentColor` que crece de 0%→100% del ancho desde la izquierda (`background-size`, 180ms ease-out). El subrayado es un relleno de un solo color (`linear-gradient(currentColor, currentColor)`), sin transición de color: así sigue al texto aunque el link salte de línea. Externo: `target="_blank" rel="noopener noreferrer"` + icono flecha 12px, gap 4px.
+- **Code (inline):** Atkinson Hyperlegible 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`, 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` y padding `--card-padding`; `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 `--accent`, texto `--text-on-primary`), `.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: un estado activo y pasajero, por eso admite el tinte.
+- **`.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 lavanda. 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) | Se marca con sobriedad: un fundido o un trazo, nunca confeti |
+| Ocasional (abrir un panel, un modal) | Transición clara y breve |
+| 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 son cortas y precisas: el movimiento confirma y se aparta, y esa rapidez es parte de la sensación de control. El feedback táctil (`instant`) es inmediato y el techo (`page`) no pasa de 300ms.
+
+```css
+:root {
+  --duration-instant: 100ms;  /* feedback táctil: press, toggle */
+  --duration-fast: 140ms;     /* hover, focus, color */
+  --duration-base: 180ms;     /* dropdowns, tooltips, switches */
+  --duration-slow: 240ms;     /* modales, toasts, drawers */
+  --duration-page: 300ms;     /* 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. **Solo `transform` y `opacity`** — Nunca animar `width/height/top/left` (evita reflow). Excepciones controladas: width de Progress y `grid-template-rows` del Accordion.
+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 140ms + `shadow-sm` |
+| Botón | press | `scale(0.98)` 100ms |
+| Link | hover | color 140ms + subrayado que crece de 0 a 100% (180ms) |
+| Tarjeta interactiva | hover | borde `--border` → `--border-strong`, 180ms; sin desplazamiento |
+| Input | focus | ring que aparece con fade 140ms |
+| Checkbox | check | trazo del check dibujándose 180ms `ease-spring` |
+| Toggle | cambio | thumb desliza 180ms `ease-spring` |
+| SegmentedControl | cambio | la opción activa toma fondo `--surface` 180ms `--ease-out` |
+| Slider | press | thumb escala 1.15, 100ms |
+| Acordeón | abrir | `grid-template-rows` (0fr→1fr) 240ms + fade del contenido |
+| Dropdown / Menu | abrir | fade + translateY(-4px→0) 160–180ms |
+| Modal | abrir | overlay fade 180ms; panel fade + scale(0.96→1) 240ms |
+| Toast | entrar | slide-in + fade 240ms `ease-out` |
+| Icon swap (p. ej. copiar→check) | cambio | cross-fade: opacity + scale(0.9→1), 140ms; nunca blur |
+| Progress | cambio | width / stroke-dashoffset 240ms `ease-out` |
+| Página/vista | cambio | fade + translateY(8px→0) 300ms |
+
+### 11.4 Loading
+
+- Spinner: ver §10.3.
+- Progress: ver §10.18.
+- Skeleton: pulso de opacidad de 1.2s por tramo, en loop alternado (ver §10.25).
+- Si la carga dura <300ms, **no mostrar spinner** (evita parpadeo).
+
+### 11.5 Accesibilidad del movimiento
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+}
+```
+
+Este reset con `*` es el **piso de seguridad**: garantiza que ningún motion sobreviva si el usuario pide reducirlo, incluso en componentes que no se revisaron a mano. Donde el movimiento comunica información real (progreso, un check, un conteo) y eliminarlo del todo perjudicaría la comprensión, un componente puede sobrescribir el reset con un selector más específico y una duración corta (p. ej. `transition-duration: 80ms`) en vez de colapsar a 0.01ms — hoy ningún componente del sistema ejerce esta excepción; todos usan el piso global.
+
+**Gating de hover:** los efectos de hover que mueven o elevan (transform, box-shadow) van dentro de `@media (hover: hover) and (pointer: fine)` — en touch no hay hover real y el tap dispara hovers falsos que se quedan pegados hasta el siguiente toque. Los hover de solo color/fondo pueden quedar fuera: un cambio de color pegado no estorba. La sombra del botón primario va dentro; el borde de la tarjeta interactiva también, aunque solo cambie de color, para que un tap no la deje marcada como si siguiera bajo el cursor.
+
+```css
+@media (hover: hover) and (pointer: fine) {
+  .btn--primary:hover:not(:disabled) { box-shadow: var(--shadow-sm); }
+  .card--interactive:hover { border-color: var(--border-strong); }
+}
+```
+
+### 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 180ms, opacity 180ms` |
+| `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; la niebla es un color plano, la elevación va en el borde |
+| Duración excesiva | > el techo del sistema (`--duration-page`, 300ms) 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 rompe la sensación de control |
+| 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.
+
+Regla: un gap en UI primaria (el flujo principal) es crítico; en UI secundaria, medio. Toda entrada/salida condicional necesita su transición de `opacity`/`transform`, con su contraparte de salida más discreta.
+
+---
+
+## 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`: **13.46:1** ✅ AAA (sobre `--bg` 12.38 · sobre `--surface-alt` 11.44).
+- `--text-secondary` (`neutral-600`): **8.74:1** sobre `--surface` · 8.04 sobre `--bg` · 7.43 sobre `--surface-alt` ✅ AA.
+- `--text-muted` (`neutral-500`): **6.38:1** sobre `--surface` · 5.86 sobre `--bg` · 5.42 sobre `--surface-alt` ✅ AA.
+- `--link` (`primary-600`) sobre `--surface`: **7.98:1** ✅ AA (sobre `--bg` 7.34 · sobre `--surface-alt` 6.79) — por eso links y ghost usan `--link`.
+- Blanco (`--text-on-primary`) sobre `primary-500`: **6.61:1** ✅ AA para texto normal (hover 8.25 · active 10.11).
+- `--accent` sobre `--surface`: **6.40:1** ✅ (mínimo de UI 3:1).
+- `--border-strong` (`neutral-400`) sobre `--surface`: **3.51:1** ✅ (mínimo de UI 3:1; sobre `--bg` 3.23).
+- `primary-300` (`#9d99c4`) sobre `--surface`: **2.61:1** — **nunca como texto**, solo decorativo. `primary-400`: 3.98:1, solo iconos y UI.
+- Tonos `--*-text` garantizan AA sobre los fondos suaves `*-100`: success **6.30:1** · warning **5.58:1** · danger **6.35:1** · info **5.89:1**.
+- Sólidos `-500` sobre `--surface`: success 4.95 · warning 3.44 · danger 5.01 · info 4.56. 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.97:1** sobre `--bg` · 7.58 sobre `--surface` · 6.35 sobre `danger-100`. `danger-500` daría 4.61 sobre `--bg`, sin margen, y 4.20 sobre `danger-100`.
+- **Éxito frente a acento:** ΔE76 entre `--accent` y `--success-500` = **52.6** (mínimo 15 en el test). El éxito, además, siempre lleva ✓.
+- **Acento sin violeta saturado:** saturación HSL del `--accent` claro 22.7% (máximo 25%) y croma C\*ab 31.3 (máximo 40), comprobados en `slop-sistemas.test.ts`.
+- Tokens de componente del framework (los fija el mismo test): contorno de foco `--focus-color` sobre `--surface` **6.40:1** · `--text-on-danger` sobre `danger-500` **5.01:1** (hover 5.70 · active 6.34) · `--border-hover` sobre `--surface` **6.38:1**.
+- Otros pares de componentes: avatar (`--text-on-primary-solid` sobre `--accent-soft-strong`) 7.04 · sidebar activo (`--link` sobre `--accent-soft-strong`) 5.75 · tooltip (`neutral-0` sobre `neutral-900`) 15.94.
+- 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
+:root {
+  /* == Primitivos: primario (Lavanda) ==
+     Lavanda apagada, nunca violeta saturado. El acento no rellena áreas grandes:
+     solo controles, estados activos y anillos de foco. */
+  --primary-50: #e5e3f1; --primary-100: #d8d5ea; --primary-200: #bdb9da;
+  --primary-300: #9d99c4; --primary-400: #7c78a8; --primary-500: #5b578a;
+  --primary-600: #4d4979; --primary-700: #403d66; --primary-800: #35334f;
+  --primary-900: #2c2b38;
+
+  /* == Primitivos: neutrales (Niebla) == */
+  --neutral-0: #fbfbfd; --neutral-50: #f2f1f6; --neutral-100: #e9e8f0;
+  --neutral-200: #dedce8; --neutral-300: #b8b6c8; --neutral-400: #86849a;
+  --neutral-500: #5d5b6e; --neutral-600: #48475a; --neutral-700: #393846;
+  --neutral-800: #2c2b38; --neutral-900: #1f1e28;
+
+  /* == Primitivos: semánticos (ramp de 3: sólido / fondo / texto AA) ==
+     El éxito es verde azulado, lejos del acento lavanda: el acento nunca comunica éxito. */
+  --success-500: #2f7a68; --success-100: #dcefe9; --success-text: #235e50;
+  --warning-500: #b07f2a; --warning-100: #f5ecd9; --warning-text: #7a5716;
+  --danger-500: #b24c55;  --danger-100: #f6e3e5;  --danger-text: #8b3540;
+  --info-500: #4f7896;    --info-100: #e1eaf1;    --info-text: #3a5b74;
+
+  /* == 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.98:1 sobre --surface — texto de links y ghost */
+
+  /* == Tipografía == */
+  --font-display: "Bricolage Grotesque", system-ui, sans-serif;
+  --font-body: "Atkinson Hyperlegible Next", system-ui, -apple-system, sans-serif;
+  --font-mono: "Atkinson Hyperlegible Mono", 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; densidad algo compacta) == */
+  --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-5); --card-padding-mobile: var(--space-4);
+  --section-gap: var(--space-12); --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 ==
+     La elevación se apoya en el borde; las sombras son mínimas y van
+     teñidas de la tinta, nunca negro puro. */
+  --radius-sm: 6px; --radius-md: 8px; --radius-lg: 12px;
+  --radius-xl: 16px; --radius-full: 9999px;
+  --border-width: 1px;
+  --shadow-xs: 0 1px 1px rgba(44,43,56,.04);
+  --shadow-sm: 0 1px 2px rgba(44,43,56,.06);
+  --shadow-md: 0 2px 6px rgba(44,43,56,.07), 0 1px 2px rgba(44,43,56,.04);
+  --shadow-lg: 0 8px 20px rgba(44,43,56,.09), 0 2px 6px rgba(44,43,56,.05);
+  --shadow-xl: 0 16px 36px rgba(44,43,56,.12);
+
+  /* == Focus == */
+  --ring: 0 0 0 3px rgba(91,87,138,.25);
+  --ring-color: rgba(91,87,138,.25);
+
+  /* == Motion (corto y preciso) == */
+  --duration-instant: 100ms; --duration-fast: 140ms; --duration-base: 180ms;
+  --duration-slow: 240ms; --duration-page: 300ms;
+  --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;
+}
+```
+
+Estilos base (extracto del framework — clase `.bruma-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.
+
+---
+
+## 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 — de la niebla de la mañana a la penumbra de la noche, igual de ordenada.
+
+### 15.1 Filosofía de la inversión
+
+- Los fondos se derivan de la tinta `#2c2b38` (nunca negro puro ni gris genérico): `#16151c` conserva el frío lavanda de la marca.
+- El acento se **aclara**: sobre fondo oscuro, `#5b578a` pierde fuerza, así que el rol de acento pasa a una lavanda clara `#b0acdc` y el texto sobre él se vuelve oscuro (`#16151c`). Sigue apagada (croma C\*ab 26.2) y sigue reservada a controles, estados activos y foco. El éxito también se aclara (`#6cc1ad`) y conserva su distancia con el acento (ΔE76 49.2).
+- Sin sombras en las capas: la elevación se apoya en superficies más claras + bordes, igual que en claro, y solo los overlays (`--shadow-lg`/`--shadow-xl`) conservan una sombra tenue.
+
+### 15.2 Mapeo de tokens
+
+| Token semántico | Light | Dark |
+|---|---|---|
+| `--bg` | `#f2f1f6` | `#16151c` |
+| `--surface` | `#fbfbfd` | `#1f1e27` |
+| `--surface-alt` | `#e9e8f0` | `#27262f` |
+| `--border` | `#dedce8` | `#2f2d3a` |
+| `--border-strong` | `#86849a` | `#747189` |
+| `--text-primary` | `#2c2b38` | `#e7e6ef` |
+| `--text-secondary` | `#48475a` | `#c9c7d6` |
+| `--text-muted` | `#5d5b6e` | `#aaa8bb` |
+| `--text-disabled` | `#86849a` | `#7b7990` |
+| `--accent` (botones, focus) | `#5b578a` | `#b0acdc` |
+| `--accent-hover` | `#4d4979` | `#c4c1e6` |
+| `--accent-active` | `#403d66` | `#9d98cf` |
+| `--accent-soft` | `#e5e3f1` | `#2b2940` |
+| `--accent-soft-strong` | `#d8d5ea` | `#36334f` |
+| `--text-on-primary` | `#ffffff` | `#16151c` |
+| `--text-on-primary-solid` | `#403d66` | `#c4c1e6` |
+| `--link` | `#4d4979` | `#c4c1e6` |
+| `--success` | `#2f7a68` | `#6cc1ad` |
+| `--warning` | `#b07f2a` | `#d6a752` |
+| `--danger` | `#b24c55` | `#e08890` |
+| `--info` | `#4f7896` | `#8daecb` |
+| `--ring` | `rgba(91,87,138,.25)` | `rgba(176,172,220,.3)` |
+
+Fondos suaves semánticos en dark: `success #13261f` · `warning #29220f` · `danger #2c171a` · `info #172129`.
+
+### 15.3 Elevación en dark
+
+| Nivel | Superficie | Sombra |
+|---|---|---|
+| 0 | `#16151c` | — |
+| 1 | `#1f1e27` + borde `#2f2d3a` | ninguna (`--shadow-xs`/`--shadow-sm`: `none`) |
+| 2 | `#1f1e27` + borde `#747189` (hover de la tarjeta interactiva) | ninguna (`--shadow-md`: `none`) |
+| 3 | `#1f1e27` + borde `#2f2d3a` (menús, popovers) | `0 8px 20px rgba(8,8,12,.28)` (`lg`) · `0 16px 32px rgba(8,8,12,.32)` (`xl`) |
+
+### 15.4 Ajustes de componentes en dark
+
+- **Botón primario:** fondo `#b0acdc`, texto `#16151c` (8.44:1 ✅). Hover `#c4c1e6` (10.46:1), active `#9d98cf` (6.76:1).
+- **Inputs:** fondo `--surface` `#1f1e27`, borde `#747189` (3.51:1), hover `#aaa8bb` (`--border-hover`), placeholder `#7b7990`; focus borde `#b0acdc` + ring.
+- **Botón destructivo:** fondo `#e08890`, texto `#16151c` (`--text-on-danger`, 6.99:1).
+- **Foco de teclado:** contorno `#b0acdc` (`--focus-color`, 7.68:1 sobre `--surface`).
+- **Tabla:** header y hover de fila `#16151c` (`--bg`), seleccionada `#2b2940` (`--accent-soft`).
+- **Sidebar activo:** fondo `#36334f`, texto `#c4c1e6` (6.95:1), icono `#b0acdc`.
+- **Tooltip:** se invierte — fondo `#e7e6ef`, texto `#1f1e28` (13.31:1).
+- **Overlay de modal:** `rgba(0,0,0,.6)`.
+- **Card interactiva:** el hover se lee en el borde, que pasa a `#747189` (`--border-strong`), igual que en claro.
+- **Skeleton:** base `#27262f`, 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` `#e7e6ef` sobre `#16151c`: **14.65:1** ✅ AAA (sobre `--surface` 13.32 · sobre `--surface-alt` 12.08).
+- `--text-secondary` `#c9c7d6`: 10.90 / 9.91 / 8.99 · `--text-muted` `#aaa8bb`: 7.80 / 7.09 / 6.43 (sobre `--bg` / `--surface` / `--surface-alt`) ✅.
+- `--link` `#c4c1e6` sobre `#16151c`: **10.46:1** ✅ (sobre `--surface` 9.52 · sobre `--surface-alt` 8.63).
+- `--text-on-primary` `#16151c` sobre `--accent` `#b0acdc`: **8.44:1** ✅.
+- `--accent` sobre `--surface`: **7.68:1** · `--border-strong` sobre `--surface`: **3.51:1** ✅ (mínimo de UI 3:1).
+- Tokens de componente: `--focus-color` sobre `--surface` **7.68:1** · `--text-on-danger` sobre `danger-500` **6.99:1** (hover 5.95 · active 5.27) · `--border-hover` sobre `--surface` **7.09:1**.
+- Tonos `--*-text` sobre sus `*-100` en dark: success **9.04:1** · warning **9.13:1** · danger **8.38:1** · info **8.93:1**. `--danger-text` sobre `--bg`: **9.01:1** · sobre `--surface`: 8.19.
+- `--text-on-primary-solid` `#c4c1e6` sobre `--accent-soft-strong` `#36334f` (iniciales del avatar, `+N` del AvatarGroup): **6.95:1**.
+- **Éxito frente a acento:** ΔE76 = **49.2** (mínimo 15).
+
+### 15.6 Implementación
+
+```css
+[data-theme="dark"] {
+  --bg: #16151c;
+  --surface: #1f1e27;
+  --surface-alt: #27262f;
+  --border: #2f2d3a;
+  --border-strong: #747189;
+  --text-primary: #e7e6ef;
+  --text-secondary: #c9c7d6;
+  --text-muted: #aaa8bb;
+  --text-disabled: #7b7990;
+  --accent: #b0acdc;
+  --accent-hover: #c4c1e6;
+  --accent-active: #9d98cf;
+  --accent-soft: #2b2940;
+  --accent-soft-strong: #36334f;
+  --text-on-primary: #16151c;
+  --text-on-primary-solid: #c4c1e6;
+  --link: #c4c1e6;
+  --success-500: #6cc1ad; --success-100: #13261f; --success-text: #8bd1c0;
+  --warning-500: #d6a752; --warning-100: #29220f; --warning-text: #e4c07f;
+  --danger-500: #e08890;  --danger-100: #2c171a;  --danger-text: #eba4ab;
+  --info-500: #8daecb;    --info-100: #172129;    --info-text: #a8c3da;
+  --ring: 0 0 0 3px rgba(176,172,220,.3);
+  --ring-color: rgba(176,172,220,.3);
+  --shadow-xs: none;
+  --shadow-sm: none;
+  --shadow-md: none;
+  --shadow-lg: 0 8px 20px rgba(8,8,12,.28);
+  --shadow-xl: 0 16px 32px rgba(8,8,12,.32);
+  color-scheme: dark;
+}
+```
+
+---
+
+## 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-bruma-lavanda.md` | Fuente de verdad legible |
+| **Style guide interactivo** | `bruma-lavanda.html` | Referencia visual siempre disponible (abrir en navegador) |
+| **Tokens CSS** | `dist/bruma-lavanda/tokens.css` | Drop-in para cualquier proyecto (vanilla, React, Angular, Vue) |
+| **Framework CSS** | `dist/bruma-lavanda/bruma-lavanda.css` | Tokens + clases de componentes (`.btn`, `.card`, `.sidebar`…) y la clase `.bruma-reset` |
+| **Tailwind v4** | `dist/bruma-lavanda/tailwind.css` | Bloque `@theme` — genera utilidades `bg-primary-500`, `text-neutral-800`, etc. |
+| **DTCG JSON** | `dist/bruma-lavanda/tokens.json` | Formato estándar W3C DTCG 2025.10 — interoperable con Figma/Tokens Studio/Style Dictionary |
+| **Paquete npm** | `@higinio/design-css/bruma/…` | Subrutas `bruma/tokens.css`, `bruma/framework.css`, `bruma/tailwind.css` y `bruma/tokens.json` |
+| **MCP** | `system="bruma"` | Tokens, specs de componentes y validación desde el servidor MCP (`get_token(system="bruma", name="--accent")`) |
+| **Skill de Claude** | `~/.claude/skills/bruma-lavanda-design/` | Invocable desde cualquier sesión de Claude Code |
+
+**Cómo consumirlo en un proyecto nuevo:**
+
+1. Copiar `dist/bruma-lavanda/tokens.css` (o importar `@higinio/design-css/bruma/tokens.css`) antes que cualquier estilo propio, **o** pegar el bloque `@theme` en el CSS de Tailwind v4 (`@higinio/design-css/bruma/tailwind.css`). Para tener también las clases de componentes, `@higinio/design-css/bruma/framework.css`.
+2. Aplicar la clase `.bruma-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="#f2f1f6">` (el `--bg` claro, niebla); con el tema oscuro activo, actualizarlo a `#16151c` para que la barra del navegador acompañe al fondo.