hamzacakmakk/generador-de-sistemas-de-diseño

Generador de Sistemas de Diseño

Construye el sistema más pequeño que haga consistente el producto. Un sistema de diseño es un conjunto de decisiones, no un gran conjunto de valores: menos tokens, bien nombrados, superan a escalas exhaustivas que nadie usa.

Si el skill frontend-design está instalado, frontend-design/references/tokens.md contiene un conjunto inicial completo y verificado de contraste; comienza desde ahí y adáptalo.

1. Entradas

• Lee lo que existe: CSS actual, configuración de Tailwind, archivos de tema, biblioteca de componentes, activos de marca. Inventaría los valores reales en uso (colores, tamaños de fuente, espaciado, radios) y con qué frecuencia aparece cada uno.
• Aclara (o infiere y declara) el tono del producto, las plataformas (web, iOS, Android), la densidad y si se requieren el modo oscuro y el modo de alto contraste.

2. Arquitectura: tres capas

1. Tokens primitivos: valores brutos con nombres neutros. --gray-50 ... --gray-950, --blue-600, --space-4, --radius-md. Nunca se usan directamente en componentes.
2. Tokens semánticos: alias basados en propósito. --bg, --surface, --surface-sunken, --border, --border-strong, --text, --text-muted, --text-subtle, --accent, --accent-fg, --accent-subtle, --focus-ring, --success, --warning, --danger, --info (+ variantes -subtle). Los temas intercambian estos.
3. Tokens de componente (solo cuando sea necesario): --button-height-md, --input-border, --card-padding. Agréguelos cuando un componente necesite ser tematizado de forma independiente.

Nomenclatura: categoría-rol-variante-estado (--text-muted, --accent-hover). Sin nombres de color en tokens semánticos (--accent, no --blue).

3. Decisiones a tomar

• Espaciado: base de 4px. Escala 0, 2, 4, 8, 12, 16, 20, 24, 32, 40, 48, 64, 80, 96, 128. (Fluent 2 y Material se basan en 4px; la escala predeterminada de Tailwig está basada en 4px).
• Tipografía: una o dos familias; una escala modular (1.2 denso, 1.25 producto, 1.333+ editorial); roles en lugar de tamaños (display, título, encabezado, cuerpo, etiqueta, leyenda, código); alturas de línea por rol; clamp() fluido solo para tamaños display.
• Color: rampa neutra de 10–12 pasos (ligeramente cálida o fría, elegida con propósito), una rampa de acento, cuatro tonos semánticos. Genera rampas en OKLCH para pasos perceptivos uniformes.
• Radio: una familia (afilado, suave o redondo) con 3–4 pasos más full.
• Elevación: como máximo 3 niveles (elevado, flotante, superposición), sombras neutras de dos capas; en modo oscuro prefiere superficies más claras sobre sombras más pesadas.
• Movimiento: 3 duraciones (rápido ~140ms, base ~220ms, lento ~320ms), 3 curvas de aceleración (out, in, in-out) y una regla de movimiento reducido.
• Capas: una escala pequeña de z-index (sticky, desplegable, superposición, diálogo, notificación, tooltip).
• Puntos de ruptura: basados en contenido; un conjunto común es 640, 768, 1024, 1280, 1536.

4. Temas y contraste

• Define claro y oscuro juntos. Modo oscuro: fondo casi negro (no #000), texto blanco roto (no #fff), superficies más claras para elevación, acento aclarado y ligeramente desaturado.
• Agrega una variante prefers-contrast: more que fortalezca los bordes y el texto atenuado.
• Verifica cada par de texto/fondo con la fórmula WCAG 2 y publica las relaciones: texto 4.5:1, texto grande y UI significativa (bordes de entrada, iconos, anillos de enfoque) 3:1. Incluye los números en la documentación; no afirmes "cumple AA" sin calcularlo.

5. Entregables

Produce, en el stack del proyecto:

1. tokens.css (propiedades personalizadas CSS, claro + oscuro + alto contraste), y/o la asignación del tema de Tailwind (@theme en v4, theme.extend en v3), y/o tokens.json en el formato del W3C Design Tokens Community Group si se usa una canalización (Style Dictionary).
2. Un breve DESIGN.md que documente: principios (3–5 líneas), las tablas de tokens con relaciones de contraste, roles tipográficos, reglas de uso de espaciado y recomendaciones/no recomendaciones para los componentes centrales (botón, entrada, tarjeta, diálogo, tabla, notificación).
3. Opcionalmente, un solo styleguide.html / página de historia que renderice cada token y estado de componente en ambos temas, para que el sistema pueda verificarse visualmente.

6. Migración (productos existentes)

• Asigna los valores existentes al token más cercano; enumera los valores que desaparecen y por qué.
• Reemplaza en orden: colores, luego espaciado, luego tipografía, luego radios y sombras.
• Mantén una capa de alias temporal para nombres antiguos si la base de código es grande.

Lista de verificación

• Las capas primitiva, semántica y (solo donde sea necesario) de componente están separadas.
• Los componentes solo hacen referencia a tokens semánticos.
• Existen temas claro, oscuro y de alto contraste, y cada par tiene una relación calculada.
• El espaciado está basado en 4px; una familia de radio; como máximo tres niveles de elevación.
• Los roles tipográficos cubren desde display hasta leyenda; como máximo dos familias, tres pesos.
• Los tokens de movimiento incluyen una regla de movimiento reducido.
• La documentación explica cuándo usar cada token, no solo su valor.