|
|
---
|
|
|
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 <file> # 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)
|
