@3xhaust/oh-my-design 0.16.1

package/core/motion/recipes/split-text-entrance.md

@@ -0,0 +1,222 @@
+# Split-text entrance (character / word stagger)
+
+Split-text is the technique of decomposing a heading into individual `<span>` elements —
+one per character or one per word — then staggering their entrance via a CSS animation
+delay cascade. Each fragment arrives fractionally after the last, so the text assembles
+itself in front of the viewer rather than appearing complete.
+
+## When it earns its place / When it does not
+
+Condition: the hero type is the primary visual event and the words are part of the concept
+— something is being said, not just displayed. A heading that reads "The infrastructure
+that disappears" reveals meaning word by word; each word lands with intent. The reveal
+enacts the concept.
+
+Condition against: body copy, UI labels, secondary headings, navigation items, any text
+the user needs to skim or operate. Split-text on body copy converts reading into waiting
+— the user must watch the paragraph assemble itself before they can begin. It is the most
+common technique deployed too broadly. The `expressive.md` technique catalogue states
+this directly: "Split-text on body copy turns reading into waiting." The stagger budget
+is consumed by the entrance; there is nothing left for the content. Apply this technique
+to one element per page — the one element whose arrival is the event.
+
+Character-level stagger is more dramatic than word-level; use character-level only when
+the display type is large enough (roughly 60px+) that individual characters read as
+distinct forms. At smaller sizes, word-level stagger is the correct granularity.
+
+## Parameters
+
+```css
+:root {
+  /* Duration for each character/word span's fade-translate entrance. */
+  --duration-split: 480ms;
+
+  /* Easing for each span. ease-out-expo reads as authoritative; ease-out-quint
+     slightly softer. Both from core/motion/easing.md. */
+  --ease-split: var(--ease-out-expo);
+
+  /* Delay between each successive span. 40ms minimum (below this the stagger
+     is imperceptible); 80ms maximum (above this it becomes a waterfall).
+     core/theory/motion.md: "Sibling stagger: 40–80ms offset." */
+  --stagger-split: 55ms;
+
+  /* Vertical offset the span travels from on entrance. Keep small — 16–24px.
+     Larger values read as falling rather than arriving. */
+  --translate-split: 20px;
+}
+```
+
+## Implementation
+
+```html
+<!-- The heading must have complete text content in the HTML. The JS adds spans;
+     if it fails or is disabled, the text reads normally. -->
+<h1 class="split-hero" aria-label="The infrastructure that disappears">
+  The infrastructure that disappears
+</h1>
+```
+
+```css
+.split-hero .split-char,
+.split-hero .split-word {
+  display: inline-block; /* required: transform does not apply to inline */
+  opacity: 0;
+  transform: translateY(var(--translate-split));
+  animation: split-enter var(--duration-split) var(--ease-split) forwards;
+  animation-play-state: paused; /* JS un-pauses after splitting */
+}
+
+@keyframes split-enter {
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+/* Space characters must be preserved as visible spans or words gap wrong */
+.split-hero .split-space {
+  display: inline-block;
+  white-space: pre;
+}
+```
+
+```js
+// Split at word level (swap 'word' for 'char' for character-level stagger).
+// Run once on DOMContentLoaded — not on scroll, not on re-render.
+function splitTextEntrance(el, mode = 'word') {
+  const text = el.textContent ?? '';
+  const units = mode === 'char'
+    ? [...text].map(ch => ({ text: ch, isSpace: ch === ' ' }))
+    : text.split(' ').map((w, i, arr) => ({ text: w, isSpace: false, addSpace: i < arr.length - 1 }));
+
+  el.textContent = '';
+  units.forEach(({ text, isSpace, addSpace }, i) => {
+    if (isSpace) {
+      const sp = document.createElement('span');
+      sp.className = 'split-space';
+      sp.textContent = ' ';
+      el.appendChild(sp);
+      return;
+    }
+    const span = document.createElement('span');
+    span.className = mode === 'char' ? 'split-char' : 'split-word';
+    span.textContent = text;
+    // Each span's delay is its index × the stagger custom property value.
+    // Read the value from the root so the hand's token wiring is respected.
+    const stagger = parseFloat(getComputedStyle(document.documentElement)
+      .getPropertyValue('--stagger-split')) || 55;
+    span.style.animationDelay = `${i * stagger}ms`;
+    span.style.animationPlayState = 'running';
+    el.appendChild(span);
+    if (addSpace) {
+      const sp = document.createElement('span');
+      sp.className = 'split-space';
+      sp.textContent = ' ';
+      el.appendChild(sp);
+    }
+  });
+}
+
+document.addEventListener('DOMContentLoaded', () => {
+  document.querySelectorAll('.split-hero').forEach(el => splitTextEntrance(el, 'word'));
+});
+```
+
+## React
+
+```tsx
+import { motion } from 'framer-motion';
+
+// Framer Motion handles the span decomposition via staggerChildren.
+// variants.container drives the orchestration; variants.item drives each word.
+const container = {
+  hidden: {},
+  visible: {
+    transition: {
+      staggerChildren: 0.055, // --stagger-split equivalent
+    },
+  },
+};
+
+const item = {
+  hidden: { opacity: 0, y: 20 },
+  visible: {
+    opacity: 1,
+    y: 0,
+    transition: {
+      duration: 0.48, // --duration-split equivalent
+      ease: [0.16, 1, 0.3, 1], // --ease-out-expo
+    },
+  },
+};
+
+function SplitHero({ text }: { text: string }) {
+  const words = text.split(' ');
+  return (
+    <motion.h1
+      aria-label={text}
+      variants={container}
+      initial="hidden"
+      animate="visible"
+      style={{ display: 'flex', flexWrap: 'wrap', gap: '0.25em' }}
+    >
+      {words.map((word, i) => (
+        <motion.span key={i} variants={item} style={{ display: 'inline-block' }}>
+          {word}
+        </motion.span>
+      ))}
+    </motion.h1>
+  );
+}
+```
+
+Framer Motion respects `prefers-reduced-motion` automatically when you pass
+`reducedMotion="user"` to `<MotionConfig>` at the app root. Add this once:
+
+```tsx
+import { MotionConfig } from 'framer-motion';
+// In your root layout:
+<MotionConfig reducedMotion="user">{children}</MotionConfig>
+```
+
+## Reduced-motion variant
+
+When `prefers-reduced-motion: reduce` is set, the text must be complete and legible —
+not an empty space, not a deferred render. The split spans are not created; the heading
+renders as normal text with a single short opacity fade.
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  .split-hero .split-char,
+  .split-hero .split-word {
+    /* Collapse all spans to visible immediately — no transform, no stagger. */
+    opacity: 1;
+    transform: none;
+    animation: none;
+  }
+}
+```
+
+In the JS split function, check before splitting:
+
+```js
+const prefersReduced = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+if (!prefersReduced) {
+  document.querySelectorAll('.split-hero').forEach(el => splitTextEntrance(el, 'word'));
+}
+```
+
+## Performance note
+
+Each span animates only `opacity` and `transform: translateY()` — both compositor-only
+properties. No layout is triggered on any frame. The GPU handles each span independently;
+the main thread is not involved after the initial DOM construction.
+
+`will-change: transform` on every span would promote each to its own compositor layer,
+consuming GPU memory proportional to the number of characters. On a 40-character heading
+at character-level stagger, this is forty compositor layers. Do not apply `will-change`
+here. The browser's compositor schedules the animations correctly without it.
+
+The JS runs once on `DOMContentLoaded`. It does not run on scroll, on re-render, or
+on visibility change. The spans are DOM elements for the lifetime of the page; there is
+no teardown cost.

package/core/motion/recipes/stagger-orchestrator.md

@@ -0,0 +1,227 @@
+# Stagger orchestrator
+
+A stagger orchestrator drives a group of sibling elements — cards, list items, nav links,
+feature blocks — so each child enters slightly after the previous, reading the group as a
+sequence rather than a simultaneous burst. The recipe handles both static lists (CSS
+nth-child delay cascade) and dynamic lists (JS-computed delays) and centralises the
+stagger math so it is filled from the board's motion invariants rather than hardcoded
+per-component.
+
+## When it earns its place / When it does not
+
+Condition: the elements have an implied order — a feature list whose items have a
+sequence, a card grid whose items are ranked, a navigation whose items flow from primary
+to secondary. The stagger communicates that order; the eye follows the arrival sequence
+and reads a hierarchy. `core/theory/motion.md`: "staggering their arrivals reads the
+group as a sequence — semantically correct when the elements have an implied order."
+
+Condition against: elements with no meaningful order — a tag cloud, a random mosaic, a
+grid of equally-weighted items. Staggering unordered items implies a sequence that does
+not exist, which is misleading choreography. Also: long lists. A 30-item list staggered
+at 60ms arrives over 1.8 seconds — the last card enters nearly two seconds after the
+first, by which point the user has scrolled past it. Cap staggered groups at eight to
+ten items; beyond that, consider grouping (reveal the first row together, then the second)
+or collapsing the stagger to 20ms so the total remains under 600ms.
+
+The stagger budget calculation: `--stagger-base × (n - 1)` must stay under 600ms.
+For a group of eight at 55ms, the total span is 385ms — within budget. For fifteen items
+at 55ms, the span is 770ms — over budget. Either reduce the group or reduce the delay.
+
+## Parameters
+
+```css
+:root {
+  /* Delay between each successive element. 40–80ms from core/theory/motion.md.
+     Below 40ms: imperceptible, wasted. Above 80ms: waterfall. */
+  --stagger-base: 55ms;
+
+  /* Duration for each element's entrance animation. Independent of stagger;
+     each element animates for its full duration from its delayed start. */
+  --stagger-duration: 320ms;
+
+  /* Easing for each element's entrance. */
+  --stagger-ease: var(--ease-out-quint);
+
+  /* Vertical translate offset on entrance. */
+  --stagger-translate-y: 20px;
+}
+```
+
+## Implementation
+
+```css
+/* ── CSS nth-child cascade (for static, known-count lists) ─────────────────── */
+
+.stagger-group > * {
+  opacity: 0;
+  transform: translateY(var(--stagger-translate-y));
+  animation: stagger-in var(--stagger-duration) var(--stagger-ease) forwards;
+}
+
+@keyframes stagger-in {
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+/* Generate nth-child delays via CSS. For a group of up to 10 items: */
+.stagger-group > *:nth-child(1)  { animation-delay: calc(var(--stagger-base) * 0); }
+.stagger-group > *:nth-child(2)  { animation-delay: calc(var(--stagger-base) * 1); }
+.stagger-group > *:nth-child(3)  { animation-delay: calc(var(--stagger-base) * 2); }
+.stagger-group > *:nth-child(4)  { animation-delay: calc(var(--stagger-base) * 3); }
+.stagger-group > *:nth-child(5)  { animation-delay: calc(var(--stagger-base) * 4); }
+.stagger-group > *:nth-child(6)  { animation-delay: calc(var(--stagger-base) * 5); }
+.stagger-group > *:nth-child(7)  { animation-delay: calc(var(--stagger-base) * 6); }
+.stagger-group > *:nth-child(8)  { animation-delay: calc(var(--stagger-base) * 7); }
+.stagger-group > *:nth-child(9)  { animation-delay: calc(var(--stagger-base) * 8); }
+.stagger-group > *:nth-child(10) { animation-delay: calc(var(--stagger-base) * 9); }
+```
+
+```js
+// ── JS version for dynamic lists or when scroll-triggered stagger is needed ──
+// Reads the custom property from :root so the board-wired token is respected.
+
+function applyStagger(container) {
+  const base = parseFloat(
+    getComputedStyle(document.documentElement).getPropertyValue('--stagger-base')
+  ) || 55;
+
+  const children = Array.from(container.children);
+  children.forEach((child, i) => {
+    child.style.animationDelay = `${i * base}ms`;
+    child.style.animationPlayState = 'running';
+  });
+}
+
+// For scroll-triggered stagger: observe the container, apply delays when it enters view.
+const observer = new IntersectionObserver(
+  (entries) => {
+    entries.forEach((entry) => {
+      if (entry.isIntersecting) {
+        applyStagger(entry.target);
+        observer.unobserve(entry.target);
+      }
+    });
+  },
+  { threshold: 0.1 }
+);
+
+document.querySelectorAll('.stagger-group').forEach((el) => observer.observe(el));
+```
+
+## React
+
+```tsx
+import { motion } from 'framer-motion';
+
+const containerVariants = {
+  hidden: {},
+  visible: {
+    transition: {
+      staggerChildren: 0.055, // --stagger-base
+      delayChildren: 0,
+    },
+  },
+};
+
+const itemVariants = {
+  hidden: { opacity: 0, y: 20 },
+  visible: {
+    opacity: 1,
+    y: 0,
+    transition: {
+      duration: 0.32,          // --stagger-duration
+      ease: [0.22, 1, 0.36, 1], // --ease-out-quint
+    },
+  },
+};
+
+function StaggerGroup<T>({
+  items,
+  renderItem,
+}: {
+  items: T[];
+  renderItem: (item: T, i: number) => React.ReactNode;
+}) {
+  return (
+    <motion.ul
+      variants={containerVariants}
+      initial="hidden"
+      animate="visible"
+    >
+      {items.map((item, i) => (
+        <motion.li key={i} variants={itemVariants}>
+          {renderItem(item, i)}
+        </motion.li>
+      ))}
+    </motion.ul>
+  );
+}
+```
+
+For scroll-triggered stagger in React, combine with `useInView`:
+
+```tsx
+import { useInView } from 'framer-motion';
+import { useRef } from 'react';
+
+function ScrollStaggerGroup({ items, renderItem }) {
+  const ref = useRef(null);
+  const isInView = useInView(ref, { once: true, margin: '-15% 0px' });
+
+  return (
+    <motion.ul
+      ref={ref}
+      variants={containerVariants}
+      initial="hidden"
+      animate={isInView ? 'visible' : 'hidden'}
+    >
+      {items.map((item, i) => (
+        <motion.li key={i} variants={itemVariants}>
+          {renderItem(item, i)}
+        </motion.li>
+      ))}
+    </motion.ul>
+  );
+}
+```
+
+## Reduced-motion variant
+
+In reduced-motion context, all group members are visible simultaneously — no stagger,
+no translate, no fade sequence. The content is available immediately.
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  .stagger-group > * {
+    opacity: 1;
+    transform: none;
+    animation: none !important;
+  }
+}
+```
+
+For the JS path, check before applying delays:
+
+```js
+const prefersReduced = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+if (!prefersReduced) {
+  document.querySelectorAll('.stagger-group').forEach((el) => observer.observe(el));
+}
+```
+
+## Performance note
+
+Each child animates only `opacity` and `transform: translateY()` — compositor-only
+properties. At 60fps on mid-range hardware, ten simultaneous opacity + transform
+animations present no measurable cost. The browser composites them independently on
+the GPU.
+
+The CSS nth-child approach requires no JavaScript and is therefore zero-overhead at
+runtime. Prefer it for static lists. The JS approach adds one IntersectionObserver
+callback per group; the callback fires once and is immediately disconnected.
+
+Do not generate more than ten nth-child rules in CSS for staggered groups — beyond ten
+items, the total stagger duration at 55ms/item (550ms+) exceeds the perceivable range
+and the JS approach with a capped delay is preferable.

package/core/motion/recipes/sticky-scene-transition.md

@@ -0,0 +1,246 @@
+# Sticky scene transition
+
+A sticky scene pins the viewport at a fixed scroll position while the user continues
+scrolling, advancing an animation timeline inside the pinned area instead of moving the
+page. The result: sections that behave as discrete scenes rather than continuous columns.
+The scroll gesture becomes a time axis — the user controls playback by scrolling, the
+interface responds frame by frame.
+
+## When it earns its place / When it does not
+
+Condition: a multi-scene showpiece where each scene requires the user's full attention
+before they advance — a product demo that teaches a feature sequence, a narrative
+microsite with distinct chapters, a brand campaign where each scroll beat corresponds
+to a concept moment. The scene boundary is earned: the user has finished one scene and
+is deliberately entering the next. `expressive.md`: "The stage pins the viewport while
+scroll advances the timeline inside the scene."
+
+Condition against: sites where the user is goal-oriented and scrolling to find specific
+content. Any product with return visits — a sticky stage the user has already watched
+becomes pure friction; they must scroll through the entire scene again to reach content
+below it. If there is any chance of return visits, a skip control is required. Also:
+sites with more than three or four scenes — beyond that, the user's sense of scroll
+distance breaks down and they feel trapped rather than guided. `expressive.md`: "Sticky
+stages are navigation debt — the user cannot scroll past to scan; they must watch the
+scene play."
+
+## Parameters
+
+```css
+:root {
+  /* Height of the sticky container — how much scroll distance each scene consumes.
+     Larger values give more scroll range per scene (smoother progress on trackpad);
+     smaller values feel more abrupt. 200–300vh per scene is typical. */
+  --scene-height: 250vh;
+
+  /* Duration of the transition between scenes when using CSS transitions on
+     scene-specific elements. */
+  --scene-transition-duration: 480ms;
+
+  /* Easing for scene element transitions. */
+  --scene-ease: var(--ease-in-out-quint);
+
+  /* Easing for elements entering during a scene. */
+  --scene-enter-ease: var(--ease-out-expo);
+}
+```
+
+## Implementation
+
+```html
+<!-- Each .scene-stage is one scene. The inner .scene-content is the pinned viewport.
+     The outer .scene-stage provides the scroll track. -->
+<div class="scene-stage">
+  <div class="scene-content" data-scene="1">
+    <div class="scene-panel panel-a">First beat content</div>
+    <div class="scene-panel panel-b">Second beat content</div>
+  </div>
+</div>
+
+<div class="scene-stage">
+  <div class="scene-content" data-scene="2">
+    <!-- ... -->
+  </div>
+</div>
+```
+
+```css
+.scene-stage {
+  /* The scroll track: tall enough for the scene's full timeline. */
+  height: var(--scene-height);
+  position: relative;
+}
+
+.scene-content {
+  /* Pin the content area for the height of its parent track. */
+  position: sticky;
+  top: 0;
+  height: 100vh;
+  overflow: hidden;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+/* ── CSS scroll-driven: advance panels via scroll progress ────────────────── */
+.scene-panel {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  opacity: 0;
+  transform: translateY(40px);
+  animation: scene-enter var(--scene-transition-duration) var(--scene-enter-ease) forwards;
+  animation-timeline: view(block);
+  animation-range: entry 10% entry 40%;
+}
+
+.scene-panel.panel-b {
+  /* Second panel enters at a later point in the scroll range. */
+  animation-range: entry 50% entry 80%;
+}
+
+@keyframes scene-enter {
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+```
+
+```js
+// JS-driven alternative when precise scroll-progress control is needed
+// (e.g., driving a canvas, SVG, or WebGL scene with scroll position).
+
+function SceneController(stageEl) {
+  const contentEl = stageEl.querySelector('.scene-content');
+
+  function update() {
+    const rect = stageEl.getBoundingClientRect();
+    const trackHeight = stageEl.offsetHeight - window.innerHeight;
+    // progress: 0 = scene just pinned, 1 = scene about to unpin
+    const progress = Math.max(0, Math.min(1, -rect.top / trackHeight));
+
+    // Distribute progress to child panels
+    const panels = contentEl.querySelectorAll('.scene-panel');
+    const segmentSize = 1 / panels.length;
+    panels.forEach((panel, i) => {
+      const panelProgress = Math.max(0, Math.min(1,
+        (progress - i * segmentSize) / segmentSize
+      ));
+      // Apply panelProgress to panel's opacity and transform
+      panel.style.opacity = panelProgress;
+      panel.style.transform = `translateY(${(1 - panelProgress) * 40}px)`;
+    });
+  }
+
+  window.addEventListener('scroll', update, { passive: true });
+  update();
+}
+
+document.querySelectorAll('.scene-stage').forEach((el) => SceneController(el));
+```
+
+## React
+
+```tsx
+import { motion, useScroll, useTransform } from 'framer-motion';
+import { useRef } from 'react';
+
+function StickyScene({ children }: { children: React.ReactNode }) {
+  const trackRef = useRef<HTMLDivElement>(null);
+
+  // scrollYProgress: 0 = scene pinned, 1 = scene unpinning
+  const { scrollYProgress } = useScroll({
+    target: trackRef,
+    offset: ['start start', 'end end'],
+  });
+
+  return (
+    // The track provides scroll height; the sticky wrapper pins content.
+    <div ref={trackRef} style={{ height: 'var(--scene-height, 250vh)' }}>
+      <div style={{ position: 'sticky', top: 0, height: '100vh' }}>
+        {/* Pass scrollYProgress to children via context or props
+            for per-element transform wiring */}
+        {children}
+      </div>
+    </div>
+  );
+}
+
+// A single panel driven by scroll progress:
+function ScenePanel({
+  enter,  // [0..1] range at which panel enters
+  leave,  // [0..1] range at which panel leaves
+  scrollProgress,
+  children,
+}: {
+  enter: [number, number];
+  leave: [number, number];
+  scrollProgress: import('framer-motion').MotionValue<number>;
+  children: React.ReactNode;
+}) {
+  const opacity = useTransform(scrollProgress, [enter[0], enter[1], leave[0], leave[1]], [0, 1, 1, 0]);
+  const y = useTransform(scrollProgress, [enter[0], enter[1]], [40, 0]);
+
+  return (
+    <motion.div style={{ opacity, y, position: 'absolute', inset: 0 }}>
+      {children}
+    </motion.div>
+  );
+}
+```
+
+## Reduced-motion variant
+
+In reduced-motion context, the sticky pinning is retained (it is a layout choice, not
+a motion effect) but all animated transitions within the scene are removed. Each panel
+is visible and the scroll track does not drive any per-frame style change.
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  .scene-panel {
+    opacity: 1;
+    transform: none;
+    animation: none !important;
+    /* Stack panels and let the user read them in document flow. */
+    position: relative;
+  }
+
+  /* Disable the sticky pinning entirely in reduced-motion to restore normal scroll. */
+  .scene-content {
+    position: relative;
+    height: auto;
+  }
+
+  .scene-stage {
+    height: auto;
+  }
+}
+```
+
+The JS controller should check `prefers-reduced-motion` and skip scroll-driven updates:
+
+```js
+const prefersReduced = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+if (!prefersReduced) {
+  document.querySelectorAll('.scene-stage').forEach((el) => SceneController(el));
+}
+```
+
+## Performance note
+
+The CSS scroll-driven approach runs off the main thread in Chromium — zero JavaScript
+per frame. The JS controller uses `{ passive: true }` on the scroll listener and updates
+only `opacity` and `transform`, both compositor properties. Neither path touches layout
+on scroll.
+
+`will-change: transform` on pinned panels is appropriate here because these elements are
+actively animated for the duration of the scene. Apply it at most to two or three panels
+simultaneously; panels that have exited can have `will-change` removed.
+
+The scroll track height (`--scene-height: 250vh`) determines how much scroll travel
+each scene consumes. Longer tracks feel smoother on high-resolution trackpads; shorter
+tracks feel abrupt. Test on both trackpad and scroll wheel — the scroll granularity
+differs and a scene that feels cinematic on a MacBook may stutter on a mouse.