Design Systems Que Entienden los Agentes

Tu design system es documentación para humanos. Pero ahora tu agente de IA también lo está leyendo. ¿Está diseñado para ambos?

Esta pregunta parece teórica hasta que le pides a un agente que genere un componente y te devuelve bg-blue-500 en lugar de bg-brand-500. O usa padding: 24px en vez de tu token p-card. El agente no está adivinando mal — está trabajando con lo que le diste. Y lo que le diste probablemente es ambiguo.

El problema: documentación para humanos, confusa para agentes

La mayoría de design systems tienen inconsistencias que los humanos compensan sin pensar. Sabes que "primary blue" es brand-500 porque llevas meses en el proyecto. Sabes que el padding de una card es siempre 24px porque lo has construido veinte veces. Ese conocimiento tribal vive en tu cabeza, no en el sistema.

Un agente de IA no tiene ese contexto. Lee tu sistema de diseño de forma literal: nombres de tokens, APIs de componentes, variables CSS. Si la nomenclatura es inconsistente, si las props son ambiguas, si no documentas cuándo no usar algo — el agente va a producir código técnicamente correcto pero semánticamente incorrecto.

El resultado: pasas más tiempo corrigiendo el output que el que habrías tardado escribiéndolo tú. El agente no te ayuda porque tu sistema no le da suficiente contexto para ayudarte.

Qué hace un design system legible para IA

No necesitas reescribir todo. Son cuatro principios que amplifican lo que ya tienes.

1. Naming conventions consistentes

El nombre de un token debería comunicar su función, no su valor visual. color-brand-500 le dice al agente qué rol cumple ese color en tu sistema. primary-blue le dice un color y un adjetivo — pero ¿primario de qué? ¿Botones? ¿Fondos? ¿Enlaces?

Un esquema predecible como {categoría}-{propiedad}-{variante} permite que el agente infiera tokens que no ha visto directamente. Si existe color-surface-default, puede anticipar que existe color-surface-raised.

2. APIs de componentes explícitas

Props con nombres descriptivos y tipos estrictos. variant="primary" es claro. type="1" no lo es. Si tu Button acepta un string genérico como variante, el agente no sabe qué valores son válidos.

Las interfaces de TypeScript son documentación ejecutable. Un agente que lee variant: "primary" | "secondary" | "ghost" sabe exactamente qué puede usar. Un agente que lee variant: string tiene que adivinar.

3. Constraints documentados

No solo documentes qué hace un componente — documenta cuándo no usarlo. "No uses Card para contenido que necesita scroll interno" es información que evita errores antes de que ocurran.

Los agentes son buenos generando código pero malos intuiendo decisiones de diseño. Si no documentas los límites, el agente va a usar tu componente en contextos donde no tiene sentido.

4. Jerarquía de tokens mapeada a CSS variables

Tus tokens deberían mapear directamente a variables CSS sin una capa de traducción mental. Si tu token se llama spacing-4 pero la variable CSS es --sp-md, estás creando una fricción innecesaria — para humanos y para agentes.

Tokens planos vs. tokens semánticos

Aquí es donde la diferencia se siente. Compara cómo un agente interpreta la misma card con dos sistemas de tokens diferentes.

Con tokens planos, el agente aplica valores correctos pero sin contexto. bg-gray-100 funciona en light mode. Pero ¿en dark mode? El agente no tiene información para adaptar.

Con tokens semánticos, el agente entiende la intención. bg-surface se adapta automáticamente al tema. p-card garantiza spacing consistente con otras cards del sistema. El token comunica el por qué, no solo el qué.

Esta diferencia no es estética — es funcional. Un sistema con tokens semánticos produce output que necesita menos corrección manual. El agente toma mejores decisiones porque tiene más contexto.

Tu CLAUDE.md es parte de tu design system

Si usas Claude Code, tu CLAUDE.md es el primer archivo que el agente lee antes de escribir código. Las convenciones que documentas ahí afectan directamente la calidad del output.

Esto significa que tu CLAUDE.md es, en la práctica, una extensión de tu design system. Cuando escribes "los colores se referencian como bg-brand-500, no como bg-blue-500", estás creando una regla de diseño que el agente respeta consistentemente.

Lo que funciona documentar en tu CLAUDE.md:

• Esquema de naming de tokens (brand-500 no primary-blue)
• Componentes base y sus variantes disponibles
• Patrones de layout preferidos (cuándo flex, cuándo grid)
• Convenciones de spacing (escala de 4px, tokens semánticos)
• Anti-patrones explícitos (qué no hacer)

Checklist: audita tu design system para agentes

Seis preguntas que revelan si tu sistema está preparado:

1. ¿Los nombres de tokens comunican función? surface-raised > gray-100. Si necesitas contexto humano para entender un token, un agente tampoco lo va a entender.
2. ¿Las props de componentes son explícitas? Union types con valores concretos > strings genéricos. TypeScript es tu mejor documentación.
3. ¿Documentas cuándo NO usar cada componente? Las constraints negativas previenen más errores que los ejemplos positivos.
4. ¿Los tokens mapean directamente a CSS variables? Sin capa de traducción. Token → variable → valor. Directo.
5. ¿Tu CLAUDE.md refleja tu design system? Las convenciones que el agente necesita deberían estar accesibles en el primer archivo que lee.
6. ¿El naming es predecible? Si un agente puede inferir tokens que no ha visto basándose en el patrón de los que sí conoce, tu sistema escala.

Un design system para agentes es mejor para todos

No estás haciendo dos versiones de tu design system — una para humanos y otra para IA. Estás haciendo una versión mejor que funciona para ambos.

Naming consistente, APIs explícitas, constraints documentados, tokens semánticos — todo esto mejora la experiencia de cualquier persona que use tu sistema. Los juniors entienden más rápido. Los seniors pierden menos tiempo buscando convenciones. Y los agentes generan código que realmente se integra.

La ironía es que diseñar para agentes te obliga a resolver los mismos problemas que llevas años posponiendo: nomenclatura inconsistente, documentación incompleta, decisiones de diseño que solo viven en la cabeza de quien las tomó.

Un design system que un agente puede leer correctamente es un design system que cualquiera puede usar correctamente. Y eso siempre fue el objetivo.

---

Este es el séptimo artículo de la serie. El primero fue sobre las herramientas que uso. El segundo sobre por qué fallan y cómo arreglarlo. El tercero sobre cómo construir un sistema de skills. El cuarto sobre el workflow de Figma a código. El quinto sobre MCP servers. Este cierra el puente entre design systems y agentes de IA — donde la estructura de tu sistema determina la calidad del output.