Documentación: Lo que Hace Útil a un Design System
Un design system sin documentación es solo una librería de componentes. La documentación es lo que transforma un archivo de Figma en una herramienta que todo el equipo puede usar de forma autónoma sin preguntar al diseñador cada 5 minutos.
Qué documentar por cada componente
- Descripción: qué es el componente y cuándo usarlo en una o dos frases
- Anatomía: diagrama que muestra las partes del componente (ícono + label + contenedor en un botón)
- Variantes: todas las variantes disponibles con nombre y cuándo usar cada una
- Estados: default, hover, active, focus, disabled, error, loading — cada uno con ejemplo visual
- Do's and Don'ts: ejemplos visuales de uso correcto e incorrecto — los diseñadores aprenden mejor viendo
- Especificaciones: medidas exactas de padding, gap, border radius, tamaños de fuente
Dónde documentar
- Dentro de Figma: crea una página 'Documentation' con secciones por componente usando frames organizados
- Storybook: herramienta web donde los desarrolladores pueden ver e interactuar con cada componente implementado
- Notion/Gitbook: documentación escrita con guías de uso, principios de diseño y reglas del sistema
- Lo ideal: Figma para diseñadores + Storybook para developers + Notion para todos como índice central
- Empieza con documentación dentro de Figma — es la que más se usa porque está junto a los componentes
Manteniendo el sistema vivo
- Asigna un 'owner' del design system — alguien responsable de mantenerlo actualizado
- Establece un proceso de contribución: ¿cómo se propone un nuevo componente? ¿Quién aprueba cambios?
- Versiona los cambios: cuando actualizas un componente, comunícalo al equipo con un changelog breve
- Haz auditorías periódicas: cada mes revisa si el producto real coincide con el design system
- Acepta que un design system nunca está 'terminado' — evoluciona con el producto
Consejo: La mejor documentación es la que escribes al mismo tiempo que creas el componente. Si la dejas para después, nunca la harás. Dedica 15 minutos extra por componente y tu equipo te lo agradecerá.
Actividad: documentar un componente para producto real
Elegí un componente crítico y escribí documentación breve para que diseño, desarrollo y producto lo usen igual.
- Propósito: qué problema resuelve.
- Anatomía: partes internas del componente.
- Variantes: primary, secondary, disabled, loading o error.
- Accesibilidad: nombre accesible, foco, contraste y teclado.
- Uso: cuándo usarlo y cuándo no.
Mini-rúbrica
- La documentación permite implementar sin preguntar al diseñador.
- Incluye al menos un ejemplo visual o textual.
- Describe estados, errores y casos borde.
- Conecta la decisión con tokens del sistema.