Organizar tu Librería: Estructura que Escala
Cómo estructurar archivos y carpetas para que crezca con tu equipo. Cubrimos sistemas de carpetas, nomenclatura y mejores prácticas.
Leer artículo
Documentación
Documentar Componentes que Otros Realmente Usan
La documentación clara con ejemplos visuales reduce el tiempo de desarrollo en un 40%. Te mostramos qué incluir en cada componente para que tu equipo trabaje sin fricciones.
Por Qué Importa la Documentación?
Cuando documentas un componente, no lo haces para ti. Lo haces para ese desarrollador que entra al proyecto en tres meses y necesita saber cómo funciona el selector de fecha sin escribir un Slack. O para ese diseñador que quiere asegurarse de que el botón secundario tiene el espaciado correcto.
La realidad es que muchos equipos documentan “para tener documentación”. Crean especificaciones hermosas que nadie lee. Nosotros hemos visto equipos donde la documentación se convierte en una herramienta valiosa —porque está enfocada en lo que la gente realmente necesita saber.
La diferencia está en cómo lo planteas. Empiezas con el uso real, no con la especificación teórica.
Empieza con el Caso de Uso Real
No documentamos componentes abstractos. Documentamos soluciones a problemas específicos. Cuando tienes un botón, la gente no quiere saber “este es un botón”. Quiere saber: “cuándo lo uso?” y “cómo se ve en contexto?”.
Empieza cada sección de documentación con el escenario real. Por ejemplo:
- Botón primario: Usalo para acciones principales — enviar formulario, crear recurso, confirmar compra.
- Botón secundario: Para acciones alternativas — cancelar, volver atrás, opciones adicionales.
- Botón de enlace: Cuando necesitas un botón que parezca enlace — mantiene la coherencia visual sin parecer tan importante.
Esta claridad hace que alguien que entra al proyecto por primera vez pueda elegir el botón correcto sin dudas. Eso es documentación que funciona.
Incluye Comportamiento, No Solo Apariencia
Un componente no es solo cómo se ve. Es cómo se comporta cuando alguien interactúa con él. Aquí está lo que necesitas documentar:
Estados: Normal, hover, activo, deshabilitado, cargando. Cada estado debe estar documentado con una imagen clara. No asumas que el desarrollador “ya lo sabe”.
Tamaños: Si tu componente viene en pequeño, mediano y grande, muéstralos lado a lado. Incluye las dimensiones exactas — muchos equipos usan una escala de 8px, así que documenta en esos términos.
Responsividad: Cómo se comporta en móvil? El texto se trunca? Se apila verticalmente? Muéstralo en tu documentación. Esto evita sorpresas cuando alguien lo usa en un proyecto real.
Una buena regla: si alguien necesita preguntarte cómo funciona algo, debería estar en la documentación.
El Código que Acompaña la Documentación
Incluye ejemplos de código real. No pseudocódigo — código que funciona. Si es React, muestra JSX. Si es HTML puro, muestra el HTML exacto que usan tus componentes. Esto es lo que diferencia documentación útil de documentación que la gente ignora. Los desarrolladores copian y pegan. Dale código que puedan usar directamente.
Propiedades, Props y Opciones
Documenta cada prop o propiedad que tu componente acepta. No es suficiente decir “acepta variantes”. Especifica qué variantes existen y cuándo usarlas.
Para cada opción, incluye:
- Nombre del prop: Exactamente como se escribe en el código.
- Tipo de dato: String, boolean, array, número. Sé específico.
- Valor por defecto: Qué sucede si no lo especifican.
- Opciones válidas: Si es un select, lista todas las opciones.
- Descripción clara: En términos simples, no técnicos.
Muchos equipos crean tablas para esto. Funciona bien si la tabla es clara y escaneable. Lo importante es que alguien pueda encontrar lo que necesita en 10 segundos.
Accesibilidad No es Opcional
Si tu componente no funciona para alguien con una discapacidad, tu documentación también debe estar clara sobre esto. Documenta los atributos ARIA que usas. Explica cómo funciona la navegación por teclado. Si hay un estado de foco especial, muéstralo.
Muchos desarrolladores que usan tus componentes no pensarán en accesibilidad a menos que tú se lo recuerdes. La documentación es tu oportunidad de hacer que esto sea fácil.
Incluye puntos de verificación de accesibilidad simples:
- Funciona solo con teclado?
- Tiene etiquetas adecuadas para lectores de pantalla?
- El contraste de color cumple con WCAG AA?
“La documentación no es para ti. Es para el desarrollador que entra en tres meses y necesita entender qué hace tu componente sin tenerte que preguntar. Si tu documentación requiere una llamada, no es suficientemente clara.”
— Principio de documentación útil
La Documentación que Funciona es Actualizada
Aquí viene la parte difícil: mantener la documentación actualizada. Cuando cambias un componente, la documentación debe cambiar también. No es negociable.
Algunos equipos vinculan su documentación directamente a su código. Usan herramientas como Storybook que generan documentación automáticamente. Otros mantienen documentación separada pero tienen un proceso claro: si cambias el componente, alguien actualiza la documentación. No es lo más emocionante de la ingeniería, pero es lo que hace que un sistema de diseño escale.
Cuando tu documentación está actualizada, tu equipo se mueve más rápido. Cuando está desactualizada, todos pierden tiempo intentando entender qué cambió y por qué. Elige qué prefieres.
La documentación que otros realmente usan no es hermosa. Es útil. Es clara. Es específica. Es actual. Si puedes lograr eso, habrás resuelto uno de los mayores dolores de cabeza de cualquier equipo de diseño y desarrollo.
Lleva tu Documentación al Siguiente Nivel
La documentación clara es la base de un sistema de diseño que escala. Si quieres explorar cómo estructurar tu librería de componentes o cómo implementar tokens de diseño, sigue leyendo.
Más sobre Sistemas de DiseñoArtículos Relacionados
Nota Importante
Este artículo proporciona información educativa sobre documentación de componentes y mejores prácticas en sistemas de diseño. Las recomendaciones están basadas en experiencias de equipos reales, pero cada proyecto tiene necesidades únicas. Adapta estas prácticas a tu contexto específico y considera consultar con tu equipo de diseño y desarrollo para determinar qué funciona mejor en tu caso.