---
title: How UIX Compares
type: notes
audience: human + agent
status: 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. → [`architecture/morfo`](./architecture/morfo.md)

### 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`](./CANON.md), [`architecture/sema`](./architecture/sema.md)

### 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`](./theming/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`](./theming/reference.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. →
[`canon/tsc.md`](./canon/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`](./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](./glossary.md) and
  [getting-started](./getting-started.md) 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.