Atlassian publica DESIGN.md: lecciones de probar en la práctica un contexto de diseño portable

• Es un formato Markdown portable para resolver el problema del "slop", donde las UI generadas por IA se vuelven genéricas y sin identidad de marca; reúne los elementos centrales del sistema de diseño en un solo archivo para incluirlo en el prompt
• DESIGN.md se compone de dos partes: tokens de diseño legibles por máquina y fundamentos de diseño (rationale) legibles por personas y agentes; no contiene la especificación técnica completa del sistema, sino su intención (intent)
• Al aplicarlo en la demo keynote de Team '26 para generar un dashboard con Figma Make, colores, espaciados, formas y tipografía se alinearon con el sistema de Atlassian, mostrando buen rendimiento en prototipos de un solo intento
• Sin embargo, en bases de código de producción consumió alrededor de 92% más tokens que su propio servidor MCP y skills, aumentó el tiempo de generación y mostró una variación de consumo de tokens entre ejecuciones de unas 2.7 veces, reduciendo la eficiencia
• Sus fortalezas propias —portabilidad y concisión— aportan valor en portabilidad cross-platform, tematización para clientes y prototipado de nuevos entornos; se posiciona como complemento, no como reemplazo, de herramientas ricas de sistemas de diseño

---

Contexto: el problema del "slop" en las UI con IA

• Cuando la IA genera UI, los resultados tienden a parecerse: botones con gradientes, títulos en mayúsculas, layouts de tarjetas genéricos, animaciones hover innecesarias, etc. La funcionalidad opera, pero falta identidad visual
• La comunidad de diseño llama a estos resultados "slop": salidas funcionales, pero sin decisiones de diseño intencionales
• La causa es la falta de contexto sobre marca, componentes y patrones: la IA produce por defecto el promedio de sus datos de entrenamiento → "Generic in, generic out"
• El equipo del sistema de diseño de Atlassian está construyendo un motor de contexto para la era de la IA, proporcionando a los agentes un contexto de diseño enriquecido mediante el servidor ADS MCP y skills de IA detalladas
  • Con esto comprobaron una reducción en costos de tokens de IA y mejoras en la precisión y calidad de los resultados generados por miles de product builders

Resumen de DESIGN.md

• Es un formato Markdown open source diseñado por Google para su herramienta de diseño Stitch, una snapshot portable de la marca y los patrones de UI de un equipo
• Su principio de funcionamiento es simple: al incluir el archivo en el prompt, los resultados generados empiezan a verse como el producto propio

• Qué es (What it is)

  • Un archivo Markdown portable que describe solo los elementos centrales de un sistema de diseño
  • La primera parte enumera tokens de diseño en un formato legible por máquina
  • La segunda parte describe fundamentos de diseño —colores, espaciado, layout, elevation, componentes, etc.— para personas y agentes

• Qué no es (What it isn't)

  • No es la especificación técnica completa de cómo opera un sistema de diseño en producción, ni contiene todos los detalles del sistema
  • No incluye bibliotecas de código existentes, linters para mantener estándares de codificación ni especificaciones de diseño detalladas de Figma
  • La especificación define este formato como una forma de capturar la intención (intent), no todos los detalles del sistema

Construcción de su propio DESIGN.md

• Atlassian ya venía preparando su sistema de diseño para consumo por IA mediante un servidor MCP, un pipeline de contenido estructurado y varias skills para agentes
• Generó su propio DESIGN.md desde el mismo pipeline de contenido estructurado que impulsa MCP y las skills de agentes
• Probó el formato en herramientas comunes de vibe coding y agregó instrucciones más estrictas para errores frecuentes que no estaban cubiertos por las guías existentes

Prueba en Team '26

• La demo keynote de Team '26, concluida hace un mes en Anaheim, se utilizó como un caso de prueba adecuado
• En una demo de la keynote, Figma Make usó Teamwork Graph para generar un dashboard personalizado, con el objetivo de alinear el lenguaje de diseño de una sola vez sin depender del servidor MCP ni de herramientas internas
• Al aplicar DESIGN.md, el resultado pasó del "slop" genérico a una salida reconociblemente Atlassian, usando valores esperados para color, espaciado, forma y tipografía, y aplicando elevation alineada con el sistema en los componentes
• Las guías y especificaciones de alto nivel del archivo son adecuadas para personalizar bibliotecas comunes como Tailwind y Shadcn y generar una UI desde cero

Trade-offs al aplicarlo en producción

• Una base de código de producción es un entorno con tokens existentes, bibliotecas de componentes, reglas estrictas de lint y verificación de tipos; es muy distinto de un entorno aislado creado desde cero
• En una tarea simple como una pantalla de login, al usar DESIGN.md como única guía de diseño se registró cerca de 92% más consumo de tokens, mayor tiempo de generación y una variación de consumo de tokens entre ejecuciones de unas 2.7 veces
  • Aun así, se aclara que estos resultados no son determinantes y pueden variar según el modelo, el prompt, el sistema de diseño, el entorno y la calidad del contexto

• Límite 1: el contexto se entrega de una vez, no bajo demanda

  • Un servidor MCP trae bajo demanda solo las instrucciones de un componente específico mediante un tool call como ads_plan
  • Evita cargar elementos innecesarios en partes pesadas, como cientos de íconos o un gran volumen de tokens de diseño semánticos
  • DESIGN.md carga todo el archivo cada vez, lo que implica mayor costo desde el inicio y respuestas más lentas; en pocas interacciones, el contexto puede recortarse y reducir la precisión

• Límite 2: mantener el archivo corto provoca pérdida de contexto

  • Un sistema de diseño es un objeto complejo que comprime el lenguaje compartido de miles de vistas, archivos Figma y componentes frontend
  • MCP y skills bajo demanda se destilan en unas 2.5 MB de instrucciones; como DESIGN.md se carga de una sola vez, necesita reducirse mucho más
  • El archivo resultante pesa 80 KB, unos 19,800 tokens de LLM (unos 10,700 sin frontmatter), un tamaño grande frente a ejemplos de la comunidad
  • Para ajustarse a ese tamaño, se eliminaron muchas guías de uso de más de 50 componentes, se redujeron drásticamente las guías básicas y se quitaron algunos tokens de diseño de bajo uso
  • Por la falta de contexto, se observó que los agentes que apuntan a calidad de producción tienden a perder precisión, recolectar contexto por su cuenta o leer directamente implementaciones de componentes para encontrar guías de uso que no están en la especificación

• Límite 3: la especificación expone el interior del sistema de diseño

  • DESIGN.md es una snapshot portable que reescribe el sistema de diseño en prosa, con el objetivo de entregar principios, especificaciones y guías para replicar e implementar el sistema desde cero
  • En entornos de producción establecidos, esta información puede ser innecesaria o inducir al agente a generar deuda técnica (tech debt), algo especialmente visible en componentes
  • En lugar de leer e interpretar todos los detalles de estilo de un botón —backgroundColor, textColor, borderColor, etc.— es preferible importar y usar el componente existente
    • Ejemplo: import Button from '@atlaskit/button'; y luego <Button appearance="primary" spacing="compact" />
  • Usar componentes compartidos es esencial para el mantenimiento: si un botón cambia en un solo lugar, se refleja en toda la base de código y facilita code reviews y mantenimiento
  • DESIGN.md excluye deliberadamente instrucciones de código y solo ofrece especificaciones de reimplementación, por lo que en las pruebas tendió más a recrear componentes que a usar el sistema existente
  • El servidor MCP y las skills ofrecen un mejor nivel de abstracción basado en la base técnica: funcionan como manual para usar el sistema existente, no como guía para reimplementarlo
  • Al combinar esto con reglas de lint que imponen estándares de codificación sin consumir tokens, se forma un loop de feedback positivo para los agentes

Cuándo DESIGN.md resulta más útil

• Dirección artística de alto nivel (High-level artistic direction)

  • El DESIGN.md más simple se concentra en la dirección visual y la sensación del sistema; si eso no estaba documentado, puede ser un resultado útil
  • Sin embargo, el frontmatter duplica contenido que ya existe en la base de código

• Prototipado rápido en entornos poco familiares

  • En prototipos blue-sky o pruebas con nuevas herramientas, ayuda a crear UI on-brand sin la carga de configurar todo el stack técnico ni las restricciones de componentes existentes

• Interoperabilidad con herramientas de diseño (Interoperability)

  • Algunas herramientas de IA ensamblan UI personalizando componentes prefabricados alineados con un lenguaje de diseño; DESIGN.md ofrece un nivel de instrucciones adecuado para esas herramientas

• Tematización de clientes para UI adaptativas (Customer theming)

  • En productos que necesitan generar interfaces dinámicas —reportes, gráficos, dashboards— ayuda a que los clientes describan fácilmente su propia marca y a que la salida de IA se sienta alineada con ella
  • Puede imaginarse como una opción para que administradores o equipos de marca suban esta información a herramientas de trabajo
• Lo que todos estos casos tienen en común es el alcance de UI generadas por agentes en entornos donde la salida del sistema de diseño existente no está disponible o no resulta práctica

Cómo empezar y contribuir al estándar

• Atlassian publicó su archivo DESIGN.md en atlassian.design/DESIGN.md porque busca dar forma al estándar, no solo reaccionar ante él
• Su archivo tiene algunas diferencias con el estándar actual: incluye atributos no estándar para renderizar componentes y, como el estándar no soporta tematización, ofrece una variante separada para modo oscuro
• Compartió feedback en GitHub, algunas propuestas ya se incorporaron a la especificación, y alienta la participación de toda la industria

Conclusión

• DESIGN.md es un formato portable útil como snapshot de un sistema de diseño, pero no reemplaza herramientas de sistemas de diseño más ricas
• Si los agentes soportan MCP o skills, ofrecen mejores resultados con menor costo
• En portabilidad cross-platform, tematización de clientes y prototipado blue-sky, un DESIGN.md bien estructurado aporta mejoras significativas
• Cuando los sistemas de diseño se vuelven legibles para la IA, todo el ecosistema se beneficia