Documentación de un design system: 6 pasos para que se lea

Al final de esta guía tendrás la documentación de tu design system organizada en seis pasos: una sola dirección para cada respuesta, páginas divididas según la pregunta de quien lee, una plantilla fija de componente que empieza por la decisión, una tabla de props generada desde el código, un formato que los agentes de IA pueden consultar y una regla que hace cambiar documentación y código en la misma pull request. La documentación de un design system es el conjunto de páginas que les dice a diseñadores, desarrolladores y ahora también a agentes de programación qué componente usar, cuándo y cómo. Solo compensa lo que cuesta si la gente la abre antes de ponerse a trabajar.

La documentación es donde más sufren los equipos de design system. El Design Systems Report 2025 de zeroheight, basado en algo menos de 300 respuestas, la señala como el mayor problema. Según la misma encuesta, el 47% de los equipos documenta su sistema en más de un sitio, con Figma y Storybook como la pareja más habitual, y el 60% incluye la documentación entre la formación que ofrece, frente al 32% que organiza talleres y cursos. Además, en la web se lee poco: Nielsen Norman Group midió que los usuarios leen alrededor del 20% de las palabras de una página media. Una página de documentación tiene que servirle a quien lee una línea de cada cinco.

Qué necesitas antes de empezar

• Una librería de componentes en código, con props tipadas (TypeScript o equivalente).
• Una librería de diseño en Figma, o en la herramienta que usen los diseñadores, con componentes que se llamen igual que en el código.
• Un sitio donde publicar la documentación: Storybook, zeroheight, una web propia hecha con el framework del producto o una mezcla. Los pasos que siguen valen para cualquiera.
• Una persona que tenga la documentación entre sus tareas, con horas reservadas en el calendario.
• Las preguntas que llegan hoy: el canal de soporte, los comentarios de revisión, las issues del repositorio del design system.

Paso 1: dale a la documentación una sola dirección y haz que todo lo demás apunte allí

Elige un sitio donde vive la respuesta y haz que cualquier otra herramienta enlace a él. Si la documentación está repartida entre descripciones de Figma, una wiki, un README y Storybook, en un trimestre las versiones ya no coinciden, y quien encuentra dos respuestas no se fía de ninguna.

Esa dirección no tiene que contenerlo todo. Tiene que ser el primer sitio al que se llega. Un reparto que funciona: la descripción del componente en Figma lleva una frase y un enlace; la story de Storybook lleva el ejemplo en vivo; la página de documentación lleva las indicaciones de uso y trae las otras dos. Cuando una pregunta en Slack tiene respuesta, la respuesta va a la página y en el hilo queda el enlace.

Paso 2: divide las páginas según la pregunta de quien lee

Quien abre la documentación llega con una de cuatro necesidades, y cada una pide una página distinta. El framework Diátaxis, escrito por Daniele Procida y adoptado por Canonical para la documentación de sus productos, las llama tutoriales, guías prácticas, referencia y explicación.

• Tutorial (aprender): los primeros pasos. Instalar el paquete, mostrar una primera pantalla, publicarla. Pensado para quien acaba de llegar al equipo.
• Guía práctica (una tarea): las recetas. Un formulario con validación, un tema nuevo, la migración desde el modal antiguo.
• Referencia (consultar): props, tokens, eventos, comportamiento con teclado. Se consulta, no se lee de principio a fin.
• Explicación (entender): los principios, por qué la escala de espaciado es la que es, por qué no hay una tercera variante de botón.

Una página de componente que mezcla las cuatro obliga al diseñador que busca indicaciones a pasar por encima de la tabla de props, y al desarrollador que busca una prop a pasar por encima de tres párrafos de filosofía. Deja en la página del componente la referencia y las indicaciones de uso; los principios y las recetas van en páginas propias que enlazan de vuelta.

Paso 3: abre cada página de componente con la decisión, siempre en el mismo orden

La primera pantalla de una página de componente responde a una pregunta: ¿es el componente adecuado? La anatomía, la historia y las variantes vienen después. El GOV.UK Design System usa el mismo orden en todas sus páginas de componente: cuándo usarlo, cuándo no usarlo, cómo funciona, la investigación sobre el componente. Quien lee aprende el orden una vez y en cualquier otra página va directo a la sección que necesita.

La plantilla que usamos en cada página de componente:

1. Una frase sobre para qué sirve el componente.
2. Un ejemplo en vivo, generado desde el componente real, nunca una captura.
3. Cuándo usarlo.
4. Cuándo no usarlo, y qué usar en su lugar, con el enlace.
5. Qué hacer y qué evitar, en parejas, cada una con una imagen de pantallas reales del producto.
6. Indicaciones de texto: longitud de las etiquetas, tono, qué dice el texto.
7. Accesibilidad: comportamiento con teclado, qué anuncia un lector de pantalla, el contraste que cumple cada variante.
8. La tabla de props, generada (paso 4).
9. Estado y changelog.

La línea «cuándo no usarlo» es la que más rinde: frena el componente equivocado antes de que llegue a una versión publicada. El estado también va en la página. GOV.UK marca los componentes nuevos como Trial y, como explica su página de estados del ciclo de vida, los pasa a Stable tras 6 meses sin comentarios negativos. Quien ve la etiqueta sabe cuánto puede fiarse de la página.

Paso 4: genera lo que el código ya sabe y escribe a mano solo lo que no puede saber

Todo dato que el código ya contiene debe salir del código. Los nombres, los tipos, los valores por defecto y la obligatoriedad de las props cambian en cada versión, y una tabla escrita a mano queda desfasada en la primera. Autodocs de Storybook monta una página a partir de las stories y los argTypes de cada componente, y saca la tabla de props de los tipos de TypeScript; otras herramientas hacen lo mismo con react-docgen o con un script que lee los tipos al compilar.

Lo que el código no sabe es el porqué. Cuándo usar un componente, cuándo no, las reglas de texto y el compromiso detrás de una variante son criterio, y el criterio es lo que la gente viene a buscar. Esas partes se escriben a mano, en párrafos cortos, junto a las generadas y en la misma página. Una regla práctica: si una frase sigue siendo cierta después de un refactor, la escribe una persona. Si cambia cuando cambia el código, la escribe un script.

Los comentarios en las props sirven a las dos partes. Un comentario de una línea en cada prop, en el archivo del componente, se convierte en su descripción en la tabla generada: quien cambia la prop actualiza su documentación en el mismo archivo. En nuestro artículo sobre la API de componentes contamos por qué una buena API necesita menos explicaciones.

Paso 5: publica la documentación en un formato que los agentes de IA puedan consultar

Los agentes de programación también leen los design systems, y un agente lee la documentación cada vez que escribe una interfaz, no una sola vez. Storybook distribuye ya un servidor MCP, @storybook/addon-mcp: funciona dentro del servidor de desarrollo de Storybook en localhost:6006/mcp, reúne componentes, stories y documentación en manifiestos JSON y le da al agente un conjunto de herramientas de documentación (list-all-documentation, get-documentation, get-documentation-for-story) para buscar un componente y sus props antes de escribir código.

La página del paso 3 es lo que le da sentido a todo esto. Un agente que lee «cuándo no usarlo: para la navegación, usa Link» elige el enlace. Un agente que solo lee la tabla de props elige cualquier cosa que compile. Escribe las indicaciones en frases sencillas, una regla por frase, con la alternativa nombrada, y el mismo texto le sirve a la persona y al modelo. Las reglas que aplicamos cuando son los agentes quienes usan el sistema están en gobernanza del design system para agentes de IA.

Paso 6: publica la documentación en la misma pull request que el código

La documentación se queda vieja cuando cambia en un día distinto al del componente. Hazla parte de la definición de terminado: una pull request que cambia el comportamiento, las props o el aspecto de un componente no se fusiona sin sus cambios en la documentación y una línea de changelog. Quien revisa comprueba la página igual que comprueba el test.

El informe de zeroheight relaciona la documentación descuidada con la poca confianza: en los equipos que menos confían en su sistema, la falta de personas y de tiempo acaba dejando abandonados elementos importantes como la accesibilidad o la documentación. Una persona responsable de la documentación con horas protegidas, más la regla de la misma pull request, es el remedio más barato que conocemos. Cuesta minutos por cambio y ahorra los días de una reescritura trimestral que nadie llega a programar.

Cómo comprobar que funciona

• La prueba de la persona nueva. Dale a alguien que se ha incorporado este mes una tarea («añade una confirmación para una acción destructiva en la página de ajustes») y mira dónde busca. Debería llegar a la página correcta en menos de un minuto sin preguntar a nadie.
• Preguntas repetidas. Cuenta las preguntas del canal de soporte que la documentación ya responde. El número debería bajar mes a mes; cada una que queda es una frase que falta o una página que nadie encuentra.
• Búsquedas sin resultados. Si la web de documentación tiene buscador, lee las consultas que no devuelven nada. Son las palabras que usan tus lectores y que tus páginas no usan.
• Desajustes. Elige cinco componentes al azar y compara la documentación con el código. Cada diferencia es una versión que se saltó el paso 6.

Fallos habituales y cómo corregirlos

• Escrita una vez en el lanzamiento y nunca más. Solución: la regla de la misma pull request del paso 6, más una persona responsable con nombre.
• Capturas en lugar de ejemplos en vivo. Se quedan viejas con el siguiente cambio visual. Solución: generar cada ejemplo desde el propio componente.
• Páginas que empiezan por la anatomía. Quien lee quería una decisión y encuentra un diagrama con etiquetas. Solución: la anatomía va debajo de «cuándo no usarlo».
• Figma y el código no coinciden. Solución: una sola dirección (paso 1) y nombres de componente idénticos en las dos herramientas.
• La IA escribe las indicaciones. zeroheight lo dice claro: parte del valor de la documentación está en lo que descubres mientras la escribes. Solución: que la IA prepare plantillas o pula el lenguaje, y que el criterio de «cuándo usarlo» se quede con quien es responsable del componente.

Para ir más allá

La documentación es el último tramo de un sistema que ya se sostiene. Si el problema real es la adopción, empieza por por qué se estanca la adopción de un design system. Si los tokens de debajo cuestan de nombrar, nuestras convenciones de nombres de design tokens fijan el vocabulario que luego usa la documentación.