borghei/ui-design-system

Sistema de Diseño UI

Genera tokens de diseño, crea paletas de colores, calcula escalas tipográficas, construye sistemas de componentes y prepara documentación para la entrega a desarrolladores.

---

Tabla de Contenidos

• Términos de Activación
• Flujos de Trabajo
  • Flujo de Trabajo 1: Generar Tokens de Diseño
  • Flujo de Trabajo 2: Crear Sistema de Componentes
  • Flujo de Trabajo 3: Diseño Responsivo
  • Flujo de Trabajo 4: Entrega a Desarrolladores
• Referencia de Herramientas
• Tablas de Referencia Rápida
• Base de Conocimiento

---

Términos de Activación

Usa esta habilidad cuando necesites:

• "generar tokens de diseño"
• "crear paleta de colores"
• "construir escala tipográfica"
• "calcular sistema de espaciado"
• "crear sistema de diseño"
• "generar variables CSS"
• "exportar tokens SCSS"
• "configurar arquitectura de componentes"
• "documentar librería de componentes"
• "calcular breakpoints responsivos"
• "preparar entrega a desarrolladores"
• "convertir color de marca a paleta"
• "verificar contraste WCAG"
• "construir sistema de cuadrícula 8pt"

---

Primero, Aclarar

Antes de generar los tokens o el sistema, establece las entradas a continuación. Cuando falte una o sea vaga y cambiaría el resultado, pregúntalo; cuando no sea así, usa un valor predeterminado sensato y menciona cuál usaste.

• Color primario de la marca (hex): la semilla para la paleta completa (guía la escala de colores y las comprobaciones de contraste WCAG).
• Preajuste de estilo: moderno, clásico o divertido (define fuentes, radio de borde y estilo de sombra).
• Formato de salida y framework: CSS, SCSS o JSON para Tailwind/styled-components/Figma (guía la exportación y la entrega a desarrolladores).

Pregunta por las dos o tres entradas que más importan para esta solicitud, no por toda la lista. Si el usuario quiere un resultado de inmediato, prodúcelo y menciona tus suposiciones al principio.

Flujos de Trabajo

Flujo de Trabajo 1: Generar Tokens de Diseño

Situación: Tienes un color de marca y necesitas un sistema completo de tokens de diseño.

Pasos:

1. Identificar el color de marca y el estilo

   • Color primario de la marca (formato hex)
   • Preferencia de estilo: moderno | clásico | divertido

2. Generar tokens usando el script

   python scripts/design_token_generator.py "#0066CC" moderno json
   

3. Revisar las categorías generadas

   • Colores: primario, secundario, neutro, semántico, superficie
   • Tipografía: fontFamily, fontSize, fontWeight, lineHeight
   • Espaciado: escala basada en cuadrícula de 8pt (0-64)
   • Bordes: radio, ancho
   • Sombras: ninguna hasta 2xl
   • Animación: duración, easing
   • Breakpoints: xs hasta 2xl

4. Exportar al formato deseado

   # Propiedades personalizadas CSS
   python scripts/design_token_generator.py "#0066CC" moderno css > design-tokens.css
   
   # Variables SCSS
   python scripts/design_token_generator.py "#0066CC" moderno scss > _design-tokens.scss
   
   # JSON para Figma/herramientas
   python scripts/design_token_generator.py "#0066CC" moderno json > design-tokens.json
   

5. Validar accesibilidad

   • Verificar que el contraste de color cumpla con WCAG AA (4.5:1 texto normal, 3:1 texto grande)
   • Asegurar que los colores semánticos tengan colores de contraste definidos

---

Flujo de Trabajo 2: Crear Sistema de Componentes

Situación: Necesitas estructurar una librería de componentes utilizando tokens de diseño.

Pasos:

1. Definir la jerarquía de componentes

   • Átomos: Botón, Input, Icono, Etiqueta, Insignia
   • Moléculas: CampoFormulario, BarraBusqueda, Tarjeta, ElementoLista
   • Organismos: Encabezado, PiePagina, TablaDatos, Modal
   • Plantillas: DiseñoPanel, DiseñoAuth

2. Mapear tokens a componentes

   Componente	Tokens Usados
   Botón	colores, tamaño, bordes, sombras, tipografía
   Input	colores, tamaño, bordes, espaciado
   Tarjeta	colores, bordes, sombras, espaciado
   Modal	colores, sombras, espaciado, z-index, animación

3. Definir patrones de variantes

   Variantes de tamaño:

   sm: altura 32px, paddingX 12px, fontSize 14px
   md: altura 40px, paddingX 16px, fontSize 16px
   lg: altura 48px, paddingX 20px, fontSize 18px
   

   Variantes de color:

   primario: fondo primary-500, texto white
   secundario: fondo neutral-100, texto neutral-900
   fantasma: fondo transparent, texto neutral-700
   

4. Documentar la API del componente

   • Interfaz de props con tipos
   • Opciones de variantes
   • Manejo de estados (hover, active, focus, disabled)
   • Requisitos de accesibilidad

5. Referencia: Consulta references/component-architecture.md

---

Flujo de Trabajo 3: Diseño Responsivo

Situación: Necesitas breakpoints, tipografía fluida o espaciado responsivo.

Pasos:

1. Definir breakpoints

   Nombre	Ancho	Objetivo
   xs	0	Teléfonos pequeños
   sm	480px	Teléfonos grandes
   md	640px	Tablets
   lg	768px	Laptops pequeños
   xl	1024px	Escritorios
   2xl	1280px	Pantallas grandes

2. Calcular tipografía fluida

   Fórmula: clamp(mínimo, preferido, máximo)

   /* 16px a 24px entre 320px y 1200px de viewport */
   font-size: clamp(1rem, 0.5rem + 2vw, 1.5rem);
   

   Escalas precalculadas:

   --fluid-h1: clamp(2rem, 1rem + 3.6vw, 4rem);
   --fluid-h2: clamp(1.75rem, 1rem + 2.3vw, 3rem);
   --fluid-h3: clamp(1.5rem, 1rem + 1.4vw, 2.25rem);
   --fluid-body: clamp(1rem, 0.95rem + 0.2vw, 1.125rem);
   

3. Configurar espaciado responsivo

   Token	Móvil	Tablet	Escritorio
   --space-md	12px	16px	16px
   --space-lg	16px	24px	32px
   --space-xl	24px	32px	48px
   --space-section	48px	80px	120px

4. Referencia: Consulta references/responsive-calculations.md

---

Flujo de Trabajo 4: Entrega a Desarrolladores

Situación: Necesitas entregar tokens de diseño al equipo de desarrollo.

Pasos:

1. Exportar tokens en los formatos requeridos

   # Para proyectos CSS
   python scripts/design_token_generator.py "#0066CC" moderno css
   
   # Para proyectos SCSS
   python scripts/design_token_generator.py "#0066CC" moderno scss
   
   # Para JavaScript/TypeScript
   python scripts/design_token_generator.py "#0066CC" moderno json
   

2. Preparar la integración con el framework

   React + Variables CSS:

   import './design-tokens.css';
   
   <button className="btn btn-primary">Click</button>
   

   Configuración de Tailwind:

   const tokens = require('./design-tokens.json');
   
   module.exports = {
     theme: {
       colors: tokens.colors,
       fontFamily: tokens.typography.fontFamily
     }
   };
   

   styled-components:

   import tokens from './design-tokens.json';
   
   const Button = styled.button`
     background: ${tokens.colors.primary['500']};
     padding: ${tokens.spacing['2']} ${tokens.spacing['4']};
   `;
   

3. Sincronizar con Figma

   • Instala el plugin Tokens Studio
   • Importa design-tokens.json
   • Los tokens se sincronizan automáticamente con los estilos de Figma

4. Lista de verificación de entrega

   • Archivos de tokens añadidos al proyecto
   • Pipeline de compilación configurado
   • Variables de Tema/CSS importadas
   • Librería de componentes alineada
   • Documentación generada

5. Referencia: Consulta references/developer-handoff.md

---

Referencia de Herramientas

design_token_generator.py

Genera un sistema completo de tokens de diseño a partir de un color de marca.

Argumento	Valores	Predeterminado	Descripción
brand_color	Color hex	#0066CC	Color primario de la marca
style	moderno, clásico, divertido	moderno	Preajuste de estilo de diseño
format	json, css, scss, summary	json	Formato de salida

Ejemplos:

# Generar tokens JSON (predeterminado)
python scripts/design_token_generator.py "#0066CC"

# Estilo clásico con salida CSS
python scripts/design_token_generator.py "#8B4513" clasico css

# Estilo divertido vista resumen
python scripts/design_token_generator.py "#FF6B6B" divertido summary

Categorías de Salida:

Categoría	Descripción	Valores Clave
colors	Paletas de colores	primario, secundario, neutro, semántico, superficie
typography	Sistema de fuentes	fontFamily, fontSize, fontWeight, lineHeight
spacing	Cuadrícula 8pt	Escala 0-64, semántico (xs-3xl)
sizing	Tamaños de componente	container, button, input, icon
borders	Valores de borde	radio (por estilo), ancho
shadows	Estilos de sombra	none hasta 2xl, inner
animation	Tokens de movimiento	duration, easing, keyframes
breakpoints	Responsivo	xs, sm, md, lg, xl, 2xl
z-index	Sistema de capas	base hasta notification

---

Tablas de Referencia Rápida

Generación de Escala de Color

Paso	Brillo	Saturación	Caso de Uso
50	95% fijo	30%	Fondos sutiles
100	95% fijo	38%	Fondos claros
200	95% fijo	46%	Estados hover
300	95% fijo	54%	Bordes
400	95% fijo	62%	Estados deshabilitados
500	Original	70%	Color base/predeterminado
600	Original × 0.8	78%	Hover (oscuro)
700	Original × 0.6	86%	Estados activos
800	Original × 0.4	94%	Texto
900	Original × 0.2	100%	Encabezados

Escala Tipográfica (Relación 1.25x)

Tamaño	Valor	Cálculo
xs	10px	16 ÷ 1.25²
sm	13px	16 ÷ 1.25¹
base	16px	Base
lg	20px	16 × 1.25¹
xl	25px	16 × 1.25²
2xl	31px	16 × 1.25³
3xl	39px	16 × 1.25⁴
4xl	49px	16 × 1.25⁵
5xl	61px	16 × 1.25⁶

Requisitos de Contraste WCAG

Nivel	Texto Normal	Texto Grande
AA	4.5:1	3:1
AAA	7:1	4.5:1

Texto grande: ≥18pt regular o ≥14pt negrita

Preajustes de Estilo

Aspecto	Moderno	Clásico	Divertido
Fuente Sans	Inter	Helvetica	Poppins
Fuente Mono	Fira Code	Courier	Source Code Pro
Radio Predeterminado	8px	4px	16px
Sombras	En capas, sutiles	Capa única	Suaves, pronunciadas

---

Base de Conocimiento

Guías de referencia detalladas en references/:

Archivo	Contenido
token-generation.md	Algoritmos de color, espacio HSV, contraste WCAG, escalas tipográficas
component-architecture.md	Diseño atómico, convenciones de nomenclatura, patrones de props
responsive-calculations.md	Breakpoints, tipografía fluida, sistemas de cuadrícula
developer-handoff.md	Formatos de exportación, configuración de frameworks, sincronización con Figma

---

Lista de Verificación de Validación

Generación de Tokens

• Color de marca proporcionado en formato hex
• El estilo coincide con los requisitos del proyecto
• Todas las categorías de tokens generadas
• Los colores semánticos incluyen valores de contraste

Sistema de Componentes

• Todos los tamaños implementados (sm, md, lg)
• Todas las variantes implementadas (primario, secundario, fantasma)
• Todos los estados funcionan (hover, active, focus, disabled)
• Usa solo tokens de diseño (sin valores codificados)

Accesibilidad

• El contraste de color cumple con WCAG AA
• Los indicadores de foco son visibles
• Los objetivos táctiles tienen ≥ 44×44px
• Se usan elementos HTML semánticos

Entrega a Desarrolladores

• Tokens exportados en el formato requerido
• Integración con el framework documentada
• Herramienta de diseño sincronizada
• Documentación del componente completa

---

Solución de Problemas

Problema	Causa	Solución
Los colores generados no cumplen con el contraste WCAG	El color de la marca es demasiado claro o saturado	Usa tonos más oscuros (600+) para texto sobre fondos claros; verifica con una herramienta de contraste
La exportación de tokens tiene valores incorrectos	Argumento de formato incorrecto o sintaxis de color incorrecta	Asegúrate de que el color hex esté entre comillas (ej. "#0066CC"); verifica que el formato sea json, css o scss
La escala tipográfica es demasiado grande/pequeña	La relación 1.25x predeterminada no se ajusta al diseño	Modifica type_scale_ratio en la clase DesignTokenGenerator (1.125 para más ajustado, 1.333 para más suelto)
Las variables SCSS entran en conflicto con las existentes	Colisión de nombres de tokens	Prefija todos los tokens con el espacio de nombres del proyecto (edita la función de exportación)
Las herramientas de diseño muestran colores diferentes	Redondeo de hex en la generación de la escala de color	Usa la exportación JSON como fuente de verdad; sincroniza con el plugin Tokens Studio
Los valores de espaciado no se alinean con la cuadrícula	Espaciado personalizado mezclado con la cuadrícula de 8pt	Usa solo valores del sistema de espaciado generado; evita valores de píxel arbitrarios
Los tokens de sombra se ven incorrectos en modo oscuro	Sombras diseñadas para fondos claros	Crea tokens de sombra separados para el modo oscuro con valores de opacidad más claros

---

Criterios de Éxito

Criterio	Objetivo	Cómo Medir
Consistencia de tokens	Cero valores de color/espaciado codificados en el código base	Conteo de violaciones de reglas de lint
Cumplimiento WCAG AA	Todos los colores de texto cumplen con una relación de contraste 4.5:1	Comprobador de contraste automatizado o auditoría manual
Cobertura de formato de exportación	CSS, SCSS y JSON se generan correctamente	Ejecuta el generador con cada formato; valida la salida
Sincronización diseño-desarrollo	<24h entre la actualización del token y el despliegue del código	Tiempo desde el cambio en Figma hasta la producción
Cobertura de tokens en componentes	El 100% de los componentes usan tokens de diseño	Audita los estilos de componentes en busca de valores codificados
Consistencia tipográfica	Todo el texto usa la escala tipográfica del sistema de diseño	Auditoría visual en todas las páginas
Comportamiento responsivo	La tipografía fluida funciona en todos los breakpoints	Prueba en anchos xs, sm, md, lg, xl, 2xl

---

Alcance y Limitaciones

Dentro del alcance:

• Generación completa de tokens de diseño a partir del color de marca
• Generación de paletas de colores (primario, secundario, neutro, semántico)
• Sistema tipográfico con escala modular
• Sistema de espaciado basado en cuadrícula 8pt
• Tokens de tamaño de componente, borde, sombra, animación
• Exportación a propiedades personalizadas CSS, variables SCSS y JSON
• Definiciones de breakpoints responsivos
• Tablas de referencia de contraste WCAG

Fuera del alcance:

• Generación de tokens para modo oscuro (requiere mapeo de paleta separado)
• Librería de animación/movimiento de diseño
• Generación de sistema de iconos
• Implementación de cambio de tema en tiempo de ejecución
• Integración con plugin o API de Figma (usa Tokens Studio)
• Pruebas de regresión visual
• Conversión de diseño a código (usa Figma Dev Mode o Locofy)

---

Puntos de Integración

…

[truncado para traducción]