Documentar Componentes que Otros Realmente Usan
La documentación clara con ejemplos visuales reduce el tiempo de desarrollo. Te mostramos cómo escribir docs que la gente realmente lee.
Leer másOrganizar tu Librería: Estructura que Escala
Cómo estructurar archivos y carpetas para que crezca con tu equipo. Cubrimos sistemas de carpetas, nomenclatura y convenciones que realmente funcionan.
Por Qué la Estructura Importa
Una librería de componentes desorganizada es como un garaje sin estantes. Al principio, quizás no te moleste. Pero cuando tienes 50 componentes, 12 variantes y 5 desarrolladores buscando cosas, todo se convierte en caos.
La estructura adecuada no es solo organización. Es la diferencia entre encontrar un botón en 10 segundos o perder 10 minutos excavando en carpetas. Reduce duplicados, acelera el desarrollo y hace que tu sistema escale realmente.
Te mostraremos cómo estructura equipos como Spotify, GitHub y Figma sus sistemas de diseño. Spoiler: no es tan complicado como parece.
La Estructura Base que Funciona
Empieza simple. No necesitas un sistema complejo desde el día uno. La mayoría de equipos exitosos usan esta estructura base:
1
Carpeta raíz por categoría
Buttons, Forms, Navigation, Layout. Agrupa componentes por función, no por tipo de archivo.
2
Archivos por componente individual
Button.jsx, ButtonGroup.jsx, ButtonIcon.jsx. Un archivo por componente, nada de mezclar.
3
Documentación junto al código
Cada componente tiene un archivo .stories o .mdx. Docs viven donde vive el código.
Nomenclatura Consistente
La nomenclatura es donde muchos equipos se pierden. “Es ButtonPrimary o PrimaryButton? PrimaryButtonLarge o LargeButton?” Estas pequeñas inconsistencias suman.
Usa estas reglas simples:
- PascalCase para componentes : Button, ButtonGroup, FormInput
- Props descriptivos : variant=”primary” no variant=”p”
- Modificadores al final : ButtonPrimary, ButtonSecondary (no PrimaryButton)
- Evita números : FormLevel2 está mal, FormNested está mejor
Documenta esto en un archivo NAMING.md. Suena aburrido pero evita 100 pequeños debates.
Cómo Escala Cuando Creces
Cuando pasas de 20 a 80 componentes, necesitas pensar diferente. La buena noticia es que tu estructura base escala si la diseñaste bien desde el principio.
A los 6 meses probablemente necesitarás una carpeta “Deprecated” para cosas que nadie usa pero que alguien podría necesitar. Mantén un registro. A los 12 meses, añade una carpeta “Patterns” para combinaciones comunes de componentes.
Lo importante es que cada cambio se haga consciente y documentado. No dejes que la estructura “simplemente suceda”.
“Pasamos de 40 a 150 componentes en un año. La única razón por la que no fue un desastre es que decidimos la estructura en la semana 1 y la respetamos.”
Herramientas que Ayudan
No necesitas herramientas sofisticadas. Pero estas tres hacen la vida más fácil:
Storybook
Documenta componentes de forma visual. Tus diseñadores ven cómo se ven realmente. Tu equipo encuentra variantes fácilmente. Gratis y open source.
Figma
Sincroniza tu librería de diseño con tokens. Los desarrolladores saben exactamente qué copiar. Mejora la coherencia entre diseño y código.
TypeScript
Las props bien tipadas previenen errores tontos. Los autocompletados ayudan a encontrar componentes. No es obligatorio pero acelera mucho.
Git Hooks
Valida la estructura antes de hacer commit. Asegúrate de que los nombres sigan las convenciones. Automatiza lo que puedas.
Errores Comunes que Debes Evitar
Hemos visto cientos de librerías de componentes. Los mejores equipos evitan estos errores:
Organizar por tipo de archivo
Una carpeta “components”, otra “styles”, otra “utils”. Hace que los archivos relacionados estén separados. Usa por función, no por tipo.
Nombres inconsistentes
Algunos componentes con números, otros con guiones, otros con palabras completas. Los desarrolladores nunca saben cómo se llama algo.
Documentación fuera del código
Documentación en una wiki, el código en otro lugar. Se desincroniza rápido. Mantén docs donde vive el código.
Demasiada estructura desde el principio
25 carpetas anidadas cuando tienes 5 componentes. Complica todo. Empieza simple, añade complejidad cuando realmente la necesites.
El Plan para Mañana
No necesitas esperar a tener una librería perfecta. Necesitas empezar con algo que escale. Esto es lo que deberías hacer esta semana:
1
Decide cómo organizas por categoría (Buttons, Forms, Layout, etc.)
2
Crea un archivo NAMING.md con tus reglas
3
Reorganiza lo que tienes (sí, va a doler un poco)
4
Documenta y celebra que ya no es un caos
Una librería bien estructurada no es un lujo. Es el fundamento sobre el que construyes un sistema de diseño real. Tómate el tiempo ahora. Tu equipo te lo agradecerá en 6 meses.
Nota sobre este artículo
Este artículo proporciona orientación general sobre la organización de sistemas de componentes. Las mejores prácticas varían según el tamaño del equipo, la tecnología utilizada y los objetivos del proyecto. No existe una solución única que funcione para todos. Te recomendamos adaptar estas sugerencias a tu contexto específico y siempre consultar con tu equipo de desarrollo.
Artículos Relacionados
