svelte-kit-vice/docs/building-a-component.md

---
title: Building a Component — the one door
type: guide
audience: human + agent
authority: navigational — THE entry point for building a new component; content lives in the linked docs
status: current
related:
  acceptance: docs/guides/completion-checklist.md (when is it done — machine-audited)
  soma: docs/guides/component-guide.md (the deepest phase doc)
---

# Building a Component — the one door

Read **this file first and only this file**. Building a component crosses the four
layers and the theming system; the knowledge lives in eight documents that each own
one phase. Nobody should have to discover that chain by archaeology — this doc IS
the chain. Each phase names **the one document to read**, what you produce, and the
guard that verifies it.

Role note (authoring rule 4 — one source per concern): this doc contains **no
content**, only sequencing. If a phase doc and this table disagree about order,
this doc wins on *order*; the phase doc wins on *content*.

---

## The route

| Phase | You produce | Read THIS | Verified by |
| --- | --- | --- | --- |
| **0 · Decide** | comparison table vs ark/bits/radix (+ react-aria), membership call (soma or eidos-native), compose-first check | [`component-guide.md`](./guides/component-guide.md) §Before You Start (1–4) · membership: [`architecture/soma.md`](./architecture/soma.md) §2 | reviewer — the table goes in the component README (phase 7) |
| **1 · Morfo** | `src/uix/morfo/components/{kebab}.ts` — parts, data/aria, keyboard, events (family/verb/intent/sequence), `texts`, `expression` | [`morfo/README.md`](./architecture/morfo.md) §Authoring a new morfo · vocabulary: [`CANON.md`](./CANON.md) | `validateMorfo` + `npm run morfo:vocabulary` + audit `A-*` |
| **2 · Soma** | `{kebab}-provider.svelte.ts` + thin wrappers + `types.ts` + provider test | [`component-guide.md`](./guides/component-guide.md) (patterns + rules A1–A37) | provider test + `npm run check` |
| **3 · Sema** | pack `src/uix/sema/components/{kebab}.ts` (or explicit `expression: 'family-default'`) — selectors via `semaSelector` ONLY | [`architecture/sema.md`](./architecture/sema.md) §packs + §typed builder · pack-vs-default criteria: [`book-deviations.md`](./decisions/book-deviations.md) D.4 | `npm run morfo:vocabulary` (expression coverage) |
| **4 · Eidos wrapper** | `eidos/components/{kebab}/` — root + attached parts (option C), visual props | [`eidos/components/README.md`](../src/uix/eidos/components/README.md) (the 7 hard rules) | `component-api-contract` test + audit `E-*` |
| **5 · Recipe + theming** | recipe tokens in `lib/recipes/base.ts` + `{kebab}.css` | [`theming/guide.md`](./theming/guide.md) pasos 1–6 · **mandatory contract**: [`canon/recipe-contract.md`](./canon/recipe-contract.md) · scope (if `data-color`): [`canon/tsc.md`](./canon/tsc.md) | `npm run generate:eidos-css` + `recipe-css-contract` test + audit `R-*` (R-4.x = the contract) |
| **6 · Demo** | `web/routes/uix/components/{kebab}/+page.svelte` — v2 9-tab layout | [`demo-authoring.md`](./guides/demo-authoring.md) | audit `D-*` + `npm run smoke` |
| **7 · Component README** | Baseline · Comparativa (≥3 refs) · Decisiones · Gaps-with-disposition · Sema events table | template = any recent PASS component's README; sections audited | audit `F-*` |
| **8 · Acceptance** | nothing new — the component passes | [`completion-checklist.md`](./guides/completion-checklist.md) | `npm run component:audit --only {kebab}` + `npm run morfo:check` + `eidos-lint` |

Cross-phase invariants you will hit in every phase: the layer boundaries
([`architecture/active-architecture.md`](./architecture/active-architecture.md) §7 hard rules) and the
2-of-3 rule for extending morfo ([`morfo/README.md`](./architecture/morfo.md)).

---

## Known traps

**The `dir` prop moves the maths and leaves the paint behind.** A component can
accept `dir`, run the chain and flip its arrow keys while nothing mirrors: a
recipe's `:dir()` branch matches the direction the element *inherited* unless
the provider stamps the attribute. Phase 2 and phase 5 decide that together —
[`canon/direction-contract.md`](./canon/direction-contract.md).

The superseded material this table used to warn about was fixed by
the 2026-07 reconciliation pass (morfo `texts:`, the degraded
GUIA_IMPLEMENTACION, THEMING §13/§14, soma deps, the archetype count), and
`npm run docs:check` now guards the recurrence classes mechanically
(vocabulary counts, phantom fields, dependency claims, checklist↔audit sync,
links). If you find a doc contradicting the code, that IS a bug: **code +
[`CANON.md`](./CANON.md) win** — fix the doc or open an issue (THEMING.md's
own footer says the same).