page controllers → composición e integración externa
Page → wiring y composición
UI → render puro
```
El sistema visual Rdx debe respetar estrictamente esta arquitectura.
---
## 3. Objetivo
Crear un estándar visual y estructural común para los principales tipos de pantalla del ERP:
```txt
Listados
Vistas de detalle
Pantallas de creación
Pantallas de edición
```
El sistema debe unificar:
- márgenes;
- padding;
- separación entre elementos;
- anchuras;
- jerarquía tipográfica;
- disposición de acciones;
- iconografía;
- estados visuales;
- superficies;
- responsive;
- accesibilidad;
- soporte claro/oscuro;
- documentación y ejemplos interactivos.
El objetivo no es crear un framework CRUD universal, sino una biblioteca pequeña de primitives y composiciones visuales explícitas.
---
## 4. Principios rectores
### 4.1 Claridad antes que abstracción
```txt
Primero claridad local.
Después repetición real.
Solo entonces abstraer.
```
No se crearán componentes genéricos sin evidencia suficiente de repetición.
### 4.2 UI pura
Los componentes Rdx no deben conocer:
- React Query;
- DTOs;
- APIs;
- controllers;
- routing;
- permisos de negocio;
- estados de dominio;
- errores de transporte.
Deben recibir props ya preparadas.
### 4.3 Composición, no configuración excesiva
Preferir:
```tsx
<RdxPageContainer>
<RdxPageStack>
<RdxPageHeader/>
<RdxListPageLayoutmain={...}aside={...}/>
</RdxPageStack>
</RdxPageContainer>
```
Evitar:
```tsx
<RdxCrudPage
entity="customers"
filters={...}
permissions={...}
routing={...}
query={...}
/>
```
### 4.4 Diseño compacto y ordenado
La interfaz debe:
- evitar espacio vacío que no aporte jerarquía;
- mantener alta densidad informativa;
- conservar suficiente separación para lectura;
- evitar ruido visual;
- evitar card dentro de card;
- usar superficies solo cuando tengan una función clara.
### 4.5 Tema claro y oscuro desde el inicio
Todo componente debe diseñarse y validarse en:
```txt
Tema claro
Tema oscuro
```
No se aceptará una implementación diseñada solo para tema claro y corregida posteriormente.
---
## 5. Referencias visuales
### 5.1 Pantalla de referencia principal
La pantalla de listado de proformas es la referencia visual inicial para:
- densidad;
- toolbar;
- espaciado;
- jerarquía de acciones;
- tratamiento de tabla;
- iconografía;
- filtros;
- composición general.
Ruta:
```txt
modules/customer-invoices/src/web/proformas/list
```
Estado de adopción a 6 de agosto de 2026:
- primera pantalla piloto migrada a `RdxPageContainer`, `RdxPageStack`, `RdxPageHeader` y `RdxPageActions`;
- se ha sustituido el header legacy solo en la Page de listado, sin tocar controllers, grid, filtros, panel lateral ni dialogs;
- el piloto confirma que las foundations actuales cubren la geometría exterior de la página sin justificar todavía `RdxListPageLayout`, `RdxResponsivePageGrid` ni `RdxContextPanel`.
- segundo piloto migrado en `modules/customers/src/web/list` con el mismo perímetro de cambio;
- ambos listados confirman la reutilización de container, stack, header y CTA principal, pero todavía no justifican abstraer la geometría interior del listado;
- los dos paneles contextuales reales confirman una separación válida entre `RightPanel` como primitive de superficie y `RdxContextPanel` como composición visual contextual.
- create y update comparten shell, header legacy, superficie editable única y secciones planas internas;
- las diferencias reales quedan en defaults, submit y wiring del controller, no en la composición visual;
-`PageFormHeader` sigue siendo funcionalmente suficiente, aunque se mantiene una deuda visual menor por su anchura full-width frente al contenido centrado.
## Fase 8 — Editor complejo
Usar `proformas/update` como piloto para:
```txt
main + aside
sticky footer
totales
acciones según scroll
```
Resultado observado a 10 de agosto de 2026:
-`proformas/update` valida `RdxEditorPageLayout` con `complexity="complex"` a ancho completo, `main` flexible y `aside` estructural aproximado de `22rem`;
- el `main` concentra la única superficie editable real del documento y el bloque de líneas mantiene su layout propio;
- el `aside` conserva únicamente controles secundarios ya presentes en la pantalla, sin convertirlo en `RightPanel` ni mover allí los totales;
- el footer sticky de totales se mantiene como dominio visual y económico de Proformas;
-`RdxEditorStickyFooter` queda justificado para combinar en una única superficie sticky la región de totales/contexto y las acciones `Cancelar` / `Guardar`;
-`PageFormHeader` queda reducido a navegación y contexto solo en `proformas/update`, sin cambio global del componente legacy;
-`RdxEditorPageLayout` también es apto para `proformas/update` cuando el `aside` contiene bloques secundarios ya existentes y el `main` conserva la única superficie editable.
-`RdxFormGrid` queda confirmado para campos en editores complejos, pero no debe envolver tablas o editores de líneas.
-`RdxEditorStickyFooter` está justificado para el patrón de editor complejo con una sola zona inferior persistente y sin duplicidad de acciones con el header.
### DECISIÓN_PROVISIONAL
- La extracción de una Page View pura es útil cuando reduce wiring y facilita tests sin controllers reales, pero no debe convertirse todavía en convención global.
- El patrón `main + aside` existe en ambos listados, pero hoy depende de `ResizablePanelGroup`, tamaños y apertura específicos de cada pantalla.
- El contrato final del footer contextual puede seguir afinándose cuando aparezcan paneles con resúmenes o acciones más heterogéneas.
-`RdxEditorPageLayout` ya cubre el editor simple, pero la convivencia visual con `PageFormHeader` debe seguir validándose antes de tocar el header legacy.
- la densidad final de la sticky zone inferior en móvil sigue requiriendo validación visual manual en múltiples resoluciones y tema oscuro.
### NO_ABSTRAER_TODAVÍA
-`RdxListPageLayout`: la geometría exterior ya queda resuelta por `RdxPageContainer`, `RdxPageStack` y la propia Page.
-`RdxResponsivePageGrid`: no encaja todavía como abstracción para listados con resize persistente.
- layouts superiores de listado mientras `ResizablePanelGroup` siga gobernando el split real.
- un layout superior específico de editor complejo mientras `RdxEditorPageLayout` + `RdxEditorStickyFooter` sigan cubriendo la geometría exterior.
---
## 22. Criterios de aceptación
La fase inicial se considerará correcta si:
-`packages/rdx-ui` contiene los primeros componentes Rdx;
- los contratos son puramente visuales;
- no existe dependencia de routing, datos o dominio;
-`proformas/list` puede adoptarlos sin perder comportamiento;
- la documentación Markdown está actualizada;
- el UI Kit muestra los componentes y sus variantes;
- tema claro y oscuro están validados;
- los tests aplicables pasan;
- no se ha creado un framework CRUD;
- las clases estructurales repetidas disminuyen;
- la Page sigue componiendo y haciendo wiring explícito.
---
## 23. Regla mental final
```txt
Rdx define geometría, jerarquía y comportamiento visual.
La Page compone.
Los controllers orquestan.
La UI no interpreta dominio ni transporte.
```
Y como criterio de calidad:
```txt
Si una abstracción ahorra pocas líneas pero empeora la lectura, no se usa.
Si un componente necesita conocer el caso de uso, no pertenece a rdx-ui.
Si un cambio visual no actualiza documentación y UI Kit, está incompleto.
