- 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>
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>
dev