Ahí es donde entra DESIGN.md, un estándar abierto todavía en fase alpha que lleva las decisiones de un design system (color, tipografía, iconografía, espaciado, componentes y reglas de uso) a un archivo de texto que pueden leer personas y agentes. En Workoholics, como agencia experta en diseño y desarrollo de experiencias digitales, estamos probando el flujo entre Figma y Dev para que la IA no solo ejecute más rápido, sino que interprete mejor el criterio con el que hemos diseñado. Creatividad y tecnología, esta vez, hablando (literalmente) el mismo idioma.
17 de septiembre, 8:30 de la mañana, sede de Workoholics, Done Bikendi plaza 2, Bilbao. Estábamos trabajando con Claude Code para llevar a desarrollo una interfaz ya diseñada en Figma. El design system está bien definido con tokens de color con nombre y propósito, tipografías con su escala, espaciados, componentes con sus variantes… Todo impecable.
Le damos contexto al agente y le pedimos que implemente el diseño. El resultado funciona pero visualmente se aleja bastante de lo que habíamos definido. Aparecen colores que no existen en nuestra paleta, espaciados inventados, una tipografía random… ni rastro del sistema. Ene bada!
No es un fallo de la IA, es la falta de contexto. Sin conocer bien las reglas con las que tiene que trabajar, había rellenado los huecos por su cuenta. La pobre.
Un nuevo interlocutor en diseño y desarrollo
En WKHS, los equipos de diseño y desarrollo trabajamos mano a mano y de forma coordinada en todo tipo de proyectos. La comunicación constante entre ambos equipos permite entender las necesidades de cada parte, resolver dudas sobre la marcha y asegurar que el resultado final se desarrolla de forma coherente con lo que se ha diseñado. Desde que buena parte del equipo de la agencia utiliza Claude Code para programar, los agentes se han convertido en un nuevo interlocutor dentro de ese proceso. Muy bienvenido, además.
Hoy en día podemos conectarlos con Figma y darles acceso a componentes, variables o información del propio diseño. Pero acceder al sistema no significa necesariamente conocer todas las decisiones y reglas que hay detrás de él. Si no les damos ese contexto de una forma clara, rellenan los huecos por su cuenta. Con intención, sí, aunque improvisando. Aquí es donde entra DESIGN.md.
DESIGN.md: ¿qué es y que no es?
Aquí merece la pena pararse un momento y empezar por aclarar esta duda, porque nosotras mismas nos hicimos esa misma pregunta en Workoholics: ¿es un DESIGN.md un Design System? Pues no exactamente.
Un DESIGN.md no es el sistema de diseño, es una representación de ese sistema en un formato que pueden leer tanto personas como agentes de IA. El sistema sigue viviendo donde tiene que vivir, en Figma, con sus componentes, sus variantes, su documentación y todas las decisiones que vamos tomando alrededor de él.
El DESIGN.md es un archivo de texto plano que recoge parte de ese sistema (tokens de color, escalas tipográficas, espaciados, radios, sombras, reglas de comportamiento de los componentes, etc.) y también permite explicar cómo y por qué deben utilizarse. Es decir, no sustituye al design system, lo complementa.
Y, si lo aplicamos de forma procedimental a nuestra metodología, puede ahorrarnos bastante tiempo. Básicamente porque muchas de las reglas que de otro modo tendríamos que volver a explicar en un prompt pasan a formar parte del contexto del propio proyecto. Y eso es un antes y un después.
Eso sí, hay una cosa importante. El DESIGN.md no se actualiza automáticamente cuando cambia el sistema de diseño en Figma. Si modificamos un token, un componente o cualquier otra regla, tendremos que trasladar también ese cambio al archivo. Por eso, conviene entenderlo como una pieza viva del sistema de diseño y pensar desde el principio en los procesos o automatizaciones necesarios para evitar que termine contando una cosa mientras Figma cuenta otra.
Reducir la fricción entre diseño y desarrollo
El DESIGN.md ayuda a convertir parte de ese conocimiento disperso (y que muchas veces vive en la cabeza de quienes han trabajado en el sistema) en un documento único, versionado y consultable.
Su valor se nota especialmente cuando alguien se incorpora a un proyecto o cuando este cambia de manos. En lugar de reconstruir el contexto a base de preguntas, memoria o varios “espera, que te enseño dónde está”, encontramos de manera ordenada buena parte de las reglas necesarias para seguir trabajando sin perder tiempo ni coherencia.
Por supuesto, DESIGN.md no sustituye la colaboración entre diseño y desarrollo. En Workoholics esa sigue y seguirá siendo la base.
Lo que puede aportar es reducir fricción. O lo que es lo mismo, menos idas y venidas para confirmar un detalle, menos interpretaciones diferentes de un mismo componente y menos tiempo explicando una y otra vez decisiones que ya estaban tomadas.
Y aquí nos hemos encontrado con algo que nos gusta especialmente. Tener que explicarle un sistema de diseño con claridad a una IA nos obliga también a explicárnoslo mejor entre nosotras: qué significa cada token, por qué existe cada regla, qué forma realmente parte del sistema y dónde empiezan las excepciones.
Al fin y al cabo, nos obliga a ordenar mejor esa conversación entre diseño y desarrollo. Y ahí creatividad y tecnología vuelven a encontrarse de una manera bastante natural. Verdaderamente, la tecnología nos ayuda a ejecutar y acelerar procesos aunque, sin embargo, necesita que detrás haya decisiones, intención y criterio. Ese sigue siendo nuestro trabajo.
¿Es el DESIGN.md un entregable para cliente?
Es una de las preguntas que más nos estamos haciendo internamente y la respuesta honesta es: depende.
Un DESIGN.md se queda corto si pensamos en él como documentación para presentar un sistema de diseño. No sustituye una librería de Figma, una guía visual o la explicación de las decisiones que hemos tomado. Su valor está en otro sitio.
Como complemento técnico al design system, especialmente para clientes cuyos equipos de producto y desarrollo ya trabajan con agentes de IA, puede ser una pieza bastante útil. Permite que parte de las reglas del sistema viaje con el proyecto y esté disponible desde el primer día para las herramientas con las que ese equipo vaya a trabajar.
Podemos verlo como una versión de bolsillo del design system. Es decir, no contiene todo lo que hay detrás, ni pretende hacerlo. Pero sí recoge una parte especialmente útil cuando ese diseño tiene que pasar de Figma al código y empezar a ser interpretado también por agentes.
Y eso abre una posibilidad interesante para nosotras como agencia al poder entregar sistemas de diseño preparados no únicamente para las personas, sino también para las herramientas con las que esas personas trabajan.
Lo que está por llegar
Seguimos aprendiendo cómo mantener todo esto vivo sin convertirlo simplemente en una tarea más de mantenimiento. Claramente, ahí está uno de los retos reales. Pero si algo tenemos claro es que el diseño nunca terminó en Figma.
Ahora hay nuevas formas de hacer que las decisiones que tomamos allí viajen con el proyecto y sigan teniendo sentido cuando llegan a desarrollo, a otros equipos o a un agente de IA. Eso sí, con una condición innegociable: nada de esto sustituye la conversación entre quien diseña y quien desarrolla.
Herramientas como DESIGN.md pueden quitar fricción por el camino. El criterio, las preguntas y las decisiones compartidas siguen siendo cosa nuestra. Y esperamos que siga siendo así.
Si estáis dándole vueltas a lo mismo o tenéis una forma mejor de resolverlo, escribidnos. Seguro que seguimos aprendiendo juntas.