@higinio/design-mcp 0.1.0

package/assets/nocturna/design-doc.md

@@ -0,0 +1,857 @@
+# DESIGN.md — Sistema de Diseño "Nocturna Eléctrica"
+
+> Sistema de marca **dark-first**, enérgico y de alto contraste, de **Higinio Sosa** para todos sus productos de software (web, móvil, dashboards, landing pages).
+> Paleta base: `#52baed` (celeste eléctrico) · `#353d7c` (índigo profundo) · `#010203` (negro nocturno)
+>
+> **Versión 2.0** — sincronizado con el proyecto [Nocturna Eléctrica Design System](https://claude.ai/design/p/1a3a2fb6-b02c-481c-96fc-017d50ec9ce7) de claude.ai/design.
+> Entregables: `nocturna-electrica.html` (style guide), `dist/nocturna-electrica/` (tokens CSS · Tailwind v4 · DTCG JSON), skill `~/.claude/skills/nocturna-electrica-design/`.
+
+---
+
+## 1. Identidad y principios
+
+**Personalidad de marca:** moderna, técnica, con energía contenida. El fondo casi negro es el escenario; el celeste eléctrico es el reflector.
+
+1. **Contraste con propósito** — El acento `#52baed` solo aparece donde hay acción o dato clave.
+2. **Profundidad por luz** — La elevación se comunica aclarando superficies, no oscureciendo bordes.
+3. **Energía contenida** — Paleta vibrante, espaciado disciplinado: nunca ruidosa.
+4. **Datos protagonistas** — Cifras y gráficas brillan; el chrome de la UI se mantiene discreto.
+5. **Movimiento con propósito** — La animación explica cambios de estado, nunca decora sola.
+
+**Regla de oro de implementación:** los componentes consumen **solo tokens semánticos** (`--surface-1`, `--text-primary`, `--accent-400`…), nunca hex directos. El theme switch es un cambio de atributo, no un refactor.
+
+---
+
+## 2. Voz y contenido
+
+- **Idioma:** español, técnico pero cercano. Tuteo implícito; sin formalismos.
+- **Tono:** directo, preciso, con energía contenida. Frases cortas y declarativas: *"El fondo casi negro es el escenario; el celeste eléctrico es el reflector."*
+- **Casing:** sentence case en headings y botones ("Crear proyecto", no "Crear Proyecto" ni "CREAR PROYECTO"). Overlines/labels en uppercase con tracking `+0.08em`.
+- **Copy de botones:** verbo + objeto, corto: "Guardar cambios", "Ver informe".
+- **Mensajes de estado:** concretos y accionables — el error dice qué pasó **y qué hacer**.
+- **Números y datos:** protagonistas — siempre en JetBrains Mono o `tabular-nums`, grandes en dashboards, con count-up al montar.
+- **Fechas y números formateados:** siempre con `Intl.DateTimeFormat` / `Intl.NumberFormat` (`es-MX`), nunca formatos hardcodeados — un "12/07/2026" a mano se rompe al cambiar de locale.
+- **`translate="no"`** en nombres de marca y tokens de código (IDs, comandos, rutas), para que la traducción automática no los corrompa.
+- **Numerales para conteos:** "8 despliegues", no "ocho despliegues" — en un dashboard el dígito se escanea más rápido.
+- **Emoji:** no se usan en la UI. El estado se comunica con color + icono + texto.
+
+---
+
+## 3. Paleta de colores
+
+### 3.1 Acento — Celeste Eléctrico (base `#52baed`)
+
+| Token | Hex | Uso |
+|---|---|---|
+| `accent-100` | `#d9f0fb` | Texto sobre fondos accent oscuros |
+| `accent-200` | `#a8ddf6` | Hover de links |
+| `accent-300` | `#7dccf1` | Iconos activos, gráficas secundarias, código inline |
+| `accent-400` | `#52baed` | **Acento principal** — CTAs, links, focus, datos clave |
+| `accent-500` | `#2fa3dd` | Hover de botones de acento |
+| `accent-600` | `#1f87bb` | Pressed |
+| `accent-700` | `#186a94` | Bordes de elementos activos |
+
+### 3.2 Secundario — Índigo Profundo (base `#353d7c`)
+
+| Token | Hex | Uso |
+|---|---|---|
+| `indigo-300` | `#7a83c4` | Texto/iconos secundarios de marca |
+| `indigo-400` | `#565fa3` | Gráficas, tags, iconos de estados vacíos |
+| `indigo-500` | `#353d7c` | **Secundario** — botones secundarios, secciones destacadas |
+| `indigo-600` | `#2b3264` | Hover del secundario, borde de avatar |
+| `indigo-700` | `#22284f` | Fondos de banners/tarjetas destacadas, fondo de avatar |
+| `indigo-800` | `#1a1e3b` | Fondos sutiles de marca, sidebar activo |
+
+### 3.3 Neutrales — Escala Nocturna (derivados de `#010203`)
+
+| Token | Hex | Uso |
+|---|---|---|
+| `night-950` | `#010203` | **Fondo base** |
+| `night-900` | `#0b0d12` | Superficie 1 (tarjetas) |
+| `night-800` | `#14171f` | Superficie 2 (modales, dropdowns, inputs) |
+| `night-700` | `#1e222d` | Superficie 3, hover de filas |
+| `night-600` | `#2a2f3d` | Bordes destacados (énfasis) |
+| `night-500` | `#3d4354` | Bordes por defecto |
+| `night-400` | `#6b7183` | Deshabilitado, placeholders |
+| `night-300` | `#9aa0b0` | Texto terciario, captions |
+| `night-200` | `#c5c9d4` | Texto secundario |
+| `night-100` | `#e8eaef` | Texto principal |
+| `night-50` | `#f6f7f9` | Máximo énfasis, headings |
+
+### 3.4 Semánticos (calibrados para fondo oscuro)
+
+| Token | Hex | Fondo suave | Uso |
+|---|---|---|---|
+| `success-400` | `#4ade80` | `#0a2617` | Confirmaciones, estados positivos |
+| `warning-400` | `#fbbf24` | `#2a2005` | Advertencias |
+| `danger-400` | `#f87171` | `#2c0f0f` | Errores, acciones destructivas |
+| `info-400` | `#52baed` | `#0d1f2c` | Informativos (reutiliza acento) |
+
+### 3.5 Capa de aliases semánticos
+
+Los componentes **nunca** usan los primitivos de arriba directamente: consumen esta capa. Así el theme switch (§15) y cualquier rebranding son cambios de una sola línea.
+
+| Alias | Valor | Rol |
+|---|---|---|
+| `--bg` | `night-950` | Fondo de la app |
+| `--surface-1` | `night-900` | Tarjetas en reposo |
+| `--surface-2` | `night-800` | Modales, dropdowns, inputs |
+| `--surface-3` | `night-700` | Hover de filas, superficie máxima |
+| `--border` | `night-500` | Borde por defecto |
+| `--border-strong` | `night-600` | Borde de énfasis (elevación 3, accordion) |
+| `--text-primary` | `night-100` | Texto principal |
+| `--text-secondary` | `night-200` | Texto secundario |
+| `--text-muted` | `night-300` | Terciario, captions |
+| `--text-disabled` | `night-400` | Deshabilitado, placeholder |
+| `--text-heading` | `night-50` | Headings, máximo énfasis |
+| `--text-on-accent` | `night-950` | Texto sobre CTAs de acento (**oscuro, nunca blanco**) |
+| `--accent-ghost-hover` | `rgba(82,186,237,.08)` | Hover de botones ghost |
+| `--accent-ghost-active` | `rgba(82,186,237,.14)` | Active de botones ghost |
+| `--accent-selected` | `rgba(82,186,237,.12)` | Filas/opciones seleccionadas |
+| `--overlay` | `rgba(1,2,3,.7)` | Overlay de modal |
+| `--success/--warning/--danger/--info` | sus `-400` | Estados semánticos |
+
+### 3.6 Proporción de uso (regla 60-30-10 adaptada a dark)
+
+- **60% — Fondos nocturnos** (`night-950/900/800`): el escenario oscuro.
+- **30% — Texto y estructura** (`night-50→300`, bordes, índigo en fondos de sección).
+- **10% — Acento eléctrico y semánticos**: CTAs, links, cifras clave, gráficas. (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:
+- El celeste `accent-400` es **el único color que grita**: un CTA primario por pantalla.
+- El índigo es el "30% de marca": fondos de hero, sidebars, estados seleccionados — nunca compite con el acento y **nunca es texto sobre negro** (contraste 1.9:1).
+- Evitar blanco puro `#ffffff` en texto masivo; usar `night-100`.
+- **Fondos siempre planos:** sin imágenes de fondo, sin texturas, sin gradientes decorativos. El único "brillo" permitido es el glow de acento (§7).
+
+---
+
+## 4. Tipografía
+
+### 4.1 Familias
+
+| Rol | Fuente | Fallback | Uso |
+|---|---|---|---|
+| Display | **Space Grotesk** (500–700) | system-ui, sans-serif | **Solo h1–h3**, cifras hero, navegación, wordmark |
+| Body/UI | **Manrope** (400–700) | system-ui, sans-serif | Párrafos, formularios, tablas, **h4 en adelante** |
+| Mono | **JetBrains Mono** (400–500) | monospace | Datos numéricos, código, IDs |
+
+Carga vía Google Fonts CDN (sin binarios adjuntos — si hay licencias locales, sustituir por `@font-face` con los mismos `font-family`):
+
+```css
+@import url('https://fonts.googleapis.com/css2?family=Space+Grotesk:wght@500;600;700&family=Manrope:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap');
+```
+
+### 4.2 Escala (ratio 1.25, base 16px, en `rem`)
+
+| Token | Tamaño | Line-height (token) | Peso | Uso |
+|---|---|---|---|---|
+| `text-xs` | 12px | 1.5 `--leading-snug` | 500 | Labels, overlines |
+| `text-sm` | 14px | 1.5 `--leading-snug` | 400 | Texto secundario, tablas |
+| `text-base` | 16px | 1.6 `--leading-body` | 400 | Párrafos, inputs |
+| `text-lg` | 18px | 1.55 | 500 | Lead |
+| `text-xl` | 20px | 1.4 `--leading-h4` | 600 | h4 (Manrope) |
+| `text-2xl` | 25px | 1.3 `--leading-h3` | 600 | h3 (Space Grotesk) |
+| `text-3xl` | 31px | 1.2 `--leading-h2` | 700 | h2 (Space Grotesk) |
+| `text-4xl` | 39px | 1.15 `--leading-heading` | 700 | h1 (Space Grotesk) |
+| `text-5xl` | 49px | 1.05 `--leading-tight` | 700 | Cifras hero |
+
+### 4.3 Reglas
+
+- En dark el texto claro "engorda" ópticamente: preferir peso **400** donde en light usarías 500.
+- Letter-spacing tokenizado: `--tracking-display: -0.02em` en display; `--tracking-overline: +0.08em` en overlines/labels uppercase.
+- Números: `tabular-nums` o JetBrains Mono.
+- Longitud de línea: `--measure: 65ch` (60–75 caracteres). Mínimo absoluto 12px.
+- `::selection`: `rgba(82,186,237,.3)`. Placeholder: `night-400`.
+
+### 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-body`/`--leading-snug`, §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`: `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 | Padding de tarjetas (`--card-padding-mobile: 16px`) |
+| `--section-gap` | 64px | Separación entre secciones (el dark agradece más aire) |
+| `--form-gap` | 20px | Gap entre campos de formulario |
+| `--button-padding` | 12px 20px | Padding de botones md |
+| `--touch-target` | 44px | Altura mínima interactiva |
+| `--grid-gutter` | 24px | Gutter del grid (`--grid-gutter-mobile: 16px`) |
+
+---
+
+## 6. Bordes, radios y focus
+
+| Token | Valor | Uso |
+|---|---|---|
+| `radius-sm` | 8px | Inputs, chips |
+| `radius-md` | 12px | Botones, dropdowns, IconButton |
+| `radius-lg` | 16px | Tarjetas, modales, accordion |
+| `radius-xl` | 24px | Hero, contenedores destacados |
+| `radius-full` | 9999px | Avatares, pills, progress |
+
+Tokens compuestos:
+
+```css
+--border-default: 1px solid var(--night-500);
+--border-emphasis: 1px solid var(--night-600);
+--focus-ring: 2px solid var(--accent-400);
+--focus-ring-offset: 2px;
+```
+
+Focus global: `:focus-visible { outline: var(--focus-ring); outline-offset: var(--focus-ring-offset); }` — se aplica a todo interactivo, solo con teclado (el click de ratón no lo dispara).
+
+---
+
+## 7. Elevación (superficie + sombra + borde)
+
+En fondo casi negro las sombras solas no bastan: la elevación combina **superficie más clara + sombra + borde sutil**.
+
+| Nivel | Superficie | Sombra | Uso |
+|---|---|---|---|
+| 0 | `night-950` | — | Fondo de la app |
+| 1 | `night-900` | `--shadow-1: 0 1px 2px rgba(0,0,0,.4)` | Tarjetas en reposo |
+| 2 | `night-800` | `--shadow-2: 0 4px 12px rgba(0,0,0,.5)` | Dropdowns, hover |
+| 3 | `night-800` + borde `night-600` | `--shadow-3: 0 12px 32px rgba(0,0,0,.6)` | Modales, popovers |
+
+Tokens adicionales:
+
+```css
+--glow-accent: 0 0 0 1px rgba(82,186,237,.35), 0 4px 20px rgba(82,186,237,.18);
+--ring: 0 0 0 3px rgba(82,186,237,.2);          /* focus de inputs */
+--ring-danger: 0 0 0 3px rgba(248,113,113,.2);  /* focus en estado error */
+--overlay: rgba(1,2,3,.7);                      /* overlay de modal */
+```
+
+**Glow de acento:** solo interactivos clave, **máximo uno por pantalla**.
+**Transparencia y blur:** únicamente en navbar (`night-950` al 80% + `backdrop-filter: blur(12px)`) y overlay de modal (+ blur 4px). En ningún otro sitio.
+
+---
+
+## 8. Iconografía
+
+- **Set:** [Lucide](https://lucide.dev) como sustituto *(flagged: no hay set propio de marca — si existe, reemplazar)*. Trazo 2px, esquinas redondeadas, estilo técnico-limpio.
+- **Componente `Icon`:** wrapper SVG viewBox 24, `stroke-width: 2`, caps/joins redondeados, `fill: none`, tamaño default 20px, color `currentColor`. Decorativo → `aria-hidden="true"`; con `aria-label` → `role="img"`. Set curado: home, chart, bell, gear, search, plus, check, x, copy, folder, chevronDown, arrowRight, user, bolt.
+- **Tamaños:** 20px en botones (gap 8px) · 18px leading en inputs · 16px en chevrons/metadatos.
+- **Color:** los iconos heredan el color del texto; activos en `accent-300/400`; estados vacíos en `indigo-400`.
+- **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.
+
+---
+
+## 9. Marca / Wordmark
+
+No hay logo dibujado — el wordmark es puramente tipográfico:
+
+- **"higinio.sosa"** en Space Grotesk 700, tracking `-0.02em`, color `--text-heading` (`night-50`), con el **punto separador en `accent-400`**. Tamaño de referencia: 31px (`text-3xl`).
+- **Variante badge:** mismo texto a 22px dentro de caja con fondo `indigo-800`, borde `1px indigo-600`, radius `md` (12px), padding `14px 22px`.
+- Donde un producto necesite logotipo, se renderiza el nombre del producto en `--font-display`; nunca se dibuja un logo aproximado.
+
+---
+
+## 10. Biblioteca de componentes
+
+### 10.1 Botones
+
+Altura: 44px (md), 36px (sm), 52px (lg). Radius `md`. Peso 600.
+
+| Variante | Reposo | Hover | Active | Disabled |
+|---|---|---|---|---|
+| Primario | fondo `accent-400`, **texto `night-950`** (no blanco) | `accent-500` + glow suave | `accent-600`, sin glow | fondo `night-700`, texto `night-400` |
+| Secundario | fondo `indigo-500`, texto `night-50` | `indigo-600` | `indigo-700` | opacidad 50% |
+| Outline | borde `night-500`, texto `night-100` | fondo `night-800`, borde `night-400` | fondo `night-700` | opacidad 50% |
+| Ghost | texto `accent-400` | fondo `--accent-ghost-hover` | fondo `--accent-ghost-active` | texto `night-400` |
+| Destructivo | fondo `danger-400`, texto `night-950` | oscurecer 8% | oscurecer 14% | opacidad 50% |
+
+- Con icono: gap 8px, icono 20px.
+- Loading: spinner 16px, botón conserva ancho (`min-width`).
+
+### 10.2 IconButton
+
+Botón cuadrado solo-icono. **Requiere `label` accesible** (`aria-label` + `title`). Tamaños sm/md/lg = 36/44/52px, radius `md`.
+
+| Variante | Reposo | Hover | Active |
+|---|---|---|---|
+| Outline | transparente, texto `night-200`, borde `night-500` | fondo `night-800`, borde `night-400` | fondo `night-700` |
+| Ghost | transparente, texto `night-300` | fondo `night-800`, texto `night-100` | fondo `night-700` |
+| Accent | texto `accent-400`, sin borde | fondo `--accent-ghost-hover` | fondo `--accent-ghost-active` |
+
+Disabled: opacidad 50% + `cursor: not-allowed`. Press: `scale(0.98)` 100ms. Transición de fondo 150ms.
+
+### 10.3 Spinner
+
+Indicador de carga circular; también sustituye el label del botón en estado loading (ver §10.1).
+
+- 16px por defecto (demo también a 24px y 32px para contextos con más peso visual).
+- Trazo `2px solid` con 25% de opacidad (`color-mix(in srgb, currentColor 25%, transparent)`) + cuarto superior en `currentColor` sólido, radius `full`.
+- Color default `accent-400`; hereda `currentColor` — `night-950` dentro de botones primario/destructivo, `night-300` en contextos neutros.
+- Rotación `0.8s linear infinite`.
+- Cargas <300ms: no mostrar spinner (evita parpadeo).
+
+### 10.4 Input
+
+- Fondo `night-800`, borde `1px night-500`, radius `sm`, altura 44px, padding `0 14px`, texto `night-100`.
+- **Label:** `text-sm` peso 500 `night-200`, margen inferior 6px. Siempre visible (nunca placeholder-como-label).
+- **Placeholder:** `night-400`.
+- **Hover:** borde `night-400`.
+- **Focus:** borde `accent-400` + `--ring`. Transición 150ms.
+- **Error:** borde `danger-400` + `--ring-danger`; mensaje `text-sm` `danger-400` con icono.
+- **Éxito:** borde `success-400` + icono check.
+- **Disabled:** fondo `night-900`, texto `night-400`, cursor `not-allowed`.
+- **Ayuda:** `text-sm` `night-300` debajo.
+- Icono leading: padding-left 40px, icono 18px `night-400`.
+- **`inputmode` según el dato** (`numeric`, `email`, `tel`, `decimal`) para el teclado correcto en móvil; `spellcheck="false"` en emails, códigos y usernames.
+- **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`. Contador `text-xs` `night-400` a la derecha.
+
+### 10.6 Select
+
+- Trigger: como input + chevron 16px `night-300` (rota 180° al abrir, 200ms).
+- Menú: fondo `night-800`, borde `night-600`, radius `md`, sombra nivel 3, padding 6px, max-height 320px.
+- Opción: padding `10px 12px`, radius `sm`, hover fondo `night-700`, seleccionada fondo `--accent-selected` + texto `accent-300` + check.
+- Entrada: fade + translateY(-4px→0), 180ms.
+
+### 10.7 SegmentedControl
+
+Selector tipo pill de **2–4 opciones mutuamente excluyentes** (cambio de vista, filtros rápidos). Para más de 4 opciones o labels largos, usar `Select`.
+
+- Contenedor: fondo `night-800`, borde `1px night-500`, radius `md`, padding 3px. Altura 44px (md) / 36px (sm).
+- Opción activa: fondo `night-700`, texto `accent-300` peso 600, sombra nivel 1; transición de fondo/color/sombra 220ms ease-out.
+- Opción inactiva: texto `night-200` peso 500, `text-sm` (`text-xs` en sm).
+- Focus: ring en la opción enfocada, igual que inputs.
+
+### 10.8 Slider
+
+Selector de valor único en un rango (`min`/`max`/`step`/`value`).
+
+- Track: 6px de alto, radius full; porción rellena `accent-400`, resto `night-700` (gradiente lineal, sin elementos extra).
+- Thumb: círculo `night-50` 18px, borde `2px accent-400`, sombra nivel 1; **al presionar escala 1.15** (100ms).
+- Label opcional `text-sm night-200` arriba-izquierda; valor en JetBrains Mono `night-300` arriba-derecha (`showValue`).
+- Disabled: opacidad 50%. Focus: ring como inputs. Respeta `prefers-reduced-motion` (el escalado del thumb al presionar se desactiva).
+
+### 10.9 Checkbox y Radio
+
+- 20px, borde `2px night-500`, radius 4px / full.
+- Checked: fondo `accent-400`, check `night-950` animado (stroke-dashoffset, 200ms).
+- Hover: borde `accent-300`. Focus: ring como inputs.
+- Label clicable, gap 10px.
+
+### 10.10 Switch
+
+- Track 44×24px, radius full. Off: fondo `night-600`. On: fondo `accent-400`.
+- Thumb 20px `night-50`; 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 + texto 400 del mismo tono (ej. `#0a2617` + `#4ade80`) + borde `1px` del tono al 30%.
+- Tag removible: botón × 14px, hover fondo más claro.
+
+### 10.12 Avatar
+
+- Circular (radius full). Tamaños xs/sm/md/lg/xl = 24/32/40/48/64px (iniciales 10/12/15/18/24px).
+- Con imagen: `object-fit: cover`, borde `1px night-600`.
+- Sin imagen: iniciales (máx. 2, uppercase) en Space Grotesk 600 tracking `-0.02em`, color `night-50` sobre fondo `indigo-700` con borde `indigo-600`.
+- Punto de estado opcional (esquina inferior derecha, ~28% del diámetro, mín. 8px, borde 2px `night-950`): online `success-400` · busy `danger-400` · away `warning-400` · offline `night-500`.
+
+### 10.13 Divider
+
+- Regla hairline `1px night-500`. `role="separator"`.
+- Horizontal (default) · horizontal con label centrado (`text-xs` uppercase, tracking `+0.08em`, `night-300`, peso 500; líneas flexibles a los lados, gap 12px — patrón "o continúa con") · vertical (ancho 1px, se estira al alto del padre flex, margen horizontal 12px).
+
+### 10.14 Accordion
+
+- Contenedor: borde `1px night-600`, radius `lg`, `overflow: hidden`; filas fondo `night-900` separadas por borde `1px night-800`.
+- Header: botón full-width, padding `16px 20px`, texto 16px peso 500 `night-100`, hover fondo `night-800` (150ms); chevron 18px `night-300` rota 180° al abrir (250ms). `aria-expanded`.
+- Panel: `grid-template-rows` 0fr→1fr 250ms ease-out + fade; contenido padding `0 20px 18px`, 15px/1.6 `night-300`.
+- Soporta apertura múltiple (`multiple`) y abiertos por defecto (`defaultOpen`).
+
+### 10.15 Tooltip
+
+Fondo `night-700`, borde `night-600`, texto `night-100` `text-xs`, padding `6px 10px`, radius `sm`. Delay 400ms, fade + translateY(4px→0) 150ms.
+
+**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** (a diferencia del Toast, transitorio): errores de formulario, avisos de plan.
+
+- 4 tonos: fondo suave semántico (`*-bg`, ej. `info-bg` `#0d1f2c`), borde `1px` del tono al 30%, radius `md`, padding 14px 16px.
+- Icono semántico 20px en el color del tono: info→`info` · success→`circle-check` · warning→`triangle-alert` · danger→`circle-alert`.
+- Título `text-sm` semibold y cuerpo `text-sm`, ambos en el color del tono (cuerpo con opacidad 88%).
+- Botón cerrar opcional (× 18px, hit-área 36px) vía `onDismiss`; hover fondo `currentColor` al 14%. `role="status"`.
+
+### 10.17 Toast
+
+- Top-right (desktop), top-center (móvil). Ancho 360px.
+- 4 tonos: `success` · `info` · `warning` · `danger` — cada uno colorea el borde izquierdo y el icono.
+- Fondo `night-800`, borde `night-600`, borde izquierdo 3px semántico, sombra nivel 3, radius `md`, padding 14px 16px.
+- Entrada: slide-in + fade 250ms. Salida: fade + translateX 200ms.
+- Auto-dismiss 5s (pausable con hover). Máximo 3 apilados, gap 12px.
+- **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).
+
+- Track: altura 6px, fondo `night-700`, radius full, `overflow: hidden`.
+- Relleno: `accent-400` con glow `0 0 12px rgba(82,186,237,.5)` (desactivable), transición width 300ms ease-out.
+- Indeterminado: segmento del 40% que barre en loop 1.2s ease-out.
+- Cabecera opcional: label 14px `night-200` + valor `%` en mono 14px `accent-400` `tabular-nums`, margen inferior 8px.
+- Accesibilidad: `role="progressbar"` + `aria-valuenow/min/max` (sin `valuenow` en indeterminado).
+- **ProgressRing:** SVG rotado -90°, track `night-700`, arco `accent-400` con `stroke-linecap: round`, `stroke-dashoffset` anima 250ms ease-out (respeta `prefers-reduced-motion`); tamaño 56px, stroke 5px; porcentaje centrado en mono `accent-400` `text-sm` semibold. Mismo `role="progressbar"` + `aria-valuenow`.
+
+### 10.19 Modal
+
+- Overlay: `--overlay` + `backdrop-filter: blur(4px)`, fade 200ms.
+- Panel: fondo `night-800`, borde `night-600`, radius `lg`, sombra nivel 3, max-width 480/640px, padding 24px.
+- Entrada: fade + scale(0.96→1) 250ms. Salida 180ms.
+- Header `text-xl` + IconButton cerrar; footer con primaria al extremo derecho.
+- Esc y click en overlay cierran (excepto flujos destructivos).
+- `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, botón "más", menú de cuenta) — mismo patrón visual que el menú de `Select`, pero se abre desde cualquier trigger.
+
+- Panel: fondo `night-800`, borde `1px night-600`, radius `md`, sombra nivel 3, padding 6px, min-width 190px, max-height 320px (`overflow: auto`).
+- Ítem: `role="menuitem"`, padding `10px 12px`, radius `sm`, `text-sm` `night-100`, icono opcional 16px `night-300`, gap 10px; hover fondo `night-700`.
+- Ítem seleccionado: fondo `--accent-selected` + texto `accent-300` (`--link` en modo claro).
+- Entrada: fade + translateY(-4px→0), 180ms. Cierra con click fuera, Esc o al seleccionar.
+
+### 10.21 Tabla
+
+- Header: fondo `night-900`, `text-xs` uppercase `+0.08em` `night-300`, borde inferior `night-600`.
+- Filas: altura 52px, borde inferior `night-800`, hover fondo `night-700`.
+- Numéricos a la derecha con `tabular-nums`.
+- Fila seleccionada: fondo `--accent-selected` + borde izquierdo 2px `accent-400`.
+
+### 10.22 Stat
+
+- **Label** overline arriba: 12px, peso 500, uppercase, tracking `+0.08em`, `night-300`.
+- **Cifra:** JetBrains Mono 49px peso 500, line-height 1.05, color `accent-400`, `tabular-nums`, `white-space: nowrap`.
+- **Delta** opcional debajo: mono 14px — `success-400` / `danger-400` / `night-300` (neutral).
+- Gap vertical 6px. Formato numérico `es-ES`.
+- **Count-up** 600ms ease-out al montar; con `prefers-reduced-motion` muestra el valor directo.
+
+### 10.23 Pagination
+
+Navegador de páginas 1-indexado, bajo tablas y listas largas.
+
+- Flechas prev/next (chevron 16px) + lista de páginas que **trunca con elipsis a partir de 7 páginas**.
+- Celdas: min-width 36px, altura 36px, radius `sm`, `text-sm` peso 500 `night-200`; hover fondo `night-800`.
+- Página activa: fondo `accent-400`, texto `night-950` (`text-on-accent`) peso 700 — no depende solo del color —, `aria-current="page"`.
+- Flechas/celdas disabled: texto `night-400`, `cursor: not-allowed`; elipsis no clicable.
+
+### 10.24 Navegación
+
+- **Navbar:** altura 64px, fondo `night-950/80%` + `backdrop-filter: blur(12px)`, borde inferior `night-600`. Link activo: texto `accent-400` + indicador inferior 2px.
+- **Sidebar:** ancho 260px, fondo `night-900`. Ítem: radius `md`, padding `10px 12px`; activo: fondo `indigo-800`, texto `night-50`, icono `accent-400`.
+- **Tabs:** borde inferior `night-600`; indicador 2px `accent-400` que se desliza (250ms).
+- **Breadcrumbs:** `text-sm` `night-300`, separador `/` (tipográfico), último ítem `night-100`.
+
+### 10.25 Skeleton y EmptyState
+
+- Skeleton: fondo `night-800` con shimmer (gradiente hacia `night-700`, barre en 1.4s loop). Radius igual al contenido.
+- Estado vacío: icono en `indigo-400`, título `text-lg` `night-100`, descripción `text-sm` `night-300`, CTA claro. Un estado vacío siempre invita a actuar.
+
+### 10.26 Card, Link y Code
+
+- **Card:** fondo `night-900`, borde `1px night-600`, radius `lg`, padding 24px (16px en móvil), sombra nivel 1.
+- **Card interactiva:** cursor pointer; hover eleva — `translateY(-2px)` + fondo `night-800` + sombra nivel 2; transición de fondo/transform/sombra 220ms ease-out.
+- **Card con glow:** firma de marca (`--glow-accent`) — **máximo una por pantalla**.
+- **Link:** color `accent-400`; hover `accent-200` (150ms). Subrayado animado: línea 1px `currentColor` a -2px, `scaleX(0)→scaleX(1)` desde la izquierda, 200ms ease-out. Externo: `target="_blank" rel="noopener noreferrer"` + icono flecha 12px, gap 4px.
+- **Code (inline):** JetBrains Mono `0.9em`, texto `accent-300`, fondo `night-800`, borde `1px night-700`, radius 6px, padding `1px 6px`.
+
+---
+
+## 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;  /* press, toggle */
+  --duration-fast: 150ms;     /* hover, focus, color */
+  --duration-base: 220ms;     /* dropdowns, tooltips, switches */
+  --duration-slow: 250ms;     /* modales, toasts */
+  --duration-page: 350ms;     /* transiciones de página/vista */
+
+  --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);
+}
+```
+
+### 11.2 Principios de movimiento
+
+1. **Entra rápido, sale más rápido** — Salida ~20% más corta que la entrada.
+2. **Solo `transform` y `opacity`** — Nunca animar propiedades de layout.
+3. **Distancias cortas** — Entradas de 4–8px.
+4. **Stagger en listas** — 30ms por ítem, máximo 6 ítems.
+5. **Firma de marca:** los elementos con acento entran con fade + glow (opacidad del glow 0→1 en 220ms). Usar solo en el elemento hero/CTA.
+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 primario | hover | color 150ms + glow suave fade-in |
+| Botón | press | `scale(0.98)` 100ms |
+| Link | hover | color a `accent-200` 150ms + subrayado 0→100% (200ms) |
+| Tarjeta interactiva | hover | `translateY(-2px)` + superficie sube a `night-800`, 200ms |
+| Input | focus | ring fade 150ms |
+| Checkbox | check | trazo dibujándose 200ms `ease-spring` |
+| Toggle | cambio | thumb desliza 200ms `ease-spring` + track cross-fade |
+| Acordeón | abrir | `grid-template-rows` 0fr→1fr 250ms + fade |
+| Tabs (indicador) | cambio | indicador desliza (transform/width) 250ms `--ease-in-out` |
+| Dropdown | abrir | fade + translateY(-4px→0) 180ms |
+| Modal | abrir | overlay fade+blur 200ms; panel fade + scale(0.96→1) 250ms |
+| Toast | entrar | slide-in + fade 250ms |
+| Icon swap (p. ej. copiar→check) | cambio | cross-fade: opacity + scale(0.9→1), 150ms; nunca blur |
+| Página/vista | cambio | fade + translateY(8px→0) 350ms |
+| Cifra/dato clave | montar | count-up numérico 350ms `ease-out` (solo dashboards; techo `--duration-page`) |
+
+### 11.4 Loading
+
+- Spinner: trazo 2px `accent-400`, rotación 0.8s linear.
+- Barra de progreso: ver §10.18.
+- Skeleton shimmer 1.4s loop.
+- Cargas <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, glow) 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-2); }
+}
+```
+
+### 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. Excepción: navbar (`blur(12px)`, §10.24) y overlay de modal (`blur(4px)`, §10.19) — únicos dos usos de la marca, ninguno más |
+| 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
+
+- `night-100` sobre `night-950`: **≈ 16:1** ✅ AAA.
+- `accent-400` sobre `night-950`: **≈ 8.5:1** ✅ — sirve como texto/link.
+- `night-950` sobre `accent-400` (CTAs): **≈ 8.5:1** ✅ — por eso el texto del CTA es oscuro.
+- `indigo-500` sobre `night-950`: **≈ 1.9:1** ⚠️ — solo fondo/decorativo, nunca texto.
+- `night-50` sobre `indigo-500`: **≈ 9:1** ✅ — texto sobre fondos índigo funciona.
+- Mínimos WCAG AA: 4.5:1 texto normal, 3:1 texto grande y UI.
+- Focus visible siempre (`:focus-visible` global, §6); estado nunca solo con color (color + icono + texto).
+- Touch targets 44×44px.
+- IconButton siempre con `aria-label`; ProgressBar con `role="progressbar"`; Accordion con `aria-expanded`.
+
+---
+
+## 13. Tokens CSS consolidados
+
+```css
+:root {
+  /* == Primitivos: acento == */
+  --accent-100: #d9f0fb; --accent-200: #a8ddf6; --accent-300: #7dccf1;
+  --accent-400: #52baed; --accent-500: #2fa3dd; --accent-600: #1f87bb; --accent-700: #186a94;
+
+  /* == Primitivos: índigo == */
+  --indigo-300: #7a83c4; --indigo-400: #565fa3; --indigo-500: #353d7c;
+  --indigo-600: #2b3264; --indigo-700: #22284f; --indigo-800: #1a1e3b;
+
+  /* == Primitivos: escala nocturna == */
+  --night-950: #010203; --night-900: #0b0d12; --night-800: #14171f;
+  --night-700: #1e222d; --night-600: #2a2f3d; --night-500: #3d4354;
+  --night-400: #6b7183; --night-300: #9aa0b0; --night-200: #c5c9d4;
+  --night-100: #e8eaef; --night-50: #f6f7f9;
+
+  /* == Primitivos: semánticos == */
+  --success-400: #4ade80; --success-bg: #0a2617;
+  --warning-400: #fbbf24; --warning-bg: #2a2005;
+  --danger-400: #f87171;  --danger-bg: #2c0f0f;
+  --info-400: #52baed;    --info-bg: #0d1f2c;
+
+  /* == Aliases semánticos (los componentes consumen SOLO esto) == */
+  --bg: var(--night-950);
+  --surface-1: var(--night-900); --surface-2: var(--night-800); --surface-3: var(--night-700);
+  --border: var(--night-500); --border-strong: var(--night-600);
+  --text-primary: var(--night-100); --text-secondary: var(--night-200);
+  --text-muted: var(--night-300); --text-disabled: var(--night-400);
+  --text-heading: var(--night-50); --text-on-accent: var(--night-950);
+  --success: var(--success-400); --warning: var(--warning-400);
+  --danger: var(--danger-400); --info: var(--info-400);
+  --accent-ghost-hover: rgba(82,186,237,.08);
+  --accent-ghost-active: rgba(82,186,237,.14);
+  --accent-selected: rgba(82,186,237,.12);
+  --overlay: rgba(1,2,3,.7);
+
+  /* == Tipografía == */
+  --font-display: "Space Grotesk", system-ui, sans-serif;
+  --font-body: "Manrope", system-ui, sans-serif;
+  --font-mono: "JetBrains Mono", 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-tight: 1.05; --leading-heading: 1.15; --leading-h2: 1.2;
+  --leading-h3: 1.3; --leading-h4: 1.4; --leading-snug: 1.5; --leading-body: 1.6;
+  --tracking-display: -0.02em; --tracking-overline: 0.08em;
+  --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: 24px; --card-padding-mobile: 16px;
+  --section-gap: 64px; --form-gap: 20px;
+  --button-padding: 12px 20px; --touch-target: 44px;
+  --grid-gutter: 24px; --grid-gutter-mobile: 16px;
+
+  /* == Radios y bordes == */
+  --radius-sm: 8px; --radius-md: 12px; --radius-lg: 16px;
+  --radius-xl: 24px; --radius-full: 9999px;
+  --border-default: 1px solid var(--night-500);
+  --border-emphasis: 1px solid var(--night-600);
+  --focus-ring: 2px solid var(--accent-400);
+  --focus-ring-offset: 2px;
+
+  /* == Elevación == */
+  --shadow-1: 0 1px 2px rgba(0,0,0,.4);
+  --shadow-2: 0 4px 12px rgba(0,0,0,.5);
+  --shadow-3: 0 12px 32px rgba(0,0,0,.6);
+  --glow-accent: 0 0 0 1px rgba(82,186,237,.35), 0 4px 20px rgba(82,186,237,.18);
+  --ring: 0 0 0 3px rgba(82,186,237,.2);
+  --ring-danger: 0 0 0 3px rgba(248,113,113,.2);
+
+  /* == Motion == */
+  --duration-instant: 100ms; --duration-fast: 150ms; --duration-base: 220ms;
+  --duration-slow: 250ms; --duration-page: 350ms;
+  --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: dark;
+}
+```
+
+Estilos base de elementos (extracto de `base.css`): body con `--bg`/`--text-primary`/`--font-body`/`--leading-body` + antialiasing; **h1–h3 en `--font-display`** color `--text-heading`; **h4 en `--font-body`**; `p { max-width: var(--measure) }`; links `accent-400`→hover `accent-200`.
+
+---
+
+## 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.
+
+**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 claro (variante)
+
+El sistema es **dark-first**, pero todo producto debe soportar light mode con los mismos tokens semánticos. La energía de la marca se conserva; solo se invierte el escenario.
+
+### 15.1 Filosofía de la inversión
+
+- Los fondos claros se tiñen levemente de azul (derivados del acento), nunca gris genérico ni blanco plano en toda la pantalla.
+- El celeste `#52baed` sobre blanco tiene contraste bajo (≈ 2.2:1): **no puede ser texto ni link en light**. Los links y textos de acción bajan a `accent-600 (#1f87bb)` y `accent-700 (#186a94)`.
+- El CTA conserva la firma de marca: **fondo `#52baed` con texto `#010203`** funciona igual sobre claro (contraste ≈ 8.5:1) — el botón se ve idéntico en ambos modos.
+- El índigo `#353d7c` gana protagonismo en light: aquí **sí** funciona como texto, headings de marca y fondos de sección con texto blanco.
+
+### 15.2 Mapeo de tokens
+
+| Token semántico | Dark | Light |
+|---|---|---|
+| `--bg` | `#010203` | `#f5f8fb` |
+| `--surface-1` | `#0b0d12` | `#ffffff` |
+| `--surface-2` | `#14171f` | `#ffffff` |
+| `--surface-3` | `#1e222d` | `#eaf1f7` |
+| `--border` | `#3d4354` | `#d8dfe8` |
+| `--border-strong` | `#2a2f3d` | `#b9c3d1` |
+| `--text-primary` | `#e8eaef` | `#14171f` |
+| `--text-secondary` | `#c5c9d4` | `#3d4354` |
+| `--text-muted` | `#9aa0b0` | `#6b7183` |
+| `--link` / texto de acción | `#52baed` | `#1f87bb` |
+| `--link-hover` | `#a8ddf6` | `#186a94` |
+| CTA primario (fondo/texto) | `#52baed` / `#010203` | `#52baed` / `#010203` (sin cambio) |
+| Secundario índigo | `#353d7c` fondo | `#353d7c` fondo, texto blanco |
+| `--success` | `#4ade80` | `#15803d` |
+| `--warning` | `#fbbf24` | `#a16207` |
+| `--danger` | `#f87171` | `#c03535` |
+| `--ring` | `rgba(82,186,237,.2)` | `rgba(31,135,187,.25)` |
+
+Fondos suaves semánticos en light: `success #e3f5ea` · `warning #fbf3dd` · `danger #fbe7e7` · `info #e3f2fb`.
+
+### 15.3 Elevación en light
+
+Vuelven las sombras clásicas (teñidas de índigo, no negro puro); las superficies dejan de aclararse por nivel:
+
+| Nivel | Superficie | Sombra |
+|---|---|---|
+| 0 | `#f5f8fb` | — |
+| 1 | `#ffffff` | `0 1px 3px rgba(53,61,124,.08)` |
+| 2 | `#ffffff` | `0 4px 10px rgba(53,61,124,.10)` |
+| 3 | `#ffffff` | `0 12px 28px rgba(53,61,124,.14)` |
+
+El glow de acento se mantiene como firma, pero más tenue: `0 0 0 1px rgba(82,186,237,.4), 0 4px 16px rgba(82,186,237,.25)` — solo en el CTA hero.
+
+### 15.4 Ajustes de componentes en light
+
+- **Botón primario:** idéntico al dark (fondo `#52baed`, texto `#010203`) — consistencia de marca entre modos.
+- **Botón secundario:** fondo `#353d7c`, texto blanco (contraste ≈ 9:1 ✅).
+- **Outline/Ghost:** borde `#b9c3d1`, texto `#14171f`; ghost con texto `#1f87bb` y hover `rgba(31,135,187,.08)`.
+- **Inputs:** fondo blanco, borde `#d8dfe8`; focus borde `#1f87bb` + ring.
+- **Tabla:** header `#eaf1f7`, hover de fila `#f5f8fb`, seleccionada `rgba(82,186,237,.12)` + borde izquierdo `#1f87bb`.
+- **Navbar:** blanco 80% + blur, borde inferior `#d8dfe8`; link activo `#186a94`.
+- **Sidebar activo:** fondo `#e3f2fb`, texto `#14171f`, icono `#1f87bb`.
+- **Tooltip:** fondo `#14171f`, texto `#f6f7f9` (se invierte).
+- **Toast:** fondo blanco, borde `#d8dfe8`, borde izquierdo semántico.
+- **Overlay de modal:** `rgba(20,23,31,.45)` + blur 4px.
+- **Skeleton:** base `#eaf1f7`, shimmer hacia `#f5f8fb`.
+- **Count-up y motion:** sin cambios; el glow de entrada baja su opacidad máxima a 0.6.
+
+### 15.5 Contraste en light
+
+- `#14171f` sobre `#f5f8fb`: ≈ 16:1 ✅ AAA.
+- `#1f87bb` sobre blanco: ≈ 4.5:1 ✅ AA — link/texto de acción válido.
+- `#52baed` sobre blanco: ≈ 2.2:1 ❌ — **solo relleno decorativo o fondo de CTA con texto oscuro**.
+- Blanco sobre `#353d7c`: ≈ 9:1 ✅ AAA.
+
+### 15.6 Implementación
+
+```css
+[data-theme="light"] {
+  --bg: #f5f8fb;
+  --surface-1: #ffffff;
+  --surface-2: #ffffff;
+  --surface-3: #eaf1f7;
+  --border: #d8dfe8;
+  --border-strong: #b9c3d1;
+  --text-primary: #14171f;
+  --text-secondary: #3d4354;
+  --text-muted: #6b7183;
+  --link: #1f87bb;
+  --link-hover: #186a94;
+  --text-on-accent: #010203; /* CTA no cambia */
+  --success: #15803d;
+  --warning: #a16207;
+  --danger: #c03535;
+  --ring: 0 0 0 3px rgba(31,135,187,.25);
+  --shadow-1: 0 1px 3px rgba(53,61,124,.08);
+  --shadow-2: 0 4px 10px rgba(53,61,124,.10);
+  --shadow-3: 0 12px 28px rgba(53,61,124,.14);
+  --glow-accent: 0 0 0 1px rgba(82,186,237,.4), 0 4px 16px rgba(82,186,237,.25);
+  color-scheme: light;
+}
+```
+
+---
+
+## 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-nocturna-electrica.md` | Fuente de verdad legible |
+| **Style guide interactivo** | `nocturna-electrica.html` | Referencia visual siempre disponible (abrir en navegador) |
+| **Tokens CSS** | `dist/nocturna-electrica/tokens.css` | Drop-in para cualquier proyecto (vanilla, React, Angular, Vue) |
+| **Tailwind v4** | `dist/nocturna-electrica/tailwind.css` | Bloque `@theme` — genera utilidades `bg-night-900`, `text-accent-400`, etc. |
+| **DTCG JSON** | `dist/nocturna-electrica/tokens.json` | Formato estándar W3C DTCG 2025.10 — interoperable con Figma/Tokens Studio/Style Dictionary |
+| **Skill de Claude** | `~/.claude/skills/nocturna-electrica-design/` | Invocable desde cualquier sesión de Claude Code |
+| **Proyecto claude.ai/design** | [Nocturna Eléctrica Design System](https://claude.ai/design/p/1a3a2fb6-b02c-481c-96fc-017d50ec9ce7) | Componentes React + specimens |
+
+**Cómo consumirlo en un proyecto nuevo:**
+
+1. Copiar `dist/nocturna-electrica/tokens.css` e importarlo antes que cualquier estilo propio, **o** pegar el bloque `@theme` en el CSS de Tailwind v4.
+2. Los componentes consumen solo aliases semánticos (§3.5) — nunca hex.
+3. Para dark/light: alternar `data-theme` en `<html>`; los tokens hacen el resto.
+4. En el `<head>`: `<meta name="theme-color" content="#010203">` (el `--bg` nocturno) — sin él, la barra del navegador queda clara sobre la app oscura. Con el tema claro activo, actualizarlo a `#f5f8fb`.