# Sistema de Color Viceversable — Reglas y Arquitectura

> **Valores de color → `design-tokens.json`** (fuente única de verdad)
> Este documento define las **reglas de uso**, no los valores. Para hex values, tokens CSS,
> tokens UI por modo, y semáforo, consultar `design-tokens.json`.

---

## Estructura del JSON

```
design-tokens.json
├── palette          → Hex values de toda la paleta (principales + 5 familias)
├── typography       → Font families
├── ui.light         → Tokens UI en light mode (bg, surface, raised, txt, border, nav)
├── ui.dark          → Tokens UI en dark mode
├── semantic.light   → Semáforo y badges en light mode
└── semantic.dark    → Semáforo y badges en dark mode
```

---

## Paleta principal — Roles

| Token | HEX | Rol |
|-------|-----|-----|
| `background` | `#F7F5F3` | Canvas principal |
| `surface` | `#F1ECE9` | Surface elevada cálida |
| `accent-soft` | `#D0B3FF` | Highlight, badges, zonas suaves |
| `accent` | `#A179FF` | Acento principal — CTAs, estados activos |
| `accent-deep` | `#8253F0` | Acento profundo, hover, énfasis secundario |
| `foreground` | `#1B071F` | Texto principal y dark canvas |

---

## Familias semánticas — Reglas de uso

Cada familia tiene 3 variantes: **tint** (fondo sutil) · **base** (vivid, dark mode) · **mid** (legible en light).

### Lima — Positivo · Rentable · Meta cumplida
Sobre fondos claros → solo `lima-mid`. `lima-base` únicamente sobre oscuro.

### Teal — Informativo neutro · Fases · Navegación
No es alerta, es información neutral. Para fases, estados "en progreso".

### Yellow — Atención · Vigilar · Pendiente (50–80%)


### Naranja — Riesgo · Ajustado · Alerta (80–100%)


### Rosa — Pérdida · Error crítico · Alerta (>100%)
Solo para lo verdaderamente crítico. Pérdidas confirmadas, errores reales.

---

## Capas de superficie en dark mode

La profundidad se logra por diferencia de superficie, no por bordes ni sombras.

```
bg (var(--violeta)) → surface (rgba(247,245,243,0.06)) → raised (rgba(247,245,243,0.10))
más oscuro                                  más claro
```

Bordes: solo con púrpura al 10-18% cuando sea necesario. Nunca blanco.
Esto alinea V-Dashboard con Voiceverse (vvSurface, vvSurfaceLight).

---

## Tokens Swift (Voiceverse / ViceversableTheme.swift)

| Swift | Token en JSON | Uso |
|-------|---------------|-----|
| `vvPurpura` | `palette.purpura` | Acento principal |
| `vvMorado` | `palette.morado` | Hover, secundario |
| `vvTeal` | `palette.teal-base` | Info neutral |
| `vvLima` | `palette.lima-base` | Positivo (dark) |
| `vvLimaDark` | `palette.lima-mid` | Positivo (light) |
| `vvYellow` | `palette.yellow-base` | Atención |
| `vvNaranja` | `palette.naranja-base` | Riesgo |
| `vvRosa` | `palette.rosa-base` | Error/crítico |
| `vvSuccess` | = vvLima | Alias semántico |
| `vvRecording` | = vvRosa | Alias semántico |
| `vvWarning` | = vvYellow | Alias semántico |

---

## Reglas absolutas

- **Nunca `box-shadow`** — la profundidad se logra con diferencia entre superficies.
- **Nunca colores vibrantes como texto sobre fondo claro** — usar siempre la variante `-mid`.
- **Los `-base` son exclusivos de dark mode** (o fondos muy oscuros).
- **El logo**: blanco sobre oscuro, `violeta` sobre claro.
- **Sin gradientes en UI** — solo en portadas y material editorial.
- **El sidebar siempre es oscuro**, independientemente del modo.
- **Texto sobre fondos tint**: usar la variante **mid** o violeta, nunca el base.
- **Siempre usar tokens `--sem-*`** cuando el color cambia según light/dark mode.
- **`slate` es solo decorativo** — nunca como texto funcional. Para texto secundario usar `txt-mid` (rgba(27,7,31,0.62)) que pasa WCAG AA.
- **`purpura` no es texto** sobre fondos claros — solo como fondo de CTA, badge o sobre superficies oscuras.