Reordenando ficheros y subida de documentacion

2026-05-27 10:27:27 +02:00
parent 6388fcaba1
commit a9ad2d7e31
52 changed files with 4707 additions and 79 deletions
--- a/design/design-system.md
+++ b/design/design-system.md
@@ -0,0 +1,486 @@
+# Reformix — Design System
+
+**Fecha:** 24-may-2026
+**Fuente:** [specs.md](../specs.md) + [copy/COPY-GUIDE.md](../copy/COPY-GUIDE.md) + [negocio/modelo-negocio.md](../negocio/modelo-negocio.md)
+**Stack:** Next.js 14 + Tailwind + shadcn/ui
+
+> **Filosofía:** Cada decisión visual aquí tiene traducción directa a token de código en `design-tokens.css` y `tailwind.config.ext.js`. Si un color no está en los tokens, no existe. Si un espaciado no está en la escala, no se usa.
+
+---
+
+## 1. Contexto y personalidad de marca
+
+### Proyecto
+
+**Reformix** — *"Un mercado de reformas más justo. Para los profesionales que cumplen lo que prometen."*
+
+SaaS B2B para empresas pequeñas de reformas en España, con captación de leads del cliente final a través de agente IA de voz + render + presupuesto entregado por WhatsApp.
+
+### Audiencias visuales
+
+| Audiencia | Perfil | Implicación visual |
+|---|---|---|
+| **Reformista** (paga el SaaS) | Hombre 35-55, técnico de obra, perfil tech medio-bajo, usa WhatsApp, no le impresiona el diseño chulo, le impresiona la utilidad clara | Cero hipsterismo, claridad brutal, jerarquía evidente, datos sobre estilo |
+| **Cliente final** (usa el widget) | Hombre/mujer 30-65, propietario de vivienda, dispuesto a invertir 10-50 K€, tiene miedo de equivocarse | Tranquilizador, tipográficamente legible, tonos cálidos que no asusten, evitar agresividad visual |
+
+### Personalidad de marca
+
+| Eje | Valor | Por qué |
+|---|---|---|
+| **Adjetivo 1** | **Profesional** | Es una herramienta de trabajo, no de juego. Los reformistas dependen de su credibilidad. |
+| **Adjetivo 2** | **Cercano** | El producto compite con marketplaces fríos (Habitissimo) y CRMs aburridos. La cercanía es diferencial. |
+| **Adjetivo 3** | **Honesto** | El sector está "deshonesto" según la entrevista. Posicionarnos como árbitros justos exige una estética que respalde eso. |
+| **NO somos** | **Corporativo frío · spammy · hipster techie** | Nada de azul corporativo genérico. Nada de "next-gen AI-powered platform". Nada de Comic Sans irónico ni gradientes psicodélicos. |
+
+### Referencias visuales
+
+- **Linear** — rigor tipográfico, jerarquía clara, dark mode sólido.
+- **Notion** — calidez, accesibilidad, espacios generosos.
+- **Stripe** — profesionalidad sin frialdad, tipografía con carácter.
+- **Holded** (referencia española B2B) — confiable, claro, no innovador agresivo.
+
+**NO referencia:** Habitissimo, Wallapop, idealista (demasiado marketplace/portal); cualquier "AI startup template" de Vercel; landings con animaciones 3D innecesarias.
+
+---
+
+## 2. Identidad verbal
+
+> Reglas detalladas en [copy/COPY-GUIDE.md](../copy/COPY-GUIDE.md). Resumen aquí para alinear con visual.
+
+### Tono
+
+- **Tuteo** universal. Reformista y cliente final.
+- **Frases cortas**, 2-3 líneas máximo por párrafo.
+- **Honestidad explícita** sobre limitaciones: *"Es orientativo. Tu visita sigue siendo la que cierra."*
+- **Lenguaje del sector** cuando aplique: showrooming, calidad básica/media/premium, ticket medio.
+- **Sin jerga corporativa**: no "optimizar pipeline", no "next-gen", no "transformación digital".
+
+### Naming
+
+- **Producto:** Reformix (sin tilde, sin guión, una palabra).
+- **Producto interno:** *Asistente IA* (cara visible del agente de voz) en vez de "voicebot" o "agente conversacional".
+- **Métricas internas para reformista:** *Leads cualificados* (no "captados" ni "prospects"), *Visita gratuita*, *Presupuesto orientativo* (no "presupuesto").
+- **Planes:** Starter / Pro / Business (estándar SaaS).
+- **Sello futuro:** *Precio Justo Certificado* (sin "®" ni tipo corporativo). Mayúscula inicial siempre.
+
+---
+
+## 3. Color
+
+### 3.1 Paleta primaria — "Architectural Warmth"
+
+Decisión: rechazamos el azul SaaS genérico. Adoptamos una paleta inspirada en la cerámica y los acabados naturales — habla el lenguaje del sector sin caer en lo rústico.
+
+#### Brand colors
+
+| Token | Hex | Uso | Justificación |
+|---|---|---|---|
+| `--color-primary-900` | `#1F3A2E` | Texto en superficies claras, headings | Verde bosque oscuro: serio, sólido, asociado a "natural" sin ser ecológico panfletario |
+| `--color-primary-700` | `#2F5C46` | Botones primarios, links activos | Verde oliva profundo: profesional, transmite "experiencia" |
+| `--color-primary-500` | `#4D8A6D` | Acento medio, hover de botones | |
+| `--color-primary-300` | `#A8C8B5` | Backgrounds suaves, badges | |
+| `--color-primary-100` | `#E8F0EB` | Backgrounds muy suaves, hover states | |
+| `--color-primary-50` | `#F4F8F5` | Background de sección destacada | |
+
+#### Accent (terracota)
+
+| Token | Hex | Uso |
+|---|---|---|
+| `--color-accent-900` | `#7A3517` | Énfasis muy fuerte (rara vez) |
+| `--color-accent-600` | `#C25E33` | CTAs secundarios destacados, alertas no críticas, highlights |
+| `--color-accent-400` | `#E08A5F` | Iconos decorativos, badges |
+| `--color-accent-100` | `#FAEAE0` | Background de bloques destacados |
+
+> El terracota se usa con **moderación**: el CTA principal es verde oliva (primary-700), el terracota es para llamar la atención sobre un solo elemento en cada vista.
+
+### 3.2 Neutrales (Stone — warm gray con tinte oliva)
+
+| Token | Hex | Uso |
+|---|---|---|
+| `--color-neutral-950` | `#161816` | Texto sobre fondo blanco — el negro más cálido |
+| `--color-neutral-900` | `#262826` | Headings sobre fondo claro |
+| `--color-neutral-700` | `#4A4E4A` | Texto body principal |
+| `--color-neutral-500` | `#7A807A` | Texto secundario, placeholders |
+| `--color-neutral-400` | `#9DA29D` | Texto disabled, separadores |
+| `--color-neutral-300` | `#C4C9C4` | Bordes |
+| `--color-neutral-200` | `#DDE0DD` | Bordes suaves, líneas divisorias |
+| `--color-neutral-100` | `#EDEFED` | Backgrounds muy suaves, cards alternas |
+| `--color-neutral-50` | `#F7F8F7` | Background secundario |
+| `--color-white` | `#FFFFFF` | Background principal, surfaces |
+
+### 3.3 Escala semántica
+
+| Token | Hex | Uso |
+|---|---|---|
+| `--color-success-700` | `#2D7A4F` | Texto de success en badges |
+| `--color-success-500` | `#4DAA73` | Iconos de success, bordes |
+| `--color-success-100` | `#E0F0E6` | Background de mensajes de success |
+| `--color-warning-700` | `#9A6B0E` | Texto warning |
+| `--color-warning-500` | `#DA9A2C` | Iconos warning |
+| `--color-warning-100` | `#FAEFD3` | Background warning (banner licencia urbanística) |
+| `--color-danger-700` | `#A8331F` | Texto error |
+| `--color-danger-500` | `#D85940` | Iconos error |
+| `--color-danger-100` | `#FAE0DA` | Background error |
+| `--color-info-700` | `#1F5C7A` | Texto info |
+| `--color-info-500` | `#3D8AAA` | Iconos info |
+| `--color-info-100` | `#DDEDF5` | Background info |
+
+### 3.4 Surfaces y combinaciones validadas (WCAG AA)
+
+| Combinación | Contraste | OK |
+|---|---|---|
+| `neutral-950` sobre `white` | 16.5:1 | ✅ AAA |
+| `neutral-700` sobre `white` | 7.8:1 | ✅ AAA |
+| `neutral-500` sobre `white` | 4.6:1 | ✅ AA |
+| `white` sobre `primary-700` | 7.2:1 | ✅ AAA — botón primario |
+| `white` sobre `accent-600` | 4.8:1 | ✅ AA — botón terracota |
+| `primary-900` sobre `primary-50` | 12.4:1 | ✅ AAA — texto en bloques destacados |
+| `danger-700` sobre `danger-100` | 6.1:1 | ✅ AA — mensajes de error |
+
+> **Regla:** ningún texto debe usar `neutral-400` o más claro sobre fondo blanco (no pasa AA).
+
+---
+
+## 4. Tipografía
+
+### 4.1 Selección
+
+| Rol | Fuente | Por qué |
+|---|---|---|
+| **Display + Headings (H1, H2)** | **Instrument Serif** (Google Fonts) | Serif moderna con carácter. Da "peso editorial" que diferencia frente al SaaS-Inter genérico. Suena profesional sin ser corporativo. Pesa muy poco. |
+| **Sub-headings (H3, H4, H5)** | **Inter** | Misma familia que el body para coherencia. Semibold da jerarquía sin cambio de fuente. |
+| **Body + UI** | **Inter** | Estándar de legibilidad universal. Funciona en móvil. La conocen todos los devs. |
+| **Mono (rara vez — código, ID, datos técnicos)** | **JetBrains Mono** | Estándar dev-friendly. Solo para panel de leads y debug. |
+
+> **Decisión consciente:** evitar fuentes "techie" tipo Geist o IBM Plex. Inter es boring pero universal, y Instrument Serif aporta el carácter sin pedir permiso.
+
+### 4.2 Escala tipográfica (modular ratio 1.25 — Major Third)
+
+| Token | Tamaño | Line-height | Uso típico |
+|---|---|---|---|
+| `text-xs` | 12px / 0.75rem | 1.5 | Captions, footnotes, badges |
+| `text-sm` | 14px / 0.875rem | 1.5 | Labels de form, secondary text, helper |
+| `text-base` | 16px / 1rem | 1.6 | **Body por defecto** (mínimo legible móvil) |
+| `text-lg` | 18px / 1.125rem | 1.5 | Body grande, intros, microcopy hero |
+| `text-xl` | 20px / 1.25rem | 1.4 | H5, subhead pequeño |
+| `text-2xl` | 24px / 1.5rem | 1.3 | H4 |
+| `text-3xl` | 30px / 1.875rem | 1.3 | H3 |
+| `text-4xl` | 36px / 2.25rem | 1.2 | H2 |
+| `text-5xl` | 48px / 3rem | 1.1 | H1 mobile, headings de sección |
+| `text-6xl` | 60px / 3.75rem | 1.05 | H1 desktop, hero |
+| `text-7xl` | 72px / 4.5rem | 1.0 | Display hero desktop (raro) |
+
+### 4.3 Pesos cargados
+
+| Familia | Pesos | Justificación |
+|---|---|---|
+| Instrument Serif | 400 (regular), 400 italic | Diseñada para una sola weight, pero italic da énfasis en titulares |
+| Inter | 400, 500, 600, 700 | Regular body, medium labels, semibold botones y H3-H5, bold solo para énfasis fuerte |
+| JetBrains Mono | 400, 500 | Muy poco uso |
+
+### 4.4 Reglas de uso
+
+- **H1 hero (desktop):** Instrument Serif, `text-6xl`, regular. Sin negrita.
+- **H1 hero (mobile):** Instrument Serif, `text-5xl`, regular.
+- **H2 sección:** Instrument Serif, `text-4xl`, regular.
+- **H3-H5:** Inter Semibold, `text-3xl` / `text-2xl` / `text-xl`.
+- **Body por defecto:** Inter Regular, `text-base`, line-height 1.6, color `neutral-700`.
+- **Labels de form:** Inter Medium, `text-sm`, color `neutral-900`.
+- **Botones:** Inter Semibold, `text-base` (md) / `text-sm` (sm) / `text-lg` (lg).
+- **Captions y helper text:** Inter Regular, `text-sm`, color `neutral-500`.
+
+---
+
+## 5. Espaciado y layout
+
+### 5.1 Escala de espaciado (base 4px — coherente con Tailwind)
+
+| Token | Valor | Uso típico |
+|---|---|---|
+| `space-1` | 4px / 0.25rem | Gaps mínimos entre iconos y texto |
+| `space-2` | 8px / 0.5rem | Padding interno compacto (badges, pills) |
+| `space-3` | 12px / 0.75rem | Gap entre elementos relacionados |
+| `space-4` | 16px / 1rem | Padding estándar de inputs y cards pequeños |
+| `space-6` | 24px / 1.5rem | Separación entre bloques de un mismo grupo |
+| `space-8` | 32px / 2rem | Padding de cards grandes, márgenes de sección móvil |
+| `space-12` | 48px / 3rem | Separación entre secciones móvil |
+| `space-16` | 64px / 4rem | Separación entre secciones desktop |
+| `space-24` | 96px / 6rem | Padding vertical del hero |
+| `space-32` | 128px / 8rem | Separación generosa entre bloques desktop grandes |
+
+### 5.2 Contenedores y grid
+
+| Token | Valor | Uso |
+|---|---|---|
+| `container-narrow` | 720px | Bloques de lectura largos (FAQ, T&C) |
+| `container-default` | 1200px | Landings, app general |
+| `container-wide` | 1440px | Panel del reformista con muchas columnas |
+| `gutter-mobile` | 24px | Padding lateral móvil |
+| `gutter-desktop` | 48px | Padding lateral desktop |
+
+### 5.3 Breakpoints (Tailwind defaults)
+
+| Token | Valor | Dispositivo |
+|---|---|---|
+| `sm` | 640px | Móvil grande / phablet |
+| `md` | 768px | Tablet portrait |
+| `lg` | 1024px | Tablet landscape / desktop pequeño |
+| `xl` | 1280px | Desktop estándar |
+| `2xl` | 1536px | Desktop grande |
+
+---
+
+## 6. Componentes base
+
+### 6.1 Border radius
+
+| Token | Valor | Uso |
+|---|---|---|
+| `rounded-sm` | 4px | Tags, badges pequeños |
+| `rounded-md` | 6px | Inputs, controles pequeños |
+| `rounded-lg` | 10px | Botones, cards, contenedores |
+| `rounded-xl` | 14px | Cards destacadas, hero blocks |
+| `rounded-2xl` | 20px | Modales, popovers grandes |
+| `rounded-full` | 9999px | Avatares, pills de estado, iconos circulares |
+
+> **Personalidad:** redondeado generoso (10-14px en cards) — friendly, moderno, pero no infantil (evitamos 24px+ en bloques que no sean decorativos).
+
+### 6.2 Sombras (warm, sutiles)
+
+| Token | Valor | Uso |
+|---|---|---|
+| `shadow-xs` | `0 1px 2px rgba(22, 24, 22, 0.05)` | Bordes muy sutiles, divisores elevados |
+| `shadow-sm` | `0 1px 3px rgba(22, 24, 22, 0.08), 0 1px 2px rgba(22, 24, 22, 0.04)` | Cards estáticos, inputs |
+| `shadow-md` | `0 4px 6px rgba(22, 24, 22, 0.07), 0 2px 4px rgba(22, 24, 22, 0.04)` | Cards interactivos, hover |
+| `shadow-lg` | `0 10px 15px rgba(22, 24, 22, 0.08), 0 4px 6px rgba(22, 24, 22, 0.05)` | Dropdowns, popovers |
+| `shadow-xl` | `0 20px 25px rgba(22, 24, 22, 0.1), 0 10px 10px rgba(22, 24, 22, 0.04)` | Modales |
+| `shadow-glow` | `0 0 0 4px rgba(47, 92, 70, 0.15)` | Focus ring (primary-700 al 15 %) |
+
+> Sombras con base de `neutral-950` (no negro puro) para coherencia con la paleta cálida.
+
+### 6.3 Botones
+
+| Variante | Background | Texto | Border | Uso |
+|---|---|---|---|---|
+| **Primary** | `primary-700` | `white` | — | CTA principal único por vista. *"Empezar gratis 14 días"*, *"Quiero mi presupuesto"* |
+| **Secondary** | `white` | `primary-700` | `primary-700` 1px | Acciones secundarias. *"Ver demo"* |
+| **Accent** | `accent-600` | `white` | — | Solo para acciones de waitlist o "Próximamente". Máximo 1 por vista. |
+| **Ghost** | `transparent` | `neutral-700` | — | Navegación, acciones de tercer nivel |
+| **Danger** | `danger-500` | `white` | — | Eliminar lead, revocar consentimiento |
+| **Link** | `transparent` | `primary-700` underline | — | Enlaces dentro de texto |
+
+#### Estados
+
+| Estado | Modificación |
+|---|---|
+| Default | Como tabla arriba |
+| Hover | Background −10 % luminosidad / opacity 0.95 |
+| Active | Background −15 % luminosidad / scale-95 |
+| Disabled | Opacity 0.5, cursor not-allowed |
+| Loading | Spinner inline, texto invisible o "Cargando..." |
+| Focus | `shadow-glow` (focus ring 4px al 15 % primary) |
+
+#### Tamaños
+
+| Tamaño | Padding | Font | Height |
+|---|---|---|---|
+| `sm` | `px-3 py-1.5` | `text-sm` semibold | 32px |
+| `md` (default) | `px-4 py-2.5` | `text-base` semibold | 44px |
+| `lg` | `px-6 py-3.5` | `text-lg` semibold | 52px |
+
+### 6.4 Inputs
+
+| Atributo | Valor |
+|---|---|
+| Background | `white` |
+| Border default | `neutral-300` 1px |
+| Border focus | `primary-700` 2px + `shadow-glow` |
+| Border error | `danger-500` 2px |
+| Padding | `px-4 py-2.5` |
+| Border radius | `rounded-md` |
+| Font | `text-base` regular |
+| Color texto | `neutral-900` |
+| Color placeholder | `neutral-500` |
+| Label | `text-sm` medium, `neutral-900`, `mb-1.5` |
+| Helper | `text-sm` regular, `neutral-500`, `mt-1.5` |
+| Error message | `text-sm` regular, `danger-700`, `mt-1.5` |
+
+### 6.5 Cards
+
+| Atributo | Valor |
+|---|---|
+| Background | `white` |
+| Border | `neutral-200` 1px |
+| Border radius | `rounded-xl` (14px) |
+| Padding | `p-6` mobile · `p-8` desktop |
+| Shadow default | `shadow-sm` |
+| Shadow hover (si interactivo) | `shadow-md` + transición 200ms |
+
+### 6.6 Badges y pills (estados de lead)
+
+| Estado | Background | Texto | Icon |
+|---|---|---|---|
+| Nuevo | `primary-100` | `primary-900` | 🆕 |
+| Contactado | `info-100` | `info-700` | 📞 |
+| Visita agendada | `warning-100` | `warning-700` | 📅 |
+| Ganado | `success-100` | `success-700` | ✅ |
+| Perdido | `neutral-100` | `neutral-700` | ❌ |
+
+Estilo: `rounded-full`, `px-2.5 py-0.5`, `text-xs` semibold.
+
+### 6.7 Alerts / banners
+
+| Tipo | Background | Border-left 4px | Texto | Uso |
+|---|---|---|---|---|
+| Info | `info-100` | `info-500` | `info-700` | Banner aviso |
+| Warning | `warning-100` | `warning-500` | `warning-700` | **"Esta obra puede requerir licencia urbanística"** |
+| Success | `success-100` | `success-500` | `success-700` | Confirmación de envío |
+| Danger | `danger-100` | `danger-500` | `danger-700` | Error de submit |
+
+Padding `p-4`, radius `rounded-lg`, icono 20px a la izquierda.
+
+---
+
+## 7. Iconografía
+
+### Librería: **Lucide** (compatible nativamente con shadcn/ui)
+
+- **Tamaño base inline:** 16px (junto a texto inline)
+- **Tamaño base UI:** 20px (botones, alerts, badges)
+- **Tamaño standalone:** 24px (hero, features destacadas)
+- **Stroke width:** 1.75 (Lucide default — equilibrio entre fino y legible)
+- **Color por defecto:** hereda `currentColor` (configurable por contexto)
+
+### Iconos clave del proyecto (recurrentes)
+
+| Concepto | Icono Lucide |
+|---|---|
+| Llamada / agente voz | `Phone`, `PhoneCall`, `Mic` |
+| WhatsApp (custom SVG) | Icono WhatsApp oficial (no en Lucide) |
+| Render / cámara | `Camera`, `ImageIcon` |
+| Presupuesto / factura | `Receipt`, `FileText` |
+| Lead nuevo | `Sparkles` |
+| Visita | `Calendar`, `MapPin` |
+| Licencia urbanística | `BookOpen`, `FileCheck2`, `Building2` |
+| Reformista pro | `HardHat`, `Hammer` |
+| Cliente final | `Home`, `User` |
+| Sello Precio Justo | `BadgeCheck` |
+| Configurador | `Settings2`, `SlidersHorizontal` |
+
+---
+
+## 8. Motion y transiciones
+
+### Duraciones
+
+| Token | Valor | Uso |
+|---|---|---|
+| `duration-fast` | 150ms | Hover, focus, micro-feedback |
+| `duration-base` | 250ms | Transiciones estándar (cards, modales pequeños) |
+| `duration-slow` | 400ms | Aparición de modales grandes, transiciones de sección |
+
+### Easing
+
+| Token | Valor | Uso |
+|---|---|---|
+| `ease-out` | `cubic-bezier(0.16, 1, 0.3, 1)` | Entradas (recomendado por defecto) |
+| `ease-in` | `cubic-bezier(0.7, 0, 0.84, 0)` | Salidas |
+| `ease-in-out` | `cubic-bezier(0.65, 0, 0.35, 1)` | Movimientos en ambos sentidos |
+
+### Qué se anima
+
+- Hover de botones (background)
+- Focus de inputs (ring)
+- Aparición de modales y popovers
+- Cuenta atrás *"Te llamamos en 1:47"* (animación de los dígitos)
+- Pasos del wizard (slide horizontal suave)
+- Aparición del render generado (fade-in + ligero scale-up)
+
+### Qué NO se anima
+
+- Texto de lectura largo
+- Tablas y datos del panel
+- Logos
+- Iconos estáticos
+
+### Reduced motion
+
+Respetar siempre `prefers-reduced-motion`: deshabilitar todas las animaciones excepto fade simples (opacity).
+
+---
+
+## 9. Imagery y fotografía
+
+### Estilo de imagen
+
+- **Fotografías reales** de cocinas y baños como base. Antes/después.
+- **Renders IA** generados por el propio producto en hero y casos de uso.
+- Tonos cálidos, luz natural, no demasiado pulcras (que parezcan casa real, no catálogo IKEA).
+- Evitar stock genérico de "team handshake" o "businessman with laptop".
+
+### Aspect ratios recomendados
+
+- Hero principal: 16:9 desktop, 4:5 mobile
+- Cards de testimonio: 1:1 o 4:5
+- Antes/después: 1:1 con divisoria deslizante
+
+---
+
+## 10. Aplicación a las superficies de specs.md
+
+### Landing B2B (superficie A)
+
+- Hero: H1 Instrument Serif `text-6xl` en `neutral-950`, subtitle `text-xl` Inter en `neutral-700`, CTA primary verde oliva
+- Sección "Lo que está roto hoy": background `neutral-50`, cards con icono terracota + texto neutral
+- Demo del widget: contenedor con `shadow-xl` y `rounded-2xl` para destacarlo
+- Pricing: 3 cards con tier Pro destacada (border `primary-700` 2px + ribbon "Recomendado")
+- "Próximamente": bloque con background `accent-100`, textos `accent-900`, CTA accent-600
+
+### Landing B2C (superficie B)
+
+- Hero con imagen antes/después grande arriba
+- Branding del reformista en header en card propio con `shadow-sm`
+- Form: 3 pasos con progress bar arriba (verde oliva), inputs con `rounded-md` generoso
+- Pantalla de cuenta atrás: dígitos grandes `text-7xl` Instrument Serif, fondo `primary-50`
+
+### Panel reformista (superficie D)
+
+- Sidebar oscuro (`primary-900` background, `primary-100` texto) con logo Reformix arriba
+- Lista de leads tipo tabla con filas hover en `neutral-50`
+- Detalle de lead: card con `shadow-md` mostrando todos los artefactos en tabs
+- Botón "Marcar Ganado" en `success-500`
+- Modal de "precio final firmado" enfocado y con focus trap
+
+---
+
+## 11. Checklist de calidad
+
+- [x] Contraste WCAG AA verificado en todas las combinaciones críticas
+- [x] La escala tipográfica respeta 16px como mínimo legible móvil
+- [x] Cubrimos los 4 estados semánticos (success, warning, danger, info)
+- [x] 10 niveles de neutrales con tinte cálido (no grays fríos genéricos)
+- [x] Escala de espaciado consistente (base 4px, sin valores arbitrarios)
+- [x] Border-radius coherente con personalidad (generoso pero no infantil)
+- [x] Fuentes disponibles en Google Fonts gratis (Instrument Serif + Inter + JetBrains Mono)
+- [x] Tokens con nombre semántico (`primary-700` no `green-medium`)
+- [x] Iconografía con librería elegida (Lucide)
+- [x] Identidad verbal documentada con tono claro y ejemplos
+- [x] Decisiones justificadas con conexión a la personalidad de marca
+- [x] Aplicación a superficies del producto descrita
+
+---
+
+## 12. Archivos asociados
+
+- [`design-tokens.json`](design-tokens.json) — Tokens en formato estándar (importables en Figma Tokens o style-dictionary)
+- [`design-tokens.css`](design-tokens.css) — CSS Custom Properties listas para `:root`
+- [`tailwind.config.ext.js`](tailwind.config.ext.js) — Extensión de la config de Tailwind con los tokens
+
+---
+
+## Próximos pasos
+
+1. **Validación visual rápida** con el equipo (15 min): proyectar la paleta y los 3-4 ejemplos de aplicación. Confirmar que verde-oliva + terracota encaja con la intuición del equipo.
+2. **Generar mockups en Stitch o Figma** usando los tokens y el copy de [COPY-GUIDE.md](../copy/COPY-GUIDE.md) — sin lorem ipsum.
+3. Instalar shadcn/ui con tema custom basado en los tokens, antes de empezar a programar.
+4. Crear un Storybook ligero (post-MVP) con los componentes core para que el equipo no reinvente cada vez.
--- a/design/design-tokens.css
+++ b/design/design-tokens.css
@@ -0,0 +1,221 @@
+/* Reformix — Design Tokens
+ * Generado a partir de design-system.md + design-tokens.json
+ * Stack: Tailwind + shadcn/ui (compatibilidad con CSS custom properties)
+ * Versión: 1.0 (2026-05-24)
+ */
+
+@import url('https://fonts.googleapis.com/css2?family=Instrument+Serif:ital@0;1&family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap');
+
+:root {
+  /* ============================================
+   * COLOR — Brand (Architectural Warmth)
+   * ============================================ */
+
+  /* Primary — Verde oliva */
+  --color-primary-50:  #F4F8F5;
+  --color-primary-100: #E8F0EB;
+  --color-primary-300: #A8C8B5;
+  --color-primary-500: #4D8A6D;
+  --color-primary-700: #2F5C46;
+  --color-primary-900: #1F3A2E;
+
+  /* Accent — Terracota */
+  --color-accent-100: #FAEAE0;
+  --color-accent-400: #E08A5F;
+  --color-accent-600: #C25E33;
+  --color-accent-900: #7A3517;
+
+  /* ============================================
+   * COLOR — Neutral (Stone — warm grays con tinte oliva)
+   * ============================================ */
+
+  --color-white:       #FFFFFF;
+  --color-neutral-50:  #F7F8F7;
+  --color-neutral-100: #EDEFED;
+  --color-neutral-200: #DDE0DD;
+  --color-neutral-300: #C4C9C4;
+  --color-neutral-400: #9DA29D;
+  --color-neutral-500: #7A807A;
+  --color-neutral-700: #4A4E4A;
+  --color-neutral-900: #262826;
+  --color-neutral-950: #161816;
+
+  /* ============================================
+   * COLOR — Semantic
+   * ============================================ */
+
+  --color-success-100: #E0F0E6;
+  --color-success-500: #4DAA73;
+  --color-success-700: #2D7A4F;
+
+  --color-warning-100: #FAEFD3;
+  --color-warning-500: #DA9A2C;
+  --color-warning-700: #9A6B0E;
+
+  --color-danger-100: #FAE0DA;
+  --color-danger-500: #D85940;
+  --color-danger-700: #A8331F;
+
+  --color-info-100: #DDEDF5;
+  --color-info-500: #3D8AAA;
+  --color-info-700: #1F5C7A;
+
+  /* ============================================
+   * COLOR — Surface aliases (uso semántico en componentes)
+   * ============================================ */
+
+  --surface-background:       var(--color-white);
+  --surface-background-muted: var(--color-neutral-50);
+  --surface-background-emphasis: var(--color-primary-50);
+  --surface-foreground:       var(--color-neutral-950);
+  --surface-foreground-muted: var(--color-neutral-500);
+  --surface-border:           var(--color-neutral-200);
+  --surface-border-strong:    var(--color-neutral-300);
+
+  /* ============================================
+   * TYPOGRAPHY
+   * ============================================ */
+
+  --font-display: 'Instrument Serif', Georgia, serif;
+  --font-sans:    'Inter', system-ui, -apple-system, sans-serif;
+  --font-mono:    'JetBrains Mono', ui-monospace, monospace;
+
+  --font-weight-regular:  400;
+  --font-weight-medium:   500;
+  --font-weight-semibold: 600;
+  --font-weight-bold:     700;
+
+  --text-xs:   0.75rem;
+  --text-sm:   0.875rem;
+  --text-base: 1rem;
+  --text-lg:   1.125rem;
+  --text-xl:   1.25rem;
+  --text-2xl:  1.5rem;
+  --text-3xl:  1.875rem;
+  --text-4xl:  2.25rem;
+  --text-5xl:  3rem;
+  --text-6xl:  3.75rem;
+  --text-7xl:  4.5rem;
+
+  --leading-tight:    1.1;
+  --leading-snug:     1.3;
+  --leading-normal:   1.5;
+  --leading-relaxed:  1.6;
+
+  /* ============================================
+   * SPACING (base 4px, coherente con Tailwind)
+   * ============================================ */
+
+  --space-1:  0.25rem;
+  --space-2:  0.5rem;
+  --space-3:  0.75rem;
+  --space-4:  1rem;
+  --space-6:  1.5rem;
+  --space-8:  2rem;
+  --space-12: 3rem;
+  --space-16: 4rem;
+  --space-24: 6rem;
+  --space-32: 8rem;
+
+  /* ============================================
+   * CONTAINER WIDTHS
+   * ============================================ */
+
+  --container-narrow:  720px;
+  --container-default: 1200px;
+  --container-wide:    1440px;
+
+  --gutter-mobile:  24px;
+  --gutter-desktop: 48px;
+
+  /* ============================================
+   * BORDER RADIUS
+   * ============================================ */
+
+  --radius-sm:   4px;
+  --radius-md:   6px;
+  --radius-lg:   10px;
+  --radius-xl:   14px;
+  --radius-2xl:  20px;
+  --radius-full: 9999px;
+
+  /* ============================================
+   * SHADOWS (warm, base neutral-950 — no negro puro)
+   * ============================================ */
+
+  --shadow-xs:   0 1px 2px rgba(22, 24, 22, 0.05);
+  --shadow-sm:   0 1px 3px rgba(22, 24, 22, 0.08), 0 1px 2px rgba(22, 24, 22, 0.04);
+  --shadow-md:   0 4px 6px rgba(22, 24, 22, 0.07), 0 2px 4px rgba(22, 24, 22, 0.04);
+  --shadow-lg:   0 10px 15px rgba(22, 24, 22, 0.08), 0 4px 6px rgba(22, 24, 22, 0.05);
+  --shadow-xl:   0 20px 25px rgba(22, 24, 22, 0.1),  0 10px 10px rgba(22, 24, 22, 0.04);
+  --shadow-glow: 0 0 0 4px rgba(47, 92, 70, 0.15);
+
+  /* ============================================
+   * MOTION
+   * ============================================ */
+
+  --duration-fast: 150ms;
+  --duration-base: 250ms;
+  --duration-slow: 400ms;
+
+  --easing-out:    cubic-bezier(0.16, 1, 0.3, 1);
+  --easing-in:     cubic-bezier(0.7, 0, 0.84, 0);
+  --easing-in-out: cubic-bezier(0.65, 0, 0.35, 1);
+
+  /* ============================================
+   * Z-INDEX scale (orden visual)
+   * ============================================ */
+
+  --z-dropdown: 50;
+  --z-sticky:   100;
+  --z-overlay:  200;
+  --z-modal:    300;
+  --z-popover:  400;
+  --z-toast:    500;
+}
+
+/* ============================================
+ * Base styles
+ * ============================================ */
+
+html {
+  font-family: var(--font-sans);
+  font-size: 16px;
+  color: var(--surface-foreground);
+  background: var(--surface-background);
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+body {
+  line-height: var(--leading-relaxed);
+}
+
+h1, h2 {
+  font-family: var(--font-display);
+  font-weight: var(--font-weight-regular);
+  line-height: var(--leading-tight);
+  color: var(--color-neutral-950);
+}
+
+h3, h4, h5, h6 {
+  font-family: var(--font-sans);
+  font-weight: var(--font-weight-semibold);
+  line-height: var(--leading-snug);
+  color: var(--color-neutral-900);
+}
+
+/* ============================================
+ * Reduced motion
+ * ============================================ */
+
+@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;
+  }
+}
--- a/design/design-tokens.json
+++ b/design/design-tokens.json
@@ -0,0 +1,133 @@
+{
+  "$schema": "https://design-tokens.github.io/community-group/format/",
+  "color": {
+    "brand": {
+      "primary": {
+        "50":  { "value": "#F4F8F5", "description": "Background sección destacada" },
+        "100": { "value": "#E8F0EB", "description": "Background suave, hover state" },
+        "300": { "value": "#A8C8B5", "description": "Backgrounds suaves, badges" },
+        "500": { "value": "#4D8A6D", "description": "Acento medio, hover de botones" },
+        "700": { "value": "#2F5C46", "description": "Botones primarios, links activos" },
+        "900": { "value": "#1F3A2E", "description": "Texto sobre claro, headings serios" }
+      },
+      "accent": {
+        "100": { "value": "#FAEAE0", "description": "Background de bloques destacados" },
+        "400": { "value": "#E08A5F", "description": "Iconos decorativos, badges" },
+        "600": { "value": "#C25E33", "description": "CTAs secundarios destacados, alertas no críticas" },
+        "900": { "value": "#7A3517", "description": "Énfasis muy fuerte" }
+      }
+    },
+    "neutral": {
+      "50":  { "value": "#F7F8F7" },
+      "100": { "value": "#EDEFED" },
+      "200": { "value": "#DDE0DD" },
+      "300": { "value": "#C4C9C4" },
+      "400": { "value": "#9DA29D" },
+      "500": { "value": "#7A807A" },
+      "700": { "value": "#4A4E4A" },
+      "900": { "value": "#262826" },
+      "950": { "value": "#161816" },
+      "white": { "value": "#FFFFFF" }
+    },
+    "semantic": {
+      "success": {
+        "100": { "value": "#E0F0E6" },
+        "500": { "value": "#4DAA73" },
+        "700": { "value": "#2D7A4F" }
+      },
+      "warning": {
+        "100": { "value": "#FAEFD3" },
+        "500": { "value": "#DA9A2C" },
+        "700": { "value": "#9A6B0E" }
+      },
+      "danger": {
+        "100": { "value": "#FAE0DA" },
+        "500": { "value": "#D85940" },
+        "700": { "value": "#A8331F" }
+      },
+      "info": {
+        "100": { "value": "#DDEDF5" },
+        "500": { "value": "#3D8AAA" },
+        "700": { "value": "#1F5C7A" }
+      }
+    }
+  },
+  "typography": {
+    "fontFamily": {
+      "display": { "value": "'Instrument Serif', Georgia, serif" },
+      "sans":    { "value": "'Inter', system-ui, -apple-system, sans-serif" },
+      "mono":    { "value": "'JetBrains Mono', ui-monospace, monospace" }
+    },
+    "fontSize": {
+      "xs":   { "value": "0.75rem",  "lineHeight": "1.5" },
+      "sm":   { "value": "0.875rem", "lineHeight": "1.5" },
+      "base": { "value": "1rem",     "lineHeight": "1.6" },
+      "lg":   { "value": "1.125rem", "lineHeight": "1.5" },
+      "xl":   { "value": "1.25rem",  "lineHeight": "1.4" },
+      "2xl":  { "value": "1.5rem",   "lineHeight": "1.3" },
+      "3xl":  { "value": "1.875rem", "lineHeight": "1.3" },
+      "4xl":  { "value": "2.25rem",  "lineHeight": "1.2" },
+      "5xl":  { "value": "3rem",     "lineHeight": "1.1" },
+      "6xl":  { "value": "3.75rem",  "lineHeight": "1.05" },
+      "7xl":  { "value": "4.5rem",   "lineHeight": "1.0" }
+    },
+    "fontWeight": {
+      "regular":  { "value": "400" },
+      "medium":   { "value": "500" },
+      "semibold": { "value": "600" },
+      "bold":     { "value": "700" }
+    }
+  },
+  "spacing": {
+    "1":  { "value": "0.25rem" },
+    "2":  { "value": "0.5rem" },
+    "3":  { "value": "0.75rem" },
+    "4":  { "value": "1rem" },
+    "6":  { "value": "1.5rem" },
+    "8":  { "value": "2rem" },
+    "12": { "value": "3rem" },
+    "16": { "value": "4rem" },
+    "24": { "value": "6rem" },
+    "32": { "value": "8rem" }
+  },
+  "borderRadius": {
+    "sm":   { "value": "4px" },
+    "md":   { "value": "6px" },
+    "lg":   { "value": "10px" },
+    "xl":   { "value": "14px" },
+    "2xl":  { "value": "20px" },
+    "full": { "value": "9999px" }
+  },
+  "shadow": {
+    "xs":   { "value": "0 1px 2px rgba(22, 24, 22, 0.05)" },
+    "sm":   { "value": "0 1px 3px rgba(22, 24, 22, 0.08), 0 1px 2px rgba(22, 24, 22, 0.04)" },
+    "md":   { "value": "0 4px 6px rgba(22, 24, 22, 0.07), 0 2px 4px rgba(22, 24, 22, 0.04)" },
+    "lg":   { "value": "0 10px 15px rgba(22, 24, 22, 0.08), 0 4px 6px rgba(22, 24, 22, 0.05)" },
+    "xl":   { "value": "0 20px 25px rgba(22, 24, 22, 0.1), 0 10px 10px rgba(22, 24, 22, 0.04)" },
+    "glow": { "value": "0 0 0 4px rgba(47, 92, 70, 0.15)" }
+  },
+  "breakpoint": {
+    "sm":  { "value": "640px" },
+    "md":  { "value": "768px" },
+    "lg":  { "value": "1024px" },
+    "xl":  { "value": "1280px" },
+    "2xl": { "value": "1536px" }
+  },
+  "container": {
+    "narrow":  { "value": "720px" },
+    "default": { "value": "1200px" },
+    "wide":    { "value": "1440px" }
+  },
+  "motion": {
+    "duration": {
+      "fast": { "value": "150ms" },
+      "base": { "value": "250ms" },
+      "slow": { "value": "400ms" }
+    },
+    "easing": {
+      "out":   { "value": "cubic-bezier(0.16, 1, 0.3, 1)" },
+      "in":    { "value": "cubic-bezier(0.7, 0, 0.84, 0)" },
+      "inOut": { "value": "cubic-bezier(0.65, 0, 0.35, 1)" }
+    }
+  }
+}
--- a/design/tailwind.config.ext.js
+++ b/design/tailwind.config.ext.js
@@ -0,0 +1,128 @@
+/**
+ * Reformix — Tailwind config extensions
+ * Stack: Next.js 14 + Tailwind + shadcn/ui
+ *
+ * Cómo usar:
+ *   En tu tailwind.config.{js,ts} del proyecto, mergea esta config:
+ *
+ *   import reformixTheme from './design/tailwind.config.ext.js'
+ *   export default {
+ *     content: [...],
+ *     theme: {
+ *       extend: {
+ *         ...reformixTheme.theme.extend,
+ *       },
+ *     },
+ *   }
+ *
+ * Si usas shadcn/ui, mantén su tema base y extiende encima con esto.
+ */
+
+/** @type {import('tailwindcss').Config} */
+const reformixTheme = {
+  theme: {
+    extend: {
+      colors: {
+        primary: {
+          50:  '#F4F8F5',
+          100: '#E8F0EB',
+          300: '#A8C8B5',
+          500: '#4D8A6D',
+          700: '#2F5C46',
+          900: '#1F3A2E',
+          DEFAULT: '#2F5C46', // primary-700
+        },
+        accent: {
+          100: '#FAEAE0',
+          400: '#E08A5F',
+          600: '#C25E33',
+          900: '#7A3517',
+          DEFAULT: '#C25E33', // accent-600
+        },
+        neutral: {
+          50:  '#F7F8F7',
+          100: '#EDEFED',
+          200: '#DDE0DD',
+          300: '#C4C9C4',
+          400: '#9DA29D',
+          500: '#7A807A',
+          700: '#4A4E4A',
+          900: '#262826',
+          950: '#161816',
+        },
+        success: {
+          100: '#E0F0E6',
+          500: '#4DAA73',
+          700: '#2D7A4F',
+        },
+        warning: {
+          100: '#FAEFD3',
+          500: '#DA9A2C',
+          700: '#9A6B0E',
+        },
+        danger: {
+          100: '#FAE0DA',
+          500: '#D85940',
+          700: '#A8331F',
+        },
+        info: {
+          100: '#DDEDF5',
+          500: '#3D8AAA',
+          700: '#1F5C7A',
+        },
+      },
+      fontFamily: {
+        display: ['Instrument Serif', 'Georgia', 'serif'],
+        sans:    ['Inter', 'system-ui', '-apple-system', 'sans-serif'],
+        mono:    ['JetBrains Mono', 'ui-monospace', 'monospace'],
+      },
+      fontSize: {
+        xs:   ['0.75rem',  { lineHeight: '1.5' }],
+        sm:   ['0.875rem', { lineHeight: '1.5' }],
+        base: ['1rem',     { lineHeight: '1.6' }],
+        lg:   ['1.125rem', { lineHeight: '1.5' }],
+        xl:   ['1.25rem',  { lineHeight: '1.4' }],
+        '2xl': ['1.5rem',   { lineHeight: '1.3' }],
+        '3xl': ['1.875rem', { lineHeight: '1.3' }],
+        '4xl': ['2.25rem',  { lineHeight: '1.2' }],
+        '5xl': ['3rem',     { lineHeight: '1.1' }],
+        '6xl': ['3.75rem',  { lineHeight: '1.05' }],
+        '7xl': ['4.5rem',   { lineHeight: '1.0' }],
+      },
+      borderRadius: {
+        sm:   '4px',
+        md:   '6px',
+        lg:   '10px',
+        xl:   '14px',
+        '2xl': '20px',
+        full: '9999px',
+      },
+      boxShadow: {
+        xs:   '0 1px 2px rgba(22, 24, 22, 0.05)',
+        sm:   '0 1px 3px rgba(22, 24, 22, 0.08), 0 1px 2px rgba(22, 24, 22, 0.04)',
+        DEFAULT: '0 1px 3px rgba(22, 24, 22, 0.08), 0 1px 2px rgba(22, 24, 22, 0.04)',
+        md:   '0 4px 6px rgba(22, 24, 22, 0.07), 0 2px 4px rgba(22, 24, 22, 0.04)',
+        lg:   '0 10px 15px rgba(22, 24, 22, 0.08), 0 4px 6px rgba(22, 24, 22, 0.05)',
+        xl:   '0 20px 25px rgba(22, 24, 22, 0.1), 0 10px 10px rgba(22, 24, 22, 0.04)',
+        glow: '0 0 0 4px rgba(47, 92, 70, 0.15)',
+      },
+      maxWidth: {
+        narrow:  '720px',
+        default: '1200px',
+        wide:    '1440px',
+      },
+      transitionDuration: {
+        fast: '150ms',
+        base: '250ms',
+        slow: '400ms',
+      },
+      transitionTimingFunction: {
+        out:   'cubic-bezier(0.16, 1, 0.3, 1)',
+        in:    'cubic-bezier(0.7, 0, 0.84, 0)',
+        'in-out': 'cubic-bezier(0.65, 0, 0.35, 1)',
+      },
+    },
+  },
+}
+
+module.exports = reformixTheme