svelte-kit-vice/docs/README.md

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 architecture/overview.md; the deep architecture in 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	docs/README.md, architecture/overview.md, docs/glossary.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
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.

Reading order for a fresh start

1. architecture/overview.md — the thesis: the four layers, what makes it different, what it is not.
2. architecture/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
architecture/active-architecture.md	The whole system — start here for depth
architecture/morfo.md	The declarative contract (DNA)
architecture/soma.md · SOMA_ARCHITECTURE.md	Headless behavior — soma.md onboards, ARCHITECTURE is the deep reference
architecture/sema.md	Perceptual engine + channels (sound/haptic) + cascade
architecture/eidos.md	The visual layer
architecture/active-uix.md	Composition root (boot modes) — first chapter migrated into the book tree (docs/process/PLAN-docs-book.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	Runtime artifacts (Engine*/Active*)
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	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	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	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	The semantic vocabulary — authoritative
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	Token Scope Contract — where every eidos token may be emitted
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	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	The RFC/design index — entry to all rationale
docs/next-features.md	The initiative registry — user-decided future work (scope, sequencing, dependencies), fed by audits and sessions
rfcs/	The eidos engine RFCs: rfc-color-model · rfc-color-engine · rfc-typography · rfc-depth · rfc-shape · rfc-structure · rfc-scaling
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	Where the implementation deviates from / extends the book (Spanish — the author's decision logbook)
decisions/guia-semantica-historica.md	The founding implementation guide (Spanish, historical seed — superseded by CANON.md + code)
theming/channels.md	The eight expression channels, synthesized
theming/notes.md	Theming: comparison vs reference libs + FAQ
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	Build a component — start here. The cross-layer route (9 phases, one doc per phase, one guard per phase)
guides/component-guide.md	The soma phase in depth (ordered steps + rules A1–A37)
guides/completion-checklist.md	Decide when a component is done (machine-audited)
theming/reference.md · theming/guide.md	Theming reference (E1) + the add-component / define-theme how-tos (E4)
theming/motion.md	The motion model — two moments, F1–F7, the preset/signature system (reference)
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	The eidos component pattern
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	Author an interactive demo page
guides/component-audit.md	The binding pre-flight audit before touching any component

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	architecture/overview.md → architecture/active-architecture.md
Know why UIX, not Radix / Mantine	docs/comparison.md
Know what a family / intent / verb means	docs/CANON.md (doctrine) · canon/vocabularies.md (the generated closed sets)
Know which archetype / hold / haptic kind / scale a part or event may use	canon/vocabularies.md — the authoritative lists, generated from the code
Build a new component	docs/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 (npm run component:audit)
Theme it / add a token	theming/reference.md + canon/tsc.md
Animate it (motion · loops · stagger · reduced-motion)	theming/motion-guide.md
Make it work in RTL (assert a direction · mirror the paint)	canon/direction-contract.md (npm run rtl:check)
Understand why a decision was made	docs/decisions.md → the relevant RFC / decisions/book-deviations.md
Use a runtime artifact (auth, cache, http, …)	architecture/active-app.md (the composition root) → arts/README.md (the map) → src/arts/{name}/README.md (per-artifact)
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_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 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/palabras + eidos/components/palabras are an active, separate development track and are deliberately outside this corpus.