User decided (mirroring F7's corpus-shape call): arts stay
E5-in-place-reconciled with only active-app promoted to an architecture
chapter; orca stays E5 for now; the DESIGN docs move to docs/decisions/
translated. B1/B2 locked; A1/A2 (drift + language) unaffected.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The docs reconciliation (F6 drift-fix + F7 corpus-libro) covered
active-uix (morfo/soma/sema/eidos) but left the active-app side — the 22
arts/ runtime artifacts — as E5-in-place, un-reconciled. This plan does
for arts what F6+F7 did for the UIX layers, grounded in a 22-agent
per-art audit (every drift verified against the code): ~40 doc-vs-code
mismatches across 15 arts, 12 READMEs needing ES->EN, ethereal missing a
README, 3 historical DESIGN docs, dead route/demo cross-refs. Batches
A0 (guard) / A1 (drift sweep) / A2 (ES->EN) / A3 (ethereal README) / B1
(active-app -> architecture chapter, the missing analogue of
active-uix) / B2 (DESIGN docs -> decisions/) / B3 (index+TOC). Three
structural open questions for the user (arts E5 vs book; orca chapter;
DESIGN docs move) mirror F7's corpus-shape decision.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Completes the runed + tabbable removal (F1+F2 in d0f41fb2). Ports runed's 11
DOM-reactive utilities into $adom, window-correct by resolving the window from
the node (getWindow) or an optional window/document — not runed's defaultWindow:
AnimationFrames, ActiveElement (+ activeElement singleton), IsDocumentVisible,
IsFocusWithin, IsInViewport, onClickOutside, PressedKeys, ScrollState,
TextareaAutosize, ElementRect, IsIdle.
Follows the committed ElementSize precedent (raw observers/listeners live in the
arts/adom implementation layer) rather than threading a `dom` param.
PersistedState is intentionally NOT ported: the $storage art already supersedes
it (its README names runed/PersistedState as the thing it replaces) — same call
as boolAttr being covered by boolToEmptyStrOrUndef.
`npm run check` = 59 (baseline, 0 in ported files); server tests unchanged
(pre-existing failures only). The runed + tabbable port is now complete.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Removes the two runtime dependencies that broke the "framework depends on
nobody" doctrine, porting them into our own code (same move as
floating-ui -> $ethereal).
F1 (dropped the deps):
- tabbable -> src/libs/dom/tabbable-core.ts (getComputedStyle/CSS.escape
resolved from the node's own window, iframe-safe); consumed by the
existing tabbable.ts wrapper and surfaced via $adom.
- runed Context + watch/watch.pre/watchOnce -> $libs/reactive.
- runed ElementSize -> $adom/element-size.svelte.ts, rebuilt window-correct
on the node's own window (not defaultWindow).
- Rewired ~33 watch + 3 Context imports; floating (ElementSize) and
focus-scope (tabbable) now consume $adom.
F2 (rest of the pure reactive runes -> $libs/reactive):
- Previous, IsMounted, onCleanup, interval, debounce/Debounced,
throttle/Throttled, StateHistory, FiniteStateMachine, resource.
- Dropped runed's React-style use* prefix; reused framework toValue
(=extract) + MaybeActiveOrGetter; added Setter<T>.
runed + tabbable removed from package.json. `npm run check` = 59 (baseline,
0 in ported files); tests unchanged (pre-existing failures only).
F3 (remaining DOM-reactive runes -> $adom on ActiveDom, + PersistedState
-> $storage) is pending: see docs/process/continue-runed-tabbable-port.md.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Continuation doc for tomorrow: full session state (C7 + eidos triage +
onion-menu/surface-subtle + functional flags + C10 reframe + S1
vocabularies), plus the three high-confidence implementation plans the
scope-stumbles-s2-s6 workflow verified against the real code (S3
part-absent condition, S2 continuous-components doctrine, S4
Gesture.rotate) with exact file:line edit maps. S5/S6 flagged for
re-scope. Foreign runed/tabbable WIP in the tree left untouched.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
An agent building a component from the docs-book alone could not assign
archetypes / holds / haptic kinds: the closed sets live only in code consts
and the corpus (correctly) forbids copying them into prose, so they were
invisible from the docs. STUMBLES #1, the top stumble.
Fix: docs/canon/vocabularies.md is GENERATED from the consts by
'npm run docs:vocabularies' — the ONE sanctioned place the lists are spelled
out (generated = no drift objection), which every other doc links to. It
covers part archetypes (with a one-line role each), sema families with their
default hold/persistence + per-intent overrides, verbs by family, intents,
the perceptual-duration scale, haptic kinds, the 33 palette scales, sizes,
variant archetypes, and the shared common.* strings.
- scripts/docs-vocabularies.ts imports the consts (robust — no fragile
JSDoc/regex parsing) and formats them; the generation is an exported
function so docs-check can compare.
- Added ARCHETYPE_DESCRIPTIONS to morfo/types.ts (co-located with
ARCHETYPE_VOCABULARY, satisfies Record<MorfoArchetype,string>) as the
authoritative one-liners the appendix reads — descriptions become
first-class data instead of inline union JSDoc a tool would have to parse.
- docs-check gains I7: it regenerates in-memory and fails if the committed
file drifts from the consts (negative-tested: corrupt -> error, regen ->
green). The appendix's own counts pass I1, so I1 doubles as a second guard.
- Linked from README (E2 canon row + two 'I want to' shortcuts), CANON.md
(doctrine here, enumerated lists there), architecture/morfo.md (pick a
part's archetype), and the component-audit minimum-package list (STUMBLES
#8).
docs:check 0 errors; npm run check unchanged in my files.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Cleared the error-severity flags that were mature components missing a
documented exception, not real gaps:
- 4 service components (format-date, format-number, relative-time, trans)
get their E-2.2 exception: they render text via $format/$langs with no
visual recipe — no {name}.css by design.
- alert-dialog gets its R-1.1 exception: it composes Dialog (soma reuses the
Dialog runtime, data-dialog-* markers reach the DOM, dialog.css paints the
chrome) — a [data-alert-dialog] root rule would style nothing.
- card gets its missing A-1.3 texts.label (+ langs entry, registered) —
card had no label at all.
C10 (maturity tiers) reframed after the classification exercise showed the
audit VERDICT is the maturity oracle, and 'experimental' is nearly empty
once exceptions are documented: stable = PASS (82); preview = NEEDS-WORK on
docs/demo only (E-2.3/F-1.x/D-*) — functionally sound but underdocumented,
which includes mature components like button/table/listbox (a README gap is
not immaturity); experimental/WIP = a real FUNCTIONAL gap or foreign track.
C10 folds into C8 (document the tier + exceptions when writing READMEs).
Real gaps registered, NOT silenced: float-panel A-3.7 (28 mutating keyboard
actions, 6 events — a morfo-completeness question), card-group (no morfo),
natural-time-picker A-3.1; announce/clipboard R-1.5 (live-region /
composed-focus) await their READMEs in C8 to host the exception.
npm run check at the 59 baseline; alert-dialog -> PASS.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Accumulated test debt (the eidos suite had been red across several feature
landings — THEME-SYS-1 named z-index, palette-first static donor library,
spin-field extraction, icon stroke-map refinement — none of them regressions;
baselined against HEAD). Each triaged stale-vs-bug by confirming current
behavior in code before touching a line.
Stale tests (code correct/improved, assertion not updated):
- z-index '76' -> 'var(--z-index-overlay-tooltip)' (the code is guarded by
THEME-SYS-1 in contracts.test.ts — the raw integer is forbidden).
- frost '80%' -> 'var(--depth-overlay-translucency, 80%)' (parameterized).
- C7 size-bundle coordinate ('--control-height-md' -> '--size-md-control-height').
- icon visual-stroke ratios 1.5->1.125, 1->0.923 (stroke map md 2->1.5, xxl
icon 48->52px; the arithmetic follows).
- delegate/CSS-only purple-9: the slim foundation legitimately emits the
role-referenced donor scales (purple=primary) as overridable :root defaults;
the real delegation guarantee is 'no baked [data-theme] block', which the
assertion now checks.
Test over-flagging (fixed the test, not the code):
- CSS-only shared layer: spin-field (no wrapper/index) excluded from the
wrapper/barrel/namespace contracts (CSS_ONLY_LAYERS).
- soma-runtime vars: 'var(--x, fallback)' is runtime-optional (the STUMBLES #7
soma->eidos surface) — only bare 'var(--x)' requires a recipe declaration.
- orphan check made corpus-wide: composition means a sibling consumes a
component's tokens (date-picker/month-grid consume calendar-control-*).
- natural-time-picker fixed-tone sky colors documented-exempt (Words-rail
doctrine).
- dialog drift-detector converted to a synthetic fixture (dialog.css no longer
ships the dead rule it self-tested against).
Real code fixes:
- declare '--pin-input-cell-readonly-bg' (I consumed it in C2b without
declaring it).
- remove 5 truly-dead tokens (drawer content-bg + 4 color-field
format-select/segment — 0 consumers anywhere in eidos/soma/web).
- clamp time-picker's 'size' to PopoverSize before forwarding (xs->sm):
TimePickerSize has xs, PopoverSize doesn't — a latent type bug my recipe
change surfaced via a complexity-budget flip. The fix dropped check 61->59,
also clearing navigation-menu-content of the same class.
card-group flagged as a REAL gap (KNOWN_MISSING_MORFO): it ships parts + chrome
but no morfo (morfo-first violation) — tracked, not silenced.
Verified: vitest src/uix/eidos 23 files / 289 tests green; npm run check 59
(better than the 61 baseline); component:audit 0 BROKEN.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The size bundle (--size-{k}-control-height / -font-size / -icon-size,
theming/reference §5) was emitted + guarded but consumed by ONE recipe
(the toggle pilot). This sweep points every recipe at the canonical
size COORDINATE instead of the raw primitive of the same coordinate:
366 refs across 34 recipes (--control-height-{k} -> --size-{k}-control-
height, and the font-size / icon-size coordinates likewise). Retuning a
size's bundle now reaches every consumer; a recipe that maps a key to a
DIFFERENT size's coordinate stays visible as a deliberate deviation.
The bundle vars are pure aliases of the primitives, so this is
computed-value identical — verified in a live browser: the accordion
chain --accordion-trigger-min-height-md = --size-md-control-height =
--control-height-md all resolve to calc(36px * 1 * 1). The generated
diff is 366-for-366 pure name swaps, nothing else moved. base/xxxl have
no size bundle and correctly stay on the typographic primitive.
Guard: recipe-css-contract forbids the raw size-coordinate primitive in
recipe token values (var(--control-height-{k}) etc.) — the drift can't
creep back. This is the ⚠️->✓ that theming/notes' comparison table flags
as the size canon's remaining asterisk (canon + guard, now + consumption).
component:audit 0 BROKEN; npm run check at the 61-error baseline; the
size-bundle guard + palette-cascade guard both green.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Two user findings from the Knob build exercise (an agent building a new
component from the docs alone — STUMBLES.md).
Quarantine: the superseded fossils no longer share shelf space with the
live corpus. docs/old-deprecated/ (with an index README explaining what
lands there and pointing readers at docs/README.md) now holds the
executed audits and fix plans: fable_audit, fable-eidos-audit,
inherit_audit + inherit_fix_plan, ARCHETYPE_COHERENCE_AUDIT_2026-06-19
(still citable — the component-guide banner and the eidos components
README repoint to it), COMPONENT_COHERENCE_AUDIT. pendiente.md (a live
pending list, not a fossil) moved to docs/process/. docs-check treats
the folder as sealed chronicle (I1/I2 exempt; I6 skips its internal
links, as its README promises). Root-level *.md is now: README, CLAUDE,
AGENTS + the user's own working files.
STUMBLES fixes applied on the spot (the doc-class ones):
- #2 kind drift: the REAL enum is 'public' | 'private' | 'virtual'
(MorfoPartKind, 671/9/14 uses) — morfo.md omitted 'private', the
checklist invented 'internal' (0 uses). Both fixed; I2 gains the
phantom-'internal' guard. A-2.1's row now says what the audit script
actually checks (kebab only — the archetype may vary, the Toggle
provider-IS-trigger doctrine).
- #6: the langs catalog SHAPE (flat keys, per-language leaves, named
export, index registration) is now shown in morfo.md instead of only
its location.
- #8: component-audit s0 defines the minimum brief package as an
explicit 8-file list.
The engineering-class stumbles are registered as plan batches S1-S6
(generated vocabularies appendix, continuous-gesture trigger doctrine,
part-absent condition, Gesture.rotate, the soma->eidos CSS-var
contract, minor frictions). docs:check 0 errors, 11-warn baseline.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
palette-{slot} is now RESERVED recipe vocabulary: normalizeRecipeTokens
(render-css) appends the full per-scale color:{scale} cascade for every
donor scale in PALETTE_SCALES to any token named palette-track/element/
border/solid/solid-hover/text/contrast — author-declared color:*
declarations win, only absent scales are appended. This is the
structural end of the hand-maintained-subset era: a recipe opts into
the per-instance palette by naming the token, and the generator
guarantees all scales (the 31-vs-33 drift class cannot recur at this
layer). Applies to app-config recipes too, since the hook sits where
every RecipeTokenSet is normalized.
Button's seven manual spreads are gone from base.ts (the helpers moved
into the generator); its generated output is byte-identical. Toggle —
which already exposed palette-* tokens — universalized itself: +330
generated lines, and <Toggle color="teal"> / color="steel" verified
resolving in a live browser (steel and fuchsia are exactly the two
scales the hand-kept lists used to miss). eidos-lint now classifies
donor-scale values on data-color as sanctioned eidos-only vocabulary
(the TSC color:* axis extension) instead of invalid — the morfo enum
keeps declaring the semantic roles, per the pilot's deliberate
runtime-open design. Guard: recipe-css-contract pins the LAST scale of
PALETTE_SCALES for every palette-bearing recipe in the generated css.
Also: the stale '31 physical color scales' test TITLE says 33 (its body
already asserted 33). Recorded in the plan: the eidos suite carries 15
pre-existing failures in 6 files (baselined against HEAD before this
change) — their triage is its own batch. npm run check at the 61-error
baseline; lint toggle baseline green again.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The 30 eventful morfos that never declared expression: ALL have a
per-component pack in src/uix/sema/components/ — so the classification
(book-deviations D.4: pack / family-default / delegated / none) is
unambiguous: expression: 'pack' across the board, placed after scope
per the switch/button idiom. The sema surface of the contract is now
explicit on all 82 eventful morfos instead of inferred from pack-file
existence. morfo:vocabulary clean (the one naming warn is media-player,
foreign WIP); npm run check at the 61-error baseline. Additional
persistence/a11ySemantic annotations deliberately NOT mass-applied —
per D.9 the canonical table is reference, authors declare per real
consumer (the six that need them already do).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Every interactive morfo now either anchors its W3C APG pattern or
documents that none exists. Real patterns (20): the picker family +
command + search-field anchor combobox (field/input + popup, the
pattern's own popup taxonomy); date-field mirrors time-field's
spinbutton (per-segment contract); rating-group -> radio;
navigation-menu -> disclosure (the APG's own site-nav guidance);
splitter -> windowsplitter; tag-group/tags-input/virtual-grid -> grid;
clipboard/file-upload -> button (the trigger IS the widget);
announce -> alert (live region); form -> the form landmark;
image-adjustments -> slider; table -> table.
The A-1.4 valve (documented exception) is wired like the R-x rules,
and five components whose widget has NO APG pattern say so in their
README instead of faking an anchor: cropper (2-D manipulation),
pagination (nav + composed Buttons), stepper, timeline (display list),
image-picker (media picker). Remaining warns are the four expected:
card/drag-drop/virtual-list host their note when C8 writes their
READMEs, media-player is foreign WIP.
Catalog: 83 PASS / 47 NEEDS-WORK / 0 BROKEN (was 75/50/5 at the
audit's start). npm run check at the 61-error baseline.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Two classes. Real fixes: 8 numeric font-weights tokenized to
var(--font-weight-medium/semibold/regular) in command,
date-range-picker, link-preview, listbox, menubar, textarea,
time-range-picker x2 — same rendered weight, but the foundation now
propagates (verified in a live browser: the token resolves to 500).
Honest annotations: the proportional/identity literals get their
/* literal: <reason> */ valve instead of a fake token — avatar
initials/badge scale with the avatar diameter (physically
proportional), the calc(1em - (md - sm)) family is the Field
label-one-step-down doctrine with a token-derived delta, 1em is
context identity (fab glyph, password toggle), the x0.85 captions are
proportional to their field token, and combobox's -1px is an optical
adjustment on a token-derived size. component:audit R-2.7: 16/16
clean; npm run check at the 61-error baseline.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The R-1.2/R-1.3/R-1.4 sweep, same method as C2a (evidence first): each
offender is either a REAL missing state or a shared-layer/composed case
that must not duplicate rules.
Real fixes, all verified in a live browser (computed-style probes, with
the transition-mid-flight trap from the demo guide s13 accounted for):
switch/toggle/rating-group get the family invalid tint
(--color-threat-element, the shipped checkbox/pin-input precedent);
toggle gets its readonly cursor; pin-input cells get the readonly
muted-surface treatment mirroring date-field segments; the SHARED
spin-field layer gains the readonly treatment it lacked (one fix covers
css-field + number-field); natural-time-picker gets the disabled
opacity/pointer rule mirroring date-field.
Exception valve wired into R-1.3/R-1.4 (was only R-1.1/1.2/1.5/E-2.2)
and cited exceptions added: css-field/number-field (states live in the
shared spin-field layer), dialog (data-disabled sits on the VIRTUAL
provider — defaultElement none — and the pressable surfaces are
composed Buttons), color-picker (color-field owns the invalid rules),
date-range-field (the runtime overlays data-date-field-input on the
same elements, per its own recipe header), time-picker (composed
time-field chrome). natural-time-picker keeps its two warns for its C8
pass rather than guessing paint targets.
All 10 audited components now PASS with 0 R-1.x pending; npm run check
at the 61-error baseline. css-field/number-field READMEs fixed on disk
but unstaged (unrelated local modifications).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The audit's focus check grepped only for :focus-visible, blind to how
the framework actually shows focus: the universal archetype ring
(archetypes.css [data-archetype]:focus-visible with its documented
exclusions), the field shell's :focus-within, and the canonical
state-attr ring ([data-focused] + focus-ring tokens, soma-written — the
spin-field/search-field pattern). Blindly adding :focus-visible rules
to the 10 flagged recipes would have recreated the exact 'double
border' anti-pattern archetypes.css documents against. The check now
accepts the four sanctioned evidences (textarea and search-field pass
on their own css; date-picker passes via exception) and the remaining
non-ring cases carry cited R-1.5 exceptions: css-field/number-field
(ring lives in the shared spin-field layer), dialog (content panel is
the documented foundation exclusion; close/trigger are composed
Buttons), date-picker (foundation ring + content exclusion),
metrics/timeline (no focusable part — interactive only by events).
clipboard/announce host their exception when C8 writes their READMEs.
css-field/number-field READMEs fixed on disk but left unstaged (they
carry unrelated local modifications).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The 5 BROKEN components (cascade, gradient-builder, menu-dial, motion,
qr-code) are BROKEN no more: cascade/motion/menu-dial now PASS,
gradient-builder/qr-code drop to NEEDS-WORK with only demo-phase (D-*)
and C8 items left.
Framework-level piece: component-audit gains the documented-exception
valve the checklist already used for A-2.3/R-1.7 — a greppable
'R-x.y exception: reason' line in the component README turns the rule
into a PASS that reports the reason. Wired for R-1.1, R-1.2, R-1.5 and
E-2.2; the checklist rows say the same. This separates deliberate
design (cascade and motion deliberately ship NO recipe — they ride the
foundation stagger + state presets; menu-dial's focus/disabled states
live in the composed Fab/Button recipes) from plain omission, which
stays an error.
Mechanical fixes: texts.label + langs entries for cascade/motion (new
files, registered) and gradient-builder (label added to its existing
entry); menu-dial's missing default export. README contract sections
(Baseline/Comparativa/Decisiones/Gaps/Passive justification + Audit
exceptions) added to cascade, motion, menu-dial and qr-code — mostly
re-heading content those docs already argued; comparativas grounded in
M3 speed dial/MUI SpeedDial/PrimeVue, Framer Motion/AnimatePresence/
Svelte transitions, ark-ui/qr-code-styling per component.
Verified: component:audit 130 -> 78 PASS / 52 NEEDS-WORK / 0 BROKEN;
npm run check at the 61-error pre-existing baseline (0 own).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Consolidated audit (2026-07-02): 130 components -> 75 PASS / 50
NEEDS-WORK / 5 BROKEN; palette-31 wired in 7 recipes, size-bundle in 1,
focus-visible missing in 11, 17 literal-typography recipes, 41/82
eventful morfos without expression:, 33 without APG anchor, 28 without
README. Demos (D-*) explicitly deferred to the next phase (component
info web). Batches C1-C10 with per-batch verification.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
CLAUDE.md 981 -> 350 lines. The 12 session hand-offs (2026-05-08 ->
2026-06-05, ~513 L) moved verbatim to docs/process/handoffs-claude-md.md
(chronicle frontmatter). Reference Documents now point into the book
tree, and the long-stale authority claim is fixed: the semantic
vocabulary source is docs/CANON.md (+ decisions/book-deviations.md),
with the Spanish guide correctly framed as a historical seed at its new
decisions/ home — the correction the guia's own banner had been
announcing since Fase 6. The four sema/eidos doctrine sections (~170 L
of copied tables, cascade diagrams and examples — the copy class
docs:check bans in the corpus) compact to the operational MUSTs
(semaSelector mandatory, packs never replace intent primitives,
channels split by owner, types-over-lint) each with its pointer to
CANON.md / architecture/sema.md / theming/channels.md /
architecture/eidos.md. Two head refs swept (eidos-motion ->
theming/motion.md, COMPONENT_GUIDE s4 -> guides/component-guide.md).
Approved by the user after diff review. docs:check 0 errors.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
COLOR_ENGINE_RFC (619 L, the largest RFC) -> rfcs/rfc-color-engine.md,
Spanish to English, same section numbering (s0 TL;DR, s6 generator +
s6.1 isomorphism + s6.2 deriveScheme/buildScheme, s7 wide-gamut
strategies, s8 APCA, s10 frozen invariants, s11 phases with 4-bis
implemented, s13 bloat-doc absorption, s14 comparison). Its
THEMING_AUDIT citation notes the audit is retired; the s25/s26 canon
citations point into theming/reference.md. decisions.md row repointed +
Status aligned (implemented through phase 4-bis); the index's naming
note rewritten — the deferred eidos-RFC rename is now DONE via stubs,
while the arts DESIGN_* docs keep their legacy names in place (their
citations were not swept).
F7.4 complete: 7 RFCs live at docs/rfcs/rfc-{scaling, structure, depth,
shape, typography, color-model, color-engine}.md; MOTION_SERVICE_RFC
stays in src (foreign/concurrent). docs:check 0 errors.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
src/uix/soma/SOMA_ARCHITECTURE.md (1058 L, Spanish) translated to English
as docs/architecture/soma-architecture.md, same s1-s17 numbering: layer
architecture, design principles, the closed six-piece model + SomaRuntime,
component model (picker composition), runtime parts, the layers inventory,
the Soma class + date/time domain + statics convention, the reactive
system, internal helpers, data-* contracts, IDs, barrels, boundaries,
directory structure, anti-patterns, current shape, stability rule,
checklist. The frozen per-provider test list (dated 2026-05-15, ~140 L)
became the timeless fact: the NO_MISSING_PROVIDER_TESTS guard + the test
tree ARE the coverage inventory (testing-and-tooling aligned). Stub with
the full sN map at the old path; corpus links swept.
F7.2 is complete: docs/architecture/ now holds the whole E1 stratum in
English (7 chapters, ~5.4k lines), with thin stubs + sN maps next to the
code. docs:check 0 errors (251 docs).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
src/uix/eidos/README.md (1020 L, Spanish) translated to English: the
ActiveEidos runtime (config/patch, themes, themeSource, CSS contract,
setCssVariables, persistence envelope, resolveToken), canonical size +
transversal primitives, what eidos consumes from morfo/soma/sema, the
--* token rule, the THEMING sN map, typographic vertebration (two
anchors + alias chain + R-2.7), the 2-of-3 rule, disciplined-option-C
API conventions (7+4 rules, Toast special case), the selector-drift
defense, and the picker patterns P-1..P-5. Two already-decided
reconciliations folded in: themes/fonts.css superseded (font-faces live
in generated/base.css) and the dated 2026-05-21 picker block merged into
the picker-patterns intro — its dead PENDIENTES.md pointer replaced by a
TODO(reconcile) note (norms N-6/N-7 orphaned by d68d2c45), which also
clears one docs:check warn (13 -> 12). Thin stub at the old path keeps
THEMING/TSC/motion pointers next to the code; corpus links swept.
docs:check 0 errors.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
src/uix/active_architecture.md (865 L, Spanish) translated to English as
docs/architecture/active-architecture.md: the s0 module contracts +
canonical naming, the four layers in depth, the transcription chain, the
causal chain of one interaction, the DOM-attribute table, the 12 hard
rules (incl. the sec-dom read-timing rule), authorship vs transcription,
what it is NOT, risks. The dated header changelog block was dropped per
the timeless rule (s10 already routes snapshots to docs/process/); the
stale themes/fonts.css mention in the eidos structure listing corrected
to the generated foundation (phase-6 fact). Stub at the old path carries
the full sN section map (the most sN-cited doc in the corpus). All docs/
corpus links repointed to the chapter. docs:check 0 errors.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
User decision (2026-07-02): the corpus stops being a MAP over dispersed
layer docs — the layer reference MOVES into docs/ with book order, in
English, superseding the kickoff-era 'hybrid structure' decision. The 189
component READMEs stay in-place (E5, linked).
- docs/process/PLAN-docs-book.md: the phase-7 plan — target tree
(architecture/ canon/ theming/ rfcs/ guides/ decisions/), the per-doc
migration pattern (translate -> Write new path -> stub at old path ->
link sweep -> docs:check -> commit per batch), batches F7.1-F7.7 with
volumes, and the known risks (sN citations get a map in the stub; the
legacy RFC renames finally become safe because the stub keeps the old
name alive for provenance citations).
- Pilot migrated end-to-end: docs/architecture/active-uix.md (English,
frontmatter, links repointed) with a thin stub at
src/uix/active-uix/README.md; docs/README map, glossary and
active_architecture s0 repointed. Validates the pattern for F7.2+.
docs:check: 0 errors (244 docs).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Closing pass of PLAN-docs-reconciliation:
- docs/building-a-component.md 'Known traps' table emptied — every trap
was fixed by phases 1a-1d/2 and docs:check guards the recurrence
classes (this was the phase's visible success indicator).
- PLAN checkboxes ticked + 'Resultado del cierre' appended (commits,
deviations from the plan, out-of-scope findings pending user decision).
- CONTINUE-docs-corpus.md Fase 6 marked HECHA.
- testing-and-tooling.md row reworded so the guard doesn't flag its own
description (the phantom-field literal).
Final state: npm run docs:check = 0 errors, 13 warns (all known foreign/
user-decision targets: THEMING_AUDIT deleted in worktree, PENDIENTES.md
deleted in d68d2c45, MOTION_SERVICE_RFC demo routes).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Phase 1c of PLAN-docs-reconciliation (fable-eidos-audit D1/D3/D4, B6/B7).
- THEMING s1 vs s2 ('5 layers' vs '6 capas'): s2 owns the layer story,
retitled count-free and rewritten against the REAL index.css imports
(generated incl. font-faces / archetypes / events / aggregated recipes;
code-split recipes + shared partials + runtime theme blocks noted);
s1 links s2. TOC updated.
- THEMING s3 capa 3 + s6 rule 7: hardcoded slot lists (13 and 9 — both
wrong, code has 12 after border-hover removal) replaced by pointers to
COLOR_ROLE_SLOTS + DEFAULT_COLOR_ROLE_SLOT_STEPS.
- THEMING s4: physical-scale mapping table (primary=indigo, risk=amber —
both stale) replaced by pointer to THEME_BASE_COLOR_ROLES with the
convention-vs-authorship note (CANONICAL_INTENT_SCALES != base theme).
- eidos/README: 'Cambios 2026-05-21' + 'Estado actual (2026-05-17)'
(frozen wrapper list ~20 vs 137 real) extracted to
docs/process/handoffs-2026-05.md; pointer left.
- eidos/components/README: frozen migration table (2026-05-20) extracted
likewise; live inventory = components tree + component:audit.
- COMPONENT_AUDIT_GUIDE: stale v1 s12.7/s12.8/s12.9 citations re-pointed
at DEMO_AUTHORING_GUIDE v2 s6 / the eidos composition doctrine.
- eidos-motion s15: title contradicted its own body (the firma moved to
EidosConfig.motion signatures in F2) — retitled, TOC synced.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Fable audit follow-through (fable_audit.md + fable-eidos-audit.md):
- RECIPE_CONTRACT.md (E2 canon): the transversal systems every recipe must
consume, enforced by component-audit R-4.1-4.6 (all at error; escape
valves /* literal */ + /* functional */; WIP tracks excluded). Stale
audit rules fixed against the current architecture (E-2.2 wrapper
imports, D-1.2 v2 9-tab union, D-3.1 single snippet, TabsVariant
mirror) - verdicts went 0/117/15 -> 75/50/5.
- Motion migration 15/15: recipes off local @keyframes onto the channel -
preset stamps (dropdown/context/select/combobox/tooltip/link-preview/
clipboard), new expand/collapse + value-flash signatures, shared-axis
reverse pair, delayed-open open-alias in the preset trigger
(PRESET_STATE_ALIASES), materials pattern for irreducible triggers
(card/timeline/tabs/nav-menu/metrics). Duration/scale hooks keep every
recipe's tuned values.
- buildScheme (fase C): full a1..a12 alpha ramp per role (was a2/a3 -
stale alphas after applyColorScheme), intentSeeds so temper starts from
the ACTIVE theme's intent mapping (risk stays orange), alpha background
self-derived from the scheme's own neutral step 1 (was hardcoded
#fff/#111); mode now forces the donor variant.
- Inventory decisions (fase D): semanticTracking axis removed (all-zero),
border-hover slot dropped (0 consumers), separator slot adopted across
line dividers (step 6, Radix divider tone), size-bundle consumption
pilot on toggle (canonical coordinates consumed, deliberate deviations
kept visible).
- Docs: building-a-component.md (the one door, 9-phase route + known
traps), PLAN-docs-reconciliation.md (fase 6 kickoff for a fresh
session), THEMING wiring updates.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
From the arts/ audit (docs/process/arts-audit-2026-06.md):
- connection: drop 'export * from helpers' (leaked internal builders) and name-export the public error surface; remove the redundant EngineConnections.close() alias (consolidated to closeConnection, consistent with openConnection/reconnectConnection/closeAll) and retarget its destructure-safety test.
- http: extract the inline ATTEMPT_COMPLETED diagnostic message into a named builder (attemptCompletedLogMessage); output preserved.
- color: drop stale 'Phase 0 / not consumed yet' comment (uix.color is consumed by Eidos).
Verified: vitest connection/http/color green, type-check clean, prettier clean. The QrCode morfo fix (literal('path')) is left in src/uix/morfo/schema.ts because that file also carries unrelated in-progress animation-morfo work — not swept in here.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The icon<->typography track is resolved (option 1: the icon follows the font the
component actually uses; cards follow the title, never inflated). The decisions
now live correctly in THEMING §5 (just corrected) + the recipes, so the hand-off
is no longer needed — most of it was the superseded "1:1 total" plan.
Its two live residual TODOs move to pendiente.md (the eidos pending tracker):
audit the Icon <svg> CSS-override bug in other components, and decide whether to
delete the /uix/icon-scale-study test bench. Recorded in the corpus hand-off.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Per explicit instruction to remove deprecated/erroneous files (noise/confusion):
- DATA_ATTRS.md (repo root, 2158 lines) — a stale "Terra Data Attributes
Contracts" catalog, already self-headed DEPRECATED. The data-* contract is the
morfo, validated by morfo:check; this file only lied about it.
- scripts/generate-contracts-docs.ts — its generator, which imports the removed
src/uix/terra/utils/contracts.ts, so it can no longer run.
No doc links to either; nothing imports the script. The package.json
`generate:contracts-docs` entry now dangles at the deleted script — left
untouched because package.json carries unrelated concurrent edits I won't sweep;
flagged in the CONTINUE hand-off to remove later.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
testing-and-tooling.md listed `generate:contracts-docs` as live codegen "from
the morfos" — it is not. The script imports `src/uix/terra/utils/contracts.ts`
(the removed terra layer), so it no longer runs, and its output DATA_ATTRS.md is
a terra-era fossil. Corrected: the data-* contract is the morfo itself, validated
by morfo:check; the legacy script + DATA_ATTRS.md survive but are dead.
Also recorded the pending-.md census in the CONTINUE hand-off: DATA_ATTRS.md
(root, retire to process), the two dated audits (audit-opus / THEMING_AUDIT —
the latter cited in ~7 places), and what to leave (fix-stext.md is cited
provenance; MOTION_SERVICE_RFC / chronos are concurrent; words/palabras excluded).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Where UIX sits relative to the two families (headless behavior: Radix/Ark/bits/
React Aria; styled systems: Mantine/Chakra/Radix Themes/shadcn), grounded in
UIX's own documented design choices rather than claims about competitors'
internals:
- morfo as a single declarative contract (compile-time drift),
- a perception layer (sema) neither family has,
- two-moment motion, theme-as-retint, validated token scope, graceful
degradation,
- and the honest trade-offs (more to learn, smaller ecosystem, sema only pays
off if used).
The one competitor-specific claim (Chakra collapses presence onto one axis) is
sourced in eidos-motion.md. Per-component prop-parity comparisons stay in each
component README, by doctrine. Wired into docs/README.md.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Consolidates the cross-cutting verification story that was scattered across
package.json, COMPONENT_GUIDE and SOMA_ARCHITECTURE into one reference:
- The two-project vitest suite (browser client / node server) and how to run one.
- Each validator and the class of bug it catches: morfo:check (DOM vs contract),
morfo:vocabulary (verb drift), component:audit (acceptance), perm:check
(state transitions), smoke (hydration), translations:check, eidos-lint.
- Codegen vs authored: generate:eidos-css, generate:contracts-docs, and the
compileMorfo primitive.
- The SSR posture: dom:false -> disabledDom, ActiveDom owner-document resolution,
ornamental sema, and why smoke (not HTTP 200) is what catches hydration bugs.
All grounded in the real package.json scripts. Wired into docs/README.md.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The narrative onboarding path that complements the map (docs/README.md) and the
build guide (COMPONENT_GUIDE): run it, the mental model, and your first change,
in order. Grounded in the real routes (/uix/components/*, /active, /temas) and
the real scripts (check / test / morfo:check / smoke / component:audit /
perm:check), it points at COMPONENT_GUIDE / THEMING_GUIDE rather than
duplicating them.
The centerpiece is "see the whole architecture in one element": inspect a toggle
and watch morfo's data-toggle, soma's data-state, sema's data-event-* and eidos's
CSS all on one node — the doctrine made visible.
Wired into docs/README.md (top callout + first "I want to…" row).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
So a session or agent that creates or edits documentation does it consistently
with the corpus, not against it. Codifies what the migration learned, each rule
tied to the failure it fixes:
1. Link the canon, never copy it (the anti-drift law — "7 families" survived in
three docs because they re-transcribed instead of linking).
2. Every doc belongs to one stratum (E0-E5 / process); where each kind lives.
3. Reference docs are timeless — hand-offs, dated status and hardcoded catalogs
go to process/ or become pointers.
4. One source per concern; two docs on a subject get distinct stated roles.
5. Frontmatter convention.
6. Sections cited by §N are load-bearing — stub-split, never silently renumber;
verify moved links resolve.
7. English target; code comments always English.
8. Naming (rfc-* / design-*), markdown relative links, pre-commit checklist.
Wired into docs/README.md ("I want to… write a doc" + a note after the strata).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Companion to the entry point: an agent or new session can look up the framework's
coined terms (morfo, soma, sema, eidos, archetype, runtime part, Presence,
polymorphic close, hold, cascade, TSC, recipe, variant, role, scaling, …) in one
place, each with a pointer to its authoritative doc. The semantic subset
(family / intent / verb / channel) points at CANON.md instead of restating the
values, so it cannot drift.
Wired into docs/README.md (E0 stratum + reading order).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
A single front door to the whole documentation set, for new sessions and agents
to orient before doing anything: the 60-second framework summary, the strata
(E0 orientation / E1 architecture / E2 canon / E3 decisions / E4 guides / E5
module reference / process), a reading order, a per-stratum map of every doc,
and task-oriented shortcuts ("I want to build a component / theme it / know why
a decision was made…").
CLAUDE.md gets a "Start here" pointer at the top of Reference Documents so the
entry point is actually reached on session start (this is the small additive
pointer, not the deferred CLAUDE.md slimming). All links verified.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Completes the renumber-safe split of THEMING.md.
- §8 "añadir componente" + §9 "definir theme" -> src/uix/eidos/THEMING_GUIDE.md
(E4 authoring guides).
- §15 "comparación con librerías" + §17 "FAQ — decisiones polémicas" ->
src/uix/eidos/THEMING_NOTES.md (E3 comparison + rationale).
THEMING.md keeps numbered pointer-stubs at §8/§9/§15/§17; §16 anti-patterns,
the ## Referencias section, and the dated §20-34 changelog stay in place. All
34 sections and every "THEMING §N" citation across the corpus + code survive.
THEMING 2571 -> 1930 lines across the three commits; it is now a leaner E1
layer reference with TSC (E2), the guides (E4) and the notes (E3) as siblings.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
dev