svelte-kit-vice/docs/glossary.md

---
title: UIX Glossary
type: reference
audience: human + agent
authority: navigational — concise definitions; the linked doc is authoritative
status: current
---

# UIX Glossary

The framework's invented vocabulary, defined in one line each, with a pointer to
the authoritative doc. The **semantic** vocabulary (families, intents, verbs,
channels) is owned by [`CANON.md`](./CANON.md) — this glossary points there
rather than re-stating the values, so they cannot drift.

New here? Start at [`docs/README.md`](./README.md).

## The layers

| Term | Meaning |
| --- | --- |
| **morfo** | The declarative contract (a component's "DNA"): its public DOM surface — parts, `data-*`/ARIA, keyboard, events — declared once in a typed object. Every other layer reads it. → [`architecture/morfo`](./architecture/morfo.md) |
| **soma** | The headless behavior layer: keyboard, focus, ARIA wiring, state machines, composition. No visuals. → [`architecture/soma`](./architecture/soma.md) |
| **sema** | The perceptual engine: turns a declared event into sound / haptic (runtime) and a `data-event-*` projection (for eidos), via a cascade. → [`architecture/sema`](./architecture/sema.md) |
| **eidos** | The visual layer: CSS recipes, tokens, themes, sizes, variants — reacts to the DOM attrs morfo promises. → [`architecture/eidos`](./architecture/eidos.md) |
| **arts** | Runtime artifacts: the `Engine*` / `Active*` services (auth, cache, http, format, langs, dom, motion, …). → [`arts/README`](../src/arts/README.md) |
| **libs** | Pure, zero-dependency helpers (`$libs/days`, `$libs/dom`, `$reactive`, …). |
| **svrs** | Server-authoritative engines (`$svrs/auth`, `$svrs/perm`, `$svrs/cache`). |
| **active-uix** | The composition root that wires the layers — `createActiveUix` (standalone) or `attachActiveUix` (attach to an app). → [`architecture/active-uix`](./architecture/active-uix.md) |
| **ActiveDom / `$adom`** | The single reactive DOM service: the only sanctioned surface for managed DOM writes, listeners, queries, focus and scroll. |
| **pack** | An encapsulated opt-in collection above the layers (decorative leaves: no morfo, outside the acceptance matrix, one-way dependency). Admission rule + P contract → [`architecture/packs`](./architecture/packs.md) |
| **scene (`EngineScene` / `$scene`)** | The ambient-scene runtime art: mounts a WebGL/canvas-2D **effect** on a host with the citizenship done once (frame loop, off-view pause, DPR cap, mandatory reduced-motion, context loss/restore, budget, teardown). Effects are shared resources (`$scene/effects`) — the same one a pack mounts decoratively, `Aura` will mount semantically. → [`arts/scene/README`](../src/arts/scene/README.md) |
| **Ambient** | The first pack (`$packs/ambient`) — animated backgrounds. `<Ambient effect="…">` mounts a registered scene effect; colors accept theme tokens (P-4). → [`src/packs/ambient/README`](../src/packs/ambient/README.md) |
| **Aura** | The canonical **agent-presence** component: it materializes the `delegate` + `sustain` families by consuming `$scene/effects` semantically (intent → speed/amplitude/hue). The promotion path it walked is in [`architecture/packs`](./architecture/packs.md). → [`eidos/components/aura/README`](../src/uix/eidos/components/aura/README.md) |
| **Background** | The canonical **host of a surface's background layers** — image, video, pattern, gradient, scrim, or a scene the app mounts itself. A CHILD, never a wrapper: it renders inside the surface it dresses and pins itself behind that surface's content, so any element can host it and layout never moves. The parent is ADOPTED by a foundation rule rather than configured. The animated effect stays in the pack tier; the host is canon because it owns a contract (`aria-hidden` layers, the WCAG 2.2.2 pause control, a token surface). → [`eidos/components/background/README`](../src/uix/eidos/components/background/README.md) |
| **text effects** | A canon family of eidos components that treat REAL text content (`TextGradient`, `TextCircular`, `TextBlur`, `TextFocus`, `TextScramble`) plus the service `CountUp` — the animated siblings of the typographic primitives. Content stays the accessibility surface; the animation is presentation. Each self-documents (README + demo). |

## Morfo vocabulary

| Term | Meaning |
| --- | --- |
| **part** | A named sub-element of a component (`provider`, `trigger`, `content`, …). |
| **archetype** | Cross-component classification of a part (`trigger`, `item`, `option`, …) — used for transversal eidos selectors and sema verbs. |
| **kind** | A part's visibility: `public` \| `internal` \| `private`. |
| **data-attr contract** | The stable markers a part emits: `data-{component}` (provider) and `data-{component}-{part}`. Never `data-soma-*`. The eidos/sema frontier. |
| **value sources (`v.*`)** | Typed origins for an ARIA/data value in morfo: `v.literal`, `v.stateRef`, `v.partRef`, `v.propRef`, `v.translationRef`. |
| **scope** | Which layers implement the component: `['soma']`, `['soma', 'eidos']`, … |
| **2-of-3 rule** | A morfo field is justified only if at least 2 of soma / sema / eidos consume it. |
| **compileMorfo** | Turns a morfo into a `CompiledMorfo` (resolved attr/keyboard/action plans + the closed set of CSS selectors), cached by morfo identity. |
| **expression** | How a morfo materializes its perceptual signature: `'pack'` \| `'family-default'` \| `'delegated'` \| `'none'`. |

## Soma vocabulary

| Term | Meaning |
| --- | --- |
| **provider** | The concrete state class for a component or part. The root registers context; sub-parts read it. Exported as `Xxx.Provider`. |
| **SomaRuntime** | The morfo interpreter in soma. `runtime.part()` registers a part; `runtime.trigger(event)` sequences prewrite → emit → handler → effect-driven attrs. |
| **layer (soma)** | A shared behavior class consumed by providers: `Presence`, `FocusScope`, `Dismissal`, `ScrollLock`, `Gesture`, `SafePolygon`. → [`SOMA_ARCHITECTURE`](./architecture/soma-architecture.md) §6 |
| **Presence** | Animation-aware mount/unmount (waits for exit animations before removing). |
| **Active\<T\> / State\<T\>** | Reactive containers (readonly / mutable, exposing `.current`) that let runes be passed by reference between classes. |
| **context convention** | The `X.create()` / `X.get()` / `X.require()` static methods every context-using class follows. |
| **roving vs virtual focus** | Two keyboard strategies: real DOM focus with one `tabindex=0` (roving) vs focus stays on the input and items are `data-highlighted` via `aria-activedescendant` (virtual). |
| **polymorphic close** | One `emerge-close` event with `allowedFamilies`; the provider chooses the family at dismiss time (used by Dialog/Drawer/Popover). |
| **prewrite / commit** | DOM written imperatively *before* the semantic emit (`prewrite`, e.g. `data-last-action`) vs the structural state written *after* (`commit`). |
| **activeDir** | The direction resolver a wrapper runs for a component; returns `Active<Direction \| undefined>`, where `undefined` means nobody asserted a direction. → [`canon/direction-contract`](./canon/direction-contract.md) |
| **resolvedDir** | A provider's concrete direction — `activeDir`'s value with the fallback applied, once, for the component's own maths. |

## Sema vocabulary

The values live in [`CANON.md`](./CANON.md); these are the term shapes.

| Term | Meaning |
| --- | --- |
| **family** | One of the **8** perceptual event families (contact · commit · signal · handle · emerge · shift · sustain · delegate). → CANON |
| **intent** | The evaluative load of an occurrence (neutral · affirm · fulfill · risk · threat · loss) — only on valenced families. → CANON |
| **verb** | The specific act within a family (`tap`, `select`, `close`, …). → CANON |
| **direction** | The sense of a traversal (`forward` \| `backward`, `SemaDirection`), stamped as `data-event-direction`. Two values, because the event NAME already separates `shift-enter-mode` from `shift-exit-mode`; what a name cannot carry is which way THIS occurrence went. Decided per emit and optional, like intent. A SENSE, not an axis — eidos maps it onto the inline axis so `:dir(rtl)` flips it. → CANON |
| **channel** | An expression modality. Sema runs two at runtime (sound, haptic) and projects `visual`; eidos owns the rest (motion/presence/depth/shape/color). → CANON |
| **hold** | The minimum perceptible duration a signal stays projected (`data-event-*` stamped during it). |
| **cascade** | The layered resolution of a perceptual signature (1 family base → 2 intent deltas → 3 per-event → 4 globals → 5a packs / 5b app rules). → [`architecture/sema`](./architecture/sema.md) |
| **persistence** | A signal's lifecycle, distinct from hold: `transient` \| `untilAction` \| `untilFix` \| `stateBound`. |

## Eidos vocabulary

| Term | Meaning |
| --- | --- |
| **recipe** | A component's token + CSS definition (in `EidosConfig.recipes` / `{name}.css`). |
| **token** | A CSS custom property. Public: `--{component}-*`; private recipe-internal: `--_{component}-*`. Never `--eidos-*` / `--soma-*`. |
| **TSC (Token Scope Contract)** | Where each token is allowed to be emitted (`:root` / `[data-{c}]` / by color / by event) + transitivity validation. → [`canon/tsc`](./canon/tsc.md) |
| **variant** | A fixed visual archetype (`solid`, `outline`, `ghost`, …). Canon of eidos — a theme cannot invent or redefine one. |
| **role** | One of the **9** canonical color roles (`primary`, `secondary`, `tertiary`, `neutral`, `affirm`, `fulfill`, `risk`, `threat`, `loss`). |
| **scaling / density** | Orthogonal structural axes: global zoom (90–110) vs spacing (compact/comfortable/spacious). |
| **theme** | A retint of the perceptually-fixed: it changes *which hex* is `affirm`, never *what* `outline` means. → [`THEMING`](./theming/reference.md) |
| **`data-dir`** | A component's own direction attribute, carrying the resolved value — opt-in, for a recipe that needs a hook which always matches; native `dir` carries the raw value and is absent when nobody asserted one. |
| **RTL-1** | The eidos lint rule (`npm run rtl:check`) that flags a logical inline anchor paired with a physical inline translate in the same CSS block. |
| **`rtl-physical:`** | The sanctioned comment that exempts a block from RTL-1 when its geometry genuinely is physical: `/* rtl-physical: <reason> */`. |