9.2 KiB

Raw Blame History

UIX

Documento corto de posicionamiento arquitectonico para src/uix.

Nota de continuidad más reciente: 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.

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

`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

`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

`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:

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:

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.

9.2 KiB Raw Blame History

UIX