159 lines
6.2 KiB
Markdown
159 lines
6.2 KiB
Markdown
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`.
|
||
|