Documentar tu Design System no es un entregable. Es el idioma con el que escala.
Documentar un Design System siempre tuvo valor. Su costo, por fin, se está erosionando.
Ya hemos hablado de lo que un Agentic Design System necesita. Reglas explícitas. Tokens con intención. Componentes que un agente pueda leer sin depender del contexto que vive en la cabeza de alguien del equipo.
Todo eso es correcto. Pero en varias conversaciones recientes me he encontrado el mismo momento. Alguien empieza a trasladar definiciones de su sistema a archivos markdown para que un agente las lea, y se sorprende. No de que falten cosas por escribir. Se sorprende de no haber sabido nunca que faltaban. La definición no estaba en ningún lado. Vivía en la cabeza de alguien. O peor, en la de nadie.
Y de ahí sale una conclusión que se siente lógica: la documentación importa porque el agente la necesita. Es un blocker para tener un Design System listo para IA. Lo destrabamos y habremos llegado.
No. Esa conclusión invierte el orden de las cosas. Esas definiciones siempre debieron estar en la documentación, porque la documentación es el mecanismo con el que un equipo toma decisiones. El agente no creó la necesidad. Solo nos cobró una deuda que ya teníamos.
Y hay algo más de fondo: los Design Systems nunca están en modo completado. Parte de por qué esa conclusión se siente tan lógica es que confundimos el sistema con sus artefactos: el repositorio, la librería, los tokens. Pero un Design System no es lo que produces. Es lo que decides.
Un sistema honesto en lugar de un sistema perfecto
Un Design System no crece de forma binaria. No hay un momento en que no teníamos nada y otro en que está listo, el crecimiento es progresivo. Siempre hay decisiones tomadas en contextos que ya cambiaron. Siempre hay reglas definidas aún no documentadas. Siempre hay componentes que evolucionaron de formas distintas a lo que el manual dice.
Eso no es un fallo. Es la naturaleza de algo en constante evolución.
El problema de fondo es no saber que los tienes.
Murphy Trueman, en su artículo “AI doesn’t need your design system to be perfect. It needs it to be honest.”, tiene una prueba simple para esto:
imagina que mañana llega un desarrollador senior a tu equipo. Talentoso, rápido, cero contexto. ¿Cuánto podría entender solo leyendo lo que tienes documentado? La IA es ese nuevo integrante.
Su argumento es que la IA puede trabajar con inconsistencias si le dices que existen. Lo que no puede hacer es compensar el desorden que nadie ha admitido. No necesitas un sistema perfecto. Necesitas saber dónde están tus problemas.
Alex Chies lo vivió de primera mano. Su agente estaba mapeando componentes automáticamente, conectando lo que existe en Figma con lo que existe en código. Funcionaba bien cuando los nombres eran iguales o parecidos. Pero fallaba cuando dos cosas significaban lo mismo sin llamarse igual.
En Figma el componente tenía un estado llamado “Disabled”. En el código ese mismo estado se llamaba “disabled: boolean”. Para cualquier persona del equipo, la conexión es obvia. Para el agente, no existía, porque nunca se había escrito explícitamente.
El agente no inventó el problema. El gap ya estaba ahí. Lo que hizo fue hacerlo visible.
La documentación no es un checklist, es un proceso continuo
La documentación no existe para describir un sistema perfecto. Existe como mecanismo para poner cosas en común: pasar de lo subjetivo a lo objetivo. Para que cuando alguien diga “necesito una excepción”, haya un argumento que responda por qué esa excepción rompe algo o por qué tiene sentido.
Por eso la documentación es necesaria desde antes de los sistemas agénticos. Ayuda a catalizar decisiones y lograr consenso con un lenguaje compartido. Es la base que permite tomar decisiones y seguir escalando. Y como el sistema evoluciona, algunas reglas pierden vigencia y hay que revisitarlas.
La documentación es el reflejo de la naturaleza del sistema. Por eso es un trabajo continuo, no una tarea terminada en un checklist.
Porque al final, lo que hace valiosa a la documentación no es el artefacto. Es que es uno de los pocos lugares donde las decisiones pueden sobrevivir a las personas que las tomaron. Sin eso, cada decisión tiene que rehacerse desde cero cada vez que alguien nuevo llega, cada vez que el contexto cambia, cada vez que alguien pregunta por qué.
Todo eso tiene sentido en teoría. En la práctica, documentar siempre fue lo primero en caer cuando el tiempo apretaba.
Documentar es más barato que nunca
Durante años, documentar fue costoso, difícil de mantener, y frecuentemente quedaba obsoleto. Los repositorios eran más confiables que los sitios de documentación. Mucha documentación terminó siendo un espejo roto del sistema real. Y los equipos aprendieron, con razón, a desconfiar de ella.
Pero el código es la fuente de verdad, no siempre la más accesible.
Un JSON tiene sus límites para gente no técnica. Figma nunca fue fuente de verdad absoluta, pero es una fuente visual compartida que llega donde el código no llega. Un componente interactivo o una demo que puedas manipular, todo eso es documentación. Y todo eso puede vivir alrededor del código.
Podríamos pensar en el tiempo que eso llevaría. Pero ese argumento se está quedando sin piso.
Hoy existen herramientas que generan visualizaciones directamente desde el código. Plataformas que sincronizan automáticamente cuando algo cambia en el sistema. Scripts que pueden leer tu repositorio y producir documentación legible para humanos sin intervención manual. El costo que justificaba evitar documentar está desapareciendo.
Entonces la pregunta ya no es si podemos permitirnos documentar. Es por qué seguimos evitándolo cuando las excusas se están acabando. No necesitas esperar a tener un Agentic Design System para sacarle partido a esto. Las herramientas están disponibles hoy. Y el beneficio, entender realmente lo que tienes, es inmediato.
Desplegar decisiones, no producir artefactos
Un Design System no es una librería. No es un conjunto de componentes. No es un repositorio ni un sitio de documentación.
Es las decisiones que tomamos con todo eso.
Los artefactos, código, Figma, tokens, docs, son formas de desplegar esas decisiones para distintas audiencias. Ninguno es la verdad completa. Todos son accesos distintos a la misma verdad. Y esos accesos pueden volverse más sofisticados, más automatizados, más inteligentes. Pero la decisión de qué desplegar, para quién y por qué es una tarea fundamentalmente humana.
No hay Design Systems perfectos y además estos están en constante evolución. Podemos escalar ignorando inconsistencias y gaps, hasta cierto punto. En algún momento esa deuda nos cobra factura.
La documentación no es un entregable. Es el reflejo del propio sistema. Sus artefactos dependen de las necesidades de cada equipo. Y todos se apoyan en la fuente de verdad que siempre ha sido el código, porque es con lo que construimos software.
Pero la verdad necesita más de un idioma.
Nos vemos en la siguiente edición
Para leer 📚
Design Systems Collective
Llevo un par de colaboraciones con este colectivo enfocado en Design Systems, la verdad es que es una fuente muy buena que reúne a practicantes que están contando que están haciendo, asi que les recomiendo que lo lean para estar al día en el tema