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).