| title |
type |
audience |
authority |
status |
related |
| UIX Decision & RFC Index |
index |
human + agent |
navigational — the single entry point to the design/RFC corpus |
current |
| canon |
theming |
| docs/CANON.md (semantic vocabulary) |
docs/theming/reference.md (eidos visual system, canonical reference) |
|
UIX Decision & RFC Index
This is the entry point to the framework's design rationale — the RFCs, the
per-subsystem design documents, and the decision logs. It is the E3 stratum of
the corpus: why it is built the way it is. Architecture (how the layers fit)
lives in architecture/active-architecture.md;
the semantic vocabulary lives in CANON.md; this file collects the
decisions.
Each entry gives the document, its status, and the one decision it records. Open
the document for the full argument — this index never copies it.
Naming note. The eidos RFCs were renamed to rfc-* when they moved into
docs/rfcs/ (docs-book F7.4, 2026-07-02). The provenance anchors cited from
source (e.g. // (DEPTH_ENGINE_RFC §5) across src/uix/eidos/lib/*.ts)
keep resolving: every old path holds a stub pointing at the new chapter with
the same section numbering. The arts design documents got the same treatment
(arts-docs-reconciliation B2, 2026-07-03): they moved to
docs/decisions/design-*.md, and every old path holds a stub so their
citations (e.g. DESIGN_TIMR §12.8 across src/arts/timer/*) keep resolving.
Eidos — expression channels (the 8 of the book)
theming/channels.md is the umbrella:
the conceptual synthesis of the book's eight expression channels (time · motion ·
presence · depth · shape · color · sound · haptic). The engine RFCs below take the
visual channels to reference-grade, one at a time, "breaking the model of the
references rather than copying it — with the cage open".
| RFC |
Status |
The decision it records |
rfc-color-model.md |
RESUELTO (2026-06-02) — canon in theming/reference.md §25 |
The conceptual color model: rich palette (33 scales) + hierarchy roles by explicit alias + intents auto-derived from the palette (identity = step 9). Rejected the "intent = single-anchor" variant. |
rfc-color-engine.md |
✅ Implementado (hasta fase 4-bis) |
The physical layer of color: OKLCH · P3 wide-gamut · APCA contrast · 1-seed generator. Changes how the color variables are produced, not which exist or what they mean. |
rfc-typography.md |
✅ Implementado (fases 1–5) |
Typography to reference-grade, additively behind the frozen token contract (audit → compare → extend, mirroring color). |
rfc-depth.md |
✅ Implementado (fases 1–5) |
The depth/presence channel: "depth is not something an element has, it is something that happens". Two-moment model (state + event). |
rfc-shape.md |
✅ Implementado (fases 1–5) |
The shape channel (the book's 8th and last expression channel) as orthogonal axes on top of the untouched --radius-* magnitude. |
Eidos — structural systems
| RFC |
Status |
The decision it records |
rfc-structure.md |
Propuesta |
Space · density · scale as state-only structural systems (the stage, not the event): rhythm, fluidity, axis composition under the open cage. |
rfc-scaling.md |
✅ IMPLEMENTADO (2026-06-02) |
Splits global zoom (scaling: 90/95/100/105/110) from density. Scales space + control-height + font-size + icon-size; radius/border/shadow/line-height excluded on purpose. |
Arts — subsystem design documents
Exhaustive design-and-implementation records for the harder runtime artifacts.
Each predates the 2026-05-14 directory-rename sweep and carries a historical-note
header about the old short names (conn/timr/sess). Moved into the corpus
(B2, 2026-07-03); a stub at each old src/arts/* path keeps the source
provenance citations resolving. design-timer.md is kept verbatim in Spanish.
| Document |
Subsystem |
The decision it records |
design-connection.md |
connection |
Realtime connection registry: transports, reconnect, heartbeat, request/reply, channels, session bridge. |
design-timer.md |
timer |
Deterministic timer scheduler: clock injection, the race-safety contract (§12.8), one-shots, intervals, backoff. |
design-session.md |
session |
Session lifecycle consultation: adopt/revoke/refresh, profile loading, SSR via cookie reader. |
Component families — design records
Design records for component families whose doctrine spans several components
(so it belongs in one durable place, not scattered across per-component READMEs).
| Document |
Family |
The decision it records |
design-media-quality.md |
media-player |
Especificado, no implementado. Por qué la calidad de reproducción no está en el puerto MediaProvider y nunca podría estarlo con un <video src> plano (los niveles los aporta un motor HLS/DASH que el framework no vendoriza); el contrato mínimo si se abre (3 campos de snapshot + setQuality + los espejos de $arts/sound + un evento de morfo que rompe el censo de 11); por qué el control se AUSENTA en vez de salir vacío; y por qué settings-button sigue declarado y sin implementar. |
design-text-effects.md |
text effects |
Why animations applied to real text are canon (a11y surface = contract surface) while backgrounds are the pack tier; the CountUp-service vs Text*-decorative split (D-T1/D-T2); the shared doctrine every member obeys (content-is-the-SR-surface, no fake interactivity, measurement discipline, reduced motion, ecosystem citizenship, theme-aware color); per-member animation home (D-T5); the TextCircular→Aura connection. |
design-chat-block.md |
chat (chat-*) |
Why the messaging block composes the ecosystem (triple-registered Feed + anchored VirtualList, Textarea, FileUpload, lucide Icon) instead of reinventing; the five sector failures it beats (a11y feed + separate live region, virtualization, transport-agnostic, headless-with-logic, threads/reactions); the anchoring doctrine (monotonic sticky, real-DOM pin); the reference visual redesign (soft bubbles, tapback bar, canonical size contract); and the two framework fixes it surfaced (langs #?-prefix, commit-set-resize channels:[]). |
Cross-cutting decision logs
| Document |
The decision it records |
LIBRO_VARIACIONES_Y_EXTENSIONES.md |
The running log of where the implementation deviates from (or extends) the book's editorial canon — verbs, adoptions, clusters, and the D.x architectural decisions. The seed for a consolidated decision-log. |
GESTURES.md |
The soma gesture layer design: Gesture.base/drag/resize, velocity ring-buffer, axis lock, deferred pointer capture. |
architecture/active-architecture.md §7 + arts/adom/arts/perf READMEs |
Sec-dom — read-timing & token-resolution (2026-06-29). The framework governs layout READS like it governs writes: dom.measure (coalesced post-layout reads), eidos.resolveToken (token→colour in JS, no getComputedStyle probe), the discoverable uix.color/uix.perf surfaces. Decided: reject a static grep-guard (too noisy across ~120 legit reads, and it can't catch the sync-read-after-write ordering nor cover routes) — the dev uix.perf detector (Long Animation Frames) is the runtime safety net instead. |
canon/direction-contract.md §1, §2, §6 |
Direction endgame — physics over convention (ratified 2026-08-05). Four decisions signed at once: (D1) the chain gains the CONTEXT link — every activeDir publishes its assertion and descendants consult it before prefs, the "implicit inheritance" phase reopened and ratified, closing both field-measured holes (in-place and portal) with one mechanism; (D2) the attribute stamps ONLY the assertion — prefs leave the per-component chain and reach the page once, through the now-AUTOMATIC boot projection (opt-out in standalone, opt-in in attach), with the environment SEED (readPrefsEnvironmentFromDom) adopting a hand-set <html dir> at precedence intent > env > derive(language) > default; (D3) the stamping mechanism belongs to the MORFO — direction: { parts } declares it, soma.runtime<M> computes the requirement from the declaration (required when declared, forbidden when not), compileMorfo validates part names fail-closed, and the census guard crosses prop ↔ morfo; (D4) the API census (7 components without the prop + chat-log) stays POSTPONED by explicit decision. |
canon/direction-contract.md |
Direction — resolution, assertion and paint. One chain resolves a component's reading direction, one native attribute asserts it to the DOM, one selector form reads it back. Decided: the resolver stops before the default and returns undefined, because nobody asserted a direction is a different fact from the default; stamping dir is conditional on who reads the direction — mandatory when the recipe branches with :dir(), needless when the dependence is pure JavaScript; and the static guard (RTL-1, npm run rtl:check) is deliberately scoped to the one trap CSS text can reveal — a logical inline anchor paired with a physical inline translate — leaving the chain, the attribute and the selector form to review. |
