Empezar aquí
Por qué un agente no ve tu Figma
Un agente de IA no interpreta tu diseño como tú. Qué información le llega de Figma, qué se pierde por el camino y por qué la documentación decide la calidad de lo que genera.
Última revisión:
Cuando miras un componente en Figma, ves su intención: sabes que el botón verde es la acción principal y que no debe repetirse en la misma vista. Un agente de IA no ve eso. Esta página explica qué información le llega de tu archivo, qué se pierde por el camino y por qué toda la guía gira alrededor de esa diferencia.
En esta página
- Lo que tú ves y lo que recibe el agente
- Lo que le llega de Figma
- Lo que no se ve en el dibujo
- Del archivo de Figma a un contrato
- En Figma
- En resumen
Lo que tú ves y lo que recibe el agente
Un agente de IA es un modelo de lenguaje con acceso a herramientas: puede leer archivos, ejecutar comandos o consultar servicios externos. Para leer Figma usa el servidor MCP de Figma, que le entrega contexto estructurado de tus archivos (Figma: Structure your Figma file for better code).
La palabra importante es estructurado. La documentación de Figma lo dice de forma directa: la calidad de lo que construye el agente depende de ese contexto y de cómo se lo pides (Figma: Structure your Figma file for better code).
| Tú ves | El agente recibe |
|---|---|
| Un botón verde de acción principal | Un nodo con un nombre, unas propiedades y unos valores |
| Que ese verde es el color de marca | Una variable enlazada, si existe; un valor hexadecimal, si no |
| Que el botón es el mismo en toda la librería | Una instancia de un componente, si lo es; un grupo de capas, si no |
| Que no debe haber dos botones principales en una vista | Nada, salvo que esté escrito en algún sitio |
La última fila es la que más importa en esta guía.
Lo que le llega de Figma
Figma documenta las prácticas que mejoran el contexto que recibe el agente (Figma: Structure your Figma file for better code). Cada una convierte algo que tú interpretas a simple vista en un dato que el agente puede leer:
| Práctica | Qué gana el agente |
|---|---|
| Usar componentes para lo que se repite | Reconoce que dos elementos son la misma pieza |
| Conectar los componentes con su código (Code Connect) | Recibe el componente real de tu librería en lugar de adivinar cuál es |
| Usar variables para color, espaciado, radio y tipografía | Referencia tus tokens en lugar de copiar valores |
| Nombrar capas y componentes por su función | Entiende qué es cada parte (CardContainer frente a Frame1268) |
| Usar auto layout | Recibe cómo se adapta el diseño en lugar de posiciones fijas |
| Añadir anotaciones y dev resources | Recibe explicaciones de comportamiento y enlaces a la documentación |
De todas, Figma señala Code Connect como la forma más eficaz de que el agente reutilice tus componentes reales: sin ese vínculo, tiene que adivinar qué componente de código corresponde a cada componente de Figma (Figma: Structure your Figma file for better code).
Lo que no se ve en el dibujo
Esas prácticas describen qué es cada pieza. No dicen cuándo se usa: cuándo un componente es el adecuado, cuándo no, qué combinaciones están prohibidas. Esas decisiones suelen vivir en la cabeza del equipo, en una reunión o en un comentario antiguo.
Un agente trata como válido todo lo que encuentra. Si tienes dos botones casi iguales, uno de ellos obsoleto, y nada lo indica, puede elegir cualquiera de los dos. Storybook lo resume en las instrucciones que propone para los agentes: antes de usar una propiedad de un componente, el agente tiene que comprobar que está documentada, en lugar de suponer que existe (Storybook: MCP server).
Las herramientas ya ofrecen sitios donde escribir esas reglas, y cada uno llega a un agente distinto:
| Dónde se escribe la regla | Quién la recibe | Fuente |
|---|---|---|
| Guidelines de la librería (archivos Markdown, en beta) | El agente de Figma, cuando diseña con esa librería | Figma: About guidelines |
| Instrucciones para el MCP en Code Connect | Cualquier agente que lea el diseño con el servidor MCP de Figma | Figma: Code Connect integration |
CLAUDE.md, AGENTS.md y skills en el repositorio | Claude Code y los agentes de código que leen esos archivos | Claude Code: Memory |
| El sistema de diseño publicado en Claude | Claude Design y los chats de Claude que lo usan | Claude Help: Set up your design system |
Recomendación
Nuestra conclusión: una regla que no está escrita no existe para el agente. Y como cada herramienta lee un sitio distinto, conviene escribir las reglas una vez, en Markdown, y publicarlas en cada destino. El capítulo Documentar explica cómo escribirlas y la página Una fuente, varios destinos, cómo repartirlas.
Del archivo de Figma a un contrato
La propuesta de esta guía es convertir las decisiones implícitas de tu sistema en un contrato explícito y versionado: un repositorio con tokens, componentes vinculados a su código, documentación en Markdown y reglas para agentes. Figma y el código alimentan ese contrato, y las herramientas de IA lo consumen.
Fuentes
Donde se toman las decisiones
- Figma, Variables y componentes
- Código, Librería de componentes
Contrato
Lo que lee el agente
- Tokens DTCG, Capítulo 3
- Documentación Markdown, Capítulo 4
- Code Connect, Capítulo 5
- Reglas para agentes, Capítulo 6
Consumo
Quien usa el contrato
- Agentes de IA, Claude Code, Claude Design y otros
Si una regla no está en la capa central, ningún agente la conoce. Por eso el trabajo se concentra ahí, y no en elegir herramientas de IA.
En Figma
Con el servidor MCP de Figma conectado a tu agente, puedes comprobar qué recibe de un componente: selecciónalo y pídele que te muestre el contexto de diseño y las variables que usa (Figma: Tools and prompts). Si una regla o un token no aparece en esa respuesta, el agente no lo conoce.
Cómo conectar el servidor MCP lo explicamos en el capítulo Capa de agente. Cómo preparar el archivo para que ese contexto sea útil, en el capítulo Preparar Figma.
En resumen
- Un agente recibe datos estructurados de Figma, no la intención con la que diseñaste.
- Componentes, variables, nombres, auto layout, anotaciones y Code Connect convierten esa intención en datos.
- Las reglas de uso no se ven en el dibujo: hay que escribirlas, una vez, y publicarlas donde las lee cada agente.
Fuentes
- Figma: Structure your Figma file for better code
- Figma: Tools and prompts
- Figma: Code Connect
- Figma: Overview of variables, collections, and modes
- Storybook: MCP server
- Figma: About guidelines
- Figma: Code Connect integration
- Claude Code: How Claude remembers your project
- Claude Help: Set up your design system in Claude Design