Guía de Design Tokens — AvanzaCast
=================================

Propósito
--------
Esta guía centraliza los tokens de diseño usados por AvanzaCast (colores, tipografías, tamaños, espaciados y sombras). Está pensada para desarrolladores y diseñadores: explica los tokens disponibles, su uso semántico y mapas a clases de Tailwind ya configuradas en `packages/studio-panel/tailwind.config.cjs`.

Resumen rápido
---------------
- Paleta principal: tokens `studio-*` (bg, muted, accent, accent-2)
- Tipografías: `inter` (principal) y `requiner` (logo)
- Tamaños tipográficos: `figma-transmision`, `figma-personas`, `figma-h1`, `figma-h2`, `figma-base`
- Pesos: `figma-light`, `figma-regular`, `figma-medium`, `figma-bold`

Colores (paleta)
-----------------
Uso semántico y clases Tailwind (extendidas en `tailwind.config.cjs`):

- studio-bg — #41444A
  - Uso: fondo de header, barras principales.
  - Clase: `bg-studio-bg`.

- studio-dark — #12151D
  - Uso: fondos muy oscuros, overlays principales.
  - Clase: `bg-studio-dark`.

- studio-muted — #7E8791
  - Uso: texto secundario, subtítulos, metadatos.
  - Clase: `text-studio-muted`.

- studio-muted-2 — #77818F
  - Uso: texto alternativo, placeholders.
  - Clase: `text-studio-muted-2`.

- studio-accent — #3B82F6
  - Uso: acentos primarios (botones, enlaces activos).
  - Clase: `bg-studio-accent` (o `text-studio-accent`).

- studio-accent-2 — #EF4444
  - Uso: acento secundario / estado destructivo.
  - Clase: `bg-studio-accent-2`.

Tokens clásicos (utility mapping)
- Fondo principal: `bg-studio-bg` (header)
- Texto secundario: `text-studio-muted`
- Botón primario: `bg-studio-accent` o gradiente `from-blue-600 to-blue-500`
- Indicador en vivo: punto rojo `bg-red-500`

Tipografías y tamaños
---------------------
Font families (extendidas en Tailwind):
- `font-inter` -> Inter (principal UI)
- `font-requiner` -> Requiner (logo)

Tamaños definidos (tailwind custom):
- `text-[figma-h1]` = 32px / lineHeight 40px (clase generada: `text-[figma-h1]`)
- `text-[figma-h2]` = 24px / lineHeight 32px
- `text-[figma-transmision]` = 12.8px / lineHeight 15.5px
- `text-[figma-personas]` = 11.3px / lineHeight 13.7px
- `text-[figma-base]` = 16px / lineHeight 24px

Pesos semánticos (clases personalizadas en `tailwind.config.cjs`):
- `font-figma-light` -> 300
- `font-figma-regular` -> 400
- `font-figma-medium` -> 500
- `font-figma-bold` -> 700

Recomendaciones de uso tipográfico
- Titulares: `text-[figma-h1]` / `text-[figma-h2]` según jerarquía, `font-figma-medium` o `font-figma-bold`.
- Labels pequeños y metadatos: `text-[figma-personas]` + `font-figma-regular`.
- UI body copy: `text-[figma-base]` + `font-figma-regular`.

Espaciado (scale)
------------------
Recomiendo usar las utilidades de espacio de Tailwind (p, px, py, gap) con esta convención semántica:
- xs: 4px -> `p-1`, `gap-1`
- sm: 8px -> `p-2`, `gap-2`
- md (base): 12px -> `p-3`, `gap-3`
- lg: 16px -> `p-4`, `gap-4`
- xl: 24px -> `p-6`, `gap-6`

En el header aplicamos: `h-14` (56px), `gap-3` (12px) y `px-4` para los laterales.

Border-radius (radio)
---------------------
- `rounded-sm` ~ 4px
- `rounded-md` ~ 8px
- `rounded-full` -> 9999px (botones circulares)
- En Brand usamos `rounded-xl` (~12px) para el contenedor del logo.

Sombras y elevación
--------------------
- Elevación leve (cards, buttons): `shadow-sm` -> `box-shadow: 0 1px 2px rgba(...)`.
- Elevación media (modales): `shadow-lg`.
- Borde sutil en header: `border-b border-white/4`.

Iconografía y tamaños
---------------------
- Iconos pequeños: `w-4 h-4` (16px)
- Iconos medios: `w-5 h-5` (20px)
- Avatares / logos: 40–48px (`w-10` / `w-12`)

Estados y microinteracciones
----------------------------
- Hover: usar `hover:bg-white/6` o `hover:brightness-95` según el elemento.
- Focus visible: ya definimos en CSS global `:focus-visible` con outline azul; preferir `focus:outline-none` y rely en `focus-visible` para accesibilidad.
- Disabled: aplicar `opacity-50 cursor-not-allowed pointer-events-none`.

Ejemplos de uso (Tailwind)
--------------------------
- Header brand:
  - Contenedor: `flex items-center gap-3 min-w-0`
  - Título: `text-[figma-h2] font-figma-medium text-white`
  - Subtítulo: `text-[figma-transmision] font-figma-regular text-studio-muted`

- Live badge:
  - `inline-flex items-center gap-2 px-3 py-0.5 rounded-full bg-black/40 ring-1 ring-white/6 font-inter`
  - Punto: `w-2 h-2 rounded-full bg-red-500 animate-pulse`

- Botón primario (ej. Grabar):
  - `rounded-full inline-flex items-center gap-2 px-3 py-1 bg-gradient-to-br from-red-600 to-red-500 text-white shadow-sm`

Cómo mantener los tokens (developer notes)
-----------------------------------------
1. Centraliza tokens en `tailwind.config.cjs` dentro de `theme.extend` (colores, fontFamily, fontSize, fontWeight).
2. Evita usar colores hex en componentes: siempre usar `bg-studio-bg`, `text-studio-muted`, etc.
3. Si se necesita un nuevo token, agrégalo a `tailwind.config.cjs` y documenta aquí bajo "Actualizaciones" con fecha y autor.

Ejemplo: añadir un color token en `tailwind.config.cjs`
```js
// tailwind.config.cjs (theme.extend)
colors: {
  'studio-bg': '#41444A',
  'studio-muted': '#7E8791',
  // ...
}
```

Guía rápida de accesibilidad
----------------------------
- Siempre añadir `aria-label` en `IconButton` y `role=status` en badges dinámicos.
- Usar `sr-only` para mensajes redundantes de accesibilidad.
- Mantener contraste suficiente para texto y elementos interactivos (usar herramientas de contraste para verificar).

Mantenimiento y gobernanza
---------------------------
- Cada cambio de token debe registrar una entrada en este documento con la fecha y la razón.
- Mantener consistencia entre Figma y `tailwind.config.cjs`: al actualizar estilos en Figma, actualizar tokens y revisar componentes.

Historial y próximas acciones
-----------------------------
- 2025-11-10: Creación inicial de la guía y mapeo de tokens usados en `packages/studio-panel`.
- Próximo: extraer sombras y radios exactos desde Figma y sincronizar con `tailwind.config.cjs` si se requiere match pixel-perfect.

Contacto
--------
Si necesitas que incluya valores exactos extraídos de Figma (letter-spacing, exact color tokens, o exportar assets) indícalo y automatizo la extracción de tokens y la actualización de `tailwind.config.cjs`.