104 lines
4.7 KiB
Markdown
104 lines
4.7 KiB
Markdown
# 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:
|
|
|
|
```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.
|