|
|
---
|
|
|
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: src/uix/COMPONENT_COMPLETION_CHECKLIST.md (when is it done — machine-audited)
|
|
|
soma: src/uix/soma/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 | [`soma/COMPONENT_GUIDE.md`](../src/uix/soma/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 | [`soma/COMPONENT_GUIDE.md`](../src/uix/soma/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: [`LIBRO_VARIACIONES`](../src/docs/LIBRO_VARIACIONES_Y_EXTENSIONES.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` | [`eidos/THEMING_GUIDE.md`](../src/uix/eidos/THEMING_GUIDE.md) pasos 1–6 · **mandatory contract**: [`eidos/RECIPE_CONTRACT.md`](../src/uix/eidos/RECIPE_CONTRACT.md) · scope (if `data-color`): [`eidos/TSC.md`](../src/uix/eidos/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_GUIDE.md`](../web/routes/uix/lib/DEMO_AUTHORING_GUIDE.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 | [`COMPONENT_COMPLETION_CHECKLIST.md`](../src/uix/COMPONENT_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
|
|
|
|
|
|
**None.** 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).
|
