Documentación del sistema

01 Por qué una web y no un archivo

Un sistema de diseño son dos cosas: las piezas y las reglas. Las piezas viven bien en Figma. Las reglas no, porque una regla es prosa condicional: “una sola acción primaria por pantalla, salvo en un diálogo, donde la destructiva va a la derecha”. En un lienzo eso es un cuadro de texto. No se busca, no se enlaza desde un ticket, no tiene historial cuando cambia, y cuando un agente de IA lo lee recibe un árbol de nodos, no la regla.

Así que las reglas están en markdown, en un repositorio. Las lee una persona con un buscador, las lee la IA tal cual, y cada cambio queda registrado con su porqué. La web es la vista pública de esos ficheros, en textplus-design-system.vercel.app.

Diseñé y construí el sitio de principio a fin, en paralelo al sistema que documenta: arquitectura de la información, contenido, tono, comportamiento en móvil y publicación, con un agente de IA como par para la parte mecánica. En un equipo de tres, la documentación es lo que permite que el desarrollador, o quien llegue nuevo, decida sin preguntarme.

02 La arquitectura

Seis secciones: Getting started, Foundations, Brand, Guidelines, Components y Tokens. Casi cualquier sistema público tiene las cinco primeras. La diferencia deliberada es Guidelines: las reglas entre componentes, escritas.

La mayoría de los sistemas deja esas reglas implícitas y confía en el criterio de quien diseña. Aquí los consumidores son un equipo de tres y un agente de IA, y ninguno de los dos puede inferir. Por eso Guidelines dice cuándo se usa un botón secundario y no uno primario, qué pasa con dos botones juntos, cuándo aparece el texto terciario, y por qué el amarillo actúa y el verde confirma. Cada regla lleva su razón al lado, para que quien llegue nuevo entienda la decisión y no solo la obedezca. Y cada página de componente sigue el mismo esqueleto, para que el desarrollador sepa dónde mirar sin aprenderse cada página.

03 Decisiones de diseño

• La cabecera es crema, nunca verde. El verde de marca es confirmación dentro de la app, y no puede colonizar la documentación. La separación entre zonas se hace por tono, sin líneas.
• Ningún color inventado. Todo lo que se ve sale de los tokens exportados de Figma, en los tres modos. Si la web necesita un color que no existe en el sistema, el problema está en el sistema.
• WCAG AA obligatorio y corregido en origen. Cuando una pareja de tokens no llega al contraste, se arregla en Figma, no se parchea en la web. La documentación no puede mentir sobre el sistema que documenta.
• Iconos licenciados servidos como raster. El set de iconos es de pago. Los SVG originales no se publican; la galería se genera como máscaras PNG para que la web sea pública sin romper la licencia.
• Móvil a 360 como requisito, no como extra. El mismo suelo de dispositivo que la app. En pantalla estrecha el título se reduce a las siglas, el interruptor de modo se oculta y la búsqueda pasa a un icono: comportamiento adaptativo definido, no un arreglo a posteriori.

04 Resultado

Veintiséis páginas en Astro Starlight con búsqueda, tres modos con interruptor y tipografía real del sistema, en línea en Vercel con despliegue automático en cada cambio: actualizar una regla y publicarla es el mismo gesto. Construido con un agente de IA como par: la IA hace la parte mecánica, desde la estructura hasta las bandas de color generadas, y yo decido el contenido, el tono y lo que se publica. Tokens e iconos salen de los mismos ficheros que consume la app, así que diseño y documentación no pueden divergir.

05 Aprendizaje

La documentación tiene que vivir donde la leen personas y máquinas a la vez. Si solo la leen personas, envejece en un archivo. Si solo la lee una máquina, nadie la discute. Un repositorio con markdown y tokens en JSON, y una web encima, resuelve las dos cosas con el mismo fichero. Y escribir la razón junto a cada regla costó más que escribir la regla, pero es lo que hace que el sistema sobreviva a quien lo hizo.

---

Documentar no es explicar lo que se hizo. Es decidir lo que se puede hacer sin preguntar.