tmj-90/design-system

Construir un sistema de diseño sistemático

La habilidad brand decide la identidad; la habilidad frontend-design decide cómo se ve una superficie. Este paquete decide cómo esa apariencia está estructurada para escalar: una arquitectura de tres capas de tokens con una única fuente de verdad, especificaciones de componentes que cubren cada estado y controles que evitan que los valores literales se filtren nuevamente. Carga una referencia cuando necesites profundidad:

Tema	Referencia
Capas, nomenclatura, modo oscuro, JSON DTCG, migración desde tokens planos	references/token-architecture.md
Variantes, tamaños y matrices de estados para botón/input/tarjeta/insignia/alerta/diálogo/tabla	references/component-specs.md
Prioridad de estados, anillos de enfoque, patrones de error/carga, ARIA por estado	references/states-and-variants.md

La arquitectura en una frase

/* PRIMITIVO — valores brutos, sin significado. Cambian raramente. */
--blue-600: oklch(55% 0.2 264);
/* SEMÁNTICO — propósito. La costura del tema: claro/oscuro/marca sobrescribe solo esta capa. */
--color-primary: var(--blue-600);
/* COMPONENTE — perillas por componente, que referencian tokens semánticos. */
--button-bg: var(--color-primary);

Los componentes consumen tokens de componente o semánticos — nunca un primitivo, nunca un literal. Los temas (oscuro, alto contraste, una segunda marca) redirigen tokens semánticos y nada más.

Fuente de verdad. Si el repositorio mantiene los tokens como JSON del W3C Design Tokens Community Group (DTCG) — el formato alcanzó su primera versión estable, 2025.10, en octubre de 2025 — esos archivos son la fuente: los tokens llevan $value y $type, los alias se escriben {color.blue.600}, y una herramienta de construcción (Style Dictionary o el equivalente del repositorio) genera variables CSS, tema de Tailwind y valores nativos. Edita el JSON y regenera; nunca edites a mano la salida generada. Si el repositorio solo tiene propiedades personalizadas CSS, esas son la fuente. No introduzcas una segunda fuente.

Pasos

1. Lee lo que existe. search_lore para ADRs de sistemas de diseño; encuentra archivos de tokens (*.tokens.json, tokens/, theme.ts, bloques :root, configuración de Tailwind), el comando de construcción que genera las salidas y dos componentes hermanos. Extiende el sistema existente en su propio lenguaje; nunca agregues uno que compita.
2. Audita antes de agregar. Cuenta los literales en los estilos de componentes (comandos abajo). Cada fuga que toques se reemplaza por un token existente o justifica uno nuevo.
3. Coloca cada nuevo token en su capa. Primitivo solo para un valor bruto genuinamente nuevo; semántico para un nuevo propósito (--color-surface-raised, --space-section); componente solo cuando un componente deba divergir. Los nombres describen propósito, no apariencia (--color-danger, no --color-red). Primitivos de color en oklch (lenguaje de la casa), tipo en una escala fluida clamp(), espaciado en una unidad base (4px o 8px).
4. Tematiza en la costura semántica. El modo oscuro y otros temas sobrescriben tokens semánticos en un bloque ([data-theme="dark"], .dark o @media (prefers-color-scheme: dark), según el repositorio) y establecen color-scheme para que los controles nativos y las barras de desplazamiento sigan. Un tema que sobrescribe un token primitivo o de componente significa que la costura está en el lugar equivocado.
5. Verifica el contraste por tema. Para cada par semántico de primer plano/fondo realmente usado (texto sobre superficie, texto sobre primario, borde sobre superficie, anillo de enfoque sobre superficie), calcula la relación de contraste WCAG en cada tema: 4.5:1 para texto del cuerpo, 3:1 para texto grande, límites de la interfaz de usuario e indicadores de enfoque. La luminosidad de oklch no es la relación WCAG — calcúlala (un script, el verificador del repositorio o una prueba). Registra la tabla.
6. Especifica los componentes completamente. Variantes, tamaños (altura explícita, relleno, token de fuente) y la matriz de estados — predeterminado, hover, focus-visible, activo, deshabilitado, carga, error, más seleccionado/marcado donde sea relevante — con el ARIA que cada estado expone. Prioridad cuando varios se aplican: deshabilitado > carga > error > activo > focus > hover > predeterminado. El focus es siempre visible (anillo :focus-visible de --color-ring, nunca outline: none solo). Detalles: las referencias.
7. Recomendando un sistema para un nuevo producto: razona desde el producto, no desde un kit — (a) patrón y densidad (marketing, panel de datos denso, flujo transaccional), (b) dirección (difiere a brand), (c) postura de la paleta (roles semánticos incl. éxito/ advertencia/peligro/información; modo oscuro solo si los usuarios lo necesitan), (d) accesibilidad y objetivos de rendimiento declarados desde el principio. Genera una justificación breve más el andamio de tokens y componentes; pasa la ejecución visual a frontend-design.
8. Verifica y proporciona evidencia. Regenera las salidas de tokens si el repositorio las construye y confirma que el diff es solo lo que pretendías; ejecuta lint, type-check y pruebas; ejecuta las comprobaciones de fugas; renderiza los componentes modificados en cada tema a través de las pruebas de componentes o capturas de pantalla del repositorio donde existan. Registra la evidencia por cada AC con la habilidad record-evidence (recuento de fugas antes/después, tabla de contraste), luego detente.

Comprobaciones de fugas

Ejecuta en los archivos de componentes y estilos modificados (excluye los propios archivos de tokens):

• colores literales: grep -rEn '#[0-9a-fA-F]{3,8}\b|rgba?\(|hsla?\(|oklch\(' src/components
• tamaños de tipo literales: grep -rEn 'font-size:\s*[0-9.]+px' src/components
• primitivos referenciados desde componentes: grep -rEn 'var\(--(gray|blue|red|green)-[0-9]+' src/components
• valores arbitrarios de Tailwind donde existen tokens: grep -rEn '\[(#|[0-9]+px)' src/components

Ajusta las rutas y los nombres de primitivos al repositorio. Las nuevas coincidencias en tu diff son defectos que el constructor debe corregir, a menos que la línea sea en sí misma una definición de token; un revisor las enumera como (opcional) a menos que una rompa un AC o el contraste de un tema.

Terminado cuando

No haya nuevos literales o referencias primitivas en los componentes; cada tema sobrescriba solo tokens semánticos; la tabla de contraste pase en cada tema; la matriz de estados de cada componente tocado esté implementada con enfoque visible; las salidas generadas coincidan con la fuente.

Capturar lore

La arquitectura de tokens de un repositorio — la división en capas, la convención de nomenclatura, la costura del modo oscuro o una regla de "nunca referenciar un primitivo en un componente" — es exactamente el hecho que el próximo agente necesita antes de comenzar. Ese tipo de hecho es lore. Captúralo a través del protocolo de captura de lore en tu brief (CLAUDE.factory.md, paso 11 "Contribución de memoria"): llama a Memory MCP suggest_lore una vez al final de tu trabajo — solo convenciones reutilizables, peculiaridades, decisiones y límites, nunca trivialidades por ticket.