svelte-kit-vice/docs/getting-started.md

title	type	audience	status
Getting Started	guide	human + agent	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 is the map (where everything is); this is the path (what to do, in order).

1. Run it

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 architecture/active-architecture.md; the vocabulary it uses is in 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

npm run check:gate    # types WITH policy — src/ and scripts/ owe zero; web/ vs the ledger
npm run check         # raw svelte-check (web/ carries frozen ledger errors)
npm run test          # vitest suite (two projects: browser client + node server)
npx vitest run <file> # one file
npm run gate          # what the pre-push hook runs (docs/testing-and-tooling §The gate)
npm run lint          # prettier --check  (npm run format to fix)

For a component specifically:

npm run morfo:check      # the real DOM vs the morfo contract (data-* attrs;
                         # role/aria-* have no DOM validator yet — informe P1)
npm run smoke            # runtime/hydration errors (needs `npm run dev` running)
npm run component:audit  # acceptance matrix (see guides/completion-checklist.md)
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. theming/guide.md (define a theme) + canon/tsc.md (where each token is allowed to live).
• Build a new component. guides/component-guide.md is the ordered process (steps 1–40 + rules A1–A37); guides/completion-checklist.md is how you know it's done.

6. Where to go next

• The map of all docs → docs/README.md
• What each zone of the repository is (and what is frozen) → docs/repository.md
• The invented vocabulary → docs/glossary.md
• The semantic canon → docs/CANON.md
• Writing or editing docs → docs/authoring.md