Lección 7 de 12 · Lectura y práctica
Documentar Componentes del Sistema
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.
Del concepto a la práctica
Taller de esta lección
La documentación de un componente debe permitir una implementación autónoma. Para lograrlo, explica la anatomía y las decisiones que no se deducen de una captura: cuándo usarlo, qué estados admite y qué ocurre cuando falta o sobra contenido.
Ejemplo resuelto
El campo de búsqueda documenta etiqueta visible, entrada, ayuda y mensaje de error. Su estado inválido conserva la etiqueta, muestra «Escribe al menos tres caracteres» y no usa el placeholder como instrucción permanente. La variante compacta solo se permite en una barra con espacio reducido.
Pruébalo
Dibuja las partes del componente y nómbralas.
Lista variantes y estados, incluidos foco, error y carga.
Escribe un caso de uso y otro caso en el que no debe emplearse.
Añade una regla de teclado y una condición de contenido largo.
Error frecuente: documentar solo el estado ideal. Corrige describiendo vacío, error, foco, deshabilitado y texto extenso.
Ejercicio: redacta la ficha de un campo de búsqueda para otra persona del equipo.
Comprueba tu resultado
puede reconstruir sus cinco estados y decidir cuándo usar la variante compacta sin hacer preguntas adicionales.
Mapa de prácticaUn componente debe adaptarse cuando cambia su contenido o el ancho disponible. Las reglas de espacio y alineación conservan la relación entre sus elementos mientras el texto se ajusta. Prueba estados reales en lugar de diseñar solo una tarjeta ideal.
Ver la infografía en tamaño completo ↗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.
Sigue con Diseño UI y Sistemas de Diseño
Esta lección forma parte de un curso de Cursalo. Revisa su programa y elige entre la compra individual o el acceso a toda la escuela.
Si ya tenías acceso a este curso, entra con tu cuenta: tus derechos y tu progreso se conservan. No necesitas comprarlo de nuevo.