# UIX Documento corto de posicionamiento arquitectonico para `src/uix`. Nota de continuidad más reciente: [src/uix/CONTINUITY_2026-04-24.md](/G:/dev/svelte/vicen/src/uix/CONTINUITY_2026-04-24.md) UIX no intenta ser "otra libreria de componentes". La apuesta es mas ambiciosa y mas estructural: **separar capas que casi todos los frameworks actuales mantienen mezcladas**. En la mayoria de sistemas de UI, estas cosas viven pegadas: - contrato publico del DOM - comportamiento headless - accesibilidad - semantica del evento - capa visual - motores modales (sound, vibra, motion) - integracion con servicios de app UIX intenta partir ese bloque en piezas con fronteras fuertes. --- ## 1. La idea central UIX modela la interfaz como varias capas cooperando, no como un unico componente gigante que hace todo a la vez. ```text App ├─ servicios transversales │ └─ ADom └─ componentes └─ capa estructural / semantica / comportamental / visual ``` La intuicion es esta: - la estructura publica del componente no es lo mismo que su comportamiento - la semantica de un evento no es lo mismo que su materializacion - el DOM activo no es lo mismo que utilidades DOM puras - la app no deberia acoplar motores modales entre si UIX pone nombres y contratos explicitos a esas separaciones. --- ## 2. Las capas de UIX ### `Morfo` Contrato estructural cross-layer del componente. Define: - partes - `data-*` - ARIA - foco - teclado - eventos No es prose ni runtime. Es la forma canonica publica del componente. Ver: [src/uix/morfo/README.md](/G:/dev/svelte/vicen/src/uix/morfo/README.md) ### `Sema` Vocabulario y contrato semantico. No ejecuta sound, vibra ni CSS. Su trabajo es decir: - que acciones existen - que ocurrencias/eventos canónicos nombra el sistema - como se relacionan esos nombres con el componente En su version madura, `Sema` debe ser **vocabulario y validacion**, no runtime. ### `Soma` Capa headless de comportamiento. Gestiona: - estado - contexto - a11y - keyboard / pointer / focus - emision de eventos hacia `ADom` `Soma` no deberia conocer la implementacion concreta de los engines modales. Su trabajo es emitir hechos del componente, no materializarlos. Ver: [src/uix/soma/SOMA_ARCHITECTURE.md](/G:/dev/svelte/vicen/src/uix/soma/SOMA_ARCHITECTURE.md) ### `Eidos` Capa visual. Reacciona a contratos DOM y a senales reflejadas, pero no implementa la logica headless del componente. Su responsabilidad es apariencia, no comportamiento. ### `ADom` Runtime observable del DOM activo. No es un helper DOM puro ni un semantic engine. Es el broker infrastructural de senales DOM activas: - recibe emisiones de `Soma` - publica a listeners tipados - refleja `data-event*` en el DOM - evita que cada engine monte su propio observer para el mismo hecho Ver: [src/uix/adom/README.md](/G:/dev/svelte/vicen/src/uix/adom/README.md) ### `uix/lib/dom` Utilidades DOM puras o casi puras. Aqui viven: - `contains` - `getDocument` - `getWindow` - foco - traversal - wrappers base de observers No contiene el runtime activo. Ese papel pertenece a `ADom`. --- ## 3. Que hace distinto a UIX ### 3.1 El contrato estructural es una capa propia En la mayoria de librerias, la estructura publica del componente esta dispersa: - atributos en el provider - roles en el render - partes en CSS - selector names en docs - contratos en tests UIX intenta concentrar eso en `Morfo`. Eso no es una comodidad menor; cambia el tipo de sistema que puedes construir: - docs derivadas del contrato - validacion cross-layer - menos drift entre headless y visual - tooling mas fiable ### 3.2 La semantica no se mezcla con la ejecucion UIX separa el **nombre de la ocurrencia** de su **materializacion modal**. Eso permite que: - sonido - vibracion - CSS - motores futuros usen el mismo vocabulario sin quedar pegados entre si. ### 3.3 El comportamiento headless no carga con toda la modalidad `Soma` no deberia ser un mega-engine que sabe de todo: - no sabe reproducir WAVs - no sabe vibrar - no sabe decidir la fisica perceptiva de cada canal `Soma` emite. Los engines ejecutan. ### 3.4 El DOM activo es infraestructura de app, no detalle incidental Muchos sistemas tratan el DOM como detalle local del componente. UIX da un paso mas: reconoce que hay hechos transversales del DOM que varios consumidores quieren escuchar, y por eso introduce `ADom`. Eso permite: - un solo punto de publicacion - listeners tipados - reflection uniforme en atributos - menos `MutationObserver` duplicados - mejor tooling y debug ### 3.5 La app compone servicios, no "super componentes" UIX se apoya en un modelo donde la app compone servicios transversales y los componentes los consumen. `langs`, `presentation`, `logger` y `ADom` viven mejor como servicios de app que como dependencias ocultas dentro de cada componente. --- ## 4. Lo que UIX no es UIX no es: - una coleccion plana de componentes visuales - un simple wrapper opinionated sobre primitives existentes - un design system clasico donde visual, comportamiento y contratos viven juntos - un semantic engine centralizado que ejecuta todas las modalidades - un `EventEmitter` global disfrazado de arquitectura Tampoco busca novedad gratuita. La originalidad de UIX no esta en inventar nombres exoticos, sino en **separar problemas reales** que otros sistemas suelen aceptar como un unico bloque. --- ## 5. Comparacion honesta con otros enfoques ### Frente a headless libraries clasicas Librerias como Radix, Ariakit o React Aria resuelven muy bien comportamiento y accesibilidad. Pero normalmente no separan: - contrato estructural declarativo - vocabulario semantico independiente - runtime transversal de DOM activo UIX quiere cubrir ese espacio. ### Frente a design systems clasicos Muchos design systems tienen tokens, componentes y guidelines, pero la frontera entre: - estructura - comportamiento - visualidad - semantica queda difusa. UIX intenta que cada una tenga una capa reconocible. ### Frente a engines modales aislados Es relativamente comun encontrar sistemas de motion o sound por separado. Lo raro es tener: - headless primitives - contrato estructural machine-readable - vocabulario comun - servicio de DOM activo - engines modales desacoplados trabajando juntos sin colapsar en un runtime monolitico. --- ## 6. Por que esto puede ser valioso Si sale bien, UIX ofrece algo poco comun: - mejor explicabilidad arquitectonica - menos drift entre capas - mas capacidad de validacion automatica - mejor testabilidad - mas libertad para introducir nuevos engines - mas honestidad sobre que pertenece al framework y que pertenece al integrador Especialmente importante: **la coherencia cross-modal puede tratarse como responsabilidad del integrador, no como una falsa promesa de un runtime centralizado que pretende saberlo todo.** El framework puede proveer: - vocabulario - contratos - transporte - puntos de extension Pero no debe fingir que puede decidir por todas las modalidades de todas las apps. --- ## 7. Los riesgos reales UIX tambien tiene riesgos claros, y conviene decirlos sin adornos. ### 7.1 Exceso de capas Si las fronteras no estan clarisimas, el sistema puede sentirse mas complejo de lo que realmente resuelve. ### 7.2 Nombres sin disciplina Si `Morfo`, `Sema`, `Soma`, `Eidos`, `ADom` no mantienen contratos nitidos, los nombres se convierten en decoracion y no en arquitectura. ### 7.3 Invasion de responsabilidades El peligro constante es que una capa intente hacer el trabajo de otra: - `Sema` convirtiendose en runtime - `Soma` convirtiendose en engine modal - `ADom` convirtiendose en semantic engine - `Eidos` acoplandose a detalles incidentales UIX solo funciona si cada capa acepta sus limites. ### 7.4 Falta de precedentes No hay demasiados sistemas con esta composicion exacta. Eso significa mas libertad, pero tambien menos patrones externos que copiar. Hay que inventar con disciplina. --- ## 8. Reglas de dependencia UIX debe preservar una direccion clara de acoplamiento. Version simplificada: ```text Morfo -> describe Sema -> nombra y valida sobre Morfo Soma -> implementa comportamiento y emite a ADom ADom -> transporta y publica Eidos -> materializa visualmente App -> compone servicios y engines ``` Y, como regla general: - `Morfo` no conoce `Soma` - `Sema` no ejecuta engines - `ADom` no conoce sonido ni vibracion - `Soma` no conoce implementaciones modales concretas - `Eidos` no duplica behavior headless --- ## 9. La diferencia en una frase Si hubiera que resumir UIX en una sola idea, seria esta: > UIX trata la interfaz no como un componente monolitico, sino como un sistema de > capas con contratos explicitos entre estructura, semantica, comportamiento, > visualidad y transporte de eventos activos. Esa es la apuesta. --- ## 10. Orden de lectura sugerido Para entender el sistema en su estado actual: 1. [src/uix/morfo/README.md](/G:/dev/svelte/vicen/src/uix/morfo/README.md) 2. [src/uix/soma/SOMA_ARCHITECTURE.md](/G:/dev/svelte/vicen/src/uix/soma/SOMA_ARCHITECTURE.md) 3. [src/uix/adom/README.md](/G:/dev/svelte/vicen/src/uix/adom/README.md) 4. [src/uix/terra/README.md](/G:/dev/svelte/vicen/src/uix/terra/README.md) 5. [src/uix/air/README.md](/G:/dev/svelte/vicen/src/uix/air/README.md) La arquitectura final seguira cambiando, pero esta es la idea fundacional que explica por que UIX no se parece demasiado a otros frameworks de UI.