Los asistentes de código IA producen UI inconsistente en el desarrollo frontend con IA cuando falta el contexto del sistema de diseño. Es el fallo central en los flujos de IA del sistema de diseño: el modelo entrega componentes creíbles que ignoran tus design tokens. La solución es una sola pipeline en el repo: exportar variables de Figma como JSON en formato DTCG, generar CSS con Style Dictionary y apuntar al asistente a AGENTS.md antes de editar código.
Este artículo se centra en esa pila única (tokens en el repo, no una comparativa de cada producto de diseño con IA). Los pasos cubren Cursor y Claude Code como asistentes representativos; la lectura opcional de Figma vía MCP se menciona una vez. Sin estructura de tokens, reglas de nombres y documentación de componentes, la salida sigue el entrenamiento. Los equipos que implementan la pila suelen reportar mejor alineación; los patrones reflejan informes de equipos, no un benchmark publicado. El “vibe coding” informal nombra el mismo problema - contexto ausente - no otra metodología.
Flujos relacionados: Design Tokens de Figma: La Guia Completa para los fundamentos de tokens y arquitectura de dos capas, Paridad Figma-Codigo para sincronizar tokens con el repositorio, y Figma MCP para lectura opcional de layout desde Figma.
En resumen
- Problema: la IA no ve tus variables de Figma de forma nativa hasta que añades archivos y reglas a la sesión.
- Pipeline: variables Figma → JSON DTCG → Style Dictionary → propiedades CSS (
--ds-*) en el repo. - Contexto: AGENTS.md en la raíz (rutas, nombres, sin hex codificado) más documentación opcional de componentes.
- Asistentes: pasos para Cursor y Claude Code más abajo; Figma MCP es opcional para layout, no sustituto de tokens.css.
- Higiene en Figma: limpia literales sin tokenizar y mide vinculación con coverage frente a auditoría untokenized antes de exportar tokens para agentes.
Por qué las herramientas de IA ignoran tu sistema de diseño
Las herramientas de código IA no tienen enlace integrado con tu sistema de diseño. Usan datos de entrenamiento y tu indicación salvo que adjuntes estructura de tokens, reglas de componentes y lógica de espaciado. El resultado es UI que adivina espaciado, color y tipografía - no tu sistema. Los límites del modelo y la ventana de contexto varían; los modos de fallo siguientes aparecen con suficiente frecuencia como para que los equipos los traten como predecibles.
Los tokens de color suelen sobrevivir mejor que el espaciado porque el hex aparece mucho en corpus de entrenamiento. Los alias semánticos - background/default referenciando color/neutral/gray-50 - a menudo se colapsan a un hex literal. Los tokens responsivos basados en modos de variables de Figma se pierden cuando la exportación aplana modos a un solo valor resuelto.
La brecha de contexto (no un techo de la IA)
Sin contexto explícito, muchos equipos ven buenos aciertos de color en pantallas simples pero fallos recurrentes en componentes anidados, tokens por modo y cadenas de alias semánticos - según informes de equipos y hilos de comunidad, no un benchmark industrial publicado. Esa brecha suele cerrarse con exportación DTCG estructurada y un AGENTS.md de una página que el agente lee primero. Los valores codificados que siguen en archivos Figma también filtran a indicaciones y lecturas MCP; encuentra valores sin tokenizar antes de confiar en generación de frontend con IA para UI de producción.
Comportamiento típico de tokens en código generado por IA sin contexto explícito (patrones de informes de equipos)
| Tipo de token | Resultado típico | Modo de fallo común |
|---|---|---|
| Colores de marca | A menudo coincidencia parcial | Literales hex en lugar de referencias var(--ds-*) |
| Escala de espaciado | A menudo omitida | Px arbitrarios del entrenamiento |
| Tokens de tipografía | Mixto | Literales de tamaño/peso en texto anidado |
| Alias semánticos | Suelen omitirse | Hex primitivo; capa semántica saltada |
| Tokens de modo / responsivos | Suelen perderse | Un valor aplanado o modos ignorados |
El formato de token que las herramientas de código IA realmente leen
JSON DTCG es el formato con más probabilidad de sobrevivir desde Figma hasta código generado. El Grupo Comunitario de Design Tokens del W3C mantiene la especificación DTCG; los campos $type y $value encajan con transformaciones de Style Dictionary descritas en la guía de configuración. JSON plano con hex suelto es ambiguo; DTCG lleva tipo, rol y cadenas de alias.
Estructura de dos capas: primitivas y semánticas
Separa DTCG en capa primitiva (valores en bruto) y capa semántica (roles que referencian primitivas). Así los agentes distinguen color/brand/blue-600 de background/interactive/primary. Sin semántica, el código generado suele inyectar el hex.
{
"color": {
"brand": {
"blue-600": { "$type": "color", "$value": "#2563EB" },
"blue-700": { "$type": "color", "$value": "#1D4ED8" }
}
},
"background": {
"interactive": {
"primary": { "$type": "color", "$value": "{color.brand.blue-600}" },
"primary-hover": { "$type": "color", "$value": "{color.brand.blue-700}" }
}
},
"space": {
"4": { "$type": "dimension", "$value": "4px" },
"8": { "$type": "dimension", "$value": "8px" },
"12": { "$type": "dimension", "$value": "12px" },
"16": { "$type": "dimension", "$value": "16px" }
}
}Exportar variables de Figma para consumo de IA
La exportación nativa de variables de Figma es JSON propietario, no DTCG. Usa Tokens Studio o un plugin compatible para mapear colecciones a $type/$value. Exporta primitivas, semánticas y anulaciones de componentes en archivos separados para conservar cadenas de alias. Aplanar a un solo archivo de valores resueltos elimina la capa semántica. Tras exportar, valida el archivo Figma: Coverage Audit frente a escaneos untokenized muestran salud de vinculación y backlog de literales antes del sync con código. Para paridad de Figma al repo, mantén las capas intactas en paridad del sistema de diseño.
De DTCG a CSS: el paso de Style Dictionary
Según la documentación de platforms de Style Dictionary, el JSON DTCG pasa a propiedades CSS, SCSS o TypeScript. Para generación de código IA web, las variables CSS son las más portables cuando dist/tokens.css está en contexto. Ejecuta el build en CI para alinear CSS con Figma.
{
"source": ["tokens/**/*.json"],
"platforms": {
"css": {
"transformGroup": "css",
"prefix": "ds",
"buildPath": "dist/",
"files": [
{
"destination": "tokens.css",
"format": "css/variables"
}
]
}
}
}Asistentes de código IA: Cursor y Claude Code
Cursor y Claude Code son los dos asistentes que más equipos conectan al mismo repo de tokens. Ambos necesitan CSS compilado y AGENTS.md en alcance; las diferencias están sobre todo en cómo cada producto carga reglas y contexto.
Cursor con un sistema de diseño de Figma
Los flujos funcionan cuando el repo define tokens, no solo el chat. Indexa según la indexación de codebase de Cursor. Añade reglas en Cursor Rules o .cursor/rules para heredar restricciones de no codificar.
- Mantén
dist/tokens.css,tokens/ydocs/components/fuera de.cursorignore. - Adjunta
@AGENTS.md,@dist/tokens.cssy la doc del componente. - Indica: solo tokens semánticos
--ds-*de tokens.css; sin hex ni px inventados. - Opcional: Figma MCP para layout; las variables CSS siguen siendo la fuente de verdad del código.
Claude Code con design tokens
Sigue la visión general de Claude Code: mismo AGENTS.md y dist/tokens.css, con reglas en AGENTS.md (y puntero desde CLAUDE.md si lo usas). Ejecuta Style Dictionary antes de sesiones largas.
- Abre la sesión pidiendo leer AGENTS.md y tokens.css antes de editar componentes.
- Las importaciones visuales pueden perder cadenas de alias - ver Claude Design y sistemas de diseño.
- Refuerza con ESLint o Stylelint en
src/.
Escribir archivos de contexto que los agentes de IA realmente leen
AGENTS.md en la raíz es el archivo de contexto compartido para asistentes de código IA (convención AGENTS.md). Mantenlo escaneable: rutas de tokens, tabla de nombres, reglas de uso, enlaces a markdown de componentes. Los agentes extraen hechos; la prosa larga se omite.
Antes y después de AGENTS.md (ejemplo compuesto)
Misma indicación: “Añade un botón primario a la tarjeta de checkout.” Sin AGENTS.md ni tokens.css en contexto, un agente típico podría emitir estilos en línea:
<button style={{ backgroundColor: "#2563EB", padding: "10px 20px", fontSize: 14 }}>
Continuar
</button>Con AGENTS.md más dist/tokens.css adjuntos, las mismas herramientas suelen emitir:
<button className="btn-primary">
Continuar
</button>
/* btn-primary usa solo tokens semánticos */
.btn-primary {
background: var(--ds-background-interactive-primary);
padding: var(--ds-space-8) var(--ds-space-16);
font-size: var(--ds-text-body-size);
}Es un antes/después simplificado que los equipos describen al incorporar diseñadores a Cursor - no un comportamiento garantizado en cada ejecución. La consistencia mejora con documentación por componente y reglas de lint.
Pila práctica: AGENTS.md como entrada, salida de Style Dictionary y /docs/components/*.md por componente. Informes de comunidad (incluidos hilos en r/DesignSystems) mencionan no desarrolladores que abren Cursor con esa configuración y ven referencias a tokens sin repetir reglas en cada indicación.
# AGENTS.md
## Design tokens
Salida CSS de tokens: dist/tokens.css (propiedades personalizadas CSS, prefijo --ds-)
Fuente DTCG: tokens/ (primitives.json, semantics.json)
Nunca codifiques valores hex, tamaños en píxeles o tamaños de fuente.
Siempre referencia la capa semántica - nunca tokens primitivos directamente.
## Nomenclatura de tokens
background/* colores de superficie (fondos, tarjetas, modales)
text/* colores de primer plano (títulos, cuerpo, pies de foto)
border/* colores de trazo y divisor
space/* espaciado y layout (padding, gap, margin)
radius/* radio de esquina
duration/* temporización de animación y transición
## Reglas de componentes
Ver docs/components/ para reglas de uso por componente.
Todos los componentes usan solo tokens semánticos.
Puntos de quiebre responsivos: docs/breakpoints.mdQué rompe la fidelidad de tokens en componentes anidados
Los componentes anidados son el punto de fallo más reportado. Un agente que genera una Tarjeta con un Botón a menudo reconstruye el Botón en lugar de importar el componente de biblioteca - y pierde referencias de tokens. Arreglos que los equipos usan: documentación por componente con tokens requeridos y regla que prohíbe reconstruir componentes existentes.
Problemas de fidelidad de tokens, causas raíz y soluciones
| Problema | Causa raíz | Solución |
|---|---|---|
| Valores hex codificados | No se proporcionó contexto de token de color | Añade propiedades personalizadas CSS al contexto; añade regla de no-codificar a AGENTS.md |
| Espaciado px arbitrario | Escala de espaciado ausente del contexto | Añade tabla de tokens de espacio a AGENTS.md con equivalentes px listados |
| Alias semánticos omitidos | La IA lee la capa primitiva directamente | Prohíbe explícitamente el uso de tokens primitivos en las reglas de AGENTS.md |
| Tokens responsivos faltantes | Variables multimodo no documentadas | Documenta cada nombre de modo, cuándo aplica y qué tokens cambian |
| Nombres de tokens transformados en la salida | Style Dictionary renombra sin mapeo | Arregla la configuración de transformación; añade linting de nombres de tokens a la canalización CI |
| El componente anidado pierde tokens | La IA reconstruye el componente hijo desde cero | Añade documentos a nivel de componente que listen los tokens requeridos por componente |
Documentación oficial
- Especificación del formato DTCG (Design Tokens Community Group)
- Grupo Comunitario de Design Tokens del W3C
- Style Dictionary - primeros pasos, platforms
- Documentación de Cursor - Rules, indexación de codebase
- Documentación de Claude Code (Anthropic)
Veredicto final: flujos de IA del sistema de diseño
La deriva en UI generada por IA suele ser un problema de contexto, no del modelo. Exporta DTCG, genera CSS con Style Dictionary y mantén AGENTS.md. Audita literales en Figma y ejecuta Cursor o Claude Code con tokens en cada sesión. Ese es el flujo de IA del sistema de diseño repetible - no una herramienta distinta por capa.
