FactuGES_ERP/docs/frontend/UI/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;
- `RdxPanel` 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;
- `RdxPanel` puede usar `variant="card"` 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:

```txt
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.