title	type	audience	authority	status
UIX Documentation — Start Here	index	human + agent	navigational — the single entry point to the whole doc corpus	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 — clone, run, and your first change, in order.

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 src/uix/README.md; the deep architecture in src/uix/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	docs/README.md, src/uix/README.md, docs/glossary.md
E1 — architecture	how the layers fit	active_architecture.md + per-layer READMEs
E2 — canon	the fixed vocabulary & contracts	CANON.md, eidos/TSC.md, GUIA_IMPLEMENTACION_SEMAUIX.md
E3 — decisions / RFC	why it is built this way	decisions.md + the RFCs & decision logs
E4 — guides	how to do a thing	COMPONENT_GUIDE.md, THEMING*
E5 — module reference	per-artifact docs	arts/*/README, libs/*, svrs/*
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.

Reading order for a fresh start

1. src/uix/README.md — the thesis: the four layers, what makes it different, what it is not.
2. src/uix/active_architecture.md — the deep architecture: the transcription chain, the DOM-primitive ownership table, the hard rules.
3. docs/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 open while you read — it defines the invented vocabulary (morfo, archetype, hold, TSC, …) one line each.

The map

E1 — Architecture

Doc	Layer
src/uix/active_architecture.md	The whole system — start here for depth
morfo/README.md	The declarative contract (DNA)
soma/README.md · SOMA_ARCHITECTURE.md	Headless behavior — README onboards, ARCHITECTURE is the deep reference
sema/README.md	Perceptual engine + channels (sound/haptic) + cascade
eidos/README.md	The visual layer
active-uix/README.md	Composition root (boot modes)
arts/README.md	Runtime artifacts (Engine*/Active*)

E2 — Canon

Doc	What it fixes
docs/CANON.md	The semantic vocabulary — authoritative
eidos/TSC.md	Token Scope Contract — where every eidos token may be emitted
src/docs/GUIA_IMPLEMENTACION_SEMAUIX.md	The canonical implementation guide (families, color subsets, holds, a11y) — authoritative for any new wrapper

E3 — Decisions / RFC

Doc	What it records
docs/decisions.md	The RFC/design index — entry to all rationale
src/docs/LIBRO_VARIACIONES_Y_EXTENSIONES.md	Where the implementation deviates from / extends the book
eidos/CHANNELS_SYNTHESIS.md	The eight expression channels, synthesized
eidos/THEMING_NOTES.md	Theming: comparison vs reference libs + FAQ

E4 — Guides

Doc	How to
soma/COMPONENT_GUIDE.md	Build a component (ordered steps + rules A1–A37)
src/uix/COMPONENT_COMPLETION_CHECKLIST.md	Decide when a component is done (machine-audited)
eidos/THEMING.md · THEMING_GUIDE.md	Theming reference (E1) + the add-component / define-theme how-tos (E4)
eidos/components/README.md	The eidos component pattern
eidos/MOTION_GUIDE.md	Animate it — the motion prop, the preset catalog, loops, stagger, reduced-motion (links the model + the motion RFC)
web/routes/uix/lib/DEMO_AUTHORING_GUIDE.md	Author an interactive demo page

E5 — Module reference

Per-artifact READMEs live next to the code: src/arts/{name}/README.md (indexed in 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
Understand the framework	src/uix/README.md → active_architecture.md
Know why UIX, not Radix / Mantine	docs/comparison.md
Know what a family / intent / verb means	docs/CANON.md
Build a new component	soma/COMPONENT_GUIDE.md
Know if a component is finished	src/uix/COMPONENT_COMPLETION_CHECKLIST.md (npm run component:audit)
Theme it / add a token	eidos/THEMING.md + eidos/TSC.md
Animate it (motion · loops · stagger · reduced-motion)	eidos/MOTION_GUIDE.md
Understand why a decision was made	docs/decisions.md → the relevant RFC / LIBRO_VARIACIONES
Use a runtime artifact (auth, cache, http, …)	arts/README.md + src/arts/{name}/README.md
Write or edit documentation	docs/authoring.md — the authoring rules
Test or validate a change	docs/testing-and-tooling.md — tests, validators, codegen, SSR

Authoritative sources & rules

• Editorial source: docs/Disenando_lo_que_ocurre_v2_3.md — the book Diseñando lo que ocurre (v2.3), the origin of the semantic canon. (Currently untracked; the local editorial reference.)
• Agent rules: CLAUDE.md and 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/ 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.

Note: soma/components/words + eidos/components/palabras are an active, separate development track and are deliberately outside this corpus.