rafters 0.0.71 → 0.0.72

package/dist/index.js

@@ -437,7 +437,7 @@ function generateThemeInlineBlock(semanticTokens) {
 function generateRootBlock(semanticTokens, darkMode = "class") {
   const semanticMappings = getSemanticMappingsFromTokens(semanticTokens);
   const lines = [];
-  lines.push(":root {");
+  lines.push(":root, :host {");
   for (const [name, mapping] of Object.entries(semanticMappings)) {
     lines.push(`  --rafters-${name}: var(--color-${mapping.light});`);
   }
@@ -750,6 +750,37 @@ function generateTypographyCompositeUtilities(compositeTokens) {
   }
   return lines.join("\n");
 }
+function generateMotionUtilities(motionTokens) {
+  const semanticTokens = motionTokens.filter((t) => t.name.startsWith("motion-semantic-"));
+  if (semanticTokens.length === 0) {
+    return "";
+  }
+  const lines = ["/* Semantic motion utilities -- transition longhand per token */"];
+  for (const token of semanticTokens) {
+    if (typeof token.value !== "string") continue;
+    let spec;
+    try {
+      spec = JSON.parse(token.value);
+    } catch {
+      continue;
+    }
+    const className = token.name.replace("motion-semantic-", "motion-");
+    lines.push(`@utility ${className} {`);
+    lines.push(`  transition-property: ${spec.properties.join(", ")};`);
+    lines.push(`  transition-duration: var(--duration-${spec.durationTier});`);
+    lines.push(`  transition-timing-function: var(--ease-${spec.curve});`);
+    if (spec.reducedMotion) {
+      lines.push("  @media (prefers-reduced-motion: reduce) {");
+      lines.push(`    transition-property: ${spec.reducedMotion.properties.join(", ")};`);
+      if (typeof spec.reducedMotion.ms === "number") {
+        lines.push(`    transition-duration: ${spec.reducedMotion.ms}ms;`);
+      }
+      lines.push("  }");
+    }
+    lines.push("}");
+  }
+  return lines.join("\n");
+}
 function overridePropertyToUtility(property, value) {
   switch (property) {
     case "fontFamily":
@@ -825,6 +856,11 @@ function tokensToTailwind(tokens, options = {}, typographyOverrides = []) {
     sections.push("");
     sections.push(depthUtilities);
   }
+  const motionUtilities = generateMotionUtilities(groups.motion);
+  if (motionUtilities) {
+    sections.push("");
+    sections.push(motionUtilities);
+  }
   const overrideCSS = generateTypographyOverrideCSS(typographyOverrides);
   if (overrideCSS) {
     sections.push("");
@@ -910,6 +946,13 @@ function escapeStringValue(value) {
   }
   return `'${value.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
 }
+var VALID_IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+function namespaceKey(namespace) {
+  return VALID_IDENTIFIER.test(namespace) ? namespace : `'${namespace}'`;
+}
+function namespaceAccess(namespace) {
+  return VALID_IDENTIFIER.test(namespace) ? `tokens.${namespace}` : `tokens['${namespace}']`;
+}
 function namespaceToTypeName(namespace) {
   return namespace.split("-").map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join("");
 }
@@ -930,7 +973,7 @@ function generateTokensObject(tokensByNamespace, includeJSDoc) {
   const namespaces = Array.from(tokensByNamespace.keys()).sort();
   for (const namespace of namespaces) {
     const tokens = tokensByNamespace.get(namespace) || [];
-    lines.push(`  ${namespace}: {`);
+    lines.push(`  ${namespaceKey(namespace)}: {`);
     for (const token of tokens) {
       const value = tokenValueToTS(token);
       if (includeJSDoc && token.semanticMeaning) {
@@ -949,7 +992,7 @@ function generateTypeAliases(namespaces) {
   lines.push("");
   for (const namespace of namespaces) {
     const typeName = `${namespaceToTypeName(namespace)}Token`;
-    lines.push(`export type ${typeName} = keyof typeof tokens.${namespace};`);
+    lines.push(`export type ${typeName} = keyof (typeof ${namespaceAccess(namespace)});`);
   }
   if (namespaces.length > 0) {
     lines.push("");
@@ -1124,15 +1167,21 @@ var DEPTH_LEVELS = [
   "tooltip",
   "overlay"
 ];
-var MOTION_DURATION_SCALE = ["instant", "fast", "normal", "slow", "slower"];
+var MOTION_DURATION_SCALE = [
+  "instant",
+  "micro",
+  "fast",
+  "moderate",
+  "normal",
+  "slow"
+];
 var EASING_CURVES = [
+  "standard",
+  "enter",
+  "exit",
   "linear",
-  "ease-in",
-  "ease-out",
-  "ease-in-out",
-  "productive",
-  "expressive",
-  "spring"
+  "spring-smooth",
+  "spring-snappy"
 ];
 var BREAKPOINT_SCALE = ["sm", "md", "lg", "xl", "2xl"];
 
@@ -21442,6 +21491,13 @@ var ExampleSchema = external_exports.object({
   description: external_exports.string().optional()
 });
 var ColorIntelligenceSchema = external_exports.object({
+  // Designer-facing evocative handle ("Aged Terracotta", "Solar Citrine") from
+  // the intelligence generator. Language, not identity: the deterministic
+  // `name` on ColorValue is the stable, parseable address; `label` is the
+  // voice. Optional because pre-label intelligence persists in Vectorize and
+  // token files. Backported from platform's generateColorIntelligence, which
+  // requires it on generation.
+  label: external_exports.string().optional(),
   reasoning: external_exports.string(),
   emotionalImpact: external_exports.string(),
   culturalContext: external_exports.string(),
@@ -21684,7 +21740,7 @@ var TokenSchema = external_exports.object({
   motionIntent: external_exports.enum(["enter", "exit", "emphasis", "transition"]).optional(),
   easingCurve: external_exports.tuple([external_exports.number(), external_exports.number(), external_exports.number(), external_exports.number()]).optional(),
   // cubicBezier [x1, y1, x2, y2]
-  easingName: external_exports.enum(["linear", "ease-in", "ease-out", "ease-in-out", "productive", "expressive", "spring"]).optional(),
+  easingName: external_exports.enum(["standard", "enter", "exit", "linear", "spring-smooth", "spring-snappy"]).optional(),
   delayMs: external_exports.number().optional(),
   // Delay before animation starts
   // Keyframe tokens (CSS @keyframes content / animation step definitions)
@@ -22301,78 +22357,216 @@ var DEFAULT_SHADOW_DEFINITIONS = {
 };
 var DEFAULT_DURATION_DEFINITIONS = {
   instant: {
-    step: "instant",
-    meaning: "Instant - no animation",
-    contexts: ["disabled-motion", "prefers-reduced-motion"],
+    ms: 0,
+    band: "",
+    meaning: "No perceptible transition. Cursor changes, text selection, badge counts. Below all perception -- there is nothing to track, so nothing is communicated.",
+    contexts: ["disabled-motion", "prefers-reduced-motion", "cursor", "badge-count"],
+    motionIntent: "transition"
+  },
+  micro: {
+    ms: 100,
+    band: "at the instantaneous threshold (Nielsen 0.1s)",
+    meaning: "Immediate but visible. Focus rings and press feedback. At the instantaneous threshold -- acknowledgment that input landed, not communication of a change.",
+    contexts: ["focus", "press", "micro-feedback"],
     motionIntent: "transition"
   },
   fast: {
-    step: -1,
-    meaning: "Fast - micro-interactions, hover states",
-    contexts: ["hover", "focus", "active", "micro-feedback"],
+    ms: 150,
+    band: "below the communicative window",
+    meaning: "Hover states. The cursor is already there, so the response must match its speed. Below the communicative window -- acknowledgment, not communication.",
+    contexts: ["hover", "micro-feedback"],
     motionIntent: "transition"
   },
-  normal: {
-    step: 0,
-    meaning: "Normal - standard UI transitions",
-    contexts: ["buttons", "toggles", "state-changes"],
+  moderate: {
+    ms: 250,
+    band: "communicative (~200-300ms)",
+    meaning: "Dropdowns, tab switches, small reveals. The communicative window: fast enough to feel responsive, slow enough for the eye to track a trajectory and build a spatial model.",
+    contexts: ["dropdowns", "tab-switches", "small-reveals"],
     motionIntent: "transition"
   },
-  slow: {
-    step: 1,
-    meaning: "Slow - enter/exit animations",
-    contexts: ["modals", "dialogs", "panels", "enter-exit"],
+  normal: {
+    ms: 350,
+    band: "communicative, larger movement",
+    meaning: "The workhorse -- modal entrances, toggles, standard state transitions. The communicative window for larger movement.",
+    contexts: ["modals", "toggles", "state-changes"],
     motionIntent: "enter"
   },
-  slower: {
-    step: 2,
-    meaning: "Slower - emphasis, large element transitions",
-    contexts: ["page-transitions", "hero-animations", "emphasis"],
-    motionIntent: "emphasis"
+  slow: {
+    ms: 500,
+    band: "at the sluggish boundary",
+    meaning: "Sheets, page transitions, large spatial movement where the user needs orientation. At the sluggish boundary -- the ceiling for anything but full-screen spatial transitions.",
+    contexts: ["sheets", "page-transitions", "large-spatial-movement"],
+    motionIntent: "enter"
   }
 };
 var DEFAULT_EASING_DEFINITIONS = {
+  standard: {
+    curve: [0.25, 0.1, 0.25, 1],
+    meaning: "Precision -- arrives exactly where it should, engineered rather than thrown. Decelerates into its final position. General-purpose state transitions and hover.",
+    contexts: ["state-changes", "hover", "general-purpose"],
+    css: "cubic-bezier(0.25, 0.1, 0.25, 1)"
+  },
+  enter: {
+    curve: [0, 0, 0.2, 1],
+    meaning: "Arrival, welcome, settling into place. The fast start communicates responsiveness; the slow finish communicates care. Anything entering the viewport. Paired with `exit` as a deliberately asymmetric couple. (Dragicevic 2011: slow-in/slow-out outperforms constant speed for tracking.)",
+    contexts: ["enter-animations", "elements-appearing"],
+    css: "cubic-bezier(0, 0, 0.2, 1)"
+  },
+  exit: {
+    curve: [0.4, 0, 1, 1],
+    meaning: "Withdrawal, giving space. The brief hesitation acknowledges the user; the fast departure avoids lingering. Anything leaving the viewport. Paired with `enter` as a deliberately asymmetric couple -- exits are faster than entrances by design.",
+    contexts: ["exit-animations", "elements-leaving"],
+    css: "cubic-bezier(0.4, 0, 1, 1)"
+  },
   linear: {
     curve: [0, 0, 1, 1],
-    meaning: "Linear - constant speed, mechanical feel",
-    contexts: ["progress-bars", "loading-spinners", "opacity-fades"],
+    meaning: "Mechanical, procedural, without personality -- a process, not a gesture. Progress and loading, where the system is working rather than interacting. Never for interactive spatial transitions.",
+    contexts: ["progress-bars", "loading-spinners", "opacity-fades", "focus-ring-fade"],
     css: "linear"
   },
-  "ease-in": {
-    curve: [0.42, 0, 1, 1],
-    meaning: "Ease in - starts slow, accelerates (exiting)",
-    contexts: ["exit-animations", "elements-leaving"],
-    css: "cubic-bezier(0.42, 0, 1, 1)"
+  "spring-smooth": {
+    curve: [0.2, 0.9, 0.3, 1],
+    meaning: "Alive, coming physically to rest -- a critically-damped spring with no overshoot. Page transitions, sheets, large tracked spatial movement. (Johansson 1973 / Pratt 2010: animate motion is perceived as alive and captures attention.)",
+    contexts: ["page-transitions", "sheets", "large-spatial-movement"],
+    css: "cubic-bezier(0.2, 0.9, 0.3, 1)"
   },
-  "ease-out": {
-    curve: [0, 0, 0.58, 1],
-    meaning: "Ease out - starts fast, decelerates (entering)",
-    contexts: ["enter-animations", "elements-appearing"],
-    css: "cubic-bezier(0, 0, 0.58, 1)"
-  },
-  "ease-in-out": {
-    curve: [0.42, 0, 0.58, 1],
-    meaning: "Ease in-out - symmetric acceleration/deceleration",
-    contexts: ["state-changes", "transforms", "general-purpose"],
-    css: "cubic-bezier(0.42, 0, 0.58, 1)"
-  },
-  productive: {
-    curve: [0.2, 0, 0.38, 0.9],
-    meaning: "Productive - quick, efficient, minimal overshoot",
-    contexts: ["work-ui", "data-displays", "business-apps"],
-    css: "cubic-bezier(0.2, 0, 0.38, 0.9)"
-  },
-  expressive: {
-    curve: [0.4, 0.14, 0.3, 1],
-    meaning: "Expressive - dramatic, attention-grabbing",
-    contexts: ["marketing", "onboarding", "celebrations", "emphasis"],
-    css: "cubic-bezier(0.4, 0.14, 0.3, 1)"
-  },
-  spring: {
-    curve: [0.175, 0.885, 0.32, 1.275],
-    meaning: "Spring - bouncy overshoot for playful feel",
-    contexts: ["buttons", "icons", "playful-ui", "celebrations"],
-    css: "cubic-bezier(0.175, 0.885, 0.32, 1.275)"
+  "spring-snappy": {
+    curve: [0.2, 0.8, 0.2, 1],
+    meaning: "Alive, tight, following input closely -- a tighter spring with less settle and no overshoot. Toggles, presses, interactions that track input.",
+    contexts: ["toggles", "presses", "input-tracking"],
+    css: "cubic-bezier(0.2, 0.8, 0.2, 1)"
+  }
+};
+var DEFAULT_MOTION_SEMANTIC_MAPPINGS = {
+  hover: {
+    properties: ["color", "background-color", "border-color"],
+    durationTier: "fast",
+    curve: "standard",
+    reducedMotion: null,
+    category: "interaction",
+    sizeReasoning: "Colour only, no movement -- the cursor is already on target, so the response matches its speed at the fast tier.",
+    meaning: "Hover-state colour transition. Acknowledges pointer presence.",
+    contexts: ["hover", "links", "interactive-surfaces"]
+  },
+  focus: {
+    properties: ["box-shadow", "outline-color"],
+    durationTier: "micro",
+    curve: "linear",
+    reducedMotion: null,
+    category: "interaction",
+    sizeReasoning: "A ring appearing, not moving -- micro tier at linear velocity reads as the system marking focus, not a gesture. (Tailwind ring is box-shadow.)",
+    meaning: "Focus-ring transition. Marks the focused element.",
+    contexts: ["focus-visible", "keyboard-navigation"]
+  },
+  press: {
+    properties: ["transform", "color", "background-color"],
+    durationTier: "micro",
+    curve: "spring-snappy",
+    reducedMotion: { properties: ["color", "background-color"] },
+    category: "interaction",
+    sizeReasoning: "The fastest, tightest feedback -- micro tier with a snappy spring follows the finger. Under reduced motion the transform drops; the colour change survives.",
+    meaning: "Press/active feedback. Confirms the input was received.",
+    contexts: ["press", "active", "buttons"]
+  },
+  toggle: {
+    properties: ["color", "background-color", "transform"],
+    durationTier: "moderate",
+    curve: "spring-snappy",
+    reducedMotion: { properties: ["color", "background-color"] },
+    category: "interaction",
+    sizeReasoning: "A thumb travelling a track is a small, tracked movement -- moderate tier, snappy spring. Reduced motion drops the transform to a colour cross-fade.",
+    meaning: "Toggle/switch state change. Shows the new state.",
+    contexts: ["switch", "toggle", "checkbox"]
+  },
+  "dropdown-in": {
+    properties: ["opacity", "transform"],
+    durationTier: "moderate",
+    curve: "enter",
+    reducedMotion: { properties: ["opacity"], ms: 100 },
+    category: "enter",
+    sizeReasoning: "A dropdown is small and travels a short distance -- moderate tier, one step below the modal, with the arrival curve.",
+    meaning: "Dropdown/menu entrance.",
+    contexts: ["dropdown", "menu", "select", "popover"]
+  },
+  "dropdown-out": {
+    properties: ["opacity", "transform"],
+    durationTier: "fast",
+    curve: "exit",
+    reducedMotion: { properties: ["opacity"], ms: 100 },
+    category: "exit",
+    sizeReasoning: "The exit of a small element -- fast tier (shorter than its moderate entrance) with the departure curve. The user already chose to dismiss it.",
+    meaning: "Dropdown/menu exit.",
+    contexts: ["dropdown", "menu", "select", "popover"]
+  },
+  "modal-in": {
+    properties: ["opacity", "transform"],
+    durationTier: "normal",
+    curve: "enter",
+    reducedMotion: { properties: ["opacity"], ms: 150 },
+    category: "enter",
+    sizeReasoning: "A modal is larger and travels farther than a dropdown -- normal tier, one step up, with the arrival curve. Size and distance produce the longer duration.",
+    meaning: "Modal/dialog entrance.",
+    contexts: ["modal", "dialog", "alert-dialog"]
+  },
+  "modal-out": {
+    properties: ["opacity", "transform"],
+    durationTier: "moderate",
+    curve: "exit",
+    reducedMotion: { properties: ["opacity"], ms: 150 },
+    category: "exit",
+    sizeReasoning: "The modal exit -- moderate tier (shorter than its normal entrance) with the departure curve.",
+    meaning: "Modal/dialog exit.",
+    contexts: ["modal", "dialog", "alert-dialog"]
+  },
+  "sheet-in": {
+    properties: ["transform"],
+    durationTier: "slow",
+    curve: "spring-smooth",
+    reducedMotion: { properties: ["opacity"], ms: 250 },
+    category: "enter",
+    sizeReasoning: "A sheet is the largest spatial movement -- slow tier with the physical settle of a smooth spring, because the user must track it into place. Reduced motion becomes a cross-fade.",
+    meaning: "Sheet/drawer entrance.",
+    contexts: ["sheet", "drawer", "side-panel"]
+  },
+  "sheet-out": {
+    properties: ["transform"],
+    durationTier: "normal",
+    curve: "exit",
+    reducedMotion: { properties: ["opacity"], ms: 250 },
+    category: "exit",
+    sizeReasoning: "The sheet exit -- normal tier (shorter than its slow entrance) with the departure curve.",
+    meaning: "Sheet/drawer exit.",
+    contexts: ["sheet", "drawer", "side-panel"]
+  },
+  expand: {
+    properties: ["grid-template-rows", "opacity"],
+    durationTier: "normal",
+    curve: "enter",
+    reducedMotion: { properties: ["opacity"] },
+    category: "enter",
+    sizeReasoning: "Content unfolding to its natural height -- normal tier with the arrival curve. Transitions grid-template-rows (0fr->1fr), the transitionable stand-in for height:auto. Reduced motion snaps the rows and fades opacity.",
+    meaning: "Expand/reveal collapsible content (accordion, disclosure).",
+    contexts: ["accordion", "collapsible", "disclosure"]
+  },
+  collapse: {
+    properties: ["grid-template-rows", "opacity"],
+    durationTier: "moderate",
+    curve: "exit",
+    reducedMotion: { properties: ["opacity"] },
+    category: "exit",
+    sizeReasoning: "Content folding away -- moderate tier (shorter than its normal expansion) with the departure curve. Reduced motion snaps the rows.",
+    meaning: "Collapse/hide collapsible content (accordion, disclosure).",
+    contexts: ["accordion", "collapsible", "disclosure"]
+  },
+  page: {
+    properties: ["opacity", "transform"],
+    durationTier: "slow",
+    curve: "spring-smooth",
+    reducedMotion: { properties: ["opacity"], ms: 200 },
+    category: "enter",
+    sizeReasoning: "A whole-view transition -- slow tier with the physical settle of a smooth spring, because the user reorients across the largest possible distance.",
+    meaning: "Page/route transition.",
+    contexts: ["page-transition", "route-change", "view-switch"]
   }
 };
 var DEFAULT_DELAY_DEFINITIONS = {
@@ -24997,7 +25191,14 @@ function tryParseUnit(cssValue, registry2 = DEFAULT_UNITS) {
 }
 
 // ../design-tokens/src/generators/motion.ts
-function generateMotionTokens(config2, durationDefs, easingDefs, delayDefs) {
+var LEGACY_EASING_REMAP = {
+  linear: "linear",
+  "ease-out": "enter",
+  "ease-in": "exit",
+  "ease-in-out": "standard",
+  spring: "spring-snappy"
+};
+function generateMotionTokens(config2, durationDefs, easingDefs, delayDefs, semanticMappings) {
   const tokens = [];
   const timestamp = (/* @__PURE__ */ new Date()).toISOString();
   const { baseTransitionDuration, progressionRatio } = config2;
@@ -25009,52 +25210,44 @@ function generateMotionTokens(config2, durationDefs, easingDefs, delayDefs) {
     value: `${baseTransitionDuration}ms`,
     category: "motion",
     namespace: "motion",
-    semanticMeaning: "Base transition duration - all motion timing derives from this",
-    usageContext: ["calculation-reference"],
+    semanticMeaning: "Legacy base transition duration. The perceptual duration scale (motion-duration-*) no longer derives from this; retained only as a reference value and delay-progression base.",
+    usageContext: ["calculation-reference", "delay-base"],
     progressionSystem: progressionRatio,
-    description: `Base duration (${baseTransitionDuration}ms). Motion uses ${progressionRatio} progression (ratio ${ratioVal}).`,
+    description: `Base duration (${baseTransitionDuration}ms). Delay tokens use ${progressionRatio} progression (ratio ${ratioVal}); duration tiers are perceptually derived literals.`,
     generatedAt: timestamp,
     containerQueryAware: false,
     reducedMotionAware: true,
     userOverride: null,
     usagePatterns: {
-      do: ["Reference as the calculation base"],
-      never: ["Change without understanding full motion scale impact"]
+      do: ["Reference as the delay-progression base"],
+      never: ["Assume the perceptual duration tiers derive from this"]
     }
   });
   for (const scale2 of MOTION_DURATION_SCALE) {
     const def = durationDefs[scale2];
     if (!def) continue;
     const scaleIndex = MOTION_DURATION_SCALE.indexOf(scale2);
-    let durationMs;
-    let mathRelationship;
-    if (def.step === "instant") {
-      durationMs = 0;
-      mathRelationship = "0";
-    } else {
-      durationMs = Math.round(computeStep(baseTransitionDuration, def.step));
-      mathRelationship = def.step === 0 ? `${baseTransitionDuration}ms (base)` : `${baseTransitionDuration} \xD7 ${ratioVal}^${def.step}`;
-    }
+    const durationMs = def.ms;
+    const bandNote = def.band ? ` Band: ${def.band}.` : "";
     tokens.push({
       name: `motion-duration-${scale2}`,
-      value: durationMs === 0 ? "0ms" : `${durationMs}ms`,
+      value: `${durationMs}ms`,
       category: "motion",
       namespace: "motion",
-      semanticMeaning: def.meaning,
+      semanticMeaning: `${def.meaning}${bandNote}`,
       usageContext: def.contexts,
       scalePosition: scaleIndex,
-      progressionSystem: progressionRatio,
       motionIntent: def.motionIntent,
       motionDuration: durationMs,
-      mathRelationship,
-      dependsOn: def.step === "instant" ? [] : ["motion-duration-base"],
-      description: `Duration ${scale2}: ${durationMs}ms. ${def.meaning}`,
+      mathRelationship: def.band ? `${durationMs}ms (perceptual: ${def.band})` : `${durationMs}ms`,
+      dependsOn: [],
+      description: `Duration ${scale2}: ${durationMs}ms.${bandNote} ${def.meaning}`,
       generatedAt: timestamp,
       containerQueryAware: false,
       reducedMotionAware: true,
       userOverride: null,
       usagePatterns: {
-        do: scale2 === "instant" ? ["Use for prefers-reduced-motion", "Use for disabled animations"] : scale2 === "fast" ? ["Use for hover/focus states", "Use for micro-interactions"] : scale2 === "normal" ? ["Use for most UI transitions", "Use for state changes"] : ["Use for enter/exit animations", "Use for emphasis"],
+        do: scale2 === "instant" ? ["Use for prefers-reduced-motion", "Use for disabled animations"] : scale2 === "micro" || scale2 === "fast" ? ["Use for acknowledgment feedback (hover, focus, press)"] : ["Use for communicative transitions where the user must track the change"],
         never: ["Ignore prefers-reduced-motion", "Use slow animations for frequent actions"]
       }
     });
@@ -25077,10 +25270,10 @@ function generateMotionTokens(config2, durationDefs, easingDefs, delayDefs) {
       reducedMotionAware: true,
       userOverride: null,
       usagePatterns: {
-        do: curve === "linear" ? ["Use for opacity fades", "Use for progress indicators"] : curve === "ease-out" ? ["Use for entering elements", "Use for appearing content"] : curve === "ease-in" ? ["Use for exiting elements", "Use for disappearing content"] : ["Use for general transitions", "Match context to curve feel"],
+        do: curve === "linear" ? ["Use for progress and loading, where the system is working not interacting"] : curve === "enter" ? ["Use for anything entering the viewport"] : curve === "exit" ? ["Use for anything leaving the viewport"] : ["Match the curve register to the interaction feel"],
         never: [
-          "Use ease-in for entering (feels sluggish)",
-          "Use ease-out for exiting (feels abrupt)"
+          "Use exit for entering (arrives reluctantly)",
+          "Use linear for interactive spatial transitions (reads as mechanical)"
         ]
       }
     });
@@ -25417,13 +25610,13 @@ function generateMotionTokens(config2, durationDefs, easingDefs, delayDefs) {
     } else {
       const durationDef = durationDefs[anim.duration];
       if (!durationDef) continue;
-      const durationMs = durationDef.step === "instant" ? 0 : Math.round(computeStep(baseTransitionDuration, durationDef.step));
-      durationValue = `${durationMs}ms`;
+      durationValue = `${durationDef.ms}ms`;
       durationRef = `var(--motion-duration-${anim.duration})`;
     }
-    const easingDef = easingDefs[anim.easing];
+    const easingKey = LEGACY_EASING_REMAP[anim.easing] ?? anim.easing;
+    const easingDef = easingDefs[easingKey];
     if (!easingDef) continue;
-    const easingRef = `var(--motion-easing-${anim.easing})`;
+    const easingRef = `var(--motion-easing-${easingKey})`;
     const iterations = anim.iterations || "";
     const animValue = iterations ? `${anim.keyframe} ${durationRef} ${easingRef} ${iterations}` : `${anim.keyframe} ${durationRef} ${easingRef}`;
     tokens.push({
@@ -25441,7 +25634,7 @@ function generateMotionTokens(config2, durationDefs, easingDefs, delayDefs) {
       dependsOn: [
         `motion-keyframe-${anim.keyframe}`,
         ...anim.duration.endsWith("s") || anim.duration.endsWith("ms") ? [] : [`motion-duration-${anim.duration}`],
-        `motion-easing-${anim.easing}`
+        `motion-easing-${easingKey}`
       ],
       description: `Animation ${anim.name}: ${anim.meaning}`,
       generatedAt: timestamp,
@@ -25489,14 +25682,10 @@ function generateMotionTokens(config2, durationDefs, easingDefs, delayDefs) {
   ];
   for (const comp of composites2) {
     const durationDef = durationDefs[comp.duration];
-    const easingDef = easingDefs[comp.easing];
+    const easingKey = LEGACY_EASING_REMAP[comp.easing] ?? comp.easing;
+    const easingDef = easingDefs[easingKey];
     if (!durationDef || !easingDef) continue;
-    let durationMs;
-    if (durationDef.step === "instant") {
-      durationMs = 0;
-    } else {
-      durationMs = Math.round(computeStep(baseTransitionDuration, durationDef.step));
-    }
+    const durationMs = durationDef.ms;
     tokens.push({
       name: comp.name,
       value: `${durationMs}ms ${easingDef.css}`,
@@ -25506,27 +25695,54 @@ function generateMotionTokens(config2, durationDefs, easingDefs, delayDefs) {
       usageContext: comp.contexts,
       motionDuration: durationMs,
       easingCurve: easingDef.curve,
-      easingName: comp.easing,
-      dependsOn: [`motion-duration-${comp.duration}`, `motion-easing-${comp.easing}`],
-      description: `${comp.meaning}. Combines ${comp.duration} duration with ${comp.easing} easing.`,
+      easingName: easingKey,
+      dependsOn: [`motion-duration-${comp.duration}`, `motion-easing-${easingKey}`],
+      description: `${comp.meaning}. Combines ${comp.duration} duration with ${easingKey} easing.`,
       generatedAt: timestamp,
       containerQueryAware: false,
       reducedMotionAware: true,
       userOverride: null
     });
   }
+  for (const [name, mapping] of Object.entries(semanticMappings)) {
+    tokens.push({
+      name: `motion-semantic-${name}`,
+      value: JSON.stringify({
+        properties: mapping.properties,
+        durationTier: mapping.durationTier,
+        curve: mapping.curve,
+        reducedMotion: mapping.reducedMotion
+      }),
+      category: "motion",
+      namespace: "motion",
+      semanticMeaning: `${mapping.meaning} ${mapping.sizeReasoning}`,
+      usageContext: mapping.contexts,
+      motionIntent: mapping.category === "enter" ? "enter" : mapping.category === "exit" ? "exit" : "transition",
+      generateUtilityClass: true,
+      dependsOn: [`motion-duration-${mapping.durationTier}`, `motion-easing-${mapping.curve}`],
+      description: `Semantic motion motion-${name}: ${mapping.properties.join(", ")} over ${mapping.durationTier} with ${mapping.curve}. ${mapping.sizeReasoning}`,
+      generatedAt: timestamp,
+      containerQueryAware: false,
+      reducedMotionAware: true,
+      userOverride: null,
+      usagePatterns: {
+        do: [`Apply class motion-${name} and let a state/presence change trigger the transition`],
+        never: ["Hardcode a raw numeric duration in place of this token"]
+      }
+    });
+  }
   tokens.push({
     name: "motion-progression",
     value: JSON.stringify({
       ratio: progressionRatio,
       ratioValue: ratioVal,
       baseDuration: baseTransitionDuration,
-      note: "Motion timing uses step-based progression (base * ratio^step) for unified feel"
+      note: "Duration tiers are perceptually derived literals (docs/MOTION.md); delay tokens use the workspace progression ratio from the base duration."
     }),
     category: "motion",
     namespace: "motion",
-    semanticMeaning: "Metadata about the motion progression system",
-    description: `Motion uses ${progressionRatio} progression from ${baseTransitionDuration}ms base.`,
+    semanticMeaning: "Metadata about the motion system",
+    description: `Duration tiers are perceptual literals; delays use ${progressionRatio} progression from ${baseTransitionDuration}ms base.`,
     generatedAt: timestamp,
     containerQueryAware: false,
     userOverride: null
@@ -26436,7 +26652,8 @@ function createGeneratorDefs(colorPaletteBases) {
         config2,
         DEFAULT_DURATION_DEFINITIONS,
         DEFAULT_EASING_DEFINITIONS,
-        DEFAULT_DELAY_DEFINITIONS
+        DEFAULT_DELAY_DEFINITIONS,
+        DEFAULT_MOTION_SEMANTIC_MAPPINGS
       )
     },
     {
@@ -27444,7 +27661,7 @@ var RegistryFileSchema = external_exports.object({
   devDependencies: external_exports.array(external_exports.string()).default([])
   // e.g., ["vitest"] - from @devDependencies JSDoc
 });
-var RegistryItemTypeSchema = external_exports.enum(["ui", "primitive", "composite", "rule"]);
+var RegistryItemTypeSchema = external_exports.enum(["ui", "primitive", "composite", "rule", "substrate"]);
 var RegistryItemIntelligenceSchema = external_exports.object({
   cognitiveLoad: external_exports.number().optional(),
   attentionEconomics: external_exports.string().optional(),
@@ -27472,7 +27689,8 @@ var RegistryIndexSchema = external_exports.object({
   components: external_exports.array(external_exports.string()),
   primitives: external_exports.array(external_exports.string()),
   composites: external_exports.array(external_exports.string()).default([]),
-  rules: external_exports.array(external_exports.string()).default([])
+  rules: external_exports.array(external_exports.string()).default([]),
+  substrate: external_exports.array(external_exports.string()).default([])
 });
 
 // src/registry/client.ts
@@ -27481,7 +27699,8 @@ var REGISTRY_SOURCE = {
   ui: { folder: "components", label: "Component" },
   primitive: { folder: "primitives", label: "Primitive" },
   composite: { folder: "composites", label: "Composite" },
-  rule: { folder: "rules", label: "Rule" }
+  rule: { folder: "rules", label: "Rule" },
+  substrate: { folder: "substrate", label: "Substrate" }
 };
 var FETCH_ORDER = Object.keys(REGISTRY_SOURCE);
 var RegistryClient = class {
@@ -27517,7 +27736,8 @@ var RegistryClient = class {
       ui: fetchFrom("ui"),
       primitive: fetchFrom("primitive"),
       composite: fetchFrom("composite"),
-      rule: fetchFrom("rule")
+      rule: fetchFrom("rule"),
+      substrate: fetchFrom("substrate")
     };
     this.fetchComponent = this.fetchByType.ui;
     this.fetchPrimitive = this.fetchByType.primitive;
@@ -28488,6 +28708,7 @@ function isSharedFile(path) {
   }
   return false;
 }
+var REACT_FALLBACK_TARGETS = /* @__PURE__ */ new Set(["astro", "vue", "svelte"]);
 function selectFilesForFramework(files, target) {
   const preferredExt = targetToExtension(target);
   const shared = files.filter((f) => isSharedFile(f.path));
@@ -28495,12 +28716,15 @@ function selectFilesForFramework(files, target) {
   if (matched.length > 0) {
     return { files: [...matched, ...shared], fallback: false };
   }
-  if (target !== "react") {
+  if (REACT_FALLBACK_TARGETS.has(target)) {
     const fallbackFiles = files.filter((f) => f.path.endsWith(".tsx"));
     if (fallbackFiles.length > 0) {
       return { files: [...fallbackFiles, ...shared], fallback: true };
     }
   }
+  if (target !== "react" && !REACT_FALLBACK_TARGETS.has(target)) {
+    return { files: shared, fallback: false };
+  }
   return { files, fallback: false };
 }
 var TARGET_GATED_COMPOSITE_FILES = [
@@ -28515,12 +28739,13 @@ function selectCompositeFiles(files, target) {
 var FOLDER_NAMES = /* @__PURE__ */ new Set(["composites"]);
 function isAlreadyInstalled(config2, item) {
   if (!config2?.installed) return false;
-  const { components, primitives, composites: composites2, rules } = config2.installed;
+  const { components, primitives, composites: composites2, rules, substrate } = config2.installed;
   const bucketByType = {
     ui: components,
     primitive: primitives,
     composite: composites2 ?? [],
-    rule: rules ?? []
+    rule: rules ?? [],
+    substrate: substrate ?? []
   };
   return bucketByType[item.type].includes(item.name);
 }
@@ -28539,11 +28764,13 @@ function trackInstalled(config2, items) {
   const installed = config2.installed;
   if (!installed.composites) installed.composites = [];
   if (!installed.rules) installed.rules = [];
+  if (!installed.substrate) installed.substrate = [];
   const bucketByType = {
     ui: installed.components,
     primitive: installed.primitives,
     composite: installed.composites,
-    rule: installed.rules
+    rule: installed.rules,
+    substrate: installed.substrate
   };
   for (const item of items) {
     const bucket = bucketByType[item.type];
@@ -28553,11 +28780,12 @@ function trackInstalled(config2, items) {
   installed.primitives.sort();
   installed.composites.sort();
   installed.rules.sort();
+  installed.substrate.sort();
 }
 function rootFor(field, cwd, fallback) {
   return field === void 0 ? fallback : resolveRoot(field, cwd, fallback);
 }
-function transformPath(registryPath, config2, cwd) {
+function transformPath(registryPath, config2, cwd = process.cwd()) {
   if (!config2) return registryPath;
   const replacements = [
     ["components/ui/", config2.componentsPath, "components/ui"],
@@ -28572,10 +28800,16 @@ function transformPath(registryPath, config2, cwd) {
   }
   return registryPath;
 }
+function substrateProjectPath(registryPath, config2, cwd = process.cwd()) {
+  const componentsResolved = rootFor(config2?.componentsPath, cwd, "components/ui");
+  const sourceRoot = componentsResolved.replace(/\/?components\/ui$/, "");
+  return sourceRoot ? join7(sourceRoot, registryPath) : registryPath;
+}
 function fileExists(cwd, relativePath) {
   return existsSync3(join7(cwd, relativePath));
 }
-function transformFileContent(content, config2, fileType = "component", cwd = process.cwd()) {
+function transformFileContent(content, config2, fileType = "component", cwd = process.cwd(), opts = {}) {
+  const { substrateKinds = [], installPath } = opts;
   let transformed = content;
   const componentsPath = rootFor(config2?.componentsPath, cwd, "components/ui");
   const primitivesPath = rootFor(config2?.primitivesPath, cwd, "lib/primitives");
@@ -28590,26 +28824,23 @@ function transformFileContent(content, config2, fileType = "component", cwd = pr
     /from\s+['"]\.\.\/primitives\/([^'"]+)['"]/g,
     `from '@/${aliasPrimitives}/$1'`
   );
-  const aliasSibling = fileType === "primitive" ? aliasPrimitives : aliasComponents;
+  const substrateOwnDir = fileType === "substrate" && installPath ? stripSourceRoot(dirname(installPath)) : null;
+  const aliasSibling = fileType === "primitive" ? aliasPrimitives : substrateOwnDir ?? aliasComponents;
   transformed = transformed.replace(/from\s+['"]\.\/([^'"]+)['"]/g, `from '@/${aliasSibling}/$1'`);
-  const aliasLib = stripSourceRoot(dirname(primitivesPath));
-  transformed = transformed.replace(
-    /from\s+['"]\.\.\/lib\/([^'"]+)['"]/g,
-    `from '@/${aliasLib}/$1'`
-  );
-  const componentsMatch = aliasComponents.match(/^(.*)components\/ui$/);
-  const aliasHooks = componentsMatch ? `${componentsMatch[1]}hooks`.replace(/^\//, "") : "hooks";
-  transformed = transformed.replace(
-    /from\s+['"]\.\.\/hooks\/([^'"]+)['"]/g,
-    `from '@/${aliasHooks}/$1'`
-  );
+  if (substrateKinds.length > 0) {
+    const kindAlternation = substrateKinds.join("|");
+    transformed = transformed.replace(
+      new RegExp(`from\\s+['"](?:\\.\\./){1,2}(${kindAlternation})/([^'"]+)['"]`, "g"),
+      "from '@/$1/$2'"
+    );
+  }
   transformed = transformed.replace(
-    /from\s+['"]\.\.\/(?!lib\/|hooks\/)([^'"]+)['"]/g,
+    /from\s+['"]\.\.\/([^'"]+)['"]/g,
     `from '@/${aliasComponents}/$1'`
   );
   return transformed;
 }
-async function installItem(cwd, item, options, config2) {
+async function installItem(cwd, item, options, config2, substrateKinds = []) {
   const installedFiles = [];
   let skipped = false;
   let filesToInstall = item.files;
@@ -28625,11 +28856,17 @@ async function installItem(cwd, item, options, config2) {
         message: `No ${targetToExtension(target)} version available for ${item.name}. Installing React version.`
       });
     }
+    const hasComponentFile = selection.files.some((f) => !isSharedFile(f.path));
+    if (!hasComponentFile) {
+      throw new Error(
+        `No ${targetToExtension(target)} version available for "${item.name}" and no compatible fallback exists.`
+      );
+    }
   } else if (item.type === "composite") {
     filesToInstall = selectCompositeFiles(item.files, getComponentTarget(config2));
   }
   for (const file2 of filesToInstall) {
-    const projectPath2 = transformPath(file2.path, config2, cwd);
+    const projectPath2 = item.type === "substrate" ? substrateProjectPath(file2.path, config2, cwd) : transformPath(file2.path, config2, cwd);
     const targetPath = join7(cwd, projectPath2);
     if (fileExists(cwd, projectPath2)) {
       if (!options.overwrite) {
@@ -28644,8 +28881,11 @@ async function installItem(cwd, item, options, config2) {
       }
     }
     await mkdir2(dirname(targetPath), { recursive: true });
-    const fileType = item.type === "primitive" ? "primitive" : "component";
-    const transformedContent = transformFileContent(file2.content, config2, fileType, cwd);
+    const fileType = item.type === "primitive" ? "primitive" : item.type === "substrate" ? "substrate" : "component";
+    const transformedContent = transformFileContent(file2.content, config2, fileType, cwd, {
+      substrateKinds,
+      installPath: file2.path
+    });
     await writeFile2(targetPath, transformedContent, "utf-8");
     installedFiles.push(projectPath2);
   }
@@ -28758,6 +28998,11 @@ async function add(componentArgs, options) {
       return;
     }
   }
+  const substrateKinds = [
+    ...new Set(
+      allItems.filter((item) => item.type === "substrate").map((item) => item.files[0]?.path.split("/")[0]).filter((segment) => Boolean(segment))
+    )
+  ];
   const installed = [];
   const skipped = [];
   const installedItems = [];
@@ -28781,7 +29026,7 @@ async function add(componentArgs, options) {
       });
     }
     try {
-      const result = await installItem(cwd, item, options, config2);
+      const result = await installItem(cwd, item, options, config2, substrateKinds);
       if (result.installed) {
         installed.push(item.name);
         installedItems.push(item);

package/dist/registry/types.d.ts

@@ -19,13 +19,19 @@ declare const RegistryFileSchema: z.ZodObject<{
 }, z.core.$strip>;
 type RegistryFile = z.infer<typeof RegistryFileSchema>;
 /**
- * Item type in registry
+ * Item type in registry.
+ * `substrate` is the behavior-layer runtime (the score contract, compose
+ * slices, reactive hooks -- everything under ui/src outside components /
+ * primitives / composites). It is a copy-in shared dependency resolved like a
+ * primitive; the specific dir it installs into (`@/lib`, `@/hooks`, ...) is
+ * carried in the item's file path, so the type never grows per kind.
  */
 declare const RegistryItemTypeSchema: z.ZodEnum<{
     ui: "ui";
     primitive: "primitive";
     composite: "composite";
     rule: "rule";
+    substrate: "substrate";
 }>;
 type RegistryItemType = z.infer<typeof RegistryItemTypeSchema>;
 /**
@@ -59,6 +65,7 @@ declare const RegistryItemSchema: z.ZodObject<{
         primitive: "primitive";
         composite: "composite";
         rule: "rule";
+        substrate: "substrate";
     }>;
     description: z.ZodOptional<z.ZodString>;
     primitives: z.ZodArray<z.ZodString>;
@@ -93,6 +100,7 @@ declare const RegistryIndexSchema: z.ZodObject<{
     primitives: z.ZodArray<z.ZodString>;
     composites: z.ZodDefault<z.ZodArray<z.ZodString>>;
     rules: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    substrate: z.ZodDefault<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
 type RegistryIndex = z.infer<typeof RegistryIndexSchema>;
 

package/dist/registry/types.js

@@ -8,7 +8,7 @@ var RegistryFileSchema = z.object({
   devDependencies: z.array(z.string()).default([])
   // e.g., ["vitest"] - from @devDependencies JSDoc
 });
-var RegistryItemTypeSchema = z.enum(["ui", "primitive", "composite", "rule"]);
+var RegistryItemTypeSchema = z.enum(["ui", "primitive", "composite", "rule", "substrate"]);
 var RegistryItemIntelligenceSchema = z.object({
   cognitiveLoad: z.number().optional(),
   attentionEconomics: z.string().optional(),
@@ -36,7 +36,8 @@ var RegistryIndexSchema = z.object({
   components: z.array(z.string()),
   primitives: z.array(z.string()),
   composites: z.array(z.string()).default([]),
-  rules: z.array(z.string()).default([])
+  rules: z.array(z.string()).default([]),
+  substrate: z.array(z.string()).default([])
 });
 export {
   RegistryFileSchema,

package/package.json

@@ -1,13 +1,22 @@
 {
   "name": "rafters",
-  "version": "0.0.71",
+  "version": "0.0.72",
   "description": "Design Intelligence CLI. Scaffold tokens, import existing shadcn/Tailwind v4 sources, add components, and serve an MCP server so AI agents read decisions instead of guessing.",
   "homepage": "https://rafters.studio",
   "license": "MIT",
-  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rafters-studio/rafters.git",
+    "directory": "packages/cli"
+  },
   "bin": {
     "rafters": "./dist/index.js"
   },
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "type": "module",
   "exports": {
     ".": "./dist/index.js",
     "./registry/types": {
@@ -15,10 +24,9 @@
       "import": "./dist/registry/types.js"
     }
   },
-  "files": [
-    "dist",
-    "LICENSE"
-  ],
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
@@ -57,13 +65,5 @@
     "typescript": "catalog:",
     "vitest": "catalog:",
     "zocker": "catalog:"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/rafters-studio/rafters.git",
-    "directory": "packages/cli"
-  },
-  "publishConfig": {
-    "access": "public"
   }
 }