diff --git a/docs/README.md b/docs/README.md index 02fd5f312..85c825c33 100644 --- a/docs/README.md +++ b/docs/README.md @@ -13,6 +13,10 @@ new session opening this repo, read this first: it tells you what exists, where 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. + ## What this framework is (60 seconds) UIX is a Svelte 5 component system built around a **declarative contract** @@ -105,6 +109,7 @@ and the server-authoritative engines in `src/svrs/`. | Goal | Go to | | --- | --- | +| Run it and make a first change | [`docs/getting-started.md`](./getting-started.md) | | 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` | diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 000000000..894578d65 --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,107 @@ +--- +title: Getting Started +type: guide +audience: human + agent +status: current +--- + +# Getting Started + +For a developer or agent opening this repo for the first time: the fast path from +clone to understanding to your first change. [`docs/README.md`](./README.md) is +the **map** (where everything is); this is the **path** (what to do, in order). + +## 1. Run it + +```bash +npm install +npm run dev # vite dev — routes resolve from web/routes/ +``` + +Open the dev server. There are three route trees: + +| Route | What it is | +| --- | --- | +| **`/uix`** | The UIX component system. `/uix/components/{name}` is an interactive testbed per component — try `/uix/components/toggle` and `/uix/components/dialog`. Each demo has **Live · API · Morfo · Sema · Recipe · A11y** tabs. | +| **`/active`** | The runtime artifacts (`arts`): `/active/docs/{name}` per artifact (auth, cache, http, format, …), plus `/active/get-started/*` and `/active/security`. | +| **`/temas`** | Themes (`/temas/grafito`) and motion (`/temas/animations`). | + +## 2. The mental model (5 minutes) + +UIX is built around a **declarative contract** that the other layers consume. +Every perceptible interaction flows through one chain: + +``` +Morfo declares → Soma transcribes → Sema projects → Eidos paints +(the contract) (behavior, state) (sound/haptic + (CSS reacting to + parts, data-*, data-event-*) the data-* attrs) + ARIA, events +``` + +- **morfo** is the single source of truth for a component's public DOM surface — + declared once, consumed by everyone. +- **soma** runs the behavior and writes the `data-*` / `aria-*` the morfo + promised. +- **sema** turns a declared event into a perceptual signal (sound, haptic) and + stamps `data-event-*` for the duration of a "hold". +- **eidos** is the CSS that styles against exactly those attributes. + +The full worked causal chain (a toast, end to end) is in +[`active_architecture.md`](../src/uix/active_architecture.md); the vocabulary it +uses is in [`CANON.md`](./CANON.md). + +## 3. See the whole architecture in one element + +Open `/uix/components/toggle`, click the toggle, and inspect it in DevTools. In +that one element you can see every layer at once: + +- `data-toggle` — the provider marker. **Morfo** declares it; **soma** writes it. +- `data-state="on" | "off"` — the state. **Soma** maintains it. +- `data-event-*` — appears for a moment when you click. **Sema** stamps it during + the hold, then removes it. +- The CSS rules that react to `[data-toggle][data-state='on']` and + `[data-event-*]` are **eidos** (the demo's **Recipe** tab lists the exact + selectors and which layer owns each). + +That is the doctrine made visible: morfo promises the attrs, soma writes them, +sema stamps the event, eidos paints — no layer reaches into another's job. + +## 4. The verification loop + +```bash +npm run check # types — svelte-check, expect 0 errors +npm run test # vitest suite (two projects: browser client + node server) +npx vitest run # one file +npm run lint # prettier --check (npm run format to fix) +``` + +For a component specifically: + +```bash +npm run morfo:check # the real DOM vs the morfo contract +npm run smoke # runtime/hydration errors (needs `npm run dev` running) +npm run component:audit # acceptance matrix (see COMPONENT_COMPLETION_CHECKLIST) +npm run perm:check # re-validate morfo across state transitions +``` + +## 5. Your first change — pick a path + +- **Read one component end to end.** Toggle is the smallest complete example: + `src/uix/morfo/components/toggle.ts` (the contract) → + `src/uix/soma/components/toggle/` (behavior) → + `src/uix/eidos/components/toggle/` (visuals). Follow one `data-*` from + declaration to CSS. +- **Tweak a theme token.** [`eidos/THEMING_GUIDE.md`](../src/uix/eidos/THEMING_GUIDE.md) + (define a theme) + [`eidos/TSC.md`](../src/uix/eidos/TSC.md) (where each token + is allowed to live). +- **Build a new component.** [`soma/COMPONENT_GUIDE.md`](../src/uix/soma/COMPONENT_GUIDE.md) + is the ordered process (steps 1–40 + rules A1–A37); + [`COMPONENT_COMPLETION_CHECKLIST.md`](../src/uix/COMPONENT_COMPLETION_CHECKLIST.md) + is how you know it's done. + +## 6. Where to go next + +- The map of all docs → [`docs/README.md`](./README.md) +- The invented vocabulary → [`docs/glossary.md`](./glossary.md) +- The semantic canon → [`docs/CANON.md`](./CANON.md) +- Writing or editing docs → [`docs/authoring.md`](./authoring.md) diff --git a/docs/process/CONTINUE-docs-corpus.md b/docs/process/CONTINUE-docs-corpus.md index b0fd8ca6a..3a5b1dac7 100644 --- a/docs/process/CONTINUE-docs-corpus.md +++ b/docs/process/CONTINUE-docs-corpus.md @@ -39,6 +39,7 @@ permanente/efímero, drift, dos idiomas. - **Fase 4 (3/3) — THEMING split (stubs)**: `THEMING.md` 2571→1930 L, partido renumber-safe en 3 docs-estrato: `eidos/TSC.md` (E2, §7+§18), `eidos/THEMING_GUIDE.md` (E4, §8+§9), `eidos/THEMING_NOTES.md` (E3, §15+§17). THEMING conserva stubs-puntero numerados → las 34 secciones y todas las citas `§N` del corpus/código sobreviven; §16 + `## Referencias` + §20-34 quedan in-place. Además §14 motion saneado (contradicción con eidos-motion.md). **Fase 4 cerrada.** - **Fase 5 (1/n) — entrada E0**: nuevo `docs/README.md` — puerta única del corpus (lo pidió el usuario: "necesario para que los agentes empiecen y para cada sesión nueva"). Contiene: orientación de 60 seg, los 7 estratos, orden de lectura, mapa de docs por estrato (E1-E5 + process) y atajos task-oriented ("I want to…"). **Cableado desde `CLAUDE.md`** ("Start here", arriba de Reference Documents) para que toda sesión/agente lo lea primero. Todos los enlaces verificados. Pendiente del E0: solo adelgazar `CLAUDE.md` (ver Diferido). - **Fase 5 (2/n) — glosario**: nuevo `docs/glossary.md` — el vocabulario inventado (las capas, morfo, soma, sema, eidos) definido en una línea cada término + puntero a la fuente autoritativa; el subset semántico (family/intent/verb/channel) **apunta a CANON, no se recopia** (sin drift). Enganchado en `docs/README.md` (estrato E0 + orden de lectura). +- **Fase 5 (4/n) — getting-started**: nuevo `docs/getting-started.md` — el camino narrativo de cero a primer cambio: run it → modelo mental con la cadena de transcripción → **ver las 4 capas en un solo elemento del DOM** (toggle: `data-toggle`/`data-state`/`data-event-*` + el CSS de eidos) → loop de verificación con scripts reales → 3 caminos de primer cambio. Anclado en rutas reales (`/uix/components/*`, `/active`, `/temas`) y scripts reales (`check`/`test`/`morfo:check`/`smoke`/`component:audit`/`perm:check`); apunta a COMPONENT_GUIDE/THEMING_GUIDE sin duplicar. Enganchado en `docs/README.md` (callout arriba + fila "I want to"). Hay además un get-started de la app en `/active/get-started/*` (incl. ai-agents) — este es el doc-side. - **Fase 5 (3/n) — reglas de autoría de doc**: nuevo `docs/authoring.md` — cómo se crea/edita documentación en el corpus, codificando lo que aprendió la migración: (1) linkear el canon, nunca copiarlo (la ley anti-drift); (2) cada doc tiene un estrato + dónde va; (3) docs de referencia atemporales (hand-offs/fechas/catálogos hardcoded → process o puntero); (4) una fuente por concern (roles distintos si hay 2 docs del mismo tema); (5) frontmatter; (6) ediciones renumber-safe (stub pattern para `§N` citadas, verificar links); (7) idioma EN; (8) naming `rfc-*`/`design-*`; + checklist pre-commit. Cada regla cita el fallo real que arregla. Enganchado en `docs/README.md` ("I want to… write a doc" + nota tras los estratos). ## PENDIENTE @@ -53,7 +54,7 @@ permanente/efímero, drift, dos idiomas. - **NOTA harness**: escribir un archivo EXISTENTE con PowerShell `Set-Content` o con regex (`\d+`, ` / ` sueltos) en el comando lo bloquea un analizador (lo lee como `Remove-Item path`). Funciona: `[System.IO.File]::WriteAllLines(abs, $arr, utf8NoBom)` + límites por `.StartsWith()` (sin regex). Crear archivos NUEVOS con `Set-Content` sí va. Las tools Edit/Write también. ### Fase 5 — huecos de libro (escribir nuevo) -~~Entrada E0~~ (hecho) · ~~Glosario~~ (hecho) · arco *getting-started* · decision-log consolidado (semilla: `src/docs/LIBRO_VARIACIONES_Y_EXTENSIONES.md`) · walkthrough "construye tu propia capa" · comparativa honesta vs Radix/Ark/Mantine (hoy dispersa en THEMING_NOTES §15, eidos-motion §16) · historia transversal SSR/testing/codegen. +~~Entrada E0~~ (hecho) · ~~Glosario~~ (hecho) · ~~reglas de autoría~~ (hecho) · ~~arco *getting-started*~~ (hecho) · decision-log consolidado (semilla: `src/docs/LIBRO_VARIACIONES_Y_EXTENSIONES.md`) · walkthrough "construye tu propia capa" · comparativa honesta vs Radix/Ark/Mantine (hoy dispersa en THEMING_NOTES §15, eidos-motion §16) · historia transversal SSR/testing/codegen. ### Diferido (decisión del usuario) - **Rename físico de RFCs/design** (`*_ENGINE_RFC`/`*_RFC` → `rfc-*`; `DESIGN_CONN`/`DESIGN`/`DESIGN_TIMR` → `design-*`): los nombres actuales están citados como provenance en ~30 archivos de código (`eidos/lib/*.ts` ×~20, `arts/timer/*`, `arts/color/*`, `arts/session/types.ts`, tests) + ~10 docs + CLAUDE.md. `docs/decisions.md` ya da el naming consistente a nivel índice sin tocar nada. El rename físico solo vale la pena si se barren TODAS las citas en el mismo pass (si no, drift) — decisión del usuario por el coste/beneficio (cosmético vs ~40 archivos + `check`). De paso: ruta mala `soma/layers/GESTURES.md` (real: `layers/gesture/GESTURES.md`) en SOMA_ARCHITECTURE/old-README.