FactuGES_ERP/packages/rdx-ui/docs/contributing-ui.md

Contributing UI

Reglas base

• todos los componentes públicos propios deben usar prefijo Rdx;
• el código y los identificadores deben estar en inglés;
• la documentación y los comentarios deben estar en español;
• usar TypeScript estricto;
• usar imports de tipos explícitos en cabecera;
• no usar tipos inline tipo import("react").ReactNode.

Responsabilidad de packages/rdx-ui

Los componentes de rdx-ui:

• no conocen React Query;
• no conocen routing;
• no conocen DTOs;
• no conocen entities;
• no conocen controllers funcionales;
• no contienen lógica de negocio.

Deben recibir props ya preparadas por la capa consumidora.

Tema y color

• todo debe funcionar en light y dark desde el inicio;
• usar tokens semánticos;
• no introducir colores físicos sin justificación fuerte y documentada;
• no usar el color como único indicador de estado.

Accesibilidad

• foco visible obligatorio;
• botones de icono con nombre accesible;
• no crear div clicables;
• mantener orden DOM coherente;
• usar controles reales proporcionados por el consumidor;
• evitar wrappers vacíos que compliquen la semántica.

API pública

• mantener una API pequeña y explícita;
• no crear abstracciones genéricas sin repetición real;
• className es un escape controlado, no la API principal;
• no usar transition-all en nuevos componentes salvo caso excepcional documentado.

Composición de paneles

• no duplicar sombras entre una primitive y su composición;
• no duplicar el control de cierre entre capas;
• las acciones de contexto deben llegar ya construidas desde el consumidor;
• los labels accesibles de acciones de dominio pertenecen al consumidor;
• una primitive reutilizable puede resolver superficie e infraestructura, mientras la composición resuelve jerarquía visual y accesibilidad contextual.

Acciones de fila

• RdxRowActions solo renderiza acciones primarias y overflow;
• el consumidor decide qué acciones existen y en qué orden aparecen;
• las acciones destructivas deben ir en overflow salvo excepción justificada por código real;
• disabledReason pertenece al consumidor y debe ser comprensible sin conocimiento de dominio en rdx-ui;
• no mover permisos, navegación, dialogs ni entidades dentro de packages/rdx-ui;
• los icon buttons deben mantener aria-label y tooltip accesible.

Editor simple

• por defecto, las pantallas cuya finalidad principal sea crear, editar o configurar mediante formulario deben usar shell app-fullscreen y no el shell con sidebar;
• usar PageFormHeader o el header de dominio ya existente para la navegación mínima de salida, sin duplicar una segunda navegación lateral;
• RdxEditorSection con variant="plain" es el patrón por defecto del editor simple;
• usar una única superficie editable cuando sea útil separar claramente la página del área de formulario;
• no envolver cada sección en Card por defecto;
• no duplicar padding entre shell, layout y superficie editable;
• RdxFormGrid debe concentrar la retícula del editor sin acoplarse a RHF;
• las diferencias entre create y update no justifican nuevos componentes si solo cambian defaults o wiring.

Editor complejo

• RdxEditorPageLayout debe reservar el aside para resumen, metadata o contexto de apoyo;
• no mover campos editables al aside solo para equilibrar visualmente columnas;
• en desktop el layout objetivo del editor complejo es minmax(0, 1fr) ~22rem;
• el aside debe apilarse debajo del main cuando no haya ancho suficiente;
• si no existe aside, no debe reservarse hueco lateral;
• mantener una única superficie principal para el formulario, también en editores complejos;
• RdxEditorSection puede usar variant="panel" dentro del aside cuando el bloque necesite superficie independiente;
• RdxFormGrid debe quedarse en grupos de campos y no envolver tablas, line editors ni layouts funcionales especializados;
• no mover los totales al aside por defecto;
• si el editor usa footer sticky inferior, no duplicar Guardar y Cancelar completos en el header;
• RdxEditorStickyFooter no conoce RHF, submit, routing ni dominio; solo compone superficie, orden, separación y responsive;
• la región leading del footer puede alojar resumen o contexto, pero ese contenido sigue perteneciendo al dominio consumidor;
• coordinar cualquier sticky lateral con el offset del header para evitar clipping y foco oculto.

Sincronización obligatoria

Todo cambio futuro que afecte a la API pública o al comportamiento visual debe actualizar en el mismo cambio:

1. implementación
2. documentación Markdown
3. página interactiva UI Kit
4. tests aplicables

Un cambio queda incompleto si cualquiera de esas cuatro piezas queda desincronizada.