|
|
|
|
@ -0,0 +1,122 @@
|
|
|
|
|
---
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
## 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`](../src/uix/README.md); the deep
|
|
|
|
|
architecture in [`src/uix/active_architecture.md`](../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 | `docs/README.md`, `src/uix/README.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 |
|
|
|
|
|
|
|
|
|
|
## Reading order for a fresh start
|
|
|
|
|
|
|
|
|
|
1. **[`src/uix/README.md`](../src/uix/README.md)** — the thesis: the four layers, what makes it different, what it is not.
|
|
|
|
|
2. **[`src/uix/active_architecture.md`](../src/uix/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).
|
|
|
|
|
|
|
|
|
|
## The map
|
|
|
|
|
|
|
|
|
|
### E1 — Architecture
|
|
|
|
|
|
|
|
|
|
| Doc | Layer |
|
|
|
|
|
| --- | --- |
|
|
|
|
|
| [`src/uix/active_architecture.md`](../src/uix/active_architecture.md) | The whole system — start here for depth |
|
|
|
|
|
| [`morfo/README.md`](../src/uix/morfo/README.md) | The declarative contract (DNA) |
|
|
|
|
|
| [`soma/README.md`](../src/uix/soma/README.md) · [`SOMA_ARCHITECTURE.md`](../src/uix/soma/SOMA_ARCHITECTURE.md) | Headless behavior — README onboards, ARCHITECTURE is the deep reference |
|
|
|
|
|
| [`sema/README.md`](../src/uix/sema/README.md) | Perceptual engine + channels (sound/haptic) + cascade |
|
|
|
|
|
| [`eidos/README.md`](../src/uix/eidos/README.md) | The visual layer |
|
|
|
|
|
| [`active-uix/README.md`](../src/uix/active-uix/README.md) | Composition root (boot modes) |
|
|
|
|
|
| [`arts/README.md`](../src/arts/README.md) | Runtime artifacts (`Engine*`/`Active*`) |
|
|
|
|
|
|
|
|
|
|
### E2 — Canon
|
|
|
|
|
|
|
|
|
|
| Doc | What it fixes |
|
|
|
|
|
| --- | --- |
|
|
|
|
|
| [`docs/CANON.md`](./CANON.md) | The semantic vocabulary — authoritative |
|
|
|
|
|
| [`eidos/TSC.md`](../src/uix/eidos/TSC.md) | Token Scope Contract — where every eidos token may be emitted |
|
|
|
|
|
| [`src/docs/GUIA_IMPLEMENTACION_SEMAUIX.md`](../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`](./decisions.md) | The RFC/design index — entry to all rationale |
|
|
|
|
|
| [`src/docs/LIBRO_VARIACIONES_Y_EXTENSIONES.md`](../src/docs/LIBRO_VARIACIONES_Y_EXTENSIONES.md) | Where the implementation deviates from / extends the book |
|
|
|
|
|
| [`eidos/CHANNELS_SYNTHESIS.md`](../src/uix/eidos/CHANNELS_SYNTHESIS.md) | The eight expression channels, synthesized |
|
|
|
|
|
| [`eidos/THEMING_NOTES.md`](../src/uix/eidos/THEMING_NOTES.md) | Theming: comparison vs reference libs + FAQ |
|
|
|
|
|
|
|
|
|
|
### E4 — Guides
|
|
|
|
|
|
|
|
|
|
| Doc | How to |
|
|
|
|
|
| --- | --- |
|
|
|
|
|
| [`soma/COMPONENT_GUIDE.md`](../src/uix/soma/COMPONENT_GUIDE.md) | Build a component (ordered steps + rules A1–A37) |
|
|
|
|
|
| [`src/uix/COMPONENT_COMPLETION_CHECKLIST.md`](../src/uix/COMPONENT_COMPLETION_CHECKLIST.md) | Decide when a component is *done* (machine-audited) |
|
|
|
|
|
| [`eidos/THEMING.md`](../src/uix/eidos/THEMING.md) · [`THEMING_GUIDE.md`](../src/uix/eidos/THEMING_GUIDE.md) | Theming reference (E1) + the add-component / define-theme how-tos (E4) |
|
|
|
|
|
| [`eidos/components/README.md`](../src/uix/eidos/components/README.md) | The eidos component pattern |
|
|
|
|
|
| [`web/routes/uix/lib/DEMO_AUTHORING_GUIDE.md`](../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`](../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 |
|
|
|
|
|
| --- | --- |
|
|
|
|
|
| Understand the framework | `src/uix/README.md` → `active_architecture.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` |
|
|
|
|
|
| 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` |
|
|
|
|
|
|
|
|
|
|
## Authoritative sources & rules
|
|
|
|
|
|
|
|
|
|
- **Editorial source**: [`docs/Disenando_lo_que_ocurre_v2_3.md`](./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`](../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/words` + `eidos/components/palabras` are an active,
|
|
|
|
|
> separate development track and are deliberately outside this corpus.
|
