Saltar a contenido

ADR 026: Arquitectura de tema del panel (4 capas)

Estado

Aceptado — 2026-07

Relacionado con ADR 003, ADR 012, ADR 016.

Contexto

El panel CUS separa declaración de negocio (manifests, dashboards, forms) del runtime React. La capa visual debe ser intercambiable por namespace de panel sin duplicar lógica en plugins.

Zen Garden (operations.css, hooks cortex-panel-*) inició la separación esqueleto/skin. Falta un contrato estable para estilos, plantillas, estáticos y slots de shell.

Decisión

Cuatro capas de presentación, análogas al ensamblaje clásico diseño → plantilla → estilo → estáticos:

Capa Responsabilidad Implementación HIVE
Layouts Diagramación y distribución CUS dashboards, layoutHandle en pantallas, renderHooks, layoutSlots en configuración del panel
Templates Markup intercambiable por skin WidgetRegistry.resolve(type, skin) → type@skin opcional
Styles Tokens y apariencia packages/cortex-panel-shadcn/src/skins/{skin}.css bajo [data-skin]
Statics Imágenes y medios framework/web-shadcn/public/skins/{skin}/assets/ con fallback a base

Herencia de skin

  • Skin base: tokens neutros shadcn.
  • Skin operations: extiende base (import CSS + overrides de marca).
  • PanelTheme.skin en API selecciona el skin activo (data-skin en <html>).

Runtime

  1. ThemeProvider aplica modo claro/oscuro y skin activo.
  2. PanelShell lee panel.configuration.theme.skin y actualiza el skin.
  3. resolveSkinAsset(skin, key) resuelve rutas con fallback /skins/base/assets/.
  4. WidgetRenderer usa registry.resolve(type, skin, config.template).

Slots de shell (MVP)

Slot Uso
shell.sidebar.footer CTA sidebar (p. ej. float IA)
module.header.stats KPIs del header (alias de headerWidgets + renderHooks)
module.header.actions Acciones del header

Los hosts declaran slots vía PanelBuilder.layout_slot().

Consecuencias

  • Cambiar apariencia del panel operations = editar operations.css + assets en public/skins/operations/.
  • Nuevo skin = CSS + carpeta assets + registro en skinManifest.ts; plugins sin cambios.
  • Layout merge registry (ADR 016) sigue aplicando al contenido CUS; slots cubren el chrome del shell.

Referencias

  • packages/cortex-panel-shadcn/src/skins/
  • packages/cortex-panel-shadcn/src/assets/resolveSkinAsset.ts
  • packages/cortex-panel-shadcn/src/theme/skinLoader.ts
  • reports/FIGMA-PARITY-OPERATIONS-2026-07-21.md