Por qué
Documentar suele ser una de las partes más tediosas en la creación de un design system.
Sin embargo es una de las más necesarias de cara a su uso por desarrollo.
Una de las principales razones por las que un design system falla es porque no se usa.
Hay que fomentar su utilización.
Que mejor manera de facilitar su uso que hacerlo accesible a través de plataformas que no te piden tener cuenta y que no necesitas aprender a usar. Notion cumple estas premisas.
La IA nos da la posibilidad de llevar la documentación a otros sitios a través de MCPs.
El MCP (Model Context Protocol) es como el cable USB universal que tiene la IA para conectarse a multitud de aplicaciones distintas.
El experimento
El design system seleccionado es uno pequeño llamado Aegis con un par de componentes y hecho a mano.
Este DS está predestinado a evolucionar y ser más grande, con componentes orientados a que la IA sea capaz de utilizarlos.
La IA tiene unas necesidades especiales para poder utilizar un componente por lo que es posible que veáis cosas que no aplicarían de manera normal a un design system.
Foundations
Color, tipografía, spacing y demás tokens base.
Componentes
Button con properties de tipo, estado, tamaño, booleano de icon only, entre otros. Link, más sencillo, con dos variantes y sus correspondientes estados.
La skill
Una skill es un conjunto de instrucciones que le dice a la IA cómo hacer un trabajo concreto, siempre igual. Así no tienes que explicarlo de cero cada vez, y el resultado queda más controlado.
En este proyecto, la skill conecta el sitio donde trabajas (Figma) con el sitio donde queda la documentación (Notion) a través de Cursor. Tú describes en lenguaje natural qué quieres documentar; el agente lee Figma, organiza la información y la escribe en páginas de Notion.
Cómo funciona
Cada vez que se lanza la skill, el agente sigue más o menos este recorrido:
-
Abrir Figma
La IA accede al archivo de Figma.
-
Descubrir qué hay
Localizar variables (los “tokens”: colores, tipografía o espacios con nombre) y componentes.
-
Preguntas mínimas
Idioma, formato de color, si quieres una copia local, etc.
-
Montar Notion
Crear la página principal, los índices y las secciones.
-
Rellenar con datos reales
Completar foundations y/o componentes con datos del archivo, no inventados.
-
Cerrar y revisar
Resumen de la ejecución y dejar lista la revisión automática.
Las foundations salen de la tabla de variables de Figma: es la fuente de verdad de los tokens.
Los componentes se documentan mirando la pieza viva (variantes, estados, variables ligadas) y, cuando existe, una vista embebida del Playground o Showcase. No se usan capturas de pantalla: el objetivo es un showcase con datos, no un album de imágenes.
El proceso de construcción de la skill
El proceso real fue iterativo: pedir de más, obtener algo genérico, y acotar hasta que la skill respetara la estructura real del design system.
Empecé con solo foundations, para fijar lo básico: qué preguntar, cómo organizar Notion, cómo sacar tokens sin inventar valores.
De ahí salieron dos ajustes clave: separar los caminos de foundations y componentes porque no se documentan igual, y reducir el intake, que generaba fricción.
La skill pasó a inferir el alcance del archivo y preguntar solo lo imprescindible.
En archivos grandes también hubo que dejar de releer Figma en cada paso: ahora descubre una vez, guarda progreso y rellena Notion desde esa copia.
Con las reglas más sólidas, probé la skill en un caso más exigente: un componente accordion de una librería más consolidada.
Ahí aparecieron fallos nuevo como documentación ignorada, colores en bruto en vez de variables asignadas que terminaron de fijar las normas de la skill.
Esas normas obligan a respetar la estructura, leer el componente vivo y documentar solo los cambios entre variantes.
Lo útil del error no fue arreglar un bug, sino ver dónde la IA aporta velocidad y dónde sigue haciendo falta criterio humano.
Esos mismos fallos silenciosos que sabemos que la IA acostumbra a hacer, una ejecución que se da por buena aunque falte algo, fueron los que llevaron a construir el hook.
El hook
Un hook es un script que Cursor lanza cuando el agente termina un turno.
Hacía falta porque que la IA haya acabado no siempre significa que la documentación esté completa: puede faltar una página, una vista embebida o un paso de cierre.
El hook lee el resumen de la ejecución y escribe un mensaje en español fácil de leer: qué está bien, qué no se completó, y qué queda pendiente por razones normales.
Solo se activa cuando esta skill deja un archivo de cierre “armado” al terminar.
Lo bueno y lo malo
Lo bueno
- Acelera el primer borrador de documentación a partir de foundations y componentes existentes.
- Obliga a definir reglas escritas que antes vivían solo en la cabeza del equipo.
- Encaja bien con un flujo Cursor → revisión humana → Notion.
- El hook cierra el ciclo: no solo documenta, también dice qué salió bien y qué falta.
Lo malo
- Sin un DS bien acotado, alucina estructura y vocabulario.
- El embed y la sync con Notion aún exigen cuidado con permisos y URLs públicas.
Resultado
El resultado del experimento se documenta en Notion: foundations, el Button y las notas del proceso.
En conjunto, el proyecto no es solo “exportar Figma a Notion”: es un sistema skill + hook que documenta con datos reales y revisa al final, qué se cumplió y qué no.
Hay que recordar que el resultado que se ve a continuación es algo que se puede adaptar y cambiar a las necesidades de cada design system para que de el mejor resultado posible.