|
|
---
|
|
|
title: UIX Documentation — Start Here
|
|
|
type: index
|
|
|
audience: human + agent
|
|
|
authority: navigational — the single entry point to the whole doc corpus
|
|
|
status: current
|
|
|
---
|
|
|
|
|
|
# UIX Documentation — Start Here
|
|
|
|
|
|
This is the front door to the framework's documentation. If you are an agent or a
|
|
|
new session opening this repo, read this first: it tells you what exists, where it
|
|
|
lives, and the order to read it in. It is a **map**, not content — every entry
|
|
|
links the real document.
|
|
|
|
|
|
> **Want to run it and make a change, not just read?** →
|
|
|
> [`docs/getting-started.md`](./getting-started.md) — clone, run, and your first
|
|
|
> change, in order. The repository's own zones (what `src/`, `web/routes/`,
|
|
|
> `apps/*` and `scripts/` are, and who may write in each) →
|
|
|
> [`docs/repository.md`](./repository.md).
|
|
|
|
|
|
## What this framework is (60 seconds)
|
|
|
|
|
|
UIX is a Svelte 5 component system built around a **declarative contract**
|
|
|
(`morfo`) that the other layers consume. A component is declared once in morfo
|
|
|
(parts, `data-*`/ARIA, keyboard, events with a semantic family/intent); `soma`
|
|
|
executes the behavior, `sema` projects the perceptual signal, and `eidos`
|
|
|
materializes the visuals — all by reading the DOM attributes the morfo promises.
|
|
|
|
|
|
> **Morfo declares · Soma transcribes · Sema projects · Eidos paints.**
|
|
|
|
|
|
The full thesis is in [`architecture/overview.md`](./architecture/overview.md); the deep
|
|
|
architecture in [`architecture/active-architecture.md`](./architecture/active-architecture.md).
|
|
|
|
|
|
## The strata
|
|
|
|
|
|
The corpus is organized in layers of permanence, not by folder:
|
|
|
|
|
|
| Stratum | What it is | Where |
|
|
|
| ------------------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
|
|
|
| **E0 — orientation** | this file; the narrative entry; the glossary; the repository's own map | `docs/README.md`, `architecture/overview.md`, `docs/glossary.md`, `docs/repository.md` |
|
|
|
| **E1 — architecture** | how the layers fit | `docs/architecture/` (the book chapters) + in-place stubs |
|
|
|
| **E2 — canon** | the fixed vocabulary & contracts | `CANON.md`, `canon/tsc.md`, `canon/recipe-contract.md` |
|
|
|
| **E3 — decisions / RFC** | _why_ it is built this way | `decisions.md` + the RFCs & decision logs |
|
|
|
| **E4 — guides** | how to do a thing | `guides/`, `theming/guide.md`, `docs/consuming.md`, `docs/testing-and-tooling.md` |
|
|
|
| **E5 — module reference** | per-artifact docs | `arts/*/README`, `libs/*`, `svrs/*`, `packs/*/README` |
|
|
|
| **process** | ephemeral (hand-offs, snapshots, audits) | `docs/process/` — never a source of truth |
|
|
|
|
|
|
Writing or editing docs? The conventions that keep this corpus drift-free —
|
|
|
link the canon, don't copy it; keep reference docs timeless; one source per
|
|
|
concern — are in [`docs/authoring.md`](./authoring.md).
|
|
|
|
|
|
## Reading order for a fresh start
|
|
|
|
|
|
1. **[`architecture/overview.md`](./architecture/overview.md)** — the thesis: the four layers, what makes it different, what it is not.
|
|
|
2. **[`architecture/active-architecture.md`](./architecture/active-architecture.md)** — the deep architecture: the transcription chain, the DOM-primitive ownership table, the hard rules.
|
|
|
3. **[`docs/CANON.md`](./CANON.md)** — the semantic vocabulary (8 families, intents, verbs, channels). **Single source of truth — every other doc links here instead of re-stating it.**
|
|
|
4. Then the **layer reference** for whatever you are touching (table below).
|
|
|
|
|
|
Keep the [**glossary**](./glossary.md) open while you read — it defines the
|
|
|
invented vocabulary (morfo, archetype, hold, TSC, …) one line each.
|
|
|
|
|
|
## The map
|
|
|
|
|
|
### E1 — Architecture
|
|
|
|
|
|
| Doc | Layer |
|
|
|
| ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
|
| [`architecture/active-architecture.md`](./architecture/active-architecture.md) | The whole system — start here for depth |
|
|
|
| [`architecture/morfo.md`](./architecture/morfo.md) | The declarative contract (DNA) |
|
|
|
| [`architecture/soma.md`](./architecture/soma.md) · [`SOMA_ARCHITECTURE.md`](./architecture/soma-architecture.md) | Headless behavior — soma.md onboards, ARCHITECTURE is the deep reference |
|
|
|
| [`architecture/sema.md`](./architecture/sema.md) | Perceptual engine + channels (sound/haptic) + cascade |
|
|
|
| [`architecture/eidos.md`](./architecture/eidos.md) | The visual layer |
|
|
|
| [`architecture/active-uix.md`](./architecture/active-uix.md) | Composition root (boot modes) — first chapter migrated into the book tree ([`docs/process/PLAN-docs-book.md`](./process/PLAN-docs-book.md)) |
|
|
|
| [`architecture/active-app.md`](./architecture/active-app.md) | The arts composition root — fixed core (logger/bus/timers/orca/prefs) + declared services + orchestration; the App-side analogue of `active-uix` |
|
|
|
| [`arts/README.md`](../src/arts/README.md) | Runtime artifacts (`Engine*`/`Active*`) |
|
|
|
| [`architecture/packs.md`](./architecture/packs.md) | The pack tier — encapsulated opt-in collections above the layers (the canon-vs-pack admission rule, the P contract, the `Aura` promotion path) |
|
|
|
| [`architecture/agent.md`](./architecture/agent.md) | The agentic axis — the delegation model (`delegate` family), the actor primitive, the per-component participation contract, minimum contracts, a11y + threat doctrine |
|
|
|
| [`spec/delegation-contract.md`](./spec/delegation-contract.md) | **NORMATIVE** — the delegation contract as a citable specification (RFC-2119, stable `AG-n` requirement ids, date-versioned). `agent.md` is the WHY; this is the WHAT a conformant implementation must do. Status: DRAFT |
|
|
|
| [`architecture/blocks.md`](./architecture/blocks.md) | The blocks tier — page-function compositions above the canon (the canon-vs-block admission rule, the B contract, `blocks:check`) |
|
|
|
|
|
|
### E2 — Canon
|
|
|
|
|
|
| Doc | What it fixes |
|
|
|
| -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
|
| [`docs/CANON.md`](./CANON.md) | The semantic vocabulary — authoritative |
|
|
|
| [`canon/vocabularies.md`](./canon/vocabularies.md) | **The closed sets, GENERATED from the code** — archetypes, families+holds, verbs, intents, haptic kinds, palette scales, sizes, variants, shared strings. Build a component from exactly these (`npm run docs:vocabularies`; guarded by `docs:check`) |
|
|
|
| [`canon/tsc.md`](./canon/tsc.md) | Token Scope Contract — where every eidos token may be emitted |
|
|
|
| [`canon/recipe-contract.md`](./canon/recipe-contract.md) | Recipe Contract — which transversal theming systems every recipe must consume (enforced by `component-audit` R-4.x) |
|
|
|
| [`canon/direction-contract.md`](./canon/direction-contract.md) | Direction Contract — the `prop → prefs → 'ltr'` resolution chain, which attribute carries the direction (raw `dir` vs resolved `data-dir`) and which selector form may read it (`:dir()`; `[dir='rtl']` is forbidden) (enforced by `rtl-lint` RTL-1) |
|
|
|
|
|
|
### E3 — Decisions / RFC
|
|
|
|
|
|
| Doc | What it records |
|
|
|
| ---------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
|
| [`docs/decisions.md`](./decisions.md) | The RFC/design index — entry to all rationale |
|
|
|
| [`docs/next-features.md`](./next-features.md) | The initiative registry — user-decided future work (scope, sequencing, dependencies), fed by audits and sessions |
|
|
|
| [`rfcs/`](./rfcs/) | The eidos engine RFCs: [`rfc-color-model`](./rfcs/rfc-color-model.md) · [`rfc-color-engine`](./rfcs/rfc-color-engine.md) · [`rfc-typography`](./rfcs/rfc-typography.md) · [`rfc-depth`](./rfcs/rfc-depth.md) · [`rfc-shape`](./rfcs/rfc-shape.md) · [`rfc-structure`](./rfcs/rfc-structure.md) · [`rfc-scaling`](./rfcs/rfc-scaling.md) |
|
|
|
| [`decisions/design-text-effects.md`](./decisions/design-text-effects.md) | The text-effects component family — why text animations are canon (not the pack tier), the CountUp-service vs `Text*`-decorative split, and the a11y / measurement doctrine every member obeys |
|
|
|
| [`decisions/book-deviations.md`](./decisions/book-deviations.md) | Where the implementation deviates from / extends the book (Spanish — the author's decision logbook) |
|
|
|
| [`decisions/guia-semantica-historica.md`](./decisions/guia-semantica-historica.md) | The founding implementation guide (Spanish, historical seed — superseded by `CANON.md` + code) |
|
|
|
| [`theming/channels.md`](./theming/channels.md) | The eight expression channels, synthesized |
|
|
|
| [`theming/notes.md`](./theming/notes.md) | Theming: comparison vs reference libs + FAQ |
|
|
|
| [`theming/changelog.md`](./theming/changelog.md) | The theming chronicle — the dated history behind the reference's standing decisions (§13, §20–§38) |
|
|
|
|
|
|
### E4 — Guides
|
|
|
|
|
|
| Doc | How to |
|
|
|
| ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
|
| [`docs/building-a-component.md`](./building-a-component.md) | **Build a component — start here.** The cross-layer route (9 phases, one doc per phase, one guard per phase) |
|
|
|
| [`guides/component-guide.md`](./guides/component-guide.md) | The soma phase in depth (ordered steps + rules A1–A37) |
|
|
|
| [`guides/completion-checklist.md`](./guides/completion-checklist.md) | Decide when a component is _done_ (machine-audited) |
|
|
|
| [`theming/reference.md`](./theming/reference.md) · [`theming/guide.md`](./theming/guide.md) | Theming reference (E1) + the add-component / define-theme how-tos (E4) |
|
|
|
| [`theming/motion.md`](./theming/motion.md) | The motion model — two moments, F1–F7, the preset/signature system (reference) |
|
|
|
| [`theming/gradient-finish.md`](./theming/gradient-finish.md) | The gradient finish — a gradient is a MATERIAL of the fill, never a color identity: the anchored ramp («la rampa huye de la tinta»), the dial, the executable guard, and the full decision record (D1–D9) |
|
|
|
| [`eidos/components/README.md`](../src/uix/eidos/components/README.md) | The eidos component pattern |
|
|
|
| [`theming/motion-guide.md`](./theming/motion-guide.md) | Animate it — the `motion` prop, the preset catalog, loops, stagger, reduced-motion (links the model + the motion RFC) |
|
|
|
| [`guides/demo-authoring.md`](./guides/demo-authoring.md) | Author an interactive demo page |
|
|
|
| [`guides/component-audit.md`](./guides/component-audit.md) | The binding pre-flight audit before touching any component |
|
|
|
| [`docs/consuming.md`](./consuming.md) | Consume the framework from an app in this workspace — aliases, runes, composition root, CSS and assets, the pre-hydration boot |
|
|
|
|
|
|
### E5 — Module reference
|
|
|
|
|
|
Per-artifact READMEs live next to the code: `src/arts/{name}/README.md` (indexed
|
|
|
in [`arts/README.md`](../src/arts/README.md)), plus the pure helpers in `src/libs/`
|
|
|
and the server-authoritative engines in `src/svrs/`.
|
|
|
|
|
|
## "I want to…"
|
|
|
|
|
|
| Goal | Go to |
|
|
|
| ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
|
| Run it and make a first change | [`docs/getting-started.md`](./getting-started.md) |
|
|
|
| Build an app on the framework | [`docs/consuming.md`](./consuming.md) — the workspace contract |
|
|
|
| Understand the framework | [`architecture/overview.md`](./architecture/overview.md) → [`architecture/active-architecture.md`](./architecture/active-architecture.md) |
|
|
|
| Know why UIX, not Radix / Mantine | [`docs/comparison.md`](./comparison.md) |
|
|
|
| Know what a family / intent / verb means | `docs/CANON.md` (doctrine) · [`canon/vocabularies.md`](./canon/vocabularies.md) (the generated closed sets) |
|
|
|
| Know which archetype / hold / haptic kind / scale a part or event may use | [`canon/vocabularies.md`](./canon/vocabularies.md) — the authoritative lists, generated from the code |
|
|
|
| **Build a new component** | [`docs/building-a-component.md`](./building-a-component.md) — the one door: the 9-phase route across all layers, with the guard for each phase and the known superseded-doc traps |
|
|
|
| Know if a component is finished | [`guides/completion-checklist.md`](./guides/completion-checklist.md) (`npm run component:audit`) |
|
|
|
| Theme it / add a token | [`theming/reference.md`](./theming/reference.md) + [`canon/tsc.md`](./canon/tsc.md) |
|
|
|
| Animate it (motion · loops · stagger · reduced-motion) | [`theming/motion-guide.md`](./theming/motion-guide.md) |
|
|
|
| Make it work in RTL (assert a direction · mirror the paint) | [`canon/direction-contract.md`](./canon/direction-contract.md) (`npm run rtl:check`) |
|
|
|
| Understand why a decision was made | `docs/decisions.md` → the relevant RFC / [`decisions/book-deviations.md`](./decisions/book-deviations.md) |
|
|
|
| Use a runtime artifact (auth, cache, http, …) | [`architecture/active-app.md`](./architecture/active-app.md) (the composition root) → [`arts/README.md`](../src/arts/README.md) (the map) → `src/arts/{name}/README.md` (per-artifact) |
|
|
|
| **Write or edit documentation** | [`docs/authoring.md`](./authoring.md) — the authoring rules |
|
|
|
| Test or validate a change | [`docs/testing-and-tooling.md`](./testing-and-tooling.md) — tests, validators, codegen, format policy, the gate, SSR |
|
|
|
| Know what a zone of the repository is for (and what is frozen) | [`docs/repository.md`](./repository.md) — the zones, the single install, the one import map |
|
|
|
| Write a guard (or reformat the tree without blinding one) | [`docs/testing-and-tooling.md`](./testing-and-tooling.md) § Guards that read source text |
|
|
|
|
|
|
## Authoritative sources & rules
|
|
|
|
|
|
- **Editorial source**: [`docs/Disenando_lo_que_ocurre_FINAL.pdf`](./Disenando_lo_que_ocurre_FINAL.pdf) — the book _Diseñando lo que ocurre_ (FINAL edition, 426 pp., tracked in-repo since 2026-07-11; the `.docx` sibling is the editable master), the origin of the semantic canon.
|
|
|
- **Agent rules**: [`CLAUDE.md`](../CLAUDE.md) and [`AGENTS.md`](../AGENTS.md) — the build/test commands, code style, and the hard rules. Read these before editing.
|
|
|
|
|
|
## Process (ephemeral — not a source of truth)
|
|
|
|
|
|
[`docs/process/`](./process/) holds session hand-offs, architecture snapshots and
|
|
|
audits. They record _what happened_, not _what is true_ — the docs above are the
|
|
|
truth. The active corpus-migration state is in
|
|
|
[`docs/process/CONTINUE-docs-corpus.md`](./process/CONTINUE-docs-corpus.md).
|
|
|
|
|
|
> **Note**: `soma/components/palabras` + `eidos/components/palabras` are an active,
|
|
|
> separate development track and are deliberately outside this corpus.
|
