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.1 El 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.2 La 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.3 Mi 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.1 Cuatro 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.2 Propiedades 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.3 Lo 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.2 Molé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.3 Organismos: 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.4 Plantillas: 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.5 Pantallas: 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.1 La 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.2 Los 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.3 Envoltorios 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.4 Un 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.1 Huecos 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.2 Variantes 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.3 Una 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.1 El 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.2 Una 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.3 Una 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.4 El 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.1 La 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.2 El 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.3 El 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.1 Lo 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.2 Migrar 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.3 Quié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.4 Las 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.1 La 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.2 Las 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.3 Presupuestos 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.4 Lo 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.5 Contraste, 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.6 Las 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.1 Lo 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.2 Lo 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#

Purpose#

This document explains how I defined and enforced the component structure of a real product: a management platform for coworking communities. It has more than 200 screens, a 3D configurator, a floor-plan editor and three brands, and its interface is built with React and TypeScript.

It's worth saying up front: I don't write the components by hand. What I do is decide the structure, its levels and its boundaries, turn it into rules that can be checked, and direct the AI sessions that build it. The outcome I care about is a component base that is scalable (it grows without degrading) and understandable (anyone, person or model, knows where each thing goes without asking).

It's my AI work method applied to the interface: context before code, decisions with their why, and limits written into the configuration.

How to read this document#

I use a few project codes. Each one comes with its meaning next to it: D-47 is a recorded decision (with its date and its why), I5v a prototype iteration, B2 a work package and R1 a rule of the automated check. They're all in the glossary (§13).

1The thesis on one page#

The product's component structure fits in five ideas.

1. Screens only compose A screen renders no HTML element, sets no className or style and writes no visual value. It picks pieces from the shared base and passes them data. All the look lives in the base.

2. Only atoms render There are four levels of pieces (atoms, molecules, organisms and templates). Only the lowest level creates DOM, SVG or 3D elements; the others just compose pieces from lower levels. So everything is nested and each thing has exactly one place.

3. The base knows nothing about the business. Pieces don't read state, permissions or the domain: they receive data and report back through functions. That makes them testable in isolation and reusable across the product's three sections (decision D-47, 30-09-2026).
4. Visual values live in layers of tokens. Primitive, semantic, component and brand. Pieces accept style props with closed values, never loose numbers.

5. A machine checks the rules A script walks the code and fails if anyone (a person or an AI session) skips a level, renders where it shouldn't or hard-codes a value. The rules don't depend on the model remembering them: they're in the configuration.

2Why atomic and why with AI#

2.1 The problem: every screen composes by hand#

When AI builds fast, each screen tends to solve its case with whatever atoms are at hand: a text, a row, a button. It works, but every card, every empty state and every header comes out slightly different. In this product we measured it: in the audit for iteration I5v (full visual redesign), screens used generic atoms about 6,000 times and molecules only about 50. Patterns repeated across dozens of screens (a queue's work card, the status sentence with its why, the filter, the empty state, the page header) were assembled by hand every time.

2.2 The answer: levels with a single rule#

Atomic design gives a well-known vocabulary (atoms, molecules, organisms, templates, screens). What I add is one checkable rule: each level only uses the ones below, and only atoms render. With that rule, "where does this go?" always has an answer, and a repeated composition has a clear path: becoming a piece.

2.3 My role and the AI's#

• I decide: the levels, the boundaries, what is a piece and what isn't, the build order and the acceptance criteria. I decide on options, with a recommended one.
• AI proposes and executes: a session acting as design director does the audit, the brief, the foundations and the plan; builder sessions write the pieces and migrate the screens.
• The machine watches: the structure check runs before every release. If it fails, nothing goes in.

3The tokens#

3.1 Four layers, each reads the one below#

primitive ──► semantic ──► component ──► pieces (ui package) ──► screens (only compose)
 (values)     (meaning)    (per piece)
                  ▲
       brands, theme and density only redefine semantics

• Primitive (459 tokens): raw values, such as colour ramps, sizes, spacing, radii, shadows, durations and easings.
• Semantic (276): what each value means, such as soft text, raised surface, border or success state. They include the dark theme.
• Component (695): what belongs to each piece, such as the button radius or the sidebar width.
• Brands: the three community brands (Amber, Indigo and Jade) only change five brand semantics.

No piece reads a primitive colour, and a brand can't change anything that isn't semantic. The machine checks it (§10).

3.2 Style props with closed values#

Pieces accept props such as hueco (gap), relleno (padding) or justificar (justify), but only with values from a table. Each value points to a token. A script generates the modifier stylesheet from that table. To allow a new value, you add it to the table; you never write it in a screen. A hand-written hueco={12} fails.

3.3 What a CSS variable can't reach#

3D, label canvases and printed documents don't understand var(). They read the resolved value of the same token through a shared hook. So no colour lives in the code, not even in three.js.

4The levels of pieces#

4.1 Atoms: the only ones that render#

115 atoms. They're the only layer that creates elements: HTML (Boton, Texto, Campo, Chip, Tarjeta), SVG (Lienzo, Poligono) or 3D (Prisma3D, Superficie3D). They all go through a single function, pintar() (render), which joins the tag, the piece's class and the style classes.

An atom has no logic: no React hooks and 40 lines at most. Its como (as) prop picks the tag (section, strong) or the router link, without duplicating the piece.

4.2 Molecules: atoms together with a purpose#

109 molecules. For example BotonIcono (a button with its icon and a counter on top), ChipEstado (a status with its colour and icon), CabeceraPagina (title, scope and main action) or TarjetaTrabajo (work card). A molecule may use other molecules at the same level, but it never renders an element.

4.3 Organisms: complete sections#

28 organisms: BarraLateral (sidebar), Kanban, Dialogo, TablaDatos, PlanoEdificio3D… They may hold local interface state (folding a column, trapping a dialog's focus), but they know nothing about the business.

4.4 Templates: the layout, with slots#

8 templates: MarcoConBarra, PaginaLista, PaginaDetalle, MarcoInmersivo… A template has no content of its own: it defines slots (the bar, the header, the filters, the content, the footer) and places them with layout atoms. Every screen answers one question and rests on one of three page shapes: list, detail or immersive (D-68, 08-10-2026).

4.5 Screens: they only compose#

Screens live in the app, organised by section (Management, Plan, Shop), not by atomic level. They read state, go through the permissions gate and write events. To render, they only compose pieces from the base: 240 of the 247 screen files import from it.

5The boundaries#

5.1 The base doesn't read state#

That's decision D-47 (30-09-2026): a shared interface base with tokens and pieces, and pieces don't read the product's state. Its why, as recorded: a single look and pieces that can be tested in isolation. Screens pass them what they render, using the base's data shapes, and pieces report back through functions (alPulsar for on press, alCerrar for on close).

5.2 Texts are injected#

The base doesn't import the translation system. The app injects a translator at start-up. So the base stays independent and no text is hand-written in the code: everything comes from the language package, in Spanish and English.

5.3 Thin wrappers for the domain#

When a molecule needs business logic (for example the residency card, which depends on permissions and states), the app has a thin wrapper with the same name. The wrapper computes and the molecule renders. The boundary isn't negotiable.

5.4 One file, one component, one name#

Each piece is a file with its own name and exports a single component. No folder per component and no intermediate indexes: one index for the base, plus a separate entry for 3D scenes so three.js stays out of the main bundle. Names are in Spanish, like the rest of the product (Pila for stack, Hilera for row, TarjetaTarea for task card), and so are props (variante, tono, medida: variant, tone, size).

6How pieces nest#

6.1 Slots instead of inheritance#

Pieces nest by composition: an organism or a template receives other pieces in its slots (props that accept any content) and places them. Nobody inherits from anybody. That's how the same Kanban serves six different queues: the organism lays out the lanes and the screen decides which card goes in each.

6.2 Closed variants#

Variants are closed lists of named values, not free styles. The button, for example, has 13 variants (principal, secundario, discreto, peligro, seleccion, pestana…: primary, secondary, subtle, danger, selection, tab) and two sizes. Each variant maps to a class of the piece. If a screen needs something that doesn't exist, it asks for a variant; it doesn't invent a style.

6.3 A tag or a link, without duplicating the piece#

With como, the same atom renders a section, a strong or the router link. In screens only meaningful tags are allowed (section, nav, h2…). For anything else there's an atom.

7Four real chains#

7.1 A community's frame#

route /:comunidad
 └─ MarcoComunidad            screen: reads the community, the role and permissions
     └─ MarcoConBarra         template: slots bar · top · content · footer
         ├─ BarraLateral      organism: sections and entries by role
         │   └─ EntradaNavegacion   molecule
         │       └─ Entrada · Icono · Texto · Contador   atoms → pintar()
         └─ Outlet            each section's screen, inside the content

The screen builds the bar and passes it to the template's barra slot. On mobile, the same bar goes inside the menu drawer. The template doesn't know what's inside.

7.2 A work queue as a Kanban#

Colas                          screen: filters, counts and records events
 └─ PaginaLista                template: slots header · filters · content
     ├─ CabeceraPagina         molecule: title, scope and actions
     └─ Kanban                 organism: lanes, folding and "see more"
         ├─ BotonIcono         molecule
         │   └─ Boton · Icono · Contador   atoms
         └─ TarjetaTrabajo     molecule, one per queue item

The logic (what's in each lane, who owns it, what happens when a card moves) stays in the screen. The organism only renders and reports.

7.3 A molecule inside another#

QueMeFalta                     screen
 └─ TarjetaTarea               molecule
     ├─ Tarjeta · Pila · Titulo · Texto   atoms
     ├─ ChipEstado             molecule
     │   └─ Chip · Icono · Texto           atoms
     └─ BotonAccion            molecule

Molecules can compose each other because they're at the same level. What they can't do is go up a level or render.

7.4 The space in 3D#

Configurator (Shop)            screen, loaded separately
 └─ EscenaEspacio3D            organism: canvas, camera and lights
     └─ Suelo3D                molecule
         └─ Extrusion3D · Prisma3D · Grupo3D   3D atoms → three.js meshes

The rule is the same in 3D: only atoms create meshes. Colours come from the same tokens as 2D, read already resolved.

8From inventory to plan#

8.1 The audit#

Before redesigning anything, an AI session acting as design director took stock of the base as it was. It had 123 pieces (69 atoms, 29 molecules, 20 organisms and 5 templates), and it ran a heuristic evaluation across more than 200 screens. Findings carry their code and severity. The most important result was the figure in §2.1: screens composed almost everything from atoms.

The audit also said what to keep: the D-47 structure itself, that is, one component per file, the levels, style props with closed values and the structure check.

8.2 The brief and the foundations#

• The brief sets who each screen is for, ten visual goals with how to check each one, and one condition: the redesign is built only with the D-47 structure and changes no feature, data, permission or route.
• The foundations set the token layers, colour, typography, spacing, elevation, motion, icons, grid, density and interface states, plus the list of pieces per level. They're the single reference for the interface (D-90, 11-10-2026).

8.3 The plan in packages#

The I5v plan splits the shared base into packages built in order:

• B1 · Tokens: the three layers rebuilt, with a mapping table from old to new so nobody invents anything.
• B2 · Atoms: the revised ones (a button with variants, fields, chips, titles with a scale) and new ones, such as Icono and Esqueleto (skeleton).
• B3 · Molecules: one for each pattern the audit found assembled by hand, such as FraseEstado (status sentence), TarjetaTrabajo, EstadoVacio (empty state), CabeceraPagina or Pestanas (tabs).
• B4 · Organisms: BarraLateral, BarraSuperior, MenuMovil, Kanban, TablaDatos…
• B5 · Templates: MarcoConBarra, MarcoInmersivo, PaginaLista and PaginaDetalle.

9The build#

9.1 Shared first#

Two decisions set the order: D-49 (01-10-2026, parallel work with several sessions, shared parts first, to save time without stepping on each other) and D-99 (12-10-2026, the shared base goes ahead of the screens). Pieces are built first, without touching any screen and additively, so not a single pixel changes until the wiring. Then builder sessions migrate the screens section by section, in parallel, each with its own brief.

9.2 Migrating without changing a pixel#

The first extraction of atoms (iteration I3a) was done with a code transformation script that replaced the screens' HTML with atoms. Each atom renders exactly the same element and classes the screen used to render, and screenshots compared pixel by pixel guarantee the result is identical. First you change the structure without changing the look; then you redesign.

9.3 Who does what#

It's the split from my method. A coordinator session knows the whole context and prepares my decisions. Builder sessions only execute their brief, which carries its list of screens, pieces, mappings and screenshots. Reviewers, also AI sessions, check each section against their own checklist. I decide on options and approve by groups of screenshots.

9.4 Decisions, with their why#

Every structural decision is recorded with its date and reason, and none is deleted:

10What the machine checks#

10.1 The structure check#

check:estructura is a script that reads each file's syntax tree. It fails if:

• a screen renders an element or sets className or style (it only allows a style carrying variables with data known at render time);
• a colour or size literal appears outside the primitives;
• a piece isn't at its level, imports a higher one, reads the domain or, without being an atom, renders an element;
• a file doesn't export exactly one component with its own name;
• a token layer is skipped, or a token is used that exists in no layer.

It's part of the closing run, the battery that runs before every release.

10.2 The fine-grained rules#

On top of that, twelve named rules:

• R1: pintar() only in atoms.
• R2: an atom has no React hooks and 40 lines at most.
• R3: como only with meaningful tags.
• R4: no style prop with a hand-written number.
• R8: brand and theme tokens, properly declared.
• R9: in CSS, no !important, no test selectors, no cross-component selectors, and each class in its piece's file.
• R10: a repeated composition (8 uses or more across 5 files or more) has to become a piece.
• R11: no string with a CSS variable in a screen.
• R12: no hand positioning in a screen.
• R13: look flags only on their own atom.
• R15: no title made of bold text.
• R16: resolved tokens are read only through the shared hook.

10.3 Budgets that only go down#

Some rules couldn't be met in one go. For them, instead of a ban, there's a budget: the number of violations measured on a given date. The check fails if the number goes up, and each fix lowers it in the script itself. In the redesign's final clean-up they all reached zero. Since then, any new violation fails. Today (18-10-2026) all twelve rules are at 0.

10.4 What isn't used, fails#

check:sin-uso fails on a piece nobody uses or a token nobody reads. So the base doesn't pile up leftovers, and its size reflects what the product really needs.

10.5 Contrast, texts and traced pieces#

• check:contraste checks AA contrast in both themes and all three brands.
• check:textos checks that no text a person reads is hand-written in the code: all of it comes from the language dictionaries.
• check:piezas checks that every functional piece carries its traceability code (D-70). For example, COL-108 · OPS-07 says which user story and which requirement the piece serves, and the demo mode shows it.

10.6 The tests#

157 unit test files (including tests for the rules themselves, with code fragments in memory) and 152 end-to-end tests with Playwright, which also pass the axe accessibility audit. Reference screenshots are compared pixel by pixel.

11In numbers#

The figure that best sums up the change is the ratio: screens used to compose with loose atoms; today almost half of what they compose are molecules with a purpose. That's what makes the interface consistent and lets a new screen be assembled from known pieces.

12What's left and what I learned#

12.1 What's left#

• The documentation lags behind the code. The base's guide and part of the foundations still name pieces that have changed name or level. The figures in this report come from the code, not from that documentation. It needs updating.
• One import rule points to an old package name. Today no piece imports the domain, but that specific rule wouldn't catch it. It needs fixing.
• There's no separate piece catalogue. The catalogue is the product itself, with the demo mode explaining each piece. For a larger team, a browsable catalogue would be the next step.

12.2 What I learned#

1. A rule the machine doesn't check ends up broken. With AI, faster: the model builds fast and, without a check that fails, the structure erodes silently.
2. Structure first, look second. Migrating without changing a pixel and redesigning afterwards was far safer than doing both at once.
3. An audit with numbers decides better than intuition. "6,000 against 50" made the case for molecules better than any style argument.
4. Budgets that only go down let you improve without stopping work. Banning everything at once would have blocked every section at the same time.
5. Understandable means you don't need to ask. If a new session knows where each thing goes by reading the rules, the structure works.

13Glossary#