# DESIGN.md — SocioCompras Motor 2 Design System

**Versión:** 1.0
**Fecha:** 2026-06-10
**Scope:** Marketplace público (sociocompras.com) + App marketplace (app.sociocompras.com)
**Mantenedor:** F413 SpA

> Este documento es la fuente única de verdad sobre el diseño visual de SocioCompras Motor 2. Cualquier interfaz nueva — landing, app web, mobile, email — debe seguir estos lineamientos. Las desviaciones requieren actualizar este doc.

---

## 1. Identidad de marca

### 1.1 Filosofía visual

SocioCompras es un **marketplace B2B HORECA** donde restaurantes en Chile compran frutas y verduras de forma colectiva. El diseño refleja **3 atributos**:

| Atributo | Cómo se traduce visualmente |
|---|---|
| **Honesto** | Datos concretos (precios, %, kilos), sin promesas vagas. Tipografía clara, sin marketing tricks. |
| **Local** | Colores naturales (verde lima = chacra), badges geográficos (🟢🟡🟣), copy en español Chile. |
| **Eficiente** | Layout limpio, jerarquía clara, cero ornamentación gratuita. Cards utilitarias, no decorativas. |

### 1.2 Voz y tono

- **Español Chile** ("tú" no "usted") · profesional pero cercano
- **Mensajes con números concretos** ($CLP, %, kg, horas) — nunca "increíble", "amazing", "revolucionario"
- **Sin exageraciones** — usar rangos honestos ("ahorro típico 15-25%") en vez de máximos como default ("hasta 30%")
- **Verbos de acción claros**: "Crear cuenta", "Hacer pedido", "Ver precios" (no "Comienza tu viaje")

---

## 2. Design Tokens

### 2.1 Colors

#### Brand primary

| Token | Hex | RGB | Uso |
|---|---|---|---|
| `--sc-brand` | `#AED440` | `174 212 64` | CTAs primarios, links activos, badges positivos, hover states |
| `--sc-brand-dark` | `#7BC22E` | `123 194 46` | Hover state del brand, énfasis |
| `--sc-brand-light` | `#D1E886` | `209 232 134` | Backgrounds tinted, badges secundarios |

#### Brand accent (urgencia / Fundador)

| Token | Hex | RGB | Uso |
|---|---|---|---|
| `--sc-accent` | `#FFD034` | `255 208 52` | Programa Fundador, cupos urgencia, descuentos especiales |
| `--sc-accent-dark` | `#E5B61F` | `229 182 31` | Hover del accent |

#### Neutral (dark mode default)

| Token | Hex | RGB | Uso |
|---|---|---|---|
| `--sc-dark` | `#13140F` | `19 20 15` | Background principal dark, texto sobre claro |
| `--sc-dark-light` | `#1E1F18` | `30 31 24` | Backgrounds elevados dark (cards, navbar) |
| `--sc-surface` | `#1b1c17` | `27 28 23` | Surface intermedia (modales, dropdowns) |

#### Neutral grays (UI elements)

| Token | Hex | RGB | Uso |
|---|---|---|---|
| `--sc-gray-50` | `#F9FAFB` | `249 250 251` | Backgrounds secciones claras alternadas |
| `--sc-gray-100` | `#F3F4F6` | `243 244 246` | Borders sutiles, dividers |
| `--sc-gray-300` | `#D1D5DB` | `209 213 219` | Texto auxiliar sobre dark |
| `--sc-gray-400` | `#9CA3AF` | `156 163 175` | Placeholders, texto deshabilitado |
| `--sc-gray-500` | `#6B7280` | `107 114 128` | Labels secundarios |
| `--sc-gray-600` | `#4B5563` | `75 85 99` | Body text sobre claro |
| `--sc-gray-700` | `#374151` | `55 65 81` | Headings secundarios sobre claro |
| `--sc-gray-900` | `#111827` | `17 24 39` | Headings principales sobre claro |

#### Semantic

| Token | Hex | Uso |
|---|---|---|
| `--sc-success` | `#10B981` | Confirmación, ahorro positivo, comuna activa |
| `--sc-warning` | `#F59E0B` | Cupos limitados, anillo activando |
| `--sc-error` | `#EF4444` | Errores de form, precios viejos en comparativas |
| `--sc-info` | `#1a91ff` | Tooltips, notificaciones neutrales |

#### Anillo status (geo)

| Token | Color | Emoji | Significado |
|---|---|---|---|
| `--sc-anillo-1` | `#10B981` (green) | 🟢 | Activa — operando |
| `--sc-anillo-2` | `#F59E0B` (amber) | 🟡 | Activando — sumando restaurantes |
| `--sc-anillo-3` | `#A855F7` (purple) | 🟣 | VIP — acceso anticipado |

### 2.2 Typography

#### Font families

| Token | Familia | Uso | Source |
|---|---|---|---|
| `--sc-font-display` | `'Calistoga', serif` | H1, H2, números grandes, hero | Google Fonts |
| `--sc-font-body` | `'Inter', system-ui, sans-serif` | Body, H3-H6, UI, formularios | Google Fonts |
| `--sc-font-mono` | `'JetBrains Mono', monospace` | Códigos referidos, IDs, datos técnicos | Google Fonts (opcional app) |

#### Type scale

| Token | Size | Line-height | Weight | Uso |
|---|---|---|---|---|
| `--sc-text-xs` | `0.75rem` (12px) | 1.5 | 400/500 | Labels, captions, meta |
| `--sc-text-sm` | `0.875rem` (14px) | 1.5 | 400/500 | Body secundario, nav, footer |
| `--sc-text-base` | `1rem` (16px) | 1.6 | 400 | Body principal — **mínimo legible** |
| `--sc-text-lg` | `1.125rem` (18px) | 1.6 | 400 | Subtítulos, lead paragraph |
| `--sc-text-xl` | `1.25rem` (20px) | 1.5 | 600 | H4, callouts |
| `--sc-text-2xl` | `1.5rem` (24px) | 1.4 | 600/700 | H3 |
| `--sc-text-3xl` | `1.875rem` (30px) | 1.3 | 700 (display) | H2 mobile |
| `--sc-text-4xl` | `2.25rem` (36px) | 1.2 | 700 (display) | H2 desktop, H1 mobile |
| `--sc-text-5xl` | `3rem` (48px) | 1.1 | 700 (display) | H1 desktop |
| `--sc-text-6xl` | `3.75rem` (60px) | 1.1 | 700 (display) | Hero principal |
| `--sc-text-display` | `clamp(2.25rem, 5vw, 4rem)` | 1.1 | 700 (display) | Hero responsive |

#### Font weights

| Token | Value | Uso |
|---|---|---|
| `--sc-font-normal` | 400 | Body |
| `--sc-font-medium` | 500 | Énfasis sutil, labels |
| `--sc-font-semibold` | 600 | CTAs, headings UI |
| `--sc-font-bold` | 700 | Headings display, énfasis fuerte |
| `--sc-font-black` | 900 | Números grandes en stats |

### 2.3 Spacing scale (basado en Tailwind 4px-grid)

| Token | Value | Uso típico |
|---|---|---|
| `--sc-space-0` | `0` | — |
| `--sc-space-1` | `0.25rem` (4px) | Padding chip mínimo |
| `--sc-space-2` | `0.5rem` (8px) | Gap entre íconos y texto |
| `--sc-space-3` | `0.75rem` (12px) | Padding botón compact |
| `--sc-space-4` | `1rem` (16px) | Padding interno default |
| `--sc-space-6` | `1.5rem` (24px) | Gap entre secciones intra-card |
| `--sc-space-8` | `2rem` (32px) | Padding card, gap grid |
| `--sc-space-12` | `3rem` (48px) | Margin entre secciones |
| `--sc-space-16` | `4rem` (64px) | Padding vertical sección |
| `--sc-space-20` | `5rem` (80px) | Padding vertical sección hero |
| `--sc-space-24` | `6rem` (96px) | Gap entre bloques mayores |

### 2.4 Border radius

| Token | Value | Uso |
|---|---|---|
| `--sc-radius-sm` | `0.5rem` (8px) | Inputs, tags compactos |
| `--sc-radius-md` | `0.75rem` (12px) | Botones, badges medianos |
| `--sc-radius-lg` | `1rem` (16px) | Cards estándar |
| `--sc-radius-xl` | `1.5rem` (24px) | Cards hero, modales |
| `--sc-radius-2xl` | `1rem` (16px) | **Default cards** (alias de lg para consistencia con Tailwind) |
| `--sc-radius-full` | `9999px` | Pills, badges, avatars |

### 2.5 Shadows

| Token | Value | Uso |
|---|---|---|
| `--sc-shadow-sm` | `0 1px 2px 0 rgba(0,0,0,.05)` | Inputs focus |
| `--sc-shadow` | `0 1px 3px 0 rgba(0,0,0,.1), 0 1px 2px -1px rgba(0,0,0,.1)` | Cards default |
| `--sc-shadow-md` | `0 4px 6px -1px rgba(0,0,0,.1), 0 2px 4px -2px rgba(0,0,0,.1)` | Dropdowns, popovers |
| `--sc-shadow-lg` | `0 10px 15px -3px rgba(0,0,0,.1), 0 4px 6px -4px rgba(0,0,0,.1)` | Modales, cards elevadas |
| `--sc-shadow-xl` | `0 20px 25px -5px rgba(0,0,0,.1), 0 8px 10px -6px rgba(0,0,0,.1)` | Hero overlays |
| `--sc-shadow-brand` | `0 16px 48px rgba(174,212,64,0.12)` | Card hover effect signature (verde lima glow) |

### 2.6 Motion

| Token | Value | Uso |
|---|---|---|
| `--sc-duration-fast` | `150ms` | Cambios de color, focus |
| `--sc-duration-normal` | `250ms` | Hover transitions, scale |
| `--sc-duration-slow` | `500ms` | Reveal on scroll, modal enter |
| `--sc-ease-out` | `cubic-bezier(0.16, 1, 0.3, 1)` | Default ease para entrada |
| `--sc-ease-in-out` | `cubic-bezier(0.4, 0, 0.2, 1)` | Transiciones bidireccionales |

**Principio:** todas las animaciones respetan `prefers-reduced-motion`. Default fallback es `transition: none`.

### 2.7 Breakpoints

| Token | Min-width | Device |
|---|---|---|
| `--sc-bp-sm` | `640px` | Mobile landscape, tablet portrait |
| `--sc-bp-md` | `768px` | Tablet landscape |
| `--sc-bp-lg` | `1024px` | Desktop |
| `--sc-bp-xl` | `1280px` | Desktop wide |
| `--sc-bp-2xl` | `1536px` | Desktop ultrawide |

**Mobile-first:** todo se diseña primero para mobile, luego escala. Min-width queries.

### 2.8 Container widths

| Token | Max-width | Uso |
|---|---|---|
| `--sc-container-narrow` | `42rem` (672px) | Long-form text (blog, legal) |
| `--sc-container-prose` | `48rem` (768px) | Form de inscripción, articles |
| `--sc-container-default` | `72rem` (1152px) | Default sections |
| `--sc-container-wide` | `80rem` (1280px) | Dashboards, listados de productos |

### 2.9 Z-index scale

| Token | Value | Uso |
|---|---|---|
| `--sc-z-base` | `0` | Default |
| `--sc-z-dropdown` | `10` | Dropdowns navbar |
| `--sc-z-sticky` | `20` | Headers sticky |
| `--sc-z-fixed` | `30` | Navbars fixed |
| `--sc-z-modal-bg` | `40` | Overlay modales |
| `--sc-z-modal` | `50` | Modales |
| `--sc-z-popover` | `60` | Popovers, tooltips |
| `--sc-z-toast` | `70` | Toasts |

---

## 3. Components

### 3.1 Button

#### Variants

| Variant | Cuándo usar | Visual |
|---|---|---|
| `primary` | CTA principal de la pantalla | `bg-brand text-dark hover:bg-brand-dark` |
| `accent` | CTA Fundador / urgencia | `bg-accent text-dark hover:bg-accent-dark` |
| `secondary` | CTA secundario | `border-2 border-white/20 text-white hover:border-brand` |
| `ghost` | Acciones tertiary | `text-gray-300 hover:text-brand bg-transparent` |
| `whatsapp` | CTAs hacia WhatsApp | `bg-[#25D366] text-white` |

#### Sizes

| Size | Padding | Min-height | Font | Uso |
|---|---|---|---|---|
| `sm` | `px-4 py-2` | `40px` | `text-sm` | Inline, tabla acciones |
| `md` | `px-5 py-2.5` | `44px` | `text-base font-semibold` | **Default** — navbar, formularios |
| `lg` | `px-8 py-4` | `56px` | `text-lg font-bold` | Hero CTAs |

#### States

| State | Visual | Comportamiento |
|---|---|---|
| Default | Background brand color | Cursor pointer |
| Hover | Background `-dark` variant | Smooth transition 250ms |
| Active | Scale 0.98 | Feedback táctil |
| Disabled | Opacity 0.5 | `pointer-events: none` |
| Loading | Spinner inline + texto "Procesando..." | `aria-busy="true"` |

#### Accessibility

- **Role:** implícito `button` (usar `<button>` o `<a role="button">`)
- **Keyboard:** Space / Enter activan, Tab navega
- **Touch target:** mínimo 44×44px (sigue WCAG 2.2)
- **Loading:** anunciar como "Procesando" con `aria-busy`

#### Anti-patterns

- ❌ Botón ghost como CTA principal en hero (insuficiente contraste con dark bg)
- ❌ Más de 2 botones primary en la misma vista (compite atención)
- ❌ Texto del botón largo (>3 palabras). Si necesitás más, usá `<a>` con CTA implícito
- ❌ Botones con solo emoji sin texto (a11y fail)

### 3.2 Card

#### Anatomy

```
┌─────────────────────────────┐
│ [Icon emoji 4xl]            │
│                             │
│ H3 título (Calistoga)       │
│                             │
│ Body text (Inter, gray-600) │
│ Leading-relaxed             │
└─────────────────────────────┘
```

#### Variants

| Variant | Background | Border | Hover | Uso |
|---|---|---|---|---|
| `default` | `bg-gray-50` | `border border-gray-100` | `card-hover` | Beneficios, FAQ |
| `floating` | `bg-white` | `border border-gray-100` | `card-hover` | Sobre sección bg-gray-50 |
| `accent` | `bg-accent/5` | `border-2 border-accent/20` | `card-hover` | Highlighted (Fundador, descuentos) |
| `brand` | `bg-brand/5` | `border-2 border-brand/20` | `card-hover` | Recomendado, mejor opción |
| `dark` | `bg-dark-light` | `border border-white/10` | `hover:border-brand` | Sobre hero dark |

#### Card hover effect (signature)

```css
.card-hover {
  transition: transform 250ms ease-out, box-shadow 250ms ease-out;
}
.card-hover:hover {
  transform: translateY(-6px);
  box-shadow: 0 16px 48px rgba(174, 212, 64, 0.12); /* verde lima glow */
}
```

#### Padding scale

| Card size | Padding | Min-height |
|---|---|---|
| `compact` | `p-6` (24px) | — |
| `default` | `p-8` (32px) | — |
| `large` | `p-10 sm:p-12` (40-48px) | — |

### 3.3 Badge / Pill

#### Variants

| Variant | Background | Border | Color | Uso |
|---|---|---|---|---|
| `brand-outline` | `bg-brand/10` | `border border-brand/30` | `text-brand` | Anillo activo, tags positivos |
| `accent-outline` | `bg-accent/10` | `border border-accent/30` | `text-accent` | Programa Fundador |
| `gold-filled` | `bg-gold/100` | — | `text-dark` | Cupos urgentes (alto contraste) |
| `lime-filled` | `bg-brand/100` | — | `text-dark` | Status confirmation |
| `dark-filled` | `bg-dark/95` | — | `text-brand` | Logo badge |

#### Sizes

| Size | Padding | Font | Uso |
|---|---|---|---|
| `xs` | `px-2 py-0.5` | `text-xs` | Tag de fila tabla |
| `sm` | `px-3 py-1` | `text-xs font-medium` | Inline badge |
| `md` | `px-4 py-1.5` | `text-sm font-medium` | Hero badge anillo |
| `lg` | `px-6 py-2` | `text-base font-semibold` | Standalone destacado |

#### Patrón Anillo (Marketplace específico)

```html
<div class="inline-flex items-center gap-2 bg-brand/10 border border-brand/30 text-brand text-sm font-medium px-4 py-1.5 rounded-full">
  🟢 Activa <span class="text-gray-300 font-normal">· Anillo 1 · Despacho local operativo</span>
</div>
```

### 3.4 Form Input

#### Anatomy

```html
<label class="block text-sm font-medium text-gray-700 mb-2">
  Nombre del restaurante <span class="text-red-500">*</span>
</label>
<input type="text" required autocomplete="organization"
       class="w-full border border-gray-300 rounded-xl px-4 py-3
              focus:border-brand focus:outline-none
              min-h-[48px] text-base"
       placeholder="Ej: La Cocina de María">
<p class="text-xs text-gray-500 mt-1">Opcional: ayuda explicativa</p>
```

#### States

| State | Border | Background | Notas |
|---|---|---|---|
| Default | `border-gray-300` | `bg-white` | — |
| Focus | `border-brand` + ring 3px `rgba(174,212,64,0.3)` | `bg-white` | Quita `outline-none` y aplica box-shadow |
| Error | `border-red-500` | `bg-red-50` | Mostrar mensaje debajo |
| Disabled | `border-gray-200` | `bg-gray-100` | `cursor-not-allowed` |
| Filled (valid) | `border-brand` (sin ring) | `bg-white` | Si necesitás indicar OK |

#### Tipos soportados

- `text` / `email` / `tel` / `number` — todos con `min-h-[48px]`
- `select` — mismo padding pero con caret custom
- `textarea` — `min-h-[120px]`, sin `min-h-[48px]`
- `checkbox` / `radio` — 20×20px con custom check brand color
- `file` — dropzone con `border-dashed`

#### Accessibility

- Siempre `<label>` asociado con `for=""`
- `aria-invalid="true"` en estado error
- `aria-describedby` apuntando al mensaje de ayuda/error
- `autocomplete` apropiado (`organization`, `tel`, `email`, etc.)
- `inputmode` correcto para mobile (`numeric`, `tel`, `email`)

### 3.5 Navbar

#### Anatomy

```html
<nav class="fixed top-0 left-0 right-0 z-50 bg-dark/95 backdrop-blur border-b border-white/10">
  <div class="max-w-6xl mx-auto px-4 sm:px-6 py-3 flex items-center justify-between">
    <a href="/" class="text-white font-bold text-lg sm:text-xl">
      <span class="text-brand">Socio</span>Compras
    </a>
    <div class="hidden md:flex items-center gap-6 text-sm">
      <a href="/path" class="text-gray-300 hover:text-brand transition">Item</a>
      <!-- max 5 nav items + 1 link sesión + 1 CTA button -->
      <a href="/registro" class="bg-brand text-dark font-semibold px-5 py-2 rounded-xl
                                 hover:bg-brand-dark transition">CTA</a>
    </div>
    <a href="/registro" class="md:hidden bg-brand text-dark font-semibold
                               px-4 py-2 rounded-xl text-sm">CTA Mobile</a>
  </div>
</nav>
```

#### Rules

- **Max 7 elementos** en desktop (5 nav + 1 login + 1 CTA)
- **Mobile** solo muestra logo + CTA principal (no hamburger menu por ahora)
- **Backdrop blur** + opacidad 0.95 para semi-transparencia sobre scroll
- **Border bottom sutil** (`border-white/10`) para definir el espacio
- **Z-50** para overlay sobre todo el contenido
- **Padding vertical fijo** `py-3` (12px) para mantener altura ~60px

### 3.6 Hero (gradient-hero pattern)

#### CSS

```css
.gradient-hero {
  background: linear-gradient(135deg, #13140F 0%, #1E1F18 40%, #2a2d1e 70%, #1a1f12 100%);
  position: relative;
  overflow: hidden;
}
.gradient-hero::before {
  content: '';
  position: absolute;
  top: -50%;
  right: -30%;
  width: 80%;
  height: 200%;
  background: radial-gradient(ellipse, rgba(174,212,64,0.06) 0%, transparent 70%);
  animation: float-glow 20s ease-in-out infinite;
}
```

#### Anatomy

```
┌──────────────────────────────────────┐
│ Breadcrumb (text-xs, gray-400)       │
│                                      │
│ [🟢 Activa · Anillo 1 · Detalle]    │ ← Badge
│                                      │
│ H1 Display (Calistoga, text-6xl)     │
│ Highlight con text-brand             │
│                                      │
│ Subtitle (text-lg gray-300)          │
│                                      │
│ [Primary CTA] [Secondary CTA]        │
└──────────────────────────────────────┘
```

#### Padding

- `pt-24` (96px top — para cubrir navbar fixed 60px + 36px breathing)
- `pb-20` (80px bottom)
- `px-4` (16px) en mobile, `max-w-5xl mx-auto` para limitar ancho

### 3.7 Footer

#### Estructura (4 columnas en desktop, stack en mobile)

```
┌───────────────────────────────────────────────────────┐
│ Logo + tagline    Plataforma    Ecosistema   Contacto │
│                   - Crear cta   - Costy      - WSP    │
│                   - Login       - Referidos  - Email  │
│                   - Funciona    - Blog       [CORFO]  │
│                   - Comuna      - Partner             │
│                   - Fundador                          │
├───────────────────────────────────────────────────────┤
│ (opcional) Grid de comunas para cross-link SEO        │
├───────────────────────────────────────────────────────┤
│ © 2026 · Privacidad · Términos                        │
└───────────────────────────────────────────────────────┘
```

#### Reglas

- Fondo `bg-dark`, texto `text-gray-300`
- Padding vertical `py-12` (48px)
- Logo destaca con `<span class="text-brand">Socio</span>Compras`
- Links secundarios `text-sm` con `hover:text-brand`
- Para SEO local, agregar grid de comunas (para Motor 2)
- Badge institucional (CORFO) en columna Contacto, `opacity-80 hover:opacity-100`

### 3.8 Section dividers (page rhythm)

El sitio alterna 3 tipos de sección para crear ritmo visual:

| Tipo | Background | Cuándo usar |
|---|---|---|
| `gradient-hero` | Dark gradient + radial glow | Apertura página, CTA final |
| `bg-white` | Blanco | Contenido principal (features) |
| `bg-gray-50` | Gris claro | Alternativa a blanco, dar respiro |

**Patrón estándar:**
```
[Hero dark] → [Features white] → [FAQ gray-50] → [CTA dark] → [Footer dark]
```

Padding vertical sección:
- `py-16` mobile (64px)
- `py-20` desktop (80px)
- `py-24` para hero/CTA final (96px)

### 3.9 Modal

Solo aplicable a app.sociocompras.com (la landing pública no usa modales).

#### Anatomy

```html
<div role="dialog" aria-modal="true"
     class="fixed inset-0 z-50 flex items-center justify-center px-4">
  <div class="absolute inset-0 bg-dark/80 backdrop-blur-sm"
       data-modal-overlay></div>
  <div class="relative bg-white rounded-2xl shadow-xl max-w-md w-full p-8">
    <button class="absolute top-4 right-4 text-gray-400 hover:text-gray-700"
            aria-label="Cerrar">×</button>
    <h2 class="font-display text-2xl mb-4">Título</h2>
    <p class="text-gray-600 mb-6">Contenido</p>
    <div class="flex gap-3 justify-end">
      <button class="px-4 py-2 text-gray-700">Cancelar</button>
      <button class="bg-brand text-dark px-5 py-2 rounded-xl font-semibold">Confirmar</button>
    </div>
  </div>
</div>
```

#### Rules

- **Overlay** semi-transparente dark + backdrop-blur
- **Click overlay** cierra modal
- **Escape key** cierra modal
- **Focus trap** dentro del modal (a11y)
- **Body scroll lock** mientras abierto
- **Max width** `max-w-md` (448px) default, `max-w-2xl` (672px) para forms
- **Padding** `p-8` (32px)

### 3.10 Toast / Notification

Para app.sociocompras.com — feedback no bloqueante.

| Variant | Background | Border | Icon | Uso |
|---|---|---|---|---|
| `success` | `bg-green-50` | `border-green-200` | ✓ | Pedido confirmado |
| `error` | `bg-red-50` | `border-red-200` | ! | Error de pago |
| `warning` | `bg-amber-50` | `border-amber-200` | ⚠ | Stock bajo |
| `info` | `bg-blue-50` | `border-blue-200` | ℹ | Update plataforma |

```html
<div role="status" aria-live="polite"
     class="fixed bottom-4 right-4 z-70 max-w-sm
            bg-green-50 border border-green-200 rounded-xl p-4 shadow-lg
            flex items-start gap-3 animate-slide-up">
  <div class="text-2xl">✓</div>
  <div class="flex-1">
    <p class="font-semibold text-green-900">Pedido confirmado</p>
    <p class="text-sm text-green-700">Tu pedido llegará el martes 12.</p>
  </div>
  <button class="text-green-700 hover:text-green-900" aria-label="Cerrar">×</button>
</div>
```

---

## 4. Patterns

### 4.1 CTA dual (primary + secondary)

Usado en hero, CTA final, modales de confirmación.

```html
<div class="flex flex-col sm:flex-row gap-4">
  <a href="/registro" class="bg-brand hover:bg-brand-dark text-dark font-bold
                              px-8 py-4 rounded-xl text-lg transition
                              min-h-[56px] flex items-center justify-center">
    Crear cuenta gratis
  </a>
  <a href="/postular" class="border-2 border-white/20 hover:border-brand
                              text-white font-semibold px-8 py-4 rounded-xl
                              text-lg transition min-h-[56px]
                              flex items-center justify-center">
    Postular como Fundador
  </a>
</div>
```

### 4.2 Grid de cards 1-2-3

Layout estándar para sección "Por qué unirte":

```html
<section class="py-20 px-4 max-w-6xl mx-auto">
  <div class="text-center mb-14">
    <h2 class="text-3xl sm:text-4xl font-display mb-3">Heading</h2>
    <p class="text-gray-600 text-lg max-w-2xl mx-auto">Subtitle</p>
  </div>
  <div class="grid grid-cols-1 md:grid-cols-3 gap-8">
    <div class="bg-gray-50 border border-gray-100 rounded-2xl p-8 card-hover">
      <div class="text-4xl mb-4">💰</div>
      <h3 class="font-display text-xl mb-3">Card title</h3>
      <p class="text-gray-600 leading-relaxed">Card body</p>
    </div>
    <!-- repeat 2 more -->
  </div>
</section>
```

**Reglas:**
- Mobile: 1 col stack
- Desktop: 2-3 cols según contenido
- Gap consistente `gap-8` (32px)
- Cards equal-height (CSS Grid hace esto automático)

### 4.3 Comparison table (2-column)

Para mostrar antes/después o competencia:

```html
<div class="grid grid-cols-2 gap-6">
  <div class="border-2 border-red-200 bg-red-50/30 rounded-2xl p-8">
    <div class="text-red-500 text-sm font-bold uppercase mb-2">Antes</div>
    <p class="text-2xl font-display">$2.400/kg</p>
    <p class="text-gray-600 mt-2">Proveedor individual</p>
  </div>
  <div class="border-2 border-brand bg-brand/5 rounded-2xl p-8 relative">
    <div class="absolute -top-3 left-8 bg-brand text-dark text-xs font-bold px-3 py-1 rounded-full">
      Recomendado
    </div>
    <div class="text-brand text-sm font-bold uppercase mb-2">Con SocioCompras</div>
    <p class="text-2xl font-display">$1.580/kg</p>
    <p class="text-gray-600 mt-2">Compra grupal</p>
  </div>
</div>
```

### 4.4 Stat callout (números grandes)

```html
<div class="text-center">
  <p class="text-6xl sm:text-7xl font-display text-brand">22%</p>
  <p class="text-lg font-semibold text-gray-700 mt-2">menos en costo de tomate</p>
  <p class="text-sm text-gray-500 mt-1">Restaurante El Huerto · Ñuñoa</p>
</div>
```

### 4.5 Empty state

Cuando una vista no tiene datos (ej. carrito vacío, sin pedidos):

```html
<div class="text-center py-16 px-4">
  <div class="text-6xl mb-4 opacity-50">🛒</div>
  <h3 class="font-display text-2xl mb-2">Tu carrito está vacío</h3>
  <p class="text-gray-600 mb-6 max-w-md mx-auto">
    Agregá productos de tu comuna para empezar.
  </p>
  <a href="/productos" class="inline-flex bg-brand text-dark font-semibold
                              px-6 py-3 rounded-xl hover:bg-brand-dark">
    Ver productos →
  </a>
</div>
```

### 4.6 Loading state

```html
<div role="status" aria-live="polite" class="flex items-center justify-center py-12">
  <svg class="animate-spin h-8 w-8 text-brand" viewBox="0 0 24 24">
    <circle class="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" stroke-width="4"></circle>
    <path class="opacity-75" fill="currentColor"
          d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4z"></path>
  </svg>
  <span class="ml-3 text-gray-600">Cargando productos...</span>
</div>
```

---

## 5. Iconography

### 5.1 Emoji-first approach

SocioCompras usa **emoji** como iconografía primaria. Razones:
- Universalmente reconocibles
- Cero dependencias (no need icon font/SVG library)
- Performance: 0 bytes extra HTTP
- Calidez visual (vs SVG corporativo)

### 5.2 Mapping consistente

| Concepto | Emoji | Cuándo |
|---|---|---|
| Comunidad / Red | 🤝 | Cómo funciona, compra colaborativa |
| Verduras / Producto | 🥬 | Catálogo, frescura |
| Despacho / Logística | 🚚 | Tiempos de entrega, operación |
| Comida / Restaurante | 🍽️ | Cliente HORECA |
| Dinero / Ahorro | 💰 | Pricing, savings |
| Carrito / Compra | 🛒 | Carrito vacío, agregar |
| Calculadora | 🧮 | Food cost, calculadora |
| Calendario | 📅 | Rondas semanales |
| Reloj | ⏰ | Tiempos, urgencia |
| Hogar / Local | 🏠 | Nodo local |
| Inicio rápido | ⚡ | Onboarding |
| Documento | 📋 | Formulario |
| Cerca de mí | 📍 | Geo, ubicación |
| Premium / Star | ⭐ | Fundador, top tier |

### 5.3 Anillos geo (específico Marketplace)

| Emoji | Anillo | Color asociado |
|---|---|---|
| 🟢 | Anillo 1 (activo) | Green |
| 🟡 | Anillo 2 (activando) | Amber |
| 🟣 | Anillo 3 (VIP) | Purple |

### 5.4 Sizing

| Tamaño | CSS class | Uso |
|---|---|---|
| `xs` | `text-xl` (20px) | Inline en texto |
| `sm` | `text-2xl` (24px) | Iconos en badges |
| `md` | `text-4xl` (36px) | Cards default |
| `lg` | `text-5xl` (48px) | Empty states |
| `xl` | `text-6xl` (60px) | Hero, callouts mayores |

### 5.5 SVG complementarios (cuando emoji no alcanza)

Para iconos UI funcionales (arrows, close, chevron, checkmark) usar **Heroicons** outline (24×24):
- ← → ↗ ✕ ✓ ⌄ ⌃ (arrow, close, check, chevron)
- Stroke width 1.5, color `currentColor`

---

## 6. Layout system

### 6.1 Container

Default container pattern:

```html
<section class="py-20 px-4">
  <div class="max-w-6xl mx-auto">
    <!-- content -->
  </div>
</section>
```

Variantes según contenido:
- `max-w-4xl` (896px) — content text-heavy (artículos, FAQ)
- `max-w-5xl` (1024px) — hero
- `max-w-6xl` (1152px) — **default** (3-col grids)
- `max-w-7xl` (1280px) — dashboards de app

### 6.2 Grid patterns

#### 3 cols → stack mobile
```html
<div class="grid grid-cols-1 md:grid-cols-3 gap-8">
```

#### 2 cols → stack mobile
```html
<div class="grid grid-cols-1 md:grid-cols-2 gap-6">
```

#### 4 cols footer → 2 cols tablet → 1 col mobile
```html
<div class="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-4 gap-8">
```

### 6.3 Stack (vertical spacing)

Para contenido secuencial vertical:

```html
<div class="space-y-6">
  <h1>Heading</h1>
  <p>Paragraph</p>
  <p>Another paragraph</p>
</div>
```

Scale típica: `space-y-4`, `space-y-6`, `space-y-8`, `space-y-12`.

### 6.4 Cluster (horizontal con wrap)

Para tags, badges, botones inline:

```html
<div class="flex flex-wrap items-center gap-3">
  <span class="badge">Tag 1</span>
  <span class="badge">Tag 2</span>
  <span class="badge">Tag 3</span>
</div>
```

---

## 7. Accessibility (WCAG 2.2 AA)

### 7.1 Color contrast

| Pair | Ratio | WCAG |
|---|---|---|
| `text-white` sobre `bg-dark` | 17.5:1 | AAA |
| `text-dark` sobre `bg-brand` | 8.2:1 | AAA |
| `text-dark` sobre `bg-accent` | 11.4:1 | AAA |
| `text-gray-600` sobre `bg-white` | 7.5:1 | AAA |
| `text-gray-300` sobre `bg-dark` | 12.3:1 | AAA |

**Toda combinación brand cumple AAA**. Verificar siempre con WebAIM contrast checker.

### 7.2 Touch targets

- **Mínimo 44×44px** para cualquier elemento clickeable (WCAG 2.5.5)
- Usar `min-h-[44px]` para botones standard, `min-h-[48px]` para forms
- Spacing entre targets ≥8px

### 7.3 Keyboard navigation

- **Tab** navega elementos focusables en orden lógico
- **Enter/Space** activa botones y links
- **Escape** cierra modales, dropdowns
- **Arrow keys** navega dentro de listas, menús
- Focus visible siempre: `outline: 3px solid var(--sc-brand)` o `box-shadow: 0 0 0 3px rgba(174,212,64,0.3)`

### 7.4 Screen readers

- Usar `<button>` para acciones, `<a>` para navegación
- Imágenes con `alt` descriptivo (o `alt=""` si decorativas)
- Forms con `<label for="">` asociado
- Loading states con `aria-busy="true"` + `aria-live="polite"`
- Errores con `aria-invalid="true"` + `aria-describedby`

### 7.5 Reduced motion

```css
@media (prefers-reduced-motion: reduce) {
  .reveal, .card-hover, .animate-* {
    animation: none !important;
    transition: none !important;
    transform: none !important;
  }
}
```

---

## 8. Performance

### 8.1 Font loading

```html
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link rel="preload"
      href="https://fonts.googleapis.com/css2?family=Calistoga&family=Inter:wght@400;500;600;700;800;900&display=swap"
      as="style"
      onload="this.onload=null;this.rel='stylesheet'">
<noscript><link rel="stylesheet" href="..."></noscript>
```

**Nunca** cargar fonts como blocking `rel="stylesheet"` (es regla del CLAUDE.md).

### 8.2 Images

- WebP / AVIF preferido, fallback JPG
- `loading="lazy"` para imágenes below-the-fold
- `width` y `height` explícitos para evitar CLS
- Lazy-load hero solo si es video, no si es solo gradient CSS

### 8.3 Critical CSS

Para landing pages: inline el CSS crítico del hero + navbar (los primeros 14KB) en `<style>`. Resto en `tailwind.min.css` con `defer`.

---

## 9. Brand voice in UI copy

### 9.1 Reglas generales

| Hacer | NO hacer |
|---|---|
| "Crear cuenta" | "Comienza tu viaje gratis" |
| "Hacer pedido" | "Sumarte a la revolución" |
| "Ahorro típico 15-25%" | "Ahorra hasta 50%" |
| "Despacho 10:00–16:00 al día siguiente" | "Despacho express" |
| "Sin contrato anual ni cuota fija" | "Sin compromisos!!" |
| "Restaurante" | "Negocio gastronómico" |

### 9.2 Errores

| ❌ Malo | ✅ Bueno |
|---|---|
| "Error: la operación falló" | "No pudimos guardar tu pedido. Revisá tu conexión y volvé a intentar." |
| "Usuario no autorizado" | "Necesitás iniciar sesión para ver esto. [Iniciar sesión]" |
| "Campo requerido" | "Necesitamos tu email para confirmar el pedido" |

### 9.3 Empty states

Siempre 3 elementos:
1. **Emoji ilustrativo** (60-72px)
2. **Headline descriptivo** ("Tu carrito está vacío")
3. **CTA + ayuda** ("Agregá productos para empezar [Ver catálogo]")

---

## 10. Files & artifacts

| Archivo | Path | Uso |
|---|---|---|
| Este doc | `DESIGN.md` | Source of truth |
| CSS tokens | `design-system/tokens.css` | Import en cualquier HTML/CSS |
| JS tokens | `design-system/tokens.json` | Import en React/Vue/Astro |
| Preview | `design-system/preview.html` | Visualizar todos los componentes |
| Logo SVG | `favicon.svg` | Brand mark vectorial |
| OG image | Cloudinary `dqzwqkgzr/...` | Imagen compartir redes |

---

## 11. Changelog

| Versión | Fecha | Cambios |
|---|---|---|
| 1.0 | 2026-06-10 | Initial — extraído de sociocompras.com Motor 2 |

---

## 12. Next steps

Después de aprobar este doc:

1. **Aplicar a `app.sociocompras.com`** — auditar la app actual contra este sistema, generar lista de gaps (componentes faltantes, inconsistencias)
2. **Crear Storybook / preview-html** — playground visual de todos los componentes
3. **Migrar a Tailwind config compartido** — si Motor 2 crece a múltiples webs, considerar publicar un npm package con los tokens
4. **Crear motion library** — animaciones reveal-on-scroll, page transitions, micro-interactions
5. **Dark mode opcional** para la app — actualmente la landing es dark-first, pero la app podría ofrecer light mode

---

> **Mantenimiento:** Este documento se actualiza con cada cambio mayor visual del sitio. Si agregás un nuevo componente, documentarlo acá antes de hacer merge. Si modificás un token, actualizar también `tokens.css` y `tokens.json` en la misma sesión.