@higinio/design-mcp 0.1.0

package/assets/celeste/design-doc.md

@@ -0,0 +1,842 @@
+# DESIGN.md — Sistema de Diseño "Celeste Clásica"
+
+> Sistema de marca **light-first**, sereno y confiable, de **Higinio Sosa** para todos sus productos de software (web, móvil, dashboards, landing pages).
+> Paleta base: `#a0c0d4` (celeste, decorativo) · `#7192ba` (primario) · `#31343e` (tinta)
+>
+> **Versión 2.0** — sincronizado con el proyecto [Celeste Clásica Design System](https://claude.ai/design/p/4569c4e4-6c41-41d5-955f-ac4c55b6ad89) de claude.ai/design.
+> Entregables: `celeste-clasica.html` (style guide), `dist/celeste-clasica/` (tokens CSS · Tailwind v4 · DTCG JSON), skill `~/.claude/skills/celeste-clasica-design/`.
+
+---
+
+## 1. Identidad y principios
+
+**Personalidad de marca:** profesional, calmada, precisa. Transmite confianza sin ser fría; la elegancia viene del orden y el aire, no de la decoración. Vibe: *una consultora seria pero cálida — "banca privada boutique", no "startup ruidosa"*.
+
+1. **Claridad primero** — El contenido siempre por encima de la decoración.
+2. **Calma visual** — Superficies claras, whitespace generoso, contraste solo donde importa.
+3. **Un acento a la vez** — El azul `#7192ba` guía la acción; nunca compite consigo mismo.
+4. **Consistencia sobre novedad** — Mismos tokens en todos los productos; cero valores mágicos.
+5. **Movimiento con propósito** — La animación explica (aparece, cambia, desaparece), nunca decora sola.
+
+**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:** calmado, directo, profesional sin ser distante. Frases cortas. Cero jerga de marketing, **cero signos de exclamación**.
+- **Voz:** segunda persona ("tu correo", "tus proyectos"), 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 ("Guardar", "Eliminar cuenta").
+- **Errores:** explican qué falló **y qué hacer**, no solo "Error".
+- **Estados vacíos:** siempre invitan a una acción concreta — nunca un simple "No hay datos".
+- **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 despliegues", no "ocho despliegues" — se escanean más rápido.
+
+---
+
+## 3. Paleta de colores
+
+### 3.1 Primario — Azul Acero (base `#7192ba`)
+
+| Token | Hex | Uso |
+|---|---|---|
+| `primary-50` | `#f2f6fa` | Fondos hover sutiles, chips |
+| `primary-100` | `#dfe9f2` | Badges, estados seleccionados suaves, chip de avatar |
+| `primary-200` | `#c3d5e6` | Bordes activos, divisores destacados |
+| `primary-300` | `#a0c0d4` | **Celeste de marca** — ilustraciones, gráficas, decorativo. **Nunca texto** |
+| `primary-400` | `#87a8c7` | Iconos secundarios |
+| `primary-500` | `#7192ba` | **Primario** — fondo de botones, bordes activos, focus, rellenos de gráficas |
+| `primary-600` | `#5d7ba3` | Hover de botones primarios |
+| `primary-700` | `#4d6588` | Pressed/active, **`--link`: texto de links y botones ghost** |
+| `primary-800` | `#40536e` | Texto de marca con alto contraste |
+| `primary-900` | `#31343e` | **Tinta de marca** — headings, texto principal |
+
+### 3.2 Neutrales — Gris Azulado (derivados de `#31343e`)
+
+| Token | Hex | Uso |
+|---|---|---|
+| `neutral-0` | `#ffffff` | Superficie de tarjetas |
+| `neutral-50` | `#f7f8fa` | Fondo general de la app |
+| `neutral-100` | `#eef0f3` | Fondos alternos, filas zebra |
+| `neutral-200` | `#dcdfe5` | Bordes y divisores por defecto |
+| `neutral-300` | `#b8bdc7` | Bordes de inputs, iconos deshabilitados |
+| `neutral-400` | `#8a8f9c` | Placeholder, texto deshabilitado |
+| `neutral-500` | `#666b78` | Texto terciario, captions |
+| `neutral-600` | `#4d5160` | Texto secundario |
+| `neutral-700` | `#3d414e` | Párrafos largos |
+| `neutral-800` | `#31343e` | Texto principal, headings |
+| `neutral-900` | `#22242b` | Texto de máximo énfasis |
+
+### 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`)**.
+
+| Estado | Sólido `-500` | Fondo `-100` | Texto `-text` | Uso |
+|---|---|---|---|---|
+| `success` | `#3d9970` | `#e2f3ec` | `#2b6e50` | Confirmaciones, estados positivos |
+| `warning` | `#c9922e` | `#faf1de` | `#8a651c` | Advertencias, pendientes |
+| `danger` | `#c04d4d` | `#f9e7e7` | `#8f3232` | Errores, acciones destructivas |
+| `info` | `#7192ba` | `#dfe9f2` | `#4d6588` | Informativos (reutiliza primario) |
+
+### 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 |
+| `--surface` | `neutral-0` | Tarjetas, paneles |
+| `--surface-alt` | `neutral-100` | Fondos alternos, zebra, tracks |
+| `--border` | `neutral-200` | Borde por defecto |
+| `--border-strong` | `neutral-300` | Bordes de inputs y botones secundarios |
+| `--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 acción, bordes activos, focus |
+| `--accent-hover` | `primary-600` | Hover del primario |
+| `--accent-active` | `primary-700` | Pressed |
+| `--accent-soft` | `primary-50` | Hover de ghost, fondos sutiles |
+| `--accent-soft-strong` | `primary-100` | Seleccionados suaves |
+| `--link` | `primary-700` | **Texto de links y botones ghost (AA ~6:1)** |
+| `--ring` | `0 0 0 3px rgba(113,146,186,.25)` | Focus ring de inputs |
+
+> ⚠️ **Regla AA de acento:** `primary-500` sobre blanco da ~3:1 — válido solo para **componentes UI** (rellenos, bordes, focus). Para **texto** (links, ghost) usar `--link` (`primary-700`, ~6:1). `primary-300` jamás como texto.
+
+### 3.5 Proporción de uso (regla 60-30-10)
+
+- **60% — Neutrales claros** (`neutral-0/50/100`): fondos y superficies.
+- **30% — Tinta y estructura** (`neutral-600→900`, bordes): texto, iconos, divisores.
+- **10% — Primario y semánticos**: botones, links, estados, gráficas. **El acento pierde poder si supera el 10%.** (Excepción: una visualización de datos multiserie usa la paleta categórica validada de la skill `dataviz-marca`, exenta de este techo — son datos, no cromo decorativo.)
+
+Reglas prácticas:
+- **Un solo botón primario visible por pantalla**; el resto secundarios o ghost.
+- **Fondos siempre planos** (`--bg`): sin gradientes, texturas ni patrones; sin full-bleed decorativo — la superficie de trabajo (tarjetas blancas) 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 | **Fraunces** (600–700) | Georgia, serif | **Solo h1–h2**, cifras hero, títulos de marketing — nunca UI ni párrafos |
+| Body/UI | **Public Sans** (400–600) | system-ui, sans-serif | Párrafos, botones, formularios, h3–h6 |
+| Mono | **IBM Plex Mono** (400–500) | ui-monospace, monospace | Datos numéricos, código, IDs, montos en tablas |
+
+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=Fraunces:ital,opsz,wght@0,9..144,600;0,9..144,700;1,9..144,600&family=Public+Sans:ital,wght@0,400;0,500;0,600;0,700;1,400&family=IBM+Plex+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 (Public Sans) |
+| `text-3xl` | 31px | 1.25 `--leading-3xl` | 600 | h2 (Fraunces) |
+| `text-4xl` | 39px | 1.15 `--leading-4xl` | 700 | h1 (Fraunces) |
+| `text-5xl` | 49px | 1.1 `--leading-5xl` | 700 | Display/hero |
+
+Pesos tokenizados: `--weight-regular 400` · `--weight-medium 500` · `--weight-semibold 600` · `--weight-bold 700`.
+
+### 4.3 Reglas
+
+- Letter-spacing tokenizado: `--tracking-display: -0.02em` (display ≥31px), `--tracking-body: 0`, `--tracking-label: +0.04em` (labels uppercase).
+- Longitud de línea: `--measure: 65ch` (60–75 caracteres).
+- Números en tablas: `font-variant-numeric: tabular-nums` o IBM Plex 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 páginas", "lun–vie"); **em dash (—) solo para incisos**, con moderación (la skill `anti-slop-diseno` marca >2 por bloque como cliché de IA).
+- **Kerning activado** (`font-kerning: normal`); ligaduras por defecto.
+- En JSX/TSX y en strings usa el carácter UTF-8 real (`'`, `"`), no escapes ni entidades (`’`, `’`), que no se decodifican igual en todos los contextos.
+
+---
+
+## 5. Espaciado
+
+Escala base 4px — tokens `--space-1…24` (número = px/4): `4 · 8 · 12 · 16 · 20 · 24 · 32 · 40 · 48 · 64 · 80 · 96`
+
+Aliases de uso (consumir estos, no números sueltos):
+
+| Alias | Valor | Uso |
+|---|---|---|
+| `--card-padding` | 24px (`--space-6`) | Padding de tarjetas (`--card-padding-mobile: 16px`) |
+| `--section-gap` | 64px (`--space-16`) | Separación entre secciones (48–64px) |
+| `--form-gap` | 20px (`--space-5`) | Gap entre campos de formulario |
+| `--button-padding-md` | 12px 20px | Botón md (`--button-padding-sm: 8px 14px`) |
+| `--control-height-sm/md/lg` | 36 / 44 / 52px | Alturas de controles |
+| `--gutter` | 24px | Gutter del grid (`--gutter-mobile: 16px`) |
+
+---
+
+## 6. Bordes, radios y focus
+
+| Token | Valor | Uso |
+|---|---|---|
+| `radius-sm` | 6px | Inputs, chips, badges |
+| `radius-md` | 10px | Botones, dropdowns, menús |
+| `radius-lg` | 14px | Tarjetas, modales, accordion |
+| `radius-xl` | 20px | Hero, imágenes destacadas |
+| `radius-full` | 9999px | Avatares, pills, toggles |
+
+- Borde por defecto: `var(--border-width, 1px) solid var(--border)`.
+- **Focus ring global de teclado** (en `base.css`, 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(--primary-500);
+  outline-offset: 2px;
+  border-radius: 2px;
+}
+```
+
+Solo lo dispara el teclado (`:focus-visible`), nunca el click de ratón.
+
+**Transparencia y blur:** únicos usos permitidos — overlay de modal `rgba(49,52,62,.5)` y ring de focus. **No hay glassmorphism ni blur en Celeste Clásica**; las superficies son opacas y planas.
+
+---
+
+## 7. Elevación
+
+Sombras frías teñidas con la tinta `#31343e`, nunca negro puro. Máximo **3 niveles visibles por pantalla**. **Sin resplandor de acento:** el `glow` es exclusivo de Nocturna Eléctrica.
+
+### Niveles
+
+| Nivel | Superficie | Sombra | Uso |
+|---|---|---|---|
+| 0 | `--bg`, sin sombra, borde discontinuo | — | Reposo del lienzo |
+| 1 | `--surface` + borde `--border` | `--shadow-xs` / `--shadow-sm` | Inputs, tarjetas en reposo |
+| 2 | `--surface` + borde `--border` | `--shadow-md` | Hover, dropdowns |
+| 3 | `--surface` + borde `--border-strong` | `--shadow-lg` / `--shadow-xl` | Modales, popovers, diálogos críticos |
+
+### Sombras
+
+| Token | Valor | Uso |
+|---|---|---|
+| `shadow-xs` | `0 1px 2px rgba(49,52,62,.06)` | Inputs, indicador de SegmentedControl |
+| `shadow-sm` | `0 1px 3px rgba(49,52,62,.08), 0 1px 2px rgba(49,52,62,.05)` | Tarjetas en reposo |
+| `shadow-md` | `0 4px 8px rgba(49,52,62,.09), 0 2px 4px rgba(49,52,62,.05)` | Hover, dropdowns |
+| `shadow-lg` | `0 12px 24px rgba(49,52,62,.12), 0 4px 8px rgba(49,52,62,.06)` | Modales, popovers, menús |
+| `shadow-xl` | `0 24px 48px rgba(49,52,62,.16)` | Diálogos críticos |
+
+---
+
+## 8. Iconografía
+
+- **Set:** [Lucide](https://lucide.dev) como sustituto *(flagged: no hay set propio de marca — si existe, reemplazar)*. Trazo 1.5–2px, esquinas redondeadas, geométrico — casa con la calma y precisión 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).
+- **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 Fraunces peso 700 (`--weight-bold`), tracking `--tracking-display` (`-0.02em`), color `--text-primary` (tinta). Tamaño de referencia: 31px (`--text-3xl`).
+- **Variante badge:** mismo texto/tamaño dentro de caja con fondo `--surface`, borde `1px --border`, radius `md` (10px), `shadow-sm`, padding `14px 22px`.
+- El wordmark es texto, no un icono: Fraunces 600–700, nunca en UI ni párrafos.
+- **Sentence case siempre:** "Higinio", nunca "HIGINIO" ni "higinio".
+- Color `--text-primary`; `primary-300` jamás como texto, tampoco en el wordmark.
+- No se genera ilustración ni isotipo 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 `neutral-200`, texto `--text-disabled` |
+| Secundario | fondo `--surface`, borde `--border-strong`, texto `neutral-800` | fondo `neutral-50` | fondo `neutral-100` | 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-700`) | fondo `--accent-soft` | fondo `--accent-soft-strong` | fondo `neutral-200`, texto `--text-disabled` |
+| Destructivo | fondo `danger-500`, texto blanco | oscurecer 8% | oscurecer 14% | opacidad 50% |
+
+- Con icono: gap 8px, icono 20px.
+- Loading: spinner 16px reemplaza el texto (el botón conserva su ancho — fijar `min-width`).
+
+### 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 40px (icono 18) · lg 48px (icono 20).
+- Variantes espejo de Button: `primary` (fondo `--accent`, icono blanco; hover `--accent-hover`), `secondary` (fondo `--surface`, borde `--border-strong`; hover `neutral-50`), `ghost` (transparente, icono `--text-secondary`; hover fondo `neutral-100`) — **default `ghost`** porque vive en chrome denso, no como CTA.
+- Disabled: opacidad 0.5. Transición de fondo 150ms.
+
+### 10.3 Spinner
+
+Export propio (extraído del estado loading de Button). SVG 16px default: círculo al 25% de opacidad + arco de ¼ sólido, stroke 2.5, rotación 0.8s linear infinita. Color default `--accent`; blanco dentro de botones primary/destructive.
+
+### 10.4 Input
+
+- Fondo blanco, borde `1px --border-strong`, radius `sm`, altura `--control-height-md`, padding `0 14px`, `text-base`.
+- **Label:** `text-sm`, peso 500, `neutral-700`, margen inferior 6px. Siempre visible (no usar placeholder como label).
+- **Placeholder:** `--text-disabled`.
+- **Hover:** borde `neutral-400`.
+- **Focus:** borde `--accent` + `--ring`. Transición 150ms.
+- **Error:** borde `danger-500` + ring rojo suave; mensaje `text-sm` `danger-500` con icono, 6px debajo.
+- **Éxito (validación):** borde `success-500` + icono check dentro del input.
+- **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.
+- **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).
+
+### 10.5 Textarea
+
+Mismos estados que input. Min-height 96px, `resize: vertical`, padding 12px 14px. Contador de caracteres `text-xs` `--text-disabled` alineado a la derecha.
+
+### 10.6 Select
+
+- Trigger: igual que input + chevron 16px `--text-muted` (rota 180° al abrir, 200ms).
+- Menú: fondo blanco, radius `md`, `shadow-lg`, padding 6px, max-height 320px con scroll.
+- Opción: padding `10px 12px`, radius `sm`, hover fondo `neutral-50`, seleccionada fondo `--accent-soft` + texto `primary-700` + check.
+- Entrada del menú: fade + translateY(-4px→0), 180ms.
+
+### 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.
+- Indicador blanco (`--surface`) deslizante, radius `calc(radius-md - 3px)`, `shadow-xs`; **desliza left/width 200ms ease-out**.
+- Segmento activo: `--text-primary` semibold; inactivo: `--text-secondary` medium; transición de color 150ms. Texto `text-sm`.
+
+### 10.8 Slider
+
+Rango de valor único.
+
+- Track: 6px de alto, radius full; porción rellena `--accent`, resto `--border` (gradiente vivo, sin elementos extra).
+- Thumb: círculo blanco 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, borde `2px --border-strong`, radius 4px (checkbox) / full (radio).
+- 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"`.
+
+### 10.10 Switch
+
+- Track 44×24px, radius full. Off: fondo `--border-strong`. On: fondo `--accent`.
+- Thumb 20px blanco con `shadow-xs`; desliza 20px en 200ms `ease-spring`.
+
+### 10.11 Badge y Tag
+
+- Badge: `text-xs` peso 500, padding `2px 8px`, radius full. Fondo suave semántico (`*-100`) + **texto `--*-text`** del mismo tono.
+- Tag removible: incluye botón × de 14px, hover fondo más oscuro.
+
+### 10.12 Avatar
+
+- Imagen de usuario con fallback automático a iniciales (máx. 2, del nombre) sobre chip `primary-100` con texto `primary-700` semibold. 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`; chevron 18px `--text-muted` rota 180° (200ms). `aria-expanded`.
+- Panel: altura animada con `grid-template-rows` 0fr→1fr 250ms 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 `neutral-900`, texto blanco `text-xs`, padding `6px 10px`, radius `sm`, flecha 6px. Delay de aparición 400ms, fade + translateY(4px→0) en 150ms. Máximo 1 línea de ayuda; si necesita más, usar popover.
+
+**Skip-delay:** solo el primer tooltip del grupo espera los 400ms; mientras haya un tooltip visible, los hermanos aparecen al instante y sin animación de entrada. El usuario ya está explorando — repetirle el delay y el fade en cada icono estorba.
+
+### 10.16 Alert
+
+Banner de estado **inline y persistente** (vs Toast, transitorio): errores de formulario, avisos de plan.
+
+- 4 tonos: fondo suave semántico (`*-100`), radius `md`, padding `14px 16px`.
+- Icono semántico 20px en `*-500`: info→`info` · success→`circle-check` · warning→`triangle-alert` · danger→`circle-alert`.
+- Título `text-sm` semibold y cuerpo `text-sm` en `--*-text` (cuerpo con opacidad 0.92).
+- Botón cerrar opcional (× 16px en el color del tono) vía `onDismiss`. `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 blanco, borde izquierdo 3px semántico, `shadow-lg`, radius `md`, padding 14px 16px, icono semántico 20px.
+- Entrada: slide-in desde la derecha + fade, 250ms. Salida: fade + translateX, 200ms.
+- Auto-dismiss 5s (pausable con hover).
+- **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 250ms 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 250ms; tamaño default 56px, stroke 5; porcentaje centrado en mono (24% del tamaño).
+
+### 10.19 Modal
+
+- Overlay: `rgba(49,52,62,.5)`, fade 200ms.
+- 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).
+- `overscroll-behavior: contain` en el panel scrolleable — al llegar al fondo, el scroll no se encadena a la página de atrás.
+
+### 10.20 Menu
+
+Lista de acciones desplegable anclada a un trigger (acciones de fila, botones "más", menú de cuenta).
+
+- Panel: fondo `--surface`, 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 `neutral-50`.
+- Ítem `danger`: texto e icono `danger-500`, hover fondo `danger-100`.
+- Separador: 1px `--border`, margen `6px 4px`. Cierra con click fuera, Esc o al seleccionar.
+
+### 10.21 Tabla
+
+- Header: fondo `neutral-50`, `text-xs` uppercase `--tracking-label`, `--text-muted`, borde inferior `--border`.
+- 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`.
+
+### 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`). Tono derivado del signo (− → danger, resto success) u override `deltaTone`; colores del delta en `--*-text` (no los `-500`).
+
+### 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 `neutral-100`.
+- Página activa: chip sólido `--accent` texto blanco semibold, `aria-current="page"`.
+- Flechas deshabilitadas en extremos (`--text-disabled`); elipsis no clicable.
+
+### 10.24 Navegación
+
+- **Navbar:** altura 64px, fondo blanco, borde inferior `--border`. Link activo: texto `primary-700` + indicador inferior 2px `--accent`.
+- **Sidebar:** ancho 260px, fondo `neutral-50`. Ítem: radius `md`, padding `10px 12px`; activo: fondo `primary-100`, texto `primary-800`, icono `primary-600`.
+- **Tabs:** borde inferior `--border`; tab activa con indicador 2px `--accent` que se desliza entre tabs (250ms).
+- **Breadcrumbs:** `text-sm` `--text-muted`, separador `/` (tipográfico), último ítem `--text-primary`.
+
+### 10.25 Skeleton y EmptyState
+
+- Skeleton: fondo `--surface-alt` con shimmer (gradiente que barre en 1.4s, loop). Radius igual al contenido que reemplaza.
+- Estado vacío (`EmptyState`): icono 40px en `primary-300` decorativo, título `text-lg`, descripción `text-sm` `--text-muted`, CTA claro. Un estado vacío siempre invita a actuar.
+
+### 10.26 Card, Link y Code
+
+- **Card:** fondo `--surface`, borde `1px --border`, radius `lg`, padding 24px (16px en móvil), `shadow-sm`.
+- **Card interactiva:** cursor pointer; hover eleva — `translateY(-2px)` + `shadow-md`; transición de transform/sombra 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.
+- **Code (inline):** IBM Plex Mono `0.9em`, texto `--text-primary`, fondo `--surface-alt`, borde `1px --border`, radius `sm`, padding `1px 6px`.
+
+---
+
+## 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, éxito) | Puede deleitar, con presencia contenida |
+| Ocasional (abrir un panel, un modal) | Transición clara y sobria |
+| Diaria / repetida (navegar, 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
+
+```css
+:root {
+  --duration-instant: 100ms;  /* feedback táctil: press, toggle */
+  --duration-fast: 150ms;     /* hover, focus, color */
+  --duration-base: 200ms;     /* dropdowns, tooltips, switches */
+  --duration-slow: 250ms;     /* modales, toasts */
+  --duration-page: 320ms;     /* transiciones de página/vista */
+
+  --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) */
+}
+```
+
+### 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 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, 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`.
+10. **`will-change` solo mientras anima** — Se pone justo antes de animar y se quita al terminar; nunca permanente en el CSS. Presupuesto de capas GPU: menos de 10 elementos promovidos a la vez.
+
+### 11.3 Micro-interacciones por componente
+
+| Elemento | Trigger | Animación |
+|---|---|---|
+| Botón | hover | color de fondo 150ms + `shadow-sm` |
+| Botón | press | `scale(0.98)` 100ms |
+| Link | hover | color 150ms + subrayado que crece de 0 a 100% (200ms) |
+| Tarjeta interactiva | hover | `translateY(-2px)` + `shadow-md`, 200ms |
+| 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` |
+| 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 |
+| Modal | abrir | overlay fade 200ms; panel fade + scale(0.96→1) 250ms |
+| Toast | entrar | slide-in + fade 250ms `ease-out` |
+| Icon swap (p. ej. copiar→check) | cambio | cross-fade: opacity + scale(0.9→1), 150ms; nunca blur |
+| Progress | cambio | width / stroke-dashoffset 250ms `ease-out` |
+| Página/vista | cambio | fade + translateY(8px→0) 320ms |
+
+### 11.4 Loading
+
+- Spinner: ver §10.3.
+- Progress: ver §10.18.
+- Skeleton shimmer: 1.4s loop (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.
+
+```css
+@media (hover: hover) and (pointer: fine) {
+  .card--interactive:hover { transform: translateY(-2px); box-shadow: var(--shadow-md); }
+}
+```
+
+### 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 200ms, opacity 200ms` |
+| `ease-in` en entradas | `ease-in` en una entrada de UI | `--ease-out`; reserva `ease-in` para salidas |
+| Animar propiedades de layout | `width/height/top/left/right/bottom/margin/padding` | `transform`/`opacity`. Excepciones: `width` de Progress, `grid-template-rows` del Accordion |
+| Blur como recurso | `filter`/`backdrop-filter: blur()` | Elimínalo; fondos planos, sombras teñidas de tinta |
+| Duración excesiva | > el techo del sistema (`--duration-page`) 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 solo en carga real |
+| 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
+
+- `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`.
+- `primary-300` (#a0c0d4) **nunca como texto sobre blanco** — solo decorativo.
+- Tonos `--*-text` garantizan AA sobre los fondos suaves `*-100`.
+- 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 == */
+  --primary-50: #f2f6fa; --primary-100: #dfe9f2; --primary-200: #c3d5e6;
+  --primary-300: #a0c0d4; --primary-400: #87a8c7; --primary-500: #7192ba;
+  --primary-600: #5d7ba3; --primary-700: #4d6588; --primary-800: #40536e;
+  --primary-900: #31343e;
+
+  /* == Primitivos: neutrales == */
+  --neutral-0: #ffffff; --neutral-50: #f7f8fa; --neutral-100: #eef0f3;
+  --neutral-200: #dcdfe5; --neutral-300: #b8bdc7; --neutral-400: #8a8f9c;
+  --neutral-500: #666b78; --neutral-600: #4d5160; --neutral-700: #3d414e;
+  --neutral-800: #31343e; --neutral-900: #22242b;
+
+  /* == Primitivos: semánticos (ramp de 3) == */
+  --success-500: #3d9970; --success-100: #e2f3ec; --success-text: #2b6e50;
+  --warning-500: #c9922e; --warning-100: #faf1de; --warning-text: #8a651c;
+  --danger-500: #c04d4d;  --danger-100: #f9e7e7;  --danger-text: #8f3232;
+  --info-500: #7192ba;    --info-100: #dfe9f2;    --info-text: #4d6588;
+
+  /* == 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-300);
+  --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-700);
+
+  /* == Tipografía == */
+  --font-display: "Fraunces", Georgia, serif;
+  --font-body: "Public Sans", system-ui, -apple-system, sans-serif;
+  --font-mono: "IBM Plex 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 == */
+  --space-1: 4px; --space-2: 8px; --space-3: 12px; --space-4: 16px;
+  --space-5: 20px; --space-6: 24px; --space-8: 32px; --space-10: 40px;
+  --space-12: 48px; --space-16: 64px; --space-20: 80px; --space-24: 96px;
+  --card-padding: var(--space-6); --card-padding-mobile: var(--space-4);
+  --section-gap: var(--space-16); --form-gap: var(--space-5);
+  --button-padding-md: 12px 20px; --button-padding-sm: 8px 14px;
+  --control-height-sm: 36px; --control-height-md: 44px; --control-height-lg: 52px;
+  --gutter: 24px; --gutter-mobile: 16px;
+
+  /* == Radios, bordes y sombras == */
+  --radius-sm: 6px; --radius-md: 10px; --radius-lg: 14px;
+  --radius-xl: 20px; --radius-full: 9999px;
+  --border-width: 1px;
+  --shadow-xs: 0 1px 2px rgba(49,52,62,.06);
+  --shadow-sm: 0 1px 3px rgba(49,52,62,.08), 0 1px 2px rgba(49,52,62,.05);
+  --shadow-md: 0 4px 8px rgba(49,52,62,.09), 0 2px 4px rgba(49,52,62,.05);
+  --shadow-lg: 0 12px 24px rgba(49,52,62,.12), 0 4px 8px rgba(49,52,62,.06);
+  --shadow-xl: 0 24px 48px rgba(49,52,62,.16);
+
+  /* == Focus == */
+  --ring: 0 0 0 3px rgba(113,146,186,.25);
+  --ring-color: rgba(113,146,186,.25);
+
+  /* == Motion == */
+  --duration-instant: 100ms; --duration-fast: 150ms; --duration-base: 200ms;
+  --duration-slow: 250ms; --duration-page: 320ms;
+  --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);
+  --ease-spring: cubic-bezier(0.34, 1.4, 0.64, 1);
+
+  color-scheme: light;
+}
+```
+
+Estilos base (extracto de `base.css` — clase `.celeste-reset` aplicable a `body` o contenedor): fondo `--bg`, color `--text-primary`, `--font-body`/`--text-base`/`--leading-base`, antialiased; **h1–h2 en display bold** 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.
+
+**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.
+
+### 15.1 Filosofía de la inversión
+
+- Los fondos se derivan de la tinta `#31343e` (nunca negro puro ni gris genérico): el dark hereda el matiz azulado de la marca.
+- El primario se **aclara un paso**: sobre fondo oscuro, `#7192ba` pierde fuerza, así que el rol de acento pasa a `primary-400 (#87a8c7)` y el celeste `#a0c0d4` gana protagonismo en links y datos.
+- Las sombras pierden peso; la elevación se apoya en superficies más claras + bordes (mismo patrón que cualquier dark bien hecho).
+
+### 15.2 Mapeo de tokens
+
+| Token semántico | Light | Dark |
+|---|---|---|
+| `--bg` | `#f7f8fa` | `#16181e` |
+| `--surface` | `#ffffff` | `#1d2028` |
+| `--surface-2` (modales, dropdowns) | `#ffffff` | `#252935` |
+| `--border` | `#dcdfe5` | `#3a3f4d` |
+| `--border-strong` | `#b8bdc7` | `#4a5060` |
+| `--text-primary` | `#31343e` | `#e6e9ee` |
+| `--text-secondary` | `#4d5160` | `#b9bfcb` |
+| `--text-muted` | `#666b78` | `#8b91a0` |
+| `--accent` (botones, focus) | `#7192ba` | `#87a8c7` |
+| `--accent-hover` | `#5d7ba3` | `#a0c0d4` |
+| `--accent-active` | `#4d6588` | `#7192ba` |
+| `--text-on-primary` | `#ffffff` | `#16181e` |
+| `--link` | `#4d6588` | `#a0c0d4` |
+| `--success` | `#3d9970` | `#5cbf93` |
+| `--warning` | `#c9922e` | `#e0ad4d` |
+| `--danger` | `#c04d4d` | `#e07777` |
+| `--ring` | `rgba(113,146,186,.25)` | `rgba(160,192,212,.3)` |
+
+Fondos suaves semánticos en dark: `success #12291f` · `warning #2b2210` · `danger #2e1515` · `info #1a2430`.
+
+### 15.3 Elevación en dark
+
+| Nivel | Superficie | Sombra |
+|---|---|---|
+| 0 | `#16181e` | — |
+| 1 | `#1d2028` | `0 1px 2px rgba(0,0,0,.35)` |
+| 2 | `#252935` | `0 4px 12px rgba(0,0,0,.45)` |
+| 3 | `#252935` + borde `#4a5060` | `0 12px 32px rgba(0,0,0,.55)` |
+
+### 15.4 Ajustes de componentes en dark
+
+- **Botón primario:** fondo `#87a8c7`, texto `#16181e` (contraste ≈ 7: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`.
+- **Tooltip:** se invierte — fondo `#e6e9ee`, texto `#31343e`.
+- **Overlay de modal:** `rgba(0,0,0,.6)`.
+- **Skeleton:** base `#252935`, shimmer hacia `#2e3340`.
+- Texto claro sobre oscuro "engorda": bajar un peso donde sea posible (500→400).
+
+### 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.
+
+### 15.6 Implementación
+
+```css
+[data-theme="dark"] {
+  --bg: #16181e;
+  --surface: #1d2028;
+  --surface-alt: #252935;
+  --border: #3a3f4d;
+  --border-strong: #4a5060;
+  --text-primary: #e6e9ee;
+  --text-secondary: #b9bfcb;
+  --text-muted: #8b91a0;
+  --text-disabled: #6f7585;
+  --accent: #87a8c7;
+  --accent-hover: #a0c0d4;
+  --accent-active: #7192ba;
+  --text-on-primary: #16181e;
+  --link: #a0c0d4;
+  --success-500: #5cbf93; --success-100: #12291f; --success-text: #7fd4ae;
+  --warning-500: #e0ad4d; --warning-100: #2b2210; --warning-text: #ecc57e;
+  --danger-500: #e07777;  --danger-100: #2e1515;  --danger-text: #eb9e9e;
+  --info-500: #87a8c7;    --info-100: #1a2430;    --info-text: #a0c0d4;
+  --ring: 0 0 0 3px rgba(160,192,212,.3);
+  --shadow-sm: 0 1px 2px rgba(0,0,0,.35);
+  --shadow-md: 0 4px 12px rgba(0,0,0,.45);
+  --shadow-lg: 0 12px 32px rgba(0,0,0,.55);
+  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-celeste-clasica.md` | Fuente de verdad legible |
+| **Style guide interactivo** | `celeste-clasica.html` | Referencia visual siempre disponible (abrir en navegador) |
+| **Tokens CSS** | `dist/celeste-clasica/tokens.css` | Drop-in para cualquier proyecto (vanilla, React, Angular, Vue) |
+| **Tailwind v4** | `dist/celeste-clasica/tailwind.css` | Bloque `@theme` — genera utilidades `bg-primary-500`, `text-neutral-800`, etc. |
+| **DTCG JSON** | `dist/celeste-clasica/tokens.json` | Formato estándar W3C DTCG 2025.10 — interoperable con Figma/Tokens Studio/Style Dictionary |
+| **Skill de Claude** | `~/.claude/skills/celeste-clasica-design/` | Invocable desde cualquier sesión de Claude Code |
+| **Proyecto claude.ai/design** | [Celeste Clásica Design System](https://claude.ai/design/p/4569c4e4-6c41-41d5-955f-ac4c55b6ad89) | Componentes React + specimens + UI kit dashboard |
+
+**Cómo consumirlo en un proyecto nuevo:**
+
+1. Copiar `dist/celeste-clasica/tokens.css` e importarlo antes que cualquier estilo propio, **o** pegar el bloque `@theme` en el CSS de Tailwind v4.
+2. Aplicar la clase `.celeste-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="#f7f8fa">` (el `--bg` claro); con el tema oscuro activo, actualizarlo a `#16181e` para que la barra del navegador acompañe al fondo.