TomasValleDuran/design-system-builder

Constructor de Sistemas de Diseño

Un sistema de diseño es un conjunto de decisiones tomadas una vez para que cada pantalla no las vuelva a decidir. Los tokens contienen las decisiones, los componentes las aplican, la documentación las explica. Escala el esfuerzo al proyecto: una aplicación de fin de semana necesita un archivo de tokens de 40 líneas y un DESIGN.md; un producto con múltiples equipos necesita pipelines y gobernanza. Empieza pequeño, crece por extracción.

Proceso

0. Lee lo que existe

Busca: archivos de tokens/tema, configuración de tailwind o bloques @theme, components.json, variables CSS, un módulo theme/, enlaces de Figma (usa el MCP de Figma get_variable_defs/search_design_system si está conectado), DESIGN.md/.interface-design/system.md. En bases de código existentes, extrae antes de inventar: busca los colores, tamaños de fuente, espaciados y radios realmente usados, agrúpalos y propón la escala consolidada. Muestra al usuario el mapeo antes→después.

1. Define la dirección (un párrafo)

Quién lo usa, cómo debería sentirse (en palabras concretas: "denso como un terminal de trading", "tranquilo como una app de lectura"), plataforma(s), restricciones de marca, densidad, claro/oscuro. Esto guía cada elección de escala a continuación. Si skills de interface-design o frontend-design están en juego, ellos son dueños de este paso estético; este skill convierte la dirección en un sistema.

2. Fundamentos (tokens)

Construye en este orden — cada uno depende del anterior:

1. Color → ejecuta la herramienta del skill color-theory: python3 <ruta-skills>/color-theory/scripts/palette.py system <hex-marca> --format tailwind|css|json (color-theory es un hermano del directorio de este skill). Produce rampas primitivas + roles semánticos claro/oscuro verificados.
2. Tipografía → familias de fuentes (≤2, más mono), una escala tipográfica con roles nombrados, alturas de línea, pesos, tracking. Ver references/scales.md.
3. Espacio → cuadrícula base de 4px; escala tipo camiseta o numérica; espaciado de diseño separado del padding de componentes.
4. Forma → escala de radio (y una regla para anidar: radio interior = radio exterior − padding), anchos de borde.
5. Elevación → escala de sombras (claro) y pasos de luminosidad de superficie (oscuro), capas de z-index.
6. Movimiento → duraciones + curvas de easing como tokens (y comportamiento de movimiento reducido).
7. Diseño → puntos de ruptura, anchos de contenedor, columnas de cuadrícula, áreas seguras (móvil).
8. Tamaño → alturas de control (sm/md/lg), tamaños de icono, objetivo táctil mínimo.

3. Arquitectura de tokens

Tres niveles — los componentes solo deben consumir el nivel semántico (o de componente):

primitivo   --blue-600, --space-4, --radius-2          valores crudos, nombrados por lo que SON
semántico   --color-accent, --space-inset-md, --radius-control   nombrados por su TRABAJO, alias de primitivos, cambian por tema
componente  --button-bg, --card-padding                 opcional; solo para componentes con necesidades reales de tematización

Cambio de tema (modo oscuro, marcas, densidad, alto contraste) = reasignar tokens semánticos. Los componentes nunca cambian. Reglas completas de nombres, formato DTCG, modos: references/token-architecture.md.

4. Despliega a la(s) plataforma(s)

• Aplicación web única: variables CSS escritas a mano + @theme de Tailwind v4 es suficiente.
• Web + móvil, o múltiples aplicaciones: autoría de tokens en JSON DTCG (una fuente), construye con Style Dictionary v5 o Terrazzo para CSS, Tailwind, TS, Swift, Kotlin/Compose, Flutter, RN. Recetas y ejemplos de salida por plataforma: references/platform-outputs.md. Archivo DTCG de inicio: assets/tokens.example.json.

5. Componentes

Construye sobre primitivos accesibles (ver ui-stack-advisor). API consistente: variant (intención visual), size, tone/color solo si es necesario, estados mediante atributos de datos, composición sobre configuración. Cada componente documenta todos los estados: por defecto, hover, activo, focus-visible, deshabilitado, cargando, error, vacío, seleccionado, solo lectura. Convenciones y lista de verificación: references/components.md.

6. Documenta y gobierna

Escribe DESIGN.md en la raíz del proyecto a partir de assets/DESIGN.template.md — dirección, tabla de tokens, inventario de componentes, hacer/no hacer, y el por qué detrás de las decisiones. Este archivo es lo que las sesiones futuras leen para mantenerse consistentes; mantenlo breve y actualizado. Sistemas más grandes añaden Storybook (o Ladle/Histoire), regresión visual, un changelog con semver y un proceso de contribución (references/components.md#governance).

Valores por defecto que funcionan (cuando el usuario no tiene preferencia)

Fundamento	Por defecto
Unidad base	4px; escala de espaciado: 0, 1, 2, 4, 6, 8, 12, 16, 20, 24, 32, 40, 48, 64, 80, 96 px
Escala tipográfica	12, 14, 16 (cuerpo), 18, 20, 24, 30, 36, 48, 60 px (≈1.2–1.25 de ratio); las UIs de producto pueden usar cuerpo de 14px
Altura de línea	1.5 para cuerpo, 1.2–1.3 para encabezados, 1.1 para displays; ajusta el tracking en tamaños grandes (−0.01 a −0.03em)
Radio	0, 4, 6, 8, 12, 16, 24, completo — elige una personalidad: afilado (2–4), suave (8–12), redondo (16+) y aplícala consistentemente
Controles	alturas 32 / 36–40 / 44–48 px; objetivos táctiles ≥ 44pt (iOS) / 48dp (Android) / 24px mínimo WCAG 2.2 (apunta a 44)
Movimiento	100 / 150 / 200 / 300 / 500 ms; ease-out cubic-bezier(0.23,1,0.32,1) para entrada, ease-in-out para movimiento, resortes en móvil
Puntos de ruptura	640, 768, 1024, 1280, 1536 (Tailwind); prefiere consultas de contenedor para componentes
Elevación	4–5 niveles de sombra; modo oscuro usa superficies más claras + bordes sutiles en su lugar
Z-index	base 0, desplegable 1000, sticky 1100, superposición 1300, modal 1400, popover 1500, toast 1600, tooltip 1700

Los valores por defecto son un piso, no un estilo. La distintividad proviene de las elecciones que varían: tipografía, tono de acento, temperatura neutra, personalidad del radio, densidad y carácter del movimiento.

Barra de calidad (verifica antes de dar por terminado)

• Sin valores crudos en componentes (hex, tamaños de fuente en px, espaciado arbitrario) — búscalos
• Los nombres semánticos describen trabajos, no valores o tonos
• Claro + oscuro ambos diseñados y verificados por contraste (WCAG 2.2 AA)
• Cada componente interactivo tiene estados visibles de foco, deshabilitado, cargando y error
• La escala tipográfica tiene roles nombrados (display, h1–h3, cuerpo, etiqueta, subtítulo, código), no solo tamaños
• Espaciado consistente: misma relación → mismo token
• Variante de movimiento reducido para tokens de movimiento
• DESIGN.md escrito y preciso
• Móvil: Dynamic Type / escalado de fuentes respetado, áreas seguras tokenizadas, objetivos táctiles ≥ 44/48

Referencias

• references/token-architecture.md — niveles, gramática de nombres, formato DTCG 2025.10, modos/temas, reglas de alias
• references/scales.md — tipografía (escalas, tipo fluido, emparejamiento), espaciado, radio, elevación, movimiento, densidad, puntos de ruptura
• references/platform-outputs.md — CSS, Tailwind v4, tematización de shadcn, React Native (NativeWind/Unistyles/Tamagui), Flutter, SwiftUI, Compose, pipeline de Style Dictionary/Terrazzo
• references/components.md — convenciones de API de componentes, anatomía, matriz de estados, composición, documentación, pruebas, gobernanza
• assets/tokens.example.json — archivo DTCG de inicio
• assets/DESIGN.template.md — plantilla de DESIGN.md