WaveSpeedAI
← Blog

design.md vs Tokens de Diseño para Flujos de Trabajo de UI con IA

Compara design.md frente a los tokens de diseño tradicionales para flujos de trabajo de UI con IA, con enfoque en la legibilidad de agentes, la consistencia y la portabilidad del flujo de trabajo.

By Dora 11 min read
design.md vs Tokens de Diseño para Flujos de Trabajo de UI con IA

Soy Dora. Paso la mayor parte de mi semana dentro de agentes de codificación y herramientas de UI con IA — Cursor, Claude Code, Stitch, la lista habitual — construyendo y reconstruyendo interfaces más rápido de lo que tengo tiempo para documentarlas. Hace aproximadamente un mes empecé a ver el mismo archivo aparecer en cada dos repositorios que tocaba: DESIGN.md. Mismo nombre, misma forma de YAML-arriba-prosa-abajo. Para el tercer proyecto me di cuenta de que no era una coincidencia. Era la cosa que reemplazaba lo que la mayoría de nosotros solíamos enviar como tokens.json.

Así que reconstruí una de mis propias bibliotecas de componentes dos veces — una con un archivo de tokens clásico al estilo DTCG, otra con un DESIGN.md — y ejecuté el mismo agente de codificación contra ambas. Esta es la parte de la comparación que no pude encontrar escrita: no qué es cada formato, sino para qué está optimizando cada uno realmente, y cuál pertenece a tu stack ahora mismo.

design.md vs tokens de diseño tradicionales

Para qué está optimizando cada formato

Los tokens de diseño, en el sentido clásico, son una metodología. El término fue acuñado en Salesforce alrededor de 2014 para resolver un problema de escala muy específico: ¿cómo mantienes una decisión de color sincronizada entre web, iOS, Android y cuatro bases de código sin presentar cuatro tickets? La respuesta fue un par nombre-valor agnóstico a la plataforma, almacenado en JSON o YAML, transformado en tiempo de compilación en lo que cada plataforma necesitaba. Esa metodología ahora está codificada por el Design Tokens Community Group en el W3C, y a finales de 2025 el formato DTCG tiene una especificación v1 estable.

Los tokens optimizan para distribución determinista. Un código hexadecimal entra, el mismo código hexadecimal sale en cada plataforma, cada compilación, para siempre. No hay ambigüedad. Tampoco hay narrativa — un archivo de tokens te dice primary: #1A1C1E pero no te dice por qué existe ese color o cuándo no usarlo.

DESIGN.md, publicado como código abierto por Google Labs en abril de 2026, optimiza para algo diferente: darle a un agente de codificación suficiente contexto para tomar decisiones que el archivo de tokens no cubre. Es un único archivo markdown con YAML al inicio para los tokens y prosa abajo para el razonamiento. El mismo archivo, dos audiencias — la parte determinista para los parsers, la parte narrativa para cualquier LLM que esté leyendo el repositorio.

Esa es la división real. No “viejo vs nuevo.” No “JSON vs Markdown.” Es valores vs valores más razonamiento en el mismo archivo.

Por qué los agentes de IA crean un nuevo conjunto de requisitos

Cuando un humano implementa un diseño, la brecha entre “el token dice #1A1C1E” y “este estado vacío necesita un tono de voz” la llena el humano. Han visto el archivo de Figma. Estuvieron en el taller de marca. Saben que el botón secundario se supone que debe sentirse discreto, no asertivo.

Un agente de codificación no tiene nada de eso. Tiene lo que tú pusiste en el repositorio y lo que puede inferir de los nombres de archivo. Así que cuando le pides que genere una pantalla que el archivo de tokens no especifica completamente — un caso límite, un nuevo componente, una decisión de diseño — adivina o usa lo que vio más frecuentemente en el entrenamiento. Esa es la fuente de la estética “beige de IA” de la que todos se quejan: no son modelos malos, simplemente falta contexto.

Esto es lo que DESIGN.md está resolviendo. La especificación oficial en GitHub es explícita al respecto — los tokens dan a los agentes valores exactos, la prosa les dice por qué existen esos valores y cómo aplicarlos. El formato espera ambas mitades.

Dónde DESIGN.md agrega valor

Contexto narrativo persistente

Lo que noté en las primeras 48 horas de pruebas: el mismo agente, con el mismo briefing, genera resultados notablemente diferentes cuando hay contexto en prosa. No “colores ligeramente mejores.” Diferentes elecciones de diseño, diferente registro de texto, diferente densidad de componentes. Los valores de los tokens eran idénticos en ambas ejecuciones — lo que cambió fue si el agente tenía un párrafo que decía “la voz de la marca es contenida y editorial; favorece el espacio en blanco sobre la decoración.”

Esta es la parte que el pipeline de tokens tradicional no transporta. Un archivo JSON DTCG puede describir --color-primary con precisión, pero no puede decirle a un agente que el color primario está destinado a usarse con moderación. DESIGN.md lleva ese juicio a cada pasada de generación, de forma persistente, sin que nadie tenga que volver a escribirlo en un prompt.

Funciona.

Mejor consistencia entre múltiples pantallas para flujos de trabajo de generación

En mi segunda prueba generé ocho pantallas para la misma aplicación a lo largo de dos días. Con contexto solo de tokens, las pantallas 5–8 empezaron a desviarse — misma paleta, pero el lenguaje de diseño se fue aflojando. Con DESIGN.md presente, la desviación fue mucho menor. No nula. Menor.

Mi lectura sobre el porqué: la sección de prosa actúa como un re-ancla cada vez que el agente lee el archivo. Los tokens solos le dan a un agente suficiente para ser correcto en valores individuales. La narrativa le da suficiente para ser consistente a través de decisiones que los tokens no anticiparon. Para generación puntual esa brecha no importa. Para salida de múltiples pantallas e iteración continua, se acumula.

También es aquí donde DESIGN.md encaja bien con el stack de instrucciones de agentes más amplio — la mayoría de las configuraciones ahora lo referencian desde un AGENTS.md junto a archivos SKILL.md, de modo que el sistema de diseño se encuentra en la misma capa de contexto que el resto de las instrucciones persistentes del agente.

Dónde los tokens tradicionales aún ganan

Dos escenarios, ambos reales.

Distribución multiplataforma más allá de la web. Si estás enviando el mismo sistema de diseño a iOS, Android, una aplicación React Native y un sitio de marketing, el pipeline DTCG a través de Style Dictionary o Terrazzo sigue siendo el camino de menor resistencia. El YAML de DESIGN.md puede exportar a DTCG JSON a través del CLI oficial @google/design.md, pero la pregunta de la fuente de verdad sigue importando — si tu grafo de tokens es grande, multi-temático y consumido por herramientas que no son IA, mantener DTCG como formato canónico es la configuración más limpia.

Sistemas de diseño maduros con gobernanza establecida. Los tokens no son solo un formato de archivo. Son una metodología con aproximadamente una década de práctica acumulada — capas primitivas, capas semánticas, aliasing, tematización, toda la taxonomía que Nathan Curtis describió en Tokens in Design Systems. Si tu equipo ya opera de esa manera, DESIGN.md no lo reemplaza. Se sienta encima de él, o junto a él, como una capa de contexto para agentes. Los tokens siguen siendo la fuente canónica; el markdown se convierte en la traducción orientada a IA.

El error sería leer DESIGN.md como un reemplazo del pipeline de tokens. No lo es. Es una capa diferente con un consumidor diferente.

Un framework de decisión para equipos que construyen pipelines de UI con IA

Vuelvo constantemente a cuatro preguntas al decidir qué poner en un repositorio:

  1. ¿Quién lee este archivo? Si el consumidor principal es un pipeline de compilación que emite CSS, Swift y Kotlin, quieres tokens en un formato canónico. Si el consumidor principal es un agente de codificación que genera UI bajo demanda, quieres DESIGN.md. Si son ambos, los mantienes ambos — y dejas que el YAML del archivo markdown refleje un subconjunto de los tokens.
  2. ¿Con qué frecuencia se regenera tu superficie de UI? Los equipos de baja frecuencia (un producto estable, pantallas nuevas ocasionales) obtienen la mayor parte de su valor de los tokens. Los equipos de alta frecuencia (prototipado rápido, iteración impulsada por agentes, pantallas nuevas cada semana) sienten agudamente la brecha del contexto faltante. Cuanto mayor es la frecuencia de regeneración, más se justifica la capa de prosa.
  3. ¿Cuántas plataformas? Solo web o web principalmente con generación impulsada por agentes — DESIGN.md es el stack más simple. Tres o más plataformas con presencia nativa seria — tokens primero, con DESIGN.md como artefacto downstream.
  4. ¿Está el razonamiento ya documentado en algún lugar? Si tus pautas de marca, el documento de voz y la filosofía de componentes viven en una página de Notion que ningún agente leerá jamás, DESIGN.md es el movimiento de mayor apalancamiento que puedes hacer este trimestre. No estás creando documentación nueva — estás moviendo documentación existente a un archivo que el agente realmente abre.

Ese es mi framework. El tuyo puede diferir. Lo que señalaría: no elijas un formato porque es nuevo. Elígelo por quién va a leer el archivo.

Preguntas frecuentes

¿Es design.md un reemplazo de los tokens de diseño?

No. DESIGN.md es un envoltorio que contiene tokens de diseño (en el encabezado YAML) más el razonamiento alrededor de ellos (en prosa markdown). Los tokens dentro de él siguen siendo tokens de diseño en el sentido convencional. Si ya tienes un archivo de tokens en formato DTCG, DESIGN.md no lo reemplaza — se sienta como un artefacto paralelo para agentes de IA, o puedes hacer que el markdown exporte DTCG JSON cuando sea necesario.

¿Por qué los agentes de IA necesitan más que tokens numéricos?

Porque la mayoría de las solicitudes de generación de UI no están completamente especificadas por el grafo de tokens. “Genera una página de precios” requiere cientos de micro-decisiones — jerarquía, densidad, tono, qué enfatizar — que ningún archivo de tokens cubre. Sin contexto narrativo, el agente llena esas brechas con lo que vio en los datos de entrenamiento, lo que produce el aspecto genérico que comparten la mayoría de las UI generadas por IA. La prosa en DESIGN.md es lo que cierra esa brecha.

¿Qué flujos de trabajo se benefician más de design.md?

Tres patrones que he visto rendir más:

  • Desarrolladores en solitario y equipos pequeños que usan Cursor, Claude Code o Stitch para enviar UI más rápido de lo que pueden escribirla a mano.
  • Equipos de sistemas de diseño que mantienen varios productos internos donde la consistencia entre pantallas generadas por IA se está convirtiendo en un problema real.
  • Agencias y equipos de contratos que quieren un único archivo listo para usar que codifique el lenguaje de diseño de un cliente para cualquier agente de codificación.

Si tu flujo de trabajo es principalmente codificado a mano con asistencia ocasional de IA, el valor marginal disminuye.

¿Cuándo la infraestructura clásica de tokens de diseño es aún suficiente?

Cuando no estás generando UI con agentes, o cuando tu alcance de plataforma se extiende mucho más allá de la web. Móvil nativo intensivo, productos de marca blanca multi-tema, prácticas maduras de operaciones de diseño — estos aún obtienen más del ecosistema DTCG que de un archivo markdown. Los dos no son mutuamente excluyentes, pero si tienes que elegir uno en el que invertir, la respuesta depende de dónde está realmente tu fricción de generación.

Conclusión

La versión honesta: DESIGN.md no es un cambio de paradigma. Es una solución enfocada a una brecha específica — agentes de codificación que carecen del razonamiento que los archivos de tokens no transportan. Para los flujos de trabajo donde esa brecha es real, la ganancia es inmediata y obvia. Para los flujos de trabajo donde no lo es, los tokens tradicionales siguen haciendo el trabajo.

Llevo dos meses usando DESIGN.md en cada proyecto de generación de IA que ejecuto. Se ha mantenido en el flujo de trabajo, que es la única prueba en la que confío. Los archivos de tokens tampoco han ido a ningún lado — siguen haciendo lo que siempre han hecho, solo que ahora con un archivo hermano para la audiencia que necesita más que números.

Pruébalo tú mismo en un proyecto. Dos días te dirán más que este artículo.

Publicaciones anteriores：

Compartir