neoris/AvanzaCast
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
AvanzaCast/docs/design-tokens.md

6.2 KiB
Raw Permalink Blame History

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

// 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.