Atomic Design: por qué la jerarquía importa
Brad Frost popularizó Atomic Design como metodología para organizar design systems. La idea central es que las interfaces se descomponen en niveles jerárquicos: atoms son los elementos más básicos (botón, input, label), molecules combinan atoms en grupos funcionales (form field con label + input + error), organisms son secciones complejas (header completo, data table), templates definen layouts y pages son instancias específicas con contenido real.
El error más común es no respetar la jerarquía: una molecule no puede importar otra molecule, debe componerse solo de atoms. Si tu Card (molecule) necesita un Avatar y eso necesita un Image (atom), la composición es válida. Pero si tu MetricCard (molecule) importa otra Card (molecule), estás violando la metodología y creando dependencias circulares difíciles de mantener a escala.
El beneficio práctico es reusabilidad y consistencia. Un equipo con 50 componentes mal organizados duplica trabajo: tres Buttons distintos, dos versiones de Input, cuatro Cards. Un equipo siguiendo Atomic Design tiene un Button con variantes definidas en el design system. Cuando se necesita un nuevo caso, se extiende el atom existente, no se crea uno nuevo. La consistencia visual mejora dramáticamente.
Convenciones de naming que escalan
Usá PascalCase para nombres de componentes. Es la convención de React, Vue y Svelte: ButtonGroup, no buttonGroup ni button-group. Esto distingue componentes de elementos HTML nativos. Para variantes, usá props en lugar de nombres separados: en vez de PrimaryButton y SecondaryButton, usá Button con prop variant. Esto evita explosión combinatoria de componentes específicos.
Para nombrar, seguí el patrón [Sustantivo][Modificador]: ProductCard (no CardProduct), UserProfile (no ProfileUser). El sustantivo principal va primero, los modificadores después. Esto facilita autocomplete: tipear 'Prod' muestra todos los componentes relacionados a productos. Si tipearas 'Card', se mezclarían con otros tipos no relacionados, complicando navegación dentro del proyecto.
Evitá nombres genéricos como Container, Wrapper, Box. Estos no comunican propósito y crecen sin control. Si necesitás un wrapper, especificá: PageContainer, FormWrapper, CenteredBox. Cada nombre debe responder a 'qué hace este componente'. Si no podés explicarlo en una frase, probablemente está haciendo demasiado y necesita división en componentes más pequeños y enfocados.
Errores comunes al implementar Atomic Design
El error más caro es sobre-atomización. Crear un atom para cada elemento HTML lleva a 200 atoms inutilizables. Reservá atoms para elementos que realmente necesitan abstracción: Button (porque tiene variantes y estados), no Span. Si un componente solo es un wrapper sin lógica propia, no merece existir como atom. Mantené el design system enfocado en elementos con valor real de abstracción.
Otro error es props drilling extensivo. Si tu organism pasa 15 props que solo viajan a atoms internos, hay un problema arquitectónico. Considerá composición con children o context API. {`
El tercer error es no documentar variantes. Sin Storybook o documentación visual, los devs duplican componentes porque no saben qué existe. Implementá documentación obligatoria: cada componente debe tener stories mostrando todas sus variantes y estados. Esto convierte el design system en herramienta consultable activa, no solo carpeta de componentes esperando ser importados sin contexto sobre cómo usarlos correctamente.
Atomic Design en proyectos reales: adaptaciones útiles
La metodología pura de Brad Frost asume rigidez total. En la práctica, los equipos adoptan variantes. Material UI y Ant Design usan estructura similar pero sin separación atoms/molecules estricta. Esto funciona para librerías generales. Para tu producto interno, podés ser más estricto: la consistencia interna importa más que adherir religiosamente a la metodología original publicada hace años.
Algunos equipos agregan un nivel quarks debajo de atoms: tokens de diseño (colores, espaciados, tipografías) que componen los atoms. Esto formaliza el design tokens layer y facilita theming. Otros eliminan templates como nivel separado, fusionándolo con pages. Cada decisión depende del tamaño del proyecto: equipos pequeños no necesitan 5 niveles, equipos enterprise sí los aprovechan plenamente.
La adopción exitosa requiere buy-in del equipo completo, no solo de diseñadores. Si los devs construyen componentes ad-hoc fuera del design system, la metodología muere. Establecé reglas: nuevos componentes pasan por review, deben justificar por qué no se puede usar uno existente. Frameworks como Storybook con linter integrado ayudan: detectan componentes duplicados o mal categorizados antes de merge a producción.