4.3 KiB
| title | type | audience | status |
|---|---|---|---|
| How UIX Compares | notes | human + agent | current |
How UIX Compares
An honest read of where UIX sits relative to the field. This is framework-level
positioning grounded in UIX's own documented design choices — not a feature
matrix of competitors' internals. The per-component prop-parity comparisons
(against ark-ui, bits-ui, radix-ui, react-aria) live in each component's
README.md, by project doctrine; this doc is the layer above them.
Two families exist
Component libraries cluster into two families, and they force a trade:
- Headless behavior (Radix Primitives, Ark UI, bits-ui, React Aria) — solve behavior + accessibility, leave visuals to you. Excellent separation, but they stop at behavior: there is no model of what an interaction means or how it should feel.
- Styled systems (Mantine, Chakra, Radix Themes, shadcn) — ship opinionated visuals and theming, but couple behavior and appearance and let a theme redefine almost anything.
UIX keeps the headless family's strict separation and adds the two things neither family has: a declarative contract above behavior, and a perception layer below visuals.
What UIX adds
1. A single declarative contract (morfo)
A component's public DOM surface — parts, data-*, ARIA, keyboard, events — is
declared once in a typed object and consumed by every layer. Rename a part and
the consuming layers break at compile time. In the headless libraries that
structural information is spread across the provider, the ARIA derivations, the
CSS and the docs, and drifts silently. → morfo/README
2. A perception layer (sema)
UIX models the meaning and feel of an interaction: 8 perceptual families,
intents (the evaluative load), verbs, and a cascade that projects the signal as
sound, haptic and a data-event-* stamp. No mainstream component library has a
perceptual layer — they animate, but they do not have a vocabulary for what
occurred. The vocabulary is grounded in the book Diseñando lo que ocurre. →
CANON.md, sema/README
3. Two-moment motion
UIX animates two moments and integrates them with the perceptual signature:
--event (the flourish during a signal's hold) and --state (the transition to
a persistent condition). The other systems collapse presence animation onto a
single axis (e.g. Chakra: only data-state + Presence). → eidos-motion.md
4. Theme = retint the perceptually-fixed
Variants (solid/outline/…) and the 9 color roles are canon of the system,
not of the theme. A theme changes which hex is affirm; it cannot invent a
variant or redefine what outline means. This is the opposite of styled systems
where a theme can redefine almost anything — UIX trades that freedom for
portability and a stable perceptual meaning across themes. → THEMING.md §19
5. Validated token scope (TSC)
Where each token may be emitted is part of the source contract and validated at
generation, instead of ad-hoc CSS variables sprinkled across selectors. →
TSC.md
6. Graceful degradation
Components are headless-functional without a DOM, and sema is ornamental — sound
/ haptic / audio-disabled / SSR environments work without special-casing. →
testing-and-tooling.md (SSR posture)
The honest trade-offs
- More to learn. Four layers + a perceptual vocabulary is more concepts than "import a styled component." The glossary and getting-started exist because of this.
- Smaller ecosystem. Radix/Mantine have years of community components and battle-testing; UIX is one codebase.
- The perception layer only pays off if you use it. A team that just wants styled, accessible widgets gets the headless behavior — but the sema layer's value (coherent sound/haptic/motion meaning) is realized only when an app wires it.
Where the per-component detail lives
Each component's README.md carries a ## Comparison table against ark-ui,
bits-ui, radix-ui (and react-aria where relevant), with every gap marked and a
disposition (implement / defer / drop). That is the contract-level honesty;
this doc is the architecture-level one.