Un design system que la IA pueda leer: tokens, reglas y ejemplos
Un design system legible por IA reúne tokens, componentes documentados y reglas de uso en archivos que un agente consulta. Qué incluir, formato y qué evitar.
¿Qué necesita saber un agente para diseñar bien?
Un agente que construye una interfaz necesita tres tipos de información. Primero, los valores: colores, tipografías, espaciados, radios y sombras. Segundo, los componentes: qué existen, qué props aceptan y qué variantes tienen. Tercero, las reglas: cuándo usar un componente y cuándo no, qué jerarquía sigue una pantalla, qué no se debe hacer.
Los dos primeros tipos suelen estar en el código. El tercero casi nunca está escrito en ningún lugar. Un design system que solo tiene tokens y componentes deja al agente adivinar la parte más difícil, que es la intención.
¿Qué formato usar?
Hay varias opciones, y no son excluyentes:
- Tokens en JSON con el formato del Design Tokens Community Group (DTCG), como se explica en design tokens que entiende un agente. La versión 2025.10 se publicó como informe final del grupo comunitario y se considera estable, aunque no es un estándar W3C. Son valores normativos, sin intención.
- Documentación de componentes que el agente consulta con el servidor MCP de Storybook, como vimos en Storybook con IA. Según su documentación, sus herramientas
docs-listydocs-showdevuelven el índice de componentes y, por componente, sus props y sus primeras historias. Está en preview, así que su API puede cambiar, y la parte de documentación exige activarcomponentsManifesten la configuración de Storybook. - DESIGN.md, un formato publicado por Google Labs. Combina tokens en YAML (al inicio del archivo, entre líneas
---) con texto en Markdown bajo encabezados##que explica el porqué. Los tokens son los valores normativos y el texto da el contexto para aplicarlos. Su versión es alfa. Trae una CLI (@google/design.md) que valida la estructura, revisa referencias rotas y contraste WCAG, y exporta los tokens a formatos como DTCG o Tailwind. - llms.txt, un archivo Markdown propuesto por Jeremy Howard en septiembre de 2024 que sirve de índice para que un modelo encuentre tu documentación. Es útil si quieres que terceros también consulten tu sistema. Revisa llms.txt para más detalle.
El servidor MCP de Figma agrega dos cosas útiles. La herramienta get_variable_defs devuelve las variables y estilos de la selección (colores, espaciado, tipografía), y el prompt create_design_system_rules genera un archivo de reglas para que el código se ajuste a tu proyecto; el resultado se guarda en una carpeta como rules/ o instructions/. Es una forma de empezar sin escribir todo a mano. También puedes enlazar componentes de Figma con su código con Code Connect.
¿Qué reglas escribir?
Las reglas más útiles son las que evitan decisiones repetidas:
- Cuándo usar cada componente, en una frase. “Usa
Modalsolo para confirmaciones. Para navegación, usa una página.” - Qué estados existen y cómo se ven: error, vacío, carga, deshabilitado.
- Qué prohibir, con ejemplos concretos. “No pongas un botón primario dentro de otro botón primario.”
- Cómo nombrar tokens y componentes, para que el agente encuentre lo que busca.
La sección “Do’s and Don’ts” de DESIGN.md es una buena plantilla para la última parte: ejemplos cortos de lo que sí y de lo que no. Si el sistema es pequeño, esa sección sola ya cambia el resultado.
¿Cómo lo mantienes sin volverte loco?
Un archivo de reglas que nadie actualiza es peor que no tenerlo. Algunas prácticas simples:
- Dejar la fuente de verdad en el repo, junto al código, y citarla desde CLAUDE.md o AGENTS.md.
- Generar lo que se pueda: los tokens salen de un solo archivo, la documentación sale de las historias.
- Validar de forma automática. Si usas DESIGN.md, su comando
lintdetecta referencias rotas entre tokens antes de que el agente las use. - Revisar el archivo cuando cambie un componente. Un cambio en código sin cambio en reglas crea contradicciones.
¿Cuándo NO conviene?
- Cuando el sistema se redefine cada mes. Escribir reglas para algo inestable obliga a reescribirlas.
- Cuando el objetivo es un prototipo. Un design system legible tiene costo de mantenimiento que no compensa en una prueba de dos días.
- Cuando quieres que el agente invente el sistema desde cero. Un agente sin sistema generará un sistema, pero no será el tuyo.
- Cuando el archivo se vuelve muy largo. Un resumen fiel vale más que un volcado que el agente no procesará bien. Cuidado con los archivos de contexto demasiado extensos, porque ocupan espacio en cada sesión.
Ejemplo
Ejemplo ilustrativo: un equipo pequeño tiene tokens en JSON, siete componentes en Storybook y ninguna regla escrita. Un agente diseña una pantalla de ajustes y usa tres estilos de botón distintos. El equipo crea un DESIGN.md con una sección de componentes, tres reglas de uso de botones y una sección de “No hagas”: nada de botones primarios múltiples en la misma vista. En la siguiente tarea, el agente usa un solo botón primario y el secundario correcto.
Lo que cambió no fue el código. Fue que el agente ya no tenía que decidir qué estilo usar.
Errores comunes
- Documentar solo los tokens y creer que eso basta para la intención.
- Escribir reglas genéricas, como “usa buen diseño”, que el agente no puede aplicar.
- Copiar el sistema completo en un archivo que nadie puede leer en una sola sesión.
- Dejar contradicciones entre el archivo de reglas y el código real.
- Depender de un formato alfa sin tener el JSON de tokens como respaldo.