Cómo estructuro los componentes de un producto con IA

Propósito#

Este documento cuenta cómo he definido y hecho cumplir la estructura de componentes de un producto real: una plataforma de gestión de comunidades de coworking. Tiene más de 200 pantallas, un configurador en 3D, un editor de planos y tres marcas, y su interfaz está hecha con React y TypeScript.

Conviene decirlo claro desde el principio: yo no escribo los componentes a mano. Lo que hago es decidir la estructura, sus niveles y sus fronteras, convertirla en reglas que se pueden comprobar y dirigir a las sesiones de IA que la construyen. El resultado que me importa es una base de componentes escalable (crece sin degradarse) y comprensible (cualquiera, persona o modelo, sabe dónde va cada cosa sin preguntar).

Es la aplicación a la interfaz de mi método de trabajo con IA: el contexto antes que el código, las decisiones con su porqué y los límites escritos en la configuración.

Cómo leer este documento#

Uso algunos códigos del proyecto. Cada uno va con su significado al lado: D-47 es una decisión registrada (con su fecha y su porqué), I5v una iteración del prototipo, B2 un paquete de trabajo y R1 una regla de la comprobación automática. Están todos en el glosario (§13).

1La tesis en una página#

La estructura de componentes del producto cabe en cinco ideas.

1. Las pantallas solo componen. Una pantalla no pinta ningún elemento HTML, no pone className ni style y no escribe ningún valor visual. Elige piezas de la base común y les pasa datos. Todo el aspecto vive en la base.
2. Solo los átomos pintan Hay cuatro niveles de piezas (átomos, moléculas, organismos y plantillas). Solo el nivel más bajo crea elementos del DOM, del SVG o del 3D; los demás se limitan a componer piezas de niveles inferiores. Así todo queda anidado y cada cosa tiene un único sitio.
3. La base no sabe nada del negocio. Las piezas no leen el estado, los permisos ni el dominio: reciben datos y avisan con funciones. Eso las hace probables por separado y reutilizables en las tres secciones del producto (decisión D-47, 30-09-2026).
4. Los valores visuales viven en capas de variables. Primitivas, semánticas, de componente y de marca. Las piezas aceptan propiedades de estilo con valores cerrados, nunca números sueltos.
5. Las reglas las comprueba la máquina. Un script recorre el código y falla si alguien (una persona o una sesión de IA) se salta un nivel, pinta donde no debe o escribe un valor a mano. Las reglas no dependen de que el modelo se acuerde de ellas: están en la configuración.

2Por qué atómico y por qué con IA#

2.1El problema: cada pantalla compone a mano#

Cuando la IA construye deprisa, cada pantalla tiende a resolver su caso con los átomos que tiene a mano: un texto, una fila, un botón. El resultado funciona, pero cada tarjeta, cada estado vacío y cada cabecera sale ligeramente distinta. En este producto lo medimos: en la auditoría de la iteración I5v (rediseño visual integral), las pantallas usaban unas 6.000 veces los átomos genéricos y solo unas 50 las moléculas. Patrones que se repetían en decenas de pantallas (la tarjeta de trabajo de una cola, la frase de estado con su porqué, el filtro, el estado vacío, la cabecera de página) se montaban a mano cada vez.

2.2La respuesta: niveles con una sola regla#

El diseño atómico da un vocabulario conocido (átomos, moléculas, organismos, plantillas, pantallas). Lo que yo añado es una regla única y comprobable: cada nivel solo usa los de abajo, y solo los átomos pintan. Con esa regla, la pregunta «¿dónde va esto?» siempre tiene respuesta, y una composición que se repite tiene un camino claro: convertirse en pieza.

2.3Mi papel y el de la IA#

• Yo decido: los niveles, las fronteras, qué es pieza y qué no, el orden de construcción y los criterios de aceptación. Decido sobre opciones, con una recomendada.
• La IA propone y ejecuta: una sesión con el papel de director de diseño hace la auditoría, el brief, los fundamentos y el plan; las sesiones constructoras escriben las piezas y migran las pantallas.
• La máquina vigila: la comprobación de estructura corre antes de cada publicación. Si falla, no entra.

3Las variables#

3.1Cuatro capas, cada una lee la de abajo#

primitivas ──► semánticas ──► de componente ──► piezas (paquete ui) ──► pantallas (solo componen)
 (valores)      (significado)   (cada pieza)
                    ▲
       marcas, tema y densidad solo redefinen semánticas

• Primitivas (459 variables): los valores en bruto, como rampas de color, tamaños, espacios, radios, sombras, duraciones y curvas.
• Semánticas (276): qué significa cada valor, como el texto suave, la superficie elevada, el borde o el estado correcto. Incluyen el tema oscuro.
• De componente (695): lo de cada pieza, como el radio del botón o el ancho de la barra lateral.
• Marcas: las tres marcas de comunidad (Ámbar, Índigo y Jade) solo cambian cinco semánticas de marca.

Ninguna pieza lee una primitiva de color, y una marca no puede cambiar nada que no sea semántico. Lo comprueba la máquina (§10).

3.2Propiedades de estilo con valores cerrados#

Las piezas aceptan propiedades como hueco, relleno o justificar, pero solo con los valores de una tabla. Cada valor apunta a una variable. Un script genera de esa tabla la hoja de modificadores. Para admitir un valor nuevo se añade a la tabla; nunca se escribe en una pantalla. Un hueco={12} escrito a mano falla.

3.3Lo que no puede leer una variable CSS#

El 3D, los lienzos de los rótulos y los documentos que se imprimen no entienden var(). Leen el valor resuelto de la misma variable a través de un gancho común. Así ningún color vive en el código, tampoco en three.js.

4Los niveles de piezas#

4.1Átomos: los únicos que pintan#

115 átomos. Son la única capa que crea elementos: HTML (Boton, Texto, Campo, Chip, Tarjeta), SVG (Lienzo, Poligono) o 3D (Prisma3D, Superficie3D). Todos pasan por una única función, pintar(), que junta la etiqueta, la clase de la pieza y las clases de estilo.

Un átomo no tiene lógica: sin ganchos de React y como mucho 40 líneas. Su propiedad como elige la etiqueta (section, strong) o el enlace del enrutador, sin duplicar la pieza.

4.2Moléculas: átomos juntos con un sentido#

109 moléculas. Por ejemplo, BotonIcono (un botón con su icono y un contador encima), ChipEstado (el estado con su color y su icono), CabeceraPagina (título, ámbito y acción principal) o TarjetaTrabajo. Una molécula puede usar otras moléculas del mismo nivel, pero nunca pinta un elemento.

4.3Organismos: secciones completas#

28 organismos: BarraLateral, Kanban, Dialogo, TablaDatos, PlanoEdificio3D… Pueden tener estado de interfaz local (plegar una columna, atrapar el foco de un diálogo), pero no saben nada del negocio.

4.4Plantillas: la disposición, con huecos#

8 plantillas: MarcoConBarra, PaginaLista, PaginaDetalle, MarcoInmersivo… Una plantilla no tiene contenido propio: define huecos (la barra, la cabecera, los filtros, el contenido, el pie) y los coloca con átomos de maquetación. Cada pantalla responde a una pregunta y se apoya en una de tres formas de página: lista, detalle o inmersiva (D-68, 08-10-2026).

4.5Pantallas: solo componen#

Las pantallas viven en la aplicación, organizadas por sección (Gestión, Plano, Tienda), no por nivel atómico. Leen el estado, pasan por la puerta de permisos y escriben hechos. Para pintar, solo componen piezas de la base: 240 de los 247 archivos de pantalla importan de ella.

5Las fronteras#

5.1La base no lee el estado#

Es la decisión D-47 (30-09-2026): una base común de la interfaz con variables y piezas, y las piezas no leen el estado del producto. Su porqué, tal como quedó registrado: un solo aspecto y piezas que se pueden probar por separado. Las pantallas les pasan lo que pintan, con las formas de datos de la base, y las piezas avisan con funciones (alPulsar, alCerrar).

5.2Los textos se inyectan#

La base no importa el sistema de traducción. La aplicación le inyecta un traductor al arrancar. Así la base sigue siendo independiente y ningún texto se escribe a mano en el código: todo sale del paquete de idiomas, en español y en inglés.

5.3Envoltorios finos para el dominio#

Cuando una molécula necesita lógica de negocio (por ejemplo, la tarjeta de residencia, que depende de permisos y estados), la aplicación tiene un envoltorio fino con el mismo nombre. El envoltorio calcula y la molécula pinta. La frontera no se negocia.

5.4Un archivo, un componente, un nombre#

Cada pieza es un archivo con su mismo nombre y exporta un solo componente. Sin carpetas por componente ni índices intermedios: un único índice de la base, y una entrada aparte para las escenas 3D, para que three.js no entre en el paquete principal. Los nombres están en español, como el resto del producto (Pila, Hilera, TarjetaTarea), y lo mismo las propiedades (variante, tono, medida).

6Cómo se anidan las piezas#

6.1Huecos en lugar de herencia#

Las piezas se anidan por composición: un organismo o una plantilla reciben otras piezas en sus huecos (propiedades que aceptan cualquier contenido) y las colocan. Nadie hereda de nadie. Esto permite que el mismo Kanban sirva para seis colas distintas: el organismo pone los carriles y la pantalla decide qué tarjeta va en cada uno.

6.2Variantes cerradas#

Las variantes son listas cerradas de valores con nombre, no estilos libres. El botón, por ejemplo, tiene 13 variantes (principal, secundario, discreto, peligro, seleccion, pestana…) y dos medidas. Cada variante corresponde a una clase de la pieza. Si una pantalla necesita algo que no existe, se pide una variante; no se inventa un estilo.

6.3Una etiqueta o un enlace, sin duplicar la pieza#

Con como, el mismo átomo pinta un section, un strong o el enlace del enrutador. En las pantallas solo se admiten etiquetas con significado (section, nav, h2…). Para lo demás hay un átomo.

7Cuatro cadenas reales#

7.1El marco de una comunidad#

ruta /:comunidad
 └─ MarcoComunidad            pantalla: lee la comunidad, el rol y los permisos
     └─ MarcoConBarra         plantilla: huecos barra · superior · contenido · pie
         ├─ BarraLateral      organismo: secciones y entradas según el rol
         │   └─ EntradaNavegacion   molécula
         │       └─ Entrada · Icono · Texto · Contador   átomos → pintar()
         └─ Outlet            la pantalla de cada sección, dentro del contenido

La pantalla construye la barra y la pasa al hueco barra de la plantilla. En el móvil, la misma barra va dentro del cajón del menú. La plantilla no sabe qué hay dentro.

7.2Una cola de trabajo en Kanban#

Colas                          pantalla: filtra, cuenta y registra hechos
 └─ PaginaLista                plantilla: huecos cabecera · filtros · contenido
     ├─ CabeceraPagina         molécula: título, ámbito y acciones
     └─ Kanban                 organismo: carriles, plegado y «ver más»
         ├─ BotonIcono         molécula
         │   └─ Boton · Icono · Contador   átomos
         └─ TarjetaTrabajo     molécula, una por elemento de la cola

La lógica (qué hay en cada carril, quién lo lleva, qué pasa al mover una tarjeta) se queda en la pantalla. El organismo solo pinta y avisa.

7.3Una molécula dentro de otra#

QueMeFalta                     pantalla
 └─ TarjetaTarea               molécula
     ├─ Tarjeta · Pila · Titulo · Texto   átomos
     ├─ ChipEstado             molécula
     │   └─ Chip · Icono · Texto           átomos
     └─ BotonAccion            molécula

Las moléculas pueden componerse entre sí porque están en el mismo nivel. Lo que no pueden es subir de nivel ni pintar.

7.4El espacio en 3D#

Configurador (Tienda)          pantalla, cargada aparte
 └─ EscenaEspacio3D            organismo: lienzo, cámara y luces
     └─ Suelo3D                molécula
         └─ Extrusion3D · Prisma3D · Grupo3D   átomos 3D → mallas de three.js

La regla es la misma en 3D: solo los átomos crean mallas. Los colores salen de las mismas variables que el 2D, leídas ya resueltas.

8Del inventario al plan#

8.1La auditoría#

Antes de rediseñar nada, una sesión de IA con el papel de director de diseño inventarió la base tal como estaba. Tenía 123 piezas (69 átomos, 29 moléculas, 20 organismos y 5 plantillas), y pasó una evaluación heurística por las más de 200 pantallas. Los hallazgos llevan su código y su gravedad. Lo más importante fue la cifra de §2.1: las pantallas componían casi todo con átomos.

La auditoría también dijo qué se conservaba: la estructura de D-47 en sí, es decir, un componente por archivo, los niveles, las propiedades de estilo con valores cerrados y la comprobación de estructura.

8.2El brief y los fundamentos#

• El brief fija para quién es cada pantalla, diez objetivos visuales con su forma de comprobarlos y una condición: el rediseño se construye solo con la estructura de D-47 y no cambia ninguna funcionalidad, dato, permiso ni ruta.
• Los fundamentos fijan las capas de variables, el color, la tipografía, el espaciado, la elevación, el movimiento, los iconos, la rejilla, la densidad y los estados de interfaz, además de la lista de piezas por nivel. Son la referencia única de la interfaz (D-90, 11-10-2026).

8.3El plan por paquetes#

El plan de I5v divide la base común en paquetes que se construyen en orden:

• B1 · Variables: las tres capas rehechas, con una tabla de equivalencias de lo viejo a lo nuevo para que nadie invente nada.
• B2 · Átomos: los revisados (botón con variantes, campos, chips, títulos con escala) y los nuevos, como Icono y Esqueleto.
• B3 · Moléculas: una por cada patrón que la auditoría encontró montado a mano, como FraseEstado, TarjetaTrabajo, EstadoVacio, CabeceraPagina o Pestanas.
• B4 · Organismos: BarraLateral, BarraSuperior, MenuMovil, Kanban, TablaDatos…
• B5 · Plantillas: MarcoConBarra, MarcoInmersivo, PaginaLista y PaginaDetalle.

9La construcción#

9.1Lo común, primero#

Dos decisiones ordenan el trabajo: D-49 (01-10-2026, trabajo en paralelo con varias sesiones, con lo común primero, para ganar tiempo sin pisarse) y D-99 (12-10-2026, la base común se adelanta a las pantallas). Primero se construyen las piezas, sin tocar ninguna pantalla y de forma aditiva, de modo que no cambia ningún píxel hasta el cableado. Después, las sesiones constructoras migran las pantallas por secciones, en paralelo, cada una con su encargo.

9.2Migrar sin cambiar un píxel#

La primera extracción de átomos (iteración I3a) se hizo con un script de transformación del código que cambió el HTML de las pantallas por átomos. Cada átomo pinta exactamente el mismo elemento y las mismas clases que pintaba la pantalla, y unas capturas comparadas píxel a píxel garantizan que el resultado es idéntico. Primero se cambia la estructura sin cambiar el aspecto; después se rediseña.

9.3Quién hace qué#

Es el reparto de mi método. Una sesión coordinadora conoce el contexto entero y me prepara las decisiones. Las sesiones constructoras solo ejecutan su encargo, que lleva su lista de pantallas, piezas, equivalencias y capturas. Unos revisores, también sesiones de IA, comprueban cada sección con su propia lista. Yo decido sobre opciones y apruebo por grupos de capturas.

9.4Las decisiones, con su porqué#

Cada decisión de la estructura está registrada con su fecha y su motivo, y no se borra ninguna:

10Lo que comprueba la máquina#

10.1La comprobación de estructura#

check:estructura es un script que lee el árbol sintáctico de cada archivo. Falla si:

• una pantalla pinta un elemento o pone className o style (solo admite un style que lleve variables con datos que se conocen al pintar);
• aparece un color o una medida literal fuera de las primitivas;
• una pieza no está en su nivel, importa uno superior, lee el dominio o, sin ser un átomo, pinta un elemento;
• un archivo no exporta exactamente un componente con su mismo nombre;
• se salta una capa de variables, o se usa una variable que no existe en ninguna.

Va dentro del cierre, la batería que corre antes de cada publicación.

10.2Las reglas finas#

Además, doce reglas con nombre:

• R1: pintar() solo en los átomos.
• R2: un átomo sin ganchos de React y de 40 líneas como mucho.
• R3: como solo con etiquetas con significado.
• R4: ninguna propiedad de estilo con un número a mano.
• R8: las variables de marca y de tema, bien declaradas.
• R9: en CSS, sin !important, sin selectores de pruebas, sin selectores entre componentes y cada clase en el archivo de su pieza.
• R10: una composición que se repite (8 usos o más en 5 archivos o más) tiene que ser una pieza.
• R11: ninguna cadena con una variable CSS en una pantalla.
• R12: ninguna posición a mano en una pantalla.
• R13: las banderas de aspecto, solo en su átomo.
• R15: ningún título hecho con texto en negrita.
• R16: la lectura de variables resueltas, solo a través del gancho común.

10.3Presupuestos que solo bajan#

Algunas reglas no podían cumplirse de golpe. Para ellas, en lugar de prohibir, hay un presupuesto: el número de incumplimientos medido en una fecha. La comprobación falla si el número sube, y cada arreglo lo baja en el propio script. En la limpieza final del rediseño todos llegaron a cero. Desde entonces, un sitio nuevo falla. Hoy (18-10-2026) las doce reglas están a 0.

10.4Lo que no se usa, falla#

check:sin-uso falla con una pieza que nadie usa o una variable que nadie lee. Así la base no acumula restos y su tamaño refleja lo que el producto necesita de verdad.

10.5Contraste, textos y piezas trazadas#

• check:contraste comprueba el contraste AA en los dos temas y las tres marcas.
• check:textos comprueba que ningún texto que lee una persona está escrito a mano en el código: todos salen de los diccionarios de idiomas.
• check:piezas comprueba que cada pieza funcional lleva su código de trazabilidad (D-70). Por ejemplo, COL-108 · OPS-07 dice a qué historia de usuario y a qué requisito sirve la pieza, y el modo demo lo enseña.

10.6Las pruebas#

157 archivos de pruebas unitarias (incluidas las de las propias reglas, con fragmentos de código en memoria) y 152 pruebas de extremo a extremo con Playwright, que pasan también la auditoría de accesibilidad con axe. Las capturas de referencia se comparan píxel a píxel.

11En cifras#

La cifra que mejor resume el cambio es la proporción: antes las pantallas componían con átomos sueltos; hoy casi la mitad de lo que componen son moléculas con sentido. Eso es lo que hace que la interfaz sea coherente y que una pantalla nueva se monte con piezas conocidas.

12Lo que queda y lo que aprendí#

12.1Lo que queda#

• La documentación va por detrás del código. La guía de la base y una parte de los fundamentos todavía nombran piezas que han cambiado de nombre o de nivel. Las cifras de este informe salen del código, no de esa documentación. Toca ponerla al día.
• Una regla de importación apunta a un nombre de paquete antiguo. Hoy ninguna pieza importa el dominio, pero esa regla concreta no lo detectaría. Hay que corregirla.
• No hay un catálogo aparte de piezas. El catálogo es el propio producto, con el modo demo que explica cada pieza. Para un equipo más grande, un catálogo navegable sería el siguiente paso.

12.2Lo que aprendí#

1. Una regla que no comprueba la máquina se acaba incumpliendo. Con IA, más rápido: el modelo construye deprisa y, sin una comprobación que falle, la estructura se erosiona en silencio.
2. Primero la estructura, después el aspecto. Migrar sin cambiar un píxel y rediseñar después fue mucho más seguro que hacer las dos cosas a la vez.
3. La auditoría con números decide mejor que la intuición. «6.000 frente a 50» convenció de crear moléculas más que cualquier argumento de estilo.
4. Los presupuestos que solo bajan permiten mejorar sin parar el trabajo. Prohibir de golpe habría bloqueado todas las secciones a la vez.
5. Comprensible significa que no hace falta preguntar. Si una sesión nueva sabe dónde va cada cosa leyendo las reglas, la estructura funciona.

13Glosario#