# UI_SKILL.md — Sistema de diseño Koin

Leer completo antes de construir o modificar cualquier componente visual.
Este skill define tanto el **qué** (stack, tokens) como el **cómo pensar** el diseño.

---

## 0. Filosofía de diseño — leer primero

Koin es una plataforma financiera B2B. El diseño comunica **confianza, precisión y control**.

### El estilo es: *data-dense, editorial, professional*

- **Información densa pero legible.** No hay espacio desperdiciado. Cada pixel tiene función.
- **Jerarquía visual a través de estructura, no de efectos.** No usar gradientes, sombras dramáticas, animaciones llamativas, ni ilustraciones decorativas para comunicar importancia. La jerarquía se logra con tipografía, espaciado y color funcional.
- **El verde Koin (`#10B132`) es un acento, no un fondo.** Aparece en acciones primarias, estados activos y métricas clave. No saturar la UI con él.
- **Sin decoración genérica de AI.** Prohibido: emojis, iconos decorativos sin función, gradientes de fondo, cards con sombra dramática, ilustraciones de relleno, skeletons innecesarios.
- **Untitled UI es el piso, no el techo.** Usar sus componentes como base. Cuando la composición lo requiera, ajustar spacing, tipografía o layout sin salirse de los tokens del sistema.

### Referencia visual de estilo

El producto se parece a: Linear, Stripe Dashboard, Vercel, Retool.
- Fondos neutros claros
- Tipografía Inter bien ajustada
- Cards con bordes sutiles, sin sombra excesiva
- Datos tabulares limpios
- Badges semánticos (no decorativos)
- Métricas destacadas con número grande + label pequeño

### Lo que distingue a Koin visualmente

- Score prominente (gauge/número grande) cuando hay una métrica principal
- Secciones colapsables con header clickeable y "ver más / ver menos"
- Insights textuales con color semántico (rojo para alertas, verde para positivos)
- Información organizada en grids de 2-4 columnas dentro de cards, no en listas verticales
- Labels en 11-12px uppercase o gray-500, valores en gray-900

---

## 1. Stack de UI

- **Framework:** React (Vite)
- **Componentes:** Untitled UI React — https://www.untitledui.com/react/components
- **Tema base:** https://github.com/otomendes/keystone-vibe — clonar, no partir de cero
- **Estilos:** Tailwind CSS (incluido en Untitled UI)
- **Tipografía:** Inter (única fuente, distintos pesos hacen la jerarquía)
- **Iconos:** Untitled UI Icons — no mezclar con otras librerías

**Regla:** Antes de crear un componente custom, verificar si existe en Untitled UI. Si existe, usar ese y ajustar tokens si es necesario.

---

## 2. Colores — Koin Keystone Design System

No inventar colores fuera de esta paleta. Fuente: PDF "Colors — KEYSTONE UI kit © 2024 KOIN".

### Gray
```
25:  #FCFCFD   50:  #F9FAFB   100: #F2F4F7   200: #EAECF0   300: #D0D5DD
400: #98A2B3   500: #667085   600: #475467   700: #344054   800: #182230
900: #101828   950: #0C111D
```

### Brand (verde Koin)
```
brand-600:   #10B132   ← acento principal, acciones, estados activos
brand-light: #F6FEF9   ← fondos de estados activos (muy sutil)
brand-mid:   #DCFAE6   ← bordes suaves en estados activos
brand-dark:  #067647   ← texto sobre fondos brand claros
```

### Semánticos
```
success-50:  #ECFDF3   success-600: #079455   success-700: #067647
error-50:    #FEF3F2   error-600:   #D92D20
warning-50:  #FFFAEB   warning-600: #DC6803
```

### Aplicación de color
| Elemento | Color |
|---|---|
| Fondo de página | gray-50 `#F9FAFB` |
| Superficies (cards, sidebar, topbar) | white |
| Bordes default | gray-200 `#EAECF0` |
| Bordes hover | gray-300 |
| Texto principal | gray-900 |
| Texto secundario | gray-500 / gray-600 |
| Labels / metadata | gray-400 / gray-500 |
| Placeholder | gray-400 |
| Acento / interactivo | brand-600 `#10B132` |
| Nav activo — fondo | brand-light |
| Nav activo — texto / borde izq | brand-600 |
| Alerta positiva | success-600, fondo success-50 |
| Alerta negativa | error-600, fondo error-50 |
| Alerta neutra/warning | warning-600, fondo warning-50 |

---

## 3. Tipografía

Inter, siempre. La jerarquía se construye con peso y tamaño, no con fuentes distintas.

| Uso | Peso | Tamaño | Color |
|---|---|---|---|
| Título de página / métrica principal | 600 | 24-28px | gray-900 |
| Títulos de sección / card header | 600 | 14px | gray-900 |
| Labels de datos | 500 | 12px | gray-500 |
| Cuerpo / valores | 400 | 14px | gray-900 |
| Texto secundario / metadata | 400 | 13px | gray-500 |
| Badges | 500 | 11–12px | semántico |
| Código | 400 | 12px mono | brand-600 sobre gray-900 |
| Insights / alertas inline | 500 | 13px | semántico (error/success/warning) |

**Regla:** Si un valor de dato es importante, ponerlo en gray-900 peso 500-600. El label que lo describe va en gray-500 peso 400, tamaño menor.

---

## 4. Composición de cards y secciones

### Card estándar
```
border: 1px solid #EAECF0
border-radius: 8px
background: white
padding: 16-20px
shadow-sm: 0 1px 2px rgba(16,24,40,0.05)
```

### Header de sección colapsable (patrón Koin)
```
[Icono] Nombre de sección          ver más / ver menos →
────────────────────────────────────────────────────────
```
- Header clickeable, colapsa/expande el contenido
- Icono: 16px, color semántico o gray-500
- Texto header: 14px 600 gray-900
- Acción: 13px 500 brand-600, cursor pointer

### Grid de datos dentro de card
Organizar información en grids, no en listas. Preferir 2-4 columnas.
```
Label        Label        Label        Label
Valor        Valor        Valor        Valor

Label        Label        Label        Label
Valor        Valor        Valor        Valor
```
- Label: 11px 500 gray-500 (puede ir uppercase)
- Valor: 13-14px 400-500 gray-900
- Gap entre columnas: 16-24px
- Gap entre filas: 12-16px

### Métricas destacadas (score, número principal)
Cuando hay una métrica clave (score, porcentaje, conteo importante):
- Número: 28-36px 600 gray-900
- Label debajo: 12px 400 gray-500
- Si tiene indicador de riesgo: badge semántico a la derecha del título

### Insights inline (lista de hallazgos)
```
● SIM swap detectado hace 15 días          ← error-600
● Email en 3 vazamentos de dados           ← error-600  
● 3 consultas de crédito en últimos 30d    ← warning-600
● Zero chargebacks en el historial         ← success-600
● Cliente hace 4 años en la red Koin       ← success-600
```
- Bullet + texto, 13px 500
- Color semántico según severidad
- Sin fondo, sin badge, solo texto con color

---

## 5. Layout general del portal

```
┌─────────────────────────────────────────────────────────┐
│  TOPBAR  64px                                            │
│  breadcrumb (izq)              progreso global (der)     │
├─────────────┬───────────────────────────────────────────┤
│             │  BARRA DE PROGRESO GLOBAL (6px, sin gap)  │
│  SIDEBAR    ├───────────────────────────────────────────┤
│  240px      │                                           │
│  fixed      │  CONTENT AREA                             │
│             │  padding 24px, fondo gray-50              │
│             │  scroll vertical                          │
└─────────────┴───────────────────────────────────────────┘
```

### Barra de progreso global — OBLIGATORIA
- Altura: 6px, sin border-radius
- Fondo: gray-100, relleno: brand-600
- Texto: `X% completado`, 12px 500 gray-500, arriba a la izquierda
- Transición: `width 0.6s ease`
- Cálculo: 8 pasos × 12.5% cada uno

### Sidebar (8 pasos)
```
[Logo Koin]  "Onboarding clientes"

  1  Alta como cliente              [badge]
  2  Comercios                      [badge]
  3  Información del negocio        [badge]
  4  Revisión manual                [badge]
  5  Consentimiento del speech      [badge]
  6  Usuarios                       [badge]
  7  Marca                          [badge]
  8  Estrategias                    [badge]

── DOCUMENTACIÓN ──
  docs/ y manuals/

── Sesión ──
  [nombre cliente]
  [email]
```

### Topbar
```
Izq: "Onboarding / Paso N — Nombre del paso"
Der: "Progreso global   X de 8 pasos completos"
```

---

## 6. Estados de pasos en el sidebar

| Estado | Visual número | Badge |
|---|---|---|
| Pendiente | círculo gray-200, número gray-400 | "Pendiente" gray-100/400 |
| En progreso | círculo brand-600, número white | "En progreso" brand-light/600 |
| Completado | círculo success-50, check success-600 | "Listo" success-50/600 |

Item activo: `background brand-light`, `border-left: 2px solid brand-600`.

---

## 7. Sombras y bordes

```
shadow-sm:  0 1px 2px rgba(16,24,40,0.05)
shadow-md:  0 4px 8px -2px rgba(16,24,40,0.1)
border:     1px solid #EAECF0
focus:      border brand-600 + ring rgba(16,177,50,0.12)
radius:     sm=6  md=8  lg=12  xl=16  full=9999  (px)
```

---

## 8. Paso 8 — Estrategias (chat)

Tres niveles: selector de estrategia → canal → chat.

### Chat layout
```
┌──────────────────────────────────────┬──────────────────────┐
│  CHAT  (flex: 1, height: 100%)       │  PANEL  (320px)      │
│  ┌─ Header: avatar + estado ────────┐│  ┌─ Progreso ───────┐│
│  ├─ Barra progreso flujo (4px) ─────┤│  │  sub-paso activo  ││
│  │  área mensajes (flex:1, scroll)  ││  └──────────────────┘│
│  ├─ Botones opciones ───────────────┤│  ┌─ Documentos ─────┐│
│  └─ Input + Enviar ────────────────┘│  │  PDF + MD links   ││
└──────────────────────────────────────┴──┴──────────────────┘
```

Altura: `calc(100vh - topbar - barra progreso - padding)`

### Chat — estilo visual (tema claro siempre)

| Elemento | Valor |
|---|---|
| Fondo área mensajes | gray-50 |
| Burbuja bot | white, border gray-200, shadow-sm, radius 4px 12px 12px 12px |
| Burbuja usuario | gray-900 bg, white text, radius 12px 4px 12px 12px |
| Avatar bot | gray-900 bg, brand-600 text, border-radius 8px |
| Avatar usuario | iniciales, brand-light bg, brand-600 text |
| Botón primario | gray-900 bg, white text |
| Botones secundarios | white bg, gray-300 border, gray-600 text |
| Input | border gray-300, focus: brand-600 + ring |
| Botón Enviar | brand-600 bg, white text |
| Tip | border-left 2px brand-600, bg rgba(16,177,50,0.05) |
| Warning | border-left 2px warning-600, bg warning-50 |
| Ok | border-left 2px success-600, bg success-50 |
| Código | gray-900 bg, brand-600 text, mono, border-left 3px brand-600 |

---

## 9. Componentes Untitled UI

| Componente | Untitled UI | Dónde |
|---|---|---|
| Sidebar | `sidebar-navigations` | Layout global |
| Page header | `page-headers` | Cada paso |
| Progress bar | `progress-indicators` | Barra global + flujo |
| Cards seleccionables | `radio-groups` | Paso 8 nivel 1 y 2 |
| Form inputs | `inputs` | Pasos 1, 3, 4 |
| File uploader | `file-uploaders` | Pasos 1, 7 |
| Tablas / toggles | `tables` / `toggles` | Pasos 2, 6 |
| Progress steps | `progress-steps` | Panel lateral chat |
| Badges | `badges` | Estados |
| Alerts | `alerts` | Tips/warnings en chat |
| Chat | `messaging` | Paso 8 |
| Code snippets | `code-snippets` | Scripts en chat |
| Empty states | `empty-states` | Canales/estrategias pendientes |

---

## 10. Anti-patrones — nunca hacer

- Emojis en la UI (ni en títulos, ni en mensajes del sistema, ni en badges)
- Gradientes de fondo o en cards
- Sombras dramáticas (`box-shadow` grandes)
- Ilustraciones decorativas sin función
- Iconos mezclados de librerías distintas
- Cards con colores de fondo saturados
- Animaciones que no comunican estado
- Texto en mayúsculas largas (solo labels cortos, máx 2-3 palabras)
- Tema oscuro (solo en bloques de código)
- HTML vanilla sin React
- Colores fuera de la paleta Keystone
- Chat que no ocupa el viewport disponible

---

## 11. Decisiones de diseño al construir — checklist mental

Antes de escribir código, responder:

1. **¿Qué información es la más importante en esta pantalla?** → Va más grande, más arriba, gray-900.
2. **¿Hay una métrica principal?** → Score o número destacado, no enterrado en una card igual a las demás.
3. **¿La información se puede organizar en grid?** → Siempre preferir grid sobre lista vertical.
4. **¿Estoy usando color para decorar o para comunicar estado?** → Solo lo segundo.
5. **¿Hay algún elemento que no tenga función?** → Sacarlo.
6. **¿Untitled UI tiene este componente?** → Usarlo. Si necesito ajustarlo, ajustar tokens, no crear desde cero.
7. **¿Se ve como un producto de análisis financiero serio?** → Si parece un landing page o una app de consumo, algo está mal.

---

## 12. Checklist antes de deploy

- [ ] Barra de progreso global visible, % correcto (8 pasos × 12.5%)
- [ ] Chat ocupa todo el alto disponible del viewport en paso 8
- [ ] Paso 8: selector estrategia → canal → chat funcionando
- [ ] Solo estrategias contratadas visibles
- [ ] Sub-paso activo resaltado en panel lateral
- [ ] Documentos del panel apuntan a archivos reales del repo
- [ ] Pasos 1–7 funcionales
- [ ] Sidebar: 8 ítems, estados actualizados
- [ ] Tema claro en todo el portal (excepto bloques de código)
- [ ] Sin emojis, sin gradientes, sin ilustraciones decorativas
- [ ] Responsive
- [ ] Checklist de `CHATBOT_SKILL.md` sección 9 pasado