7.1 KiB
| title | type | audience | authority | status | related | ||||
|---|---|---|---|---|---|---|---|---|---|
| Building a Component — the one door | guide | human + agent | navigational — THE entry point for building a new component; content lives in the linked docs | current |
|
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 §Before You Start (1–4) · membership: 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 §Authoring a new morfo · vocabulary: CANON.md |
validateMorfo + npm run morfo:vocabulary + audit A-* |
| 2 · Soma | {kebab}-provider.svelte.ts + thin wrappers + types.ts + provider test |
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 §packs + §typed builder · pack-vs-default criteria: 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 (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 pasos 1–6 · mandatory contract: canon/recipe-contract.md · scope (if data-color): 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 |
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 |
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 §7 hard rules) and the
2-of-3 rule for extending morfo (morfo/README.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.
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 win — fix the doc or open an issue (THEMING.md's
own footer says the same).