Move the active-app reference into the book tree as the arts composition root,
the App-side analogue of active-uix.md:
- new docs/architecture/active-app.md (frontmatter + fixed relative paths); the
dated Spanish "Handoff 2026-05-13" heading becomes a timeless "Quick start".
- extract that Handoff block verbatim (ES) to docs/process/handoffs-2026-05.md,
alongside the other extracted arts/uix handoffs.
- stub src/arts/active-app/README.md pointing at the chapter (active-uix pattern).
- wire the chapter into the docs/README.md E1 map.
docs:check 0 errors (11 pre-existing warnings unrelated).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Closes the provider→recipe direction of the CSS-var drift stumble the
architecture-faithful way: the morfo is the source of truth. A component now
declares the functional custom properties its soma provider writes and its eidos
recipe reads:
cssVars: [{ name: 'progress', … }, { name: 'angle', … }] // → --knob-progress, --knob-angle
- types: `MorfoCssVar` + optional `cssVars` on `Morfo` (additive; the 133
existing morfos are unaffected).
- schema: validates `cssVars` (array of `{ name, description? }`).
- compile: exposes `contracts.cssVars` as full names `--{kebab}-{name}`.
- knob morfo declares its two contract vars.
- guard (recipe-css-contract.test.ts): enumerates morfos via `import.meta.glob`
and verifies BOTH sides honour each declaration — the provider writes
`--{kebab}-{name}` AND the recipe reads it — so renaming one side without the
other fails loudly. Proven non-vacuous (a bogus cssVar is flagged on both
sides).
Why A1 and not a grep cross-check (A2): in the CSS a provider-written functional
var and a consumer-override alias are indistinguishable, and providers publish
hook vars the recipe doesn't consume — a grep gives ~17 false positives (proven
earlier). The morfo declaration is what disambiguates.
npm run check 59 (baseline, 0 in touched files); eidos recipe-css-contract 24/24;
morfo suite green (only the pre-existing dialog-role test fails); docs:check 0.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Adds a '### Authoring notes' subsection to soma.md §6 grounded in the real
defs — state<T>() vs $state, role optionality on a Provider, Without<>/
PrimitiveDivAttributes, and gesture pointermove/up ownership. Closes STUMBLES
#9; only #7 (soma->eidos CSS-var contract, design-open) remains.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
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>
The emit contract explains discrete events (one gesture → one emit → one
hold) but says nothing about direct-manipulation surfaces (Slider, Drawer,
future knob/swipe) where the pointer moves at sample rate while the value
updates continuously. Add a `## Continuous components (drag, swipe, hold)`
section after the emit contract, grounded entirely in the real Slider/Drawer
code (adversarially fact-checked, zero discrepancies):
- One door: `runtime.trigger()` is the sole path (there is no `emitEvent`).
Its Promise represents the whole occurrence incl. the visual hold — so
`void trigger()` is fire-and-forget (correct for high-frequency emits) and
`await trigger()` blocks until the hold ends (correct when a structural
change must observe the resolved signal, e.g. `close`).
- `coincident` vs `post` for a moving value: the move (handle-drag,
drag-progress) is `coincident` (signal + mutation indivisible); the commit
(commit-set) is `post` (handler settles, then the signal celebrates).
Slider is the worked example.
- Throttle continuous POINTER emits, not keyboard: pointer emits are coalesced
to animation frames + floored to a component-tuned interval via ActiveDom's
requestFrame (Slider DRAG_SIGNAL_MS, Drawer DRAG_PROGRESS_SIGNAL_MS);
keyboard commit-set fires once per keydown (already human-paced). Tuning ms
point to the code, never hard-coded here.
- The per-emit `overrides` payload owns pitch/gain/contour; a continuous
event's cascade rule sets only `channels` and MUST NOT override those
primitives, or it would clobber the live payload every frame.
Co-Authored-By: Claude Opus 4.8 <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>
The common ARIA pattern "emit aria-label only when there is no Label part"
was not declarable. Add `{ when: 'part-absent', part }` as the logical
inverse of `part-present`, plumbed through the four condition sites:
- types.ts: MorfoCondition union member + JSDoc.
- schema.ts: discriminated-union member (structural accept) + extend the
checkCondition unknown-part guard to cover part-absent (throws on unknown
part, same as part-present — the prior guard only discriminated part-present).
- compile.ts: collectConditionDeps adds the referenced part to partRefs, so
the runtime re-evaluates when the part's presence toggles.
- resolver.ts: shouldEmitMorfoEntry returns !bindings.parts?.[part] — emit
when the part is absent/falsy, suppress when present.
Runtime + keyboard paths delegate to these helpers (evalAttrPlan /
shouldEmitMorfoEntry), so no runtime change is needed. Correct by symmetry
with part-present, which reads the same presence-accurate bindings.parts.
Tests: schema accepts a part-absent condition on a known part and throws on
an unknown part; the compiler collects the part dep; the resolver emits the
value when the part is absent and undefined when present.
Docs: morfo.md condition list gains the part-absent form.
Non-breaking: no existing morfo uses it.
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 ⚠️ 'canon + guard, not consumed' asterisk is retired: the C7 sweep
made all 34 size-bearing recipes consume the bundle coordinate, so the
row is ✅ (canon + enforcement + consumption). The footnote also drops
the stale control/compact/dense archetypes (superseded by the 2026-06-17
1:1 override) — control text follows the typographic scale 1:1.
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>
Extending the I1 count guard to color roles and role slots surfaced
four more stale counts the palette fix predicted: the RFCs still said
'13 slots' and enumerated borderHover8 (the slot was retired 2026-07-02,
zero consumers — COLOR_ROLE_SLOTS is 12), and two component READMEs
(css-field, float-panel) still said '8 roles' from before tertiary made
it 9. The guard itself had the same disease it polices: extractConstArray
counted the quoted 'borderHover' inside the comment documenting its own
retirement, so expected=13 and the stale mentions passed — comments are
now stripped before extraction. css-field's README is fixed on disk but
left unstaged (it carries unrelated local modifications).
docs-check now verifies families=8, intents=6, archetypes=26,
palette=33, roles=9, slots=12 against their consts on every run.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
User-caught drift, and it was live in the UI, not just prose: the demo
harness's hand-copied PALETTE_GROUPS enumerated 31 scales — fuchsia and
steel (the two non-Radix scales) never appeared in any demo's
PalettePicker even though PALETTE_SCALES (the const, 33) and the recipe
cascade (paletteScaleDecls maps the const) resolve them fine. Fixed the
two missing entries, typed the groups as PaletteScale[], and added a
dev-time completeness assertion so growing the const without grouping
throws at module load.
Prose swept (the numbers were inherited verbatim from the pre-book
sources, which contradicted their own '33-scale library' headers):
decisions.md color-model row, demo-authoring x4 (incl. the '31-scale
palette' lede), rfc-color-engine x4 (ground-truth + templates
open-question). Where the count was incidental the text now points at
PALETTE_SCALES instead of restating a number.
Guard: docs-check I1 gains the palette count (EN + ES patterns,
~-approximation and type/space-scale exclusions; s-mark added to the
section-number skip). The check line now prints palette=33. This was
the exact class I1 already covered for families/intents/archetypes and
had not been extended to the palette.
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>
The global sweep caught the last corpus links still pointing at
pre-book paths: morfo chapter's s2.bis cross-ref (src/uix/README ->
overview.md), authoring's E1 stratum row (active_architecture ->
docs/architecture/), the related: frontmatter of decisions.md and
canon/recipe-contract.md (THEMING/THEMING_GUIDE -> theming/reference +
guide), and component-audit's typographic-vertebration pointer (eidos
README -> architecture/eidos.md with the translated heading). README
map completed as the book TOC: every chapter now has a row —
theming/motion.md (the model) and theming/changelog.md (the chronicle)
were the two missing. Remaining old-path references live only in
chronicle docs (theming/changelog, process/) and resolve via stubs;
the 11-warn baseline is all foreign targets (MOTION_SERVICE_RFC demo
routes, deleted THEMING_AUDIT/PENDIENTES).
F7.6 complete. The book tree is fully populated: architecture/ (8) +
canon/ (2) + theming/ (7) + rfcs/ (7) + guides/ (4) + decisions/ (2).
Next and last: F7.7 CLAUDE.md thinning — diff to the user first.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
LIBRO_VARIACIONES_Y_EXTENSIONES -> decisions/book-deviations.md and
GUIA_IMPLEMENTACION_SEMAUIX -> decisions/guia-semantica-historica.md,
both moved AS-IS in Spanish: the deviations registry is a logbook of the
author's literal decisions ('transcrita literal') and carries proposed
doctrinal text destined for the Spanish book — translating it would
destroy that function (s G calls itself bitacora); the guia was already
status: historical (Fase 6) and the plan exempts it explicitly. English
frontmatter added to both; internal cross-links repointed (CANON,
theming/reference, book-deviations D.11). docs-check's I2 phantom-field
exemption follows the moved file (it matched by the LIBRO_VARIACIONES
filename; now also matches decisions/book-deviations.md). Corpus swept:
CANON x3, README (E2/E3 strata + tables — also fixed the pre-Fase-6
leftover row still calling the guia 'authoritative for any new wrapper'
and the unswept eidos/TSC.md stratum mention), building-a-component D.4,
completion-checklist G-1.1 + header, theming/reference, architecture
x5 (active-architecture, eidos, morfo, overview, sema x2).
docs:check 0 errors, 11-warn baseline.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
src/uix/soma/COMPONENT_GUIDE.md (1449 L, English body) moved to
docs/guides/component-guide.md. The only Spanish passage — the
archetype-canon banner (2026-06-19) — translated in the move; the rest
is verbatim. Banner's ARCHETYPE_COHERENCE_AUDIT link reaches into src
(audit fossil, stays with the code); the checklist cross-link is now
the sibling ./completion-checklist.md and the 'soma/README s9' mention
now names architecture/soma.md (its post-F7.2 home). Corpus swept:
authoring + README E4 stratum rows (also stale THEMING_GUIDE name),
building-a-component phases 0/2, architecture/{soma-architecture s4/
s13-tree/s17, overview, morfo, active-architecture}.
F7.5 complete: docs/guides/ = component-guide, completion-checklist,
demo-authoring, component-audit. docs:check 0 errors, warns back at
the 11 baseline.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Three English guides moved verbatim (copy + link touch-ups, no
translation): COMPONENT_COMPLETION_CHECKLIST -> guides/
completion-checklist.md, COMPONENT_AUDIT_GUIDE -> guides/
component-audit.md, DEMO_AUTHORING_GUIDE -> guides/demo-authoring.md.
Tooling moved with its doc in the same pass: docs-check I5 now parses
the checklist at the new path (verified: 0 errors, rule tables found)
and component-audit.ts's two path strings updated. One reconciliation
in the audit guide's s5, applied as link-don't-copy: the copied v1
6-tab template list (stale vs the v2 9-tab guide it links, drawer
canary vs button) is replaced by a pointer to demo-authoring.md; the
domain canaries in s7 stay. demo-authoring's harness links now reach
into web/routes/uix/lib/ (the modules stay with the code); the deleted
pendiente_color_demos.md reference is marked TODO(reconcile). Corpus
swept: building-a-component (frontmatter related: + phases 6/8),
authoring, architecture/soma, theming/reference s5-parity,
testing-and-tooling, getting-started, README (E4 rows + component-audit
row added + two stale F7.3 paths in 'I want to' fixed). Remaining
warns = links to component-guide.md, which lands in F7.5 (2/2).
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>
TYPOGRAPHY_ENGINE_RFC (191 L) -> rfcs/rfc-typography.md and COLOR_MODEL_RFC
(155 L) -> rfcs/rfc-color-model.md, Spanish to English. color-model is a
RESOLVED RFC kept as the historical record of the rejected single-anchor
proposal — the resolution header travels with it, canonical model stays
theming reference s25. typography's stub notes the measurement arm
(lib/canvas-text, SText) stays in src. decisions.md rows repointed;
typography's Status aligned with the RFC's own closed-phases state.
Theming reference s21/s25 links swept. docs:check 0 errors.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
DEPTH_ENGINE_RFC (149 L) -> rfcs/rfc-depth.md and SHAPE_ENGINE_RFC (162 L)
-> rfcs/rfc-shape.md, Spanish to English. Both stubs summarize the shipped
state (phases 1-5) and keep the by-path citations resolving — including
the '// (DEPTH_ENGINE_RFC s5)' comments across src/uix/eidos/lib/*.ts that
decisions.md documents as load-bearing. decisions.md index rows repointed
and their Status column aligned with the status the RFCs themselves
declare (both said implemented; the rows still said Propuesta). Theming
reference s29/s30 canonical-guide links swept. docs:check 0 errors.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
SCALING_RFC (92 L) -> rfcs/rfc-scaling.md and STRUCTURE_ENGINE_RFC (113 L)
-> rfcs/rfc-structure.md, Spanish to English, same section numbering. The
legacy-name -> rfc-* rename that decisions.md declared deferred 'until
those citations are swept in the same pass' happens here: stubs at the old
paths keep every by-path citation resolving. Corpus links swept (theming
reference s23/s31, decisions.md index rows, channels.md capstone list —
the channels.md sibling links to rfc-color-engine/typography/depth/shape
land later in this batch). Chronicle docs (theming/changelog,
inherit_audit) keep old paths by doctrine — the stubs resolve them.
docs:check 0 errors.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
src/uix/eidos/THEMING.md (1499 L, Spanish) translated to English as
docs/theming/reference.md, same s1-s38 numbering: the mental model,
s1.bis (theming lives in eidos — the 2-of-3 derivation and the canonical
split), the CSS layers, the 7 token layers, the 9 roles, the size canon
(universal 1:1 + label step-down + container cap + the icon scale), the
naming conventions, the s7/s8/s9/s13/s15/s17/s18 stubs repointed into the
book (canon/tsc, theming/guide, theming/notes, theming/changelog,
theming/motion), runtime overrides + builders, bundle/purge, validation
tooling, s14 motion (the pickup lift), s16 anti-patterns, s19 variants
canon, and the s20-s38 standing-decision stubs. One internal
reconciliation applied: the s35 stub cited the control/compact/dense size
archetypes that s5 declares superseded by the universal 1:1 — aligned.
One stale v1 DEMO_AUTHORING s12.8 citation in s5 replaced by the v2 s6
parity rule. Stub at the old path carries the full s1-s38 map (the most
sN-cited doc in the repo: code comments, CLAUDE.md, RFCs). Corpus links
swept (CANON, docs map, comparison, glossary, eidos chapter, canon/tsc,
theming/guide + notes). docs:check 0 errors (260 docs).
F7.3 complete: docs/canon/ (tsc, recipe-contract) + docs/theming/
(reference, guide, notes, channels, motion, motion-guide, changelog).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
src/uix/eidos/eidos-motion.md (698 L, Spanish) translated to English, same
s1-s19 numbering: the two-moment thesis, the closed cascade model
(D.11-D.13), motion across the 4 layers, the two-surface registry, types,
the EngineMotion API + cleanup policy, the 5 drivers, the DOM contract
(data-animation-style), Presence integration, reduced motion, primitives/
keyframes, built-in content, per-component defaults, code map, s15 (the
events.css -> signatures migration — cited from events.css), Chakra
comparison, naming, phases F1-F7, deferred. Stub with the full s-map at
the old path; corpus links swept (comparison, eidos chapter, changelog,
motion-guide). docs:check 0 errors.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
src/uix/eidos/TSC.md (334 L) and RECIPE_CONTRACT.md (131 L), both Spanish,
translated to English as docs/canon/tsc.md + docs/canon/recipe-contract.md
(the E2 visual canon inside the book tree). Thin stubs at the old paths
(code comments and component-audit R-4.x provenance keep resolving);
corpus links swept (docs map E2 rows, authoring anti-copy law,
building-a-component phase 5, comparison, getting-started, glossary,
eidos chapter). 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>
src/uix/README.md (485 L, Spanish) translated to English as the book's
opening chapter. Two already-decided reconciliations applied in passing:
the 'authoritative GUIA' pointer now reflects its historical status
(phase-6 decision) and the frozen 2026-05-17 migration status became the
timeless statement (every component ships an eidos wrapper; inventory =
tree + component:audit). Thin stub at the old path; docs/README entry,
strata table and reading order repointed. 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 3 of PLAN-docs-reconciliation (fable_audit D5: the 'link, don't
copy' law had no mechanical guard). New scripts/docs-check.ts + npm run
docs:check with six invariants, each born from a verified drift:
- I1 vocabulary counts vs SEMA_FAMILIES/INTENTS/ARCHETYPE_VOCABULARY
(context-gated: font/shape families, variant archetypes and evaluative
subsets don't false-positive; section numbers and quoted historical
mentions skipped).
- I2 phantom fields: translations: in morfo/soma docs, defaultSemantic
outside LIBRO_VARIACIONES (rename/rejection mentions allowed).
- I3 dependency claims: soma dep lists must cite real package.json
dependencies; corpus-wide @floating-ui mentions need their devDep-only
context.
- I4 SHARED_VARIANT_VOCAB (component-audit) == EIDOS_VARIANTS (textual
mirror comparison).
- I5 checklist<->audit: every Enforcement:audit rule exists in the
script, every script rule ID is declared.
- I6 relative links resolve (WARN until the known dangling targets get
their user decision: THEMING_AUDIT deleted in worktree, PENDIENTES.md
deleted 2026-06-07, MOTION_SERVICE_RFC demo routes).
Chronicle docs (process/, changelogs, audits, CONTINUEs, status:
historical frontmatter, the book) are exempt from truth-tracking.
Also: THEMING s2 per-layer table realigned to the real entrypoint (the
fragile rule-count column dropped); stale adom link in SOMA_ARCHITECTURE
fixed; validator documented in docs/testing-and-tooling.md.
Current output: 1 error (building-a-component known-traps row — cleared
in the closing pass) + 13 warns.
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>
decisions.md (the E3 design-rationale entry point) gains a cross-cutting entry
for the read-timing & token-resolution work — including the decision to reject a
static grep-guard in favour of the runtime `uix.perf` detector — pointing to where
the full argument lives (active_architecture §7 + arts/adom + arts/perf READMEs).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The ~12 overlay recipes hardcoded an ad-hoc parallel z-index scale (raw integers
60–99/1200) that duplicated nothing reusable and had drifted out of order
(tooltip 76 < dropdown 80 — a tooltip painted BEHIND a dropdown). They are now a
named scale.
- `STATIC_Z_INDEX_OVERLAY` (static.ts) → emitted as `--z-index-overlay-{inline,
backdrop,content,floating,tooltip,detached,toast}`. A SEPARATE scale from the
global `--z-index-*` ladder (which orders the depth planes) — overlays portal
to <body> as siblings of modals, so they share one flat low band where each
rung sits just above the modal scrim. Mapping them to the 300–900 ladder would
hide a dropdown/select/popover opened INSIDE a dialog (dropdown 300 < modal
700); the combobox recipe already warned about this. `tooltip` now sits above
`floating` (fixes the inversion); `toast` stays above the soma FloatPanel band.
- Every overlay recipe token (`content-z`/`overlay-z`/`inline-z`/`toaster-z`/
`preview-z`) now references `var(--z-index-overlay-*)` — zero raw integers.
dialog/drawer gain an explicit `content-z` rung (drops the `calc(... + 1)`).
- Guard (contracts.test.ts, "overlay z-index against raw integers"): a recipe
`*-z` token must reference the scale, never a bare integer. Proven to catch
drift (a raw `'76'` makes it fail). Local `z-index: 0..5` (avatar/tabs/sticky)
is intra-component relative stacking — out of scope, stays.
- Docs: THEMING.md §35 rewritten to describe the consolidated scale + the
flat-band rationale + the guard; token table gains `--z-index-overlay-*`;
testing-and-tooling.md documents the catalogue guards (VG-8/SYS-1/A31/A30/
THEME-SYS-1).
Stacking order verified from the resolved CSS (deterministic z compare: content
70 < floating 80 < tooltip 90 < toast 1200; dropdown-in-dialog preserved). A
live browser check was blocked by a port conflict with another session's server.
check: 0 new type errors; the 5 guards green.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
- New MOTION_GUIDE.md — the task-oriented developer front door: the `motion` prop, the three
USE domains (event/state/content), the full preset catalog, recipes (animate in/out, loop,
state transitions, staggered list in&out, springs, custom presets), reduced-motion, theming
tokens, [data-debug-stagger], and constraints. Links the model (eidos-motion) + the engine
(arts/motion) + history (RFC).
- eidos-motion.md: note the 3-domain USE framing over the engine's 2 moments (the content
domain is a usage pattern over the state machinery); fix the `fallback` overclaim — it is
NOT auto-applied (the spring honours ctx.reduced itself, per the audit fix).
- docs/README.md (corpus map) + eidos/README.md: motion was undiscoverable — add the guide to
E4 Guides + the "I want to…" table + the eidos Motion section.
Co-Authored-By: Claude Opus 4.8 (1M context) <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>
First piece of the THEMING split, using the renumber-safe stub approach so the
many "THEMING §N" citations across the corpus + code keep resolving.
§7 (Token Scope Contract) and §18 (universal coverage, v2.2) move to a new
src/uix/eidos/TSC.md — the eidos visual canon (E2), with CANON.md-style
frontmatter. THEMING.md keeps numbered pointer-stubs at §7/§18, so section
numbers (and therefore §23/§25/§26/§27/§28 citations) are untouched. 2550 -> 2271
lines; 34 headers intact, TOC anchors still resolve.
Remaining split pieces (own commits): guides §8/§9 -> E4, comparison §15 +
FAQ §17 -> E3.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
THEMING §14 described motion as "deferred / data-motion-ref does not exist /
superseded by the TSC event:* scope". eidos-motion.md says the opposite: the
two-moment model is implemented (F1-F7, 2026-06-04), the engine was relocated to
arts/motion as a service, and it is the event:* scope that is now obsolete. §14
was a stale snapshot contradicting the canonical motion doc.
Rewrite §14 as a lean pointer to eidos-motion.md (canonical, current) with a
status note flagging the obsolete data-motion-ref / event:* framing, and keep
the theming-specific bit (the --motion-scale-lift "pickup" token). Renumber-safe
— §14 stays §14, so the §N citations across the corpus are untouched.
The full stratum-split of THEMING (TSC -> E2, guides -> E4, comparison/FAQ ->
E3) is deferred: it renumbers sections that are cited by number across the
corpus + code, so it needs a dedicated pass with a citation sweep.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
A single E3 entry point cataloguing the design rationale: the 7 eidos RFCs
(color model/engine, typography/depth/shape/structure engines, scaling), the
3 arts subsystem design docs (connection/timer/session), and the cross-cutting
decision logs (LIBRO_VARIACIONES, GESTURES). Each entry gives status + the one
decision it records, linking the document for the full argument.
This delivers the "naming único" goal at the index level. The physical file
rename (*_RFC -> rfc-*, DESIGN_* -> design-*) is deferred: those names are cited
as provenance anchors in ~30 source files (eidos/lib/*.ts, arts/timer/*,
arts/color/*, tests), so a rename only pays off if every citation is swept in
the same pass. The index gives consistent naming without that churn.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The "3 duplicate checklists" diagnosis was wrong. There are two legitimate,
complementary artifacts plus one redundant summary:
- COMPONENT_GUIDE.md — the build checklist (ordered authoring steps 1-40 +
rationale rules A1-A37). How to build a component.
- COMPONENT_COMPLETION_CHECKLIST.md — the acceptance matrix (machine-audited
rules with severity/applicability, bound to scripts/component-audit.ts). When
a component counts as done. Merging it into the guide would break the
script binding.
Consolidation = one source per concern, not one file. Both docs now carry a
header that states their role and cross-links the other as the complement.
soma/README §9 (the only real copy) is reduced to a pointer at both; it keeps
no checklist of its own.
Flagged out of scope: COMPONENT_COMPLETION_CHECKLIST M-3.3 still says "7
families" (canon is 8 with delegate).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The two docs overlapped ~80% (purpose, layers, runtime parts, Soma class,
data-* contracts, naming, checklist). Give each a single role:
- README (1057→400 L): onboarding + authoring guide — purpose, membership
criterion, morfo contract (slim), component + composition pattern, new-
component checklist, and a "deep reference" map pointing into the
architecture doc. Inventory now points at the live directory tree instead
of a hardcoded (drifting) list.
- SOMA_ARCHITECTURE (969→1043 L): the complete deep reference. Absorbed the
few reference bits that only lived in the README — mergeProps, KEYS /
directional keys, focus / roving / scroll-lock, boolean attr helpers, the
internal context() helper and the reactive type-aliases — into a new
§8.bis. Trimmed its purpose section (now owned by the README).
README sections renumbered contiguously; cross-references verified, no other
doc links soma/README by section number.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Close the Phase 1b debt: the "## Handoff 2026-05-14" blocks embedded at
the top of arts/README, arts/adom/README and arts/format/README move to
docs/process/handoffs-2026-05.md, so the layer references read as
timeless. Same mechanical pattern already applied to the UIX READMEs in
41c3b0f9.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Self-contained hand-off to resume the documentation-corpus reorganization in a
fresh session: objective, work rules (no agents, Castilian, never touch
words/palabras, verify-staged), agreed decisions (EN target, hybrid layout,
docs/process for the ephemeral, the E0–E5 strata, canon links code for values),
what's done (Phases 1–2 + Phase 3 2/3, with commit hashes), and what's pending
(soma de-dup — heavy, do with fresh context; the 3 arts hand-offs from 1b debt;
Phases 4–5; deferred items). Lives in docs/process/ (a hand-off is process, not
a CONTINUE-*.md loose at the repo root — which is what we've been removing).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Phase 3 (E1), per the chosen scope. active_architecture.md should read as a
timeless architecture reference:
- §0 "Handoff 2026-05-14" → "## 0. Contratos mínimos por módulo": dropped the
session framing (estado acordado, open/closed questions, P1/P2/P3 findings,
frontend context); kept the minimum-contracts table as reference. The
ownership/degradation rules it stated are now timeless in active-uix/README.
- §10 "Estado actual (2026-05-17)" → a one-line §10 pointing at docs/process/.
The dated status snapshot moved verbatim to
docs/process/active-architecture-snapshot-2026-05.md (kept for traceability;
several of its "pendientes" are since done). Section numbering stays continuous.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Phase 2 of the doc-corpus cleanup. docs/CANON.md distills the immutable semantic
doctrine — the 8 families, 6 intents, intent policy, canonical verbs, the
evaluable-vs-structural rule, composition rules, and the expression-channel owner
split — anchored to TWO sources: the book "Diseñando lo que ocurre" v2.3 (cited
by chapter) and the code (linked by file:symbol, never copied).
Design choice that fixes the root cause of the drift: the canon states DOCTRINE
and LINKS the code for VALUES. It does not re-transcribe the per-family holds,
channel signatures or full verb lists — those live in verbs.ts / types.ts /
intent.ts / sema-map.ts and are linked. A second copy of a value is a future
drift (that is how "7 families" survived in three docs). From now: any doc that
needs to state a family/intent/verb/rule links CANON.md instead of pasting it.
Semantic canon only; the visual canon (TSC, color roles, EIDOS_VARIANTS) stays in
eidos/THEMING.md and is cross-linked.
Next block (pending review): redirect the docs that still re-transcribe the
vocabulary (sema/README §policy+verbs, active_architecture §6, morfo/README,
GUIA §1) to link CANON.md, and wire it into the reading-order entry.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Phase 1b of the doc-corpus cleanup: reference docs should read as timeless.
Pulled the inline "Handoff 2026-05-1x" blocks out of the six layer READMEs
(README, morfo, sema, soma, eidos, active-uix) into
docs/process/handoffs-2026-05.md, with docs/process/README.md explaining that
process/ holds ephemeral, time-stamped artifacts (hand-offs, audits, plans) —
never the source of truth.
README.md keeps its useful "visión de conjunto" pointer to active_architecture
+ GUIA, minus the hand-off framing.
Deferred on purpose: active_architecture §0 (embeds the "contratos mínimos"
table other docs link to — separated during the architecture pass) and
CLAUDE.md's ~10 session hand-offs (it is the per-session instructions file;
its own step). Docs-only.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
dev