@3xhaust/oh-my-design 0.16.1

package/core/motion/recipes/parallax.md

@@ -0,0 +1,233 @@
+# Parallax
+
+A parallax effect moves background and foreground elements at different rates as the
+user scrolls, creating an illusion of depth. The CSS scroll-driven implementation
+(`animation-timeline: scroll()`) moves an element by a fixed offset over the full
+scroll range of its container, running off the main thread with no JavaScript per frame.
+
+Read the restraint clause below before deciding whether to use this recipe. The evidence
+for not using parallax is substantial, and the recipe's conditions are narrow.
+
+## When it earns its place / When it does not
+
+Condition: the content is a scroll-narrative — a case study, a product demo page, a
+campaign microsite — and the concept explicitly requires a sense of depth or layering.
+The parallax element contributes to the narrative; removing it would remove meaning, not
+just decoration. The movement is subtle: the `--parallax-offset` is small (20–40px over
+the full scroll range), producing depth rather than motion-sickness. `core/theory/
+motion.md`: "use scroll-linked animation only when the content is itself a
+scroll-narrative and the concept explicitly requires it."
+
+Condition against: product UI. Navigation elements. Any page where the user is scanning
+for content rather than experiencing a narrative. `core/theory/motion.md` cites the
+NN/g evidence directly: users scroll quickly to scan for keywords; parallax requires slow
+scrolling to read; users who scroll at normal speed miss the effect entirely, and users
+with vestibular disorders are harmed by it. The NN/g research ("What Parallax Lacks",
+2013) documents three failures — invisible to fast scrollers, classified as decorative
+noise by experienced users, and a vestibular trigger for sensitive users. The 2024
+performance data adds a fourth: parallax-heavy pages showed LCP exceeding 8 seconds and
+poor INP scores, constituting Core Web Vitals failures.
+
+If you are reaching for parallax because the page needs more visual interest, the correct
+answer is a better layout or a stronger type decision — not depth simulation. Apply this
+recipe only when the brief explicitly names the concept as depth-dependent and the scroll
+narrative test is met.
+
+## Parameters
+
+```css
+:root {
+  /* How far the element moves over the full scroll range of its container.
+     Keep small. 20–40px creates depth without visible motion-sickness.
+     Negative values move the element against the scroll direction (classic parallax).
+     Positive values move it with scroll (subtle, less disorienting). */
+  --parallax-offset: -30px;
+
+  /* Whether to apply the effect. Set to 'none' to disable without removing CSS. */
+  --parallax-enabled: block; /* unused in current implementation; see JS approach */
+}
+```
+
+## Implementation
+
+```html
+<section class="parallax-section">
+  <!-- The background element moves at the slower rate. -->
+  <div class="parallax-bg" aria-hidden="true">
+    <!-- decorative image or gradient -->
+  </div>
+
+  <!-- Foreground content scrolls at normal speed. -->
+  <div class="parallax-content">
+    <h2>The infrastructure layer</h2>
+  </div>
+</section>
+```
+
+```css
+/* ── CSS scroll-driven (preferred; off-thread) ────────────────────────────── */
+
+.parallax-section {
+  /* Establish a scroll timeline scoped to this container. */
+  overflow: hidden; /* contain the background overflow */
+  position: relative;
+}
+
+.parallax-bg {
+  position: absolute;
+  inset: calc(var(--parallax-offset) * -1) 0; /* compensate so bg fills section at start */
+  background-image: var(--parallax-bg-image);
+  background-size: cover;
+  background-position: center;
+
+  /* The animation moves translateY from 0 to --parallax-offset over the scroll range. */
+  animation: parallax-drift linear both;
+  animation-timeline: scroll(root block); /* tracks document scroll, not section scroll */
+  animation-range: contain 0% contain 100%;
+}
+
+@keyframes parallax-drift {
+  from { transform: translateY(0); }
+  to   { transform: translateY(var(--parallax-offset)); }
+}
+
+/* ── IntersectionObserver + requestAnimationFrame fallback ───────────────── */
+/* For browsers without scroll-driven support; also gives per-frame control. */
+```
+
+```js
+// Only use the JS path when CSS scroll-driven is unavailable.
+if (!CSS.supports('animation-timeline', 'scroll()')) {
+  document.querySelectorAll('.parallax-bg').forEach(attachParallax);
+}
+
+function attachParallax(el) {
+  const section = el.closest('.parallax-section');
+  if (!section) return;
+
+  const offset = parseFloat(
+    getComputedStyle(document.documentElement).getPropertyValue('--parallax-offset')
+  ) || -30;
+
+  let ticking = false;
+
+  function update() {
+    const rect = section.getBoundingClientRect();
+    const viewH = window.innerHeight;
+
+    // Progress: 0 = section top at bottom of viewport, 1 = section bottom at top.
+    const progress = (viewH - rect.top) / (viewH + rect.height);
+    const clamped = Math.max(0, Math.min(1, progress));
+
+    // Apply only transform — compositor-only property.
+    el.style.transform = `translateY(${clamped * offset}px)`;
+    ticking = false;
+  }
+
+  window.addEventListener('scroll', () => {
+    if (!ticking) {
+      requestAnimationFrame(update);
+      ticking = true;
+    }
+  }, { passive: true });
+}
+```
+
+## React
+
+```tsx
+import { motion, useScroll, useTransform } from 'framer-motion';
+import { useRef } from 'react';
+
+function ParallaxSection({
+  children,
+  bgContent,
+  offset = -30,
+}: {
+  children: React.ReactNode;
+  bgContent: React.ReactNode;
+  offset?: number; // px; negative = against scroll direction
+}) {
+  const sectionRef = useRef<HTMLDivElement>(null);
+
+  const { scrollYProgress } = useScroll({
+    target: sectionRef,
+    offset: ['start end', 'end start'],
+  });
+
+  const y = useTransform(scrollYProgress, [0, 1], [0, offset]);
+
+  return (
+    <div ref={sectionRef} style={{ position: 'relative', overflow: 'hidden' }}>
+      {/* Background moves at a different rate */}
+      <motion.div
+        style={{
+          position: 'absolute',
+          inset: `${Math.abs(offset)}px 0`,
+          y,
+        }}
+        aria-hidden
+      >
+        {bgContent}
+      </motion.div>
+
+      {/* Foreground at normal scroll speed */}
+      <div style={{ position: 'relative' }}>
+        {children}
+      </div>
+    </div>
+  );
+}
+```
+
+## Reduced-motion variant
+
+In reduced-motion context, the parallax background is static — no scroll-linked
+movement. The section renders identically to a non-parallax section with a normal
+background image.
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  .parallax-bg {
+    animation: none;
+    transform: none;
+    /* Restore to full-bleed static background. */
+    inset: 0;
+  }
+}
+```
+
+The JS path must also check:
+
+```js
+const prefersReduced = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+if (!prefersReduced && !CSS.supports('animation-timeline', 'scroll()')) {
+  document.querySelectorAll('.parallax-bg').forEach(attachParallax);
+}
+```
+
+This is one of the few recipes where the reduced-motion variant genuinely improves the
+experience for a broader audience — not just the audience that has set the preference.
+As `core/theory/motion.md` notes, many users who experience vestibular discomfort from
+parallax have not discovered or set the `prefers-reduced-motion` preference. The
+restraint clause above (applying this recipe narrowly) is the stronger intervention.
+
+## Performance note
+
+The CSS scroll-driven path runs entirely off the main thread in Chromium. The element's
+layer is promoted by the animation; the scroll position update drives the transform
+without touching JavaScript. This is measurably lighter than the JS `requestAnimationFrame`
+path, which fires a callback, computes a value, and writes a style on every scroll frame.
+
+The JS path uses the `ticking` pattern to batch updates to one `requestAnimationFrame`
+per scroll event burst — standard debounce for scroll handlers. The `{ passive: true }`
+flag is required; without it the browser cannot optimise scroll performance.
+
+`will-change: transform` on the parallax element is applied implicitly by the scroll-
+driven animation and the Framer Motion `useTransform` hook. Do not add it manually on
+top; double promotion provides no benefit.
+
+Keep `--parallax-offset` small. A 30px offset over a full-viewport-height section
+produces a 3% depth differential — perceptible as depth without producing foreground-
+background collision. At 100px on a 400px-tall section, foreground and background
+visibly separate, causing the page to look broken rather than deep.

package/core/motion/recipes/scroll-reveal.md

@@ -0,0 +1,210 @@
+# Scroll reveal
+
+A scroll reveal makes content visible as it enters the viewport — opacity rising from
+zero, a small translate completing to zero — so that each section announces itself as
+the user scrolls toward it rather than sitting pre-exposed on a long static page.
+
+The implementation hierarchy is: CSS scroll-driven animations first (`animation-timeline:
+view()`), IntersectionObserver as the fallback for broader browser support. The static
+layout — what the page shows when no animation fires — must be complete and legible.
+
+## When it earns its place / When it does not
+
+Condition: the content is a scroll narrative — sections have a sequential logic, and the
+reveal of each section reinforces the order of reading. A portfolio case study where
+chapters arrive one by one, a product page where features emerge in the sequence the
+concept requires. The animation confirms what the layout already implies: read this, then
+this, then this.
+
+Condition against: product UI that the user came to operate. Navigation elements. Any
+content the user is scrolling to find — when the destination is below the fold and the
+user is scanning for it, a reveal that delays visibility is a usability failure dressed
+as an aesthetic choice. `expressive.md`: "A reveal that delays reading is a usability
+failure regardless of how well-timed it is." Also: `core/theory/motion.md` — entrance
+animations that replay on scroll turn scrolling into a performance the user must watch.
+Scroll-triggered reveal belongs on presentation pages, not on tools.
+
+## Parameters
+
+```css
+:root {
+  /* How far the element travels upward on entrance. 20–32px is the legible range;
+     larger values read as falling rather than arriving. */
+  --reveal-y: 28px;
+
+  /* Duration of the reveal animation. Slightly longer than a load entrance because
+     scroll-triggered context gives the user more time to process. 280–380ms. */
+  --duration-reveal: 340ms;
+
+  /* Easing from core/motion/easing.md. ease-out-quint for graceful arrival;
+     ease-out-expo for decisive arrival. */
+  --ease-reveal: var(--ease-out-quint);
+
+  /* For staggered groups (see stagger-orchestrator.md), this is the per-item delay. */
+  --stagger-reveal: 60ms;
+}
+```
+
+## Implementation
+
+```css
+/* ── CSS scroll-driven (preferred; Chromium 115+, Safari 18+) ─────────────── */
+
+.reveal {
+  animation: reveal-up var(--duration-reveal) var(--ease-reveal) both;
+  animation-timeline: view();
+  /* entry 0% = element starts entering viewport; 25% = comfortably inside. */
+  animation-range: entry 0% entry 25%;
+}
+
+@keyframes reveal-up {
+  from {
+    opacity: 0;
+    transform: translateY(var(--reveal-y));
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+/* ── IntersectionObserver fallback for browsers without scroll-driven support ── */
+/* Start hidden; JS adds .is-visible when the element intersects. */
+@supports not (animation-timeline: view()) {
+  .reveal {
+    opacity: 0;
+    transform: translateY(var(--reveal-y));
+    transition: opacity var(--duration-reveal) var(--ease-reveal),
+                transform var(--duration-reveal) var(--ease-reveal);
+  }
+
+  .reveal.is-visible {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+```
+
+```js
+// Only runs in browsers that lack scroll-driven animation support.
+if (!CSS.supports('animation-timeline', 'view()')) {
+  const observer = new IntersectionObserver(
+    (entries) => {
+      entries.forEach((entry) => {
+        if (entry.isIntersecting) {
+          entry.target.classList.add('is-visible');
+          // Reveal fires once. Unobserve after first intersection.
+          observer.unobserve(entry.target);
+        }
+      });
+    },
+    { threshold: 0.15 } // 15% of element visible triggers reveal
+  );
+
+  document.querySelectorAll('.reveal').forEach((el) => observer.observe(el));
+}
+```
+
+## React
+
+```tsx
+import { motion, useInView } from 'framer-motion';
+import { useRef } from 'react';
+
+const revealVariants = {
+  hidden: { opacity: 0, y: 28 },
+  visible: {
+    opacity: 1,
+    y: 0,
+    transition: {
+      duration: 0.34,
+      ease: [0.22, 1, 0.36, 1], // --ease-out-quint
+    },
+  },
+};
+
+function Reveal({ children, className }: { children: React.ReactNode; className?: string }) {
+  const ref = useRef<HTMLDivElement>(null);
+  // once: true — reveals fire once, not on every scroll pass.
+  const isInView = useInView(ref, { once: true, margin: '-10% 0px' });
+
+  return (
+    <motion.div
+      ref={ref}
+      className={className}
+      variants={revealVariants}
+      initial="hidden"
+      animate={isInView ? 'visible' : 'hidden'}
+    >
+      {children}
+    </motion.div>
+  );
+}
+
+// For staggered groups, wrap in a container with staggerChildren:
+const groupVariants = {
+  hidden: {},
+  visible: { transition: { staggerChildren: 0.06 } },
+};
+
+function RevealGroup({ children }: { children: React.ReactNode }) {
+  const ref = useRef<HTMLDivElement>(null);
+  const isInView = useInView(ref, { once: true, margin: '-10% 0px' });
+
+  return (
+    <motion.div
+      ref={ref}
+      variants={groupVariants}
+      initial="hidden"
+      animate={isInView ? 'visible' : 'hidden'}
+    >
+      {children}
+    </motion.div>
+  );
+}
+```
+
+## Reduced-motion variant
+
+The reduced-motion state must be a complete, legible layout — not an empty page waiting
+for JavaScript, not hidden content. In reduced-motion context, elements are visible from
+the start. No fade, no translate, no delay.
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  .reveal {
+    /* Override both the scroll-driven animation and the IO fallback. */
+    animation: none !important;
+    opacity: 1 !important;
+    transform: none !important;
+    transition: none !important;
+  }
+}
+```
+
+The IntersectionObserver JS should also check before adding opacity:
+
+```js
+const prefersReduced = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+if (!prefersReduced && !CSS.supports('animation-timeline', 'view()')) {
+  // ... observer setup
+}
+```
+
+## Performance note
+
+`animation-timeline: view()` runs off the main thread in Chromium — the browser's
+compositor advances the animation as scroll position changes, with no JavaScript
+involvement per frame. This is why it is preferred over IntersectionObserver: IO fires
+a JS callback, which schedules a style change, which runs on the main thread. Both are
+acceptable; the scroll-driven path is measurably lighter.
+
+Animate only `opacity` and `transform`. The `translateY` in `--reveal-y` is a
+composited property; it does not trigger layout. If you are tempted to reveal by changing
+`height`, `padding`, or `margin`, the answer is no — use `transform: scaleY()` from a
+`transform-origin: top` if a size change is genuinely required.
+
+Do not apply `will-change: transform` to every `.reveal` element on the page. On a page
+with twenty reveal elements, this promotes twenty compositor layers simultaneously and
+consumes GPU memory on mobile hardware. The browser promotes elements as needed during
+the animation; pre-promoting them does not help and costs memory.

package/core/motion/recipes/section-color-inversion.md

@@ -0,0 +1,217 @@
+# Section colour inversion
+
+A section colour inversion swaps the page's colour scheme — dark background to light,
+or light to dark — at a specific scroll threshold, marking a conceptual pivot in the
+content. The background and text colours switch together so the palette inverts as a
+unit rather than changing element by element.
+
+## When it earns its place / When it does not
+
+Condition: the scroll narrative has a turn — a moment where the register shifts to mark
+a conceptual pivot. The inversion must correspond to a narrative event: a before/after
+split, a transition from problem to solution, a shift from the user's world to the
+product's. The colour change makes the pivot felt as well as read. `expressive.md`:
+"The inversion makes the change visible and felt, not just read. One inversion per page
+is usually correct; more than one is a rhythm, not a pivot."
+
+Condition against: arbitrary decoration. Using two inversions because the page has three
+sections reads as a pattern, not a moment — the technique has been applied to a grid
+rather than a concept. Also: inversion without a corresponding narrative event is visual
+noise. If you cannot complete the sentence "This is where the page pivots from __ to __",
+the inversion does not belong.
+
+The cost: users who have accessibility settings that invert colours or use high-contrast
+modes will double-invert. Test in Windows High Contrast and macOS Invert Colours modes.
+
+## Parameters
+
+```css
+:root {
+  /* The two poles of the inversion. Board-sourced tokens — never raw hex here. */
+  --color-bg-light: var(--surface-primary);    /* light section background */
+  --color-text-light: var(--text-primary);     /* light section text */
+  --color-bg-dark: var(--surface-inverse);     /* dark section background */
+  --color-text-dark: var(--text-inverse);      /* dark section text */
+
+  /* Duration of the transition when the inversion fires.
+     Faster than a typical content transition — the switch should read as a cut,
+     not a dissolve. 200–280ms. */
+  --duration-invert: 240ms;
+  --ease-invert: var(--ease-out-quint);
+}
+```
+
+## Implementation
+
+The cleanest approach: a `data-theme` attribute on the section toggles between two
+CSS variable sets. One IntersectionObserver or scroll-driven animation flips the
+attribute. The body or a persistent header that spans sections must respond to the
+active section's theme.
+
+```html
+<section class="section" data-theme="light">
+  <!-- ... light section content ... -->
+</section>
+
+<section class="section" data-theme="dark">
+  <!-- ... pivot section — the narrative turn ... -->
+</section>
+
+<section class="section" data-theme="light">
+  <!-- ... resolution section ... -->
+</section>
+
+<!-- A persistent header tracks the active section's theme -->
+<header class="site-header" data-theme="light"></header>
+```
+
+```css
+/* Define both poles as CSS variable sets. */
+[data-theme="light"] {
+  --bg: var(--color-bg-light);
+  --text: var(--color-text-light);
+  --border: var(--color-border-light, rgba(0,0,0,0.08));
+}
+
+[data-theme="dark"] {
+  --bg: var(--color-bg-dark);
+  --text: var(--color-text-dark);
+  --border: var(--color-border-dark, rgba(255,255,255,0.12));
+}
+
+.section {
+  background-color: var(--bg);
+  color: var(--text);
+  /* Instant switch — no transition on section background itself. The transition
+     is on the header and any sticky element that spans sections. */
+}
+
+/* Optional: a very short opacity dip on direct section children softens the
+   colour inversion by briefly fading content as the palette switches. This is
+   a compositor-only property (opacity) — no layout cost. */
+.section > * {
+  transition: opacity var(--duration-invert) var(--ease-invert);
+}
+
+[data-theme] .section > * {
+  opacity: 1;
+}
+
+/* The sticky header transitions between themes smoothly. */
+.site-header {
+  position: sticky;
+  top: 0;
+  background-color: var(--bg);
+  color: var(--text);
+  transition:
+    background-color var(--duration-invert) var(--ease-invert),
+    color var(--duration-invert) var(--ease-invert);
+}
+```
+
+```js
+// Track which section is currently dominant in the viewport and update the header.
+function trackSectionThemes() {
+  const header = document.querySelector('.site-header');
+  if (!header) return;
+
+  const sections = document.querySelectorAll('.section[data-theme]');
+
+  const observer = new IntersectionObserver(
+    (entries) => {
+      entries.forEach((entry) => {
+        if (entry.isIntersecting && entry.intersectionRatio >= 0.5) {
+          const theme = entry.target.getAttribute('data-theme');
+          if (theme) header.setAttribute('data-theme', theme);
+        }
+      });
+    },
+    { threshold: 0.5 }
+  );
+
+  sections.forEach((s) => observer.observe(s));
+}
+
+document.addEventListener('DOMContentLoaded', trackSectionThemes);
+```
+
+## React
+
+```tsx
+import { useEffect, useRef, useState } from 'react';
+import { motion, AnimatePresence } from 'framer-motion';
+
+type Theme = 'light' | 'dark';
+
+function useActiveTheme(sections: React.RefObject<HTMLElement>[]) {
+  const [activeTheme, setActiveTheme] = useState<Theme>('light');
+
+  useEffect(() => {
+    const observer = new IntersectionObserver(
+      (entries) => {
+        entries.forEach((entry) => {
+          if (entry.isIntersecting && entry.intersectionRatio >= 0.5) {
+            const theme = (entry.target as HTMLElement).dataset.theme as Theme;
+            if (theme) setActiveTheme(theme);
+          }
+        });
+      },
+      { threshold: 0.5 }
+    );
+
+    sections.forEach((ref) => {
+      if (ref.current) observer.observe(ref.current);
+    });
+
+    return () => observer.disconnect();
+  }, [sections]);
+
+  return activeTheme;
+}
+
+function SiteHeader({ theme }: { theme: Theme }) {
+  return (
+    <motion.header
+      animate={{
+        backgroundColor: theme === 'dark' ? 'var(--color-bg-dark)' : 'var(--color-bg-light)',
+        color: theme === 'dark' ? 'var(--color-text-dark)' : 'var(--color-text-light)',
+      }}
+      transition={{ duration: 0.24, ease: [0.22, 1, 0.36, 1] }}
+      style={{ position: 'sticky', top: 0 }}
+    >
+      {/* header content */}
+    </motion.header>
+  );
+}
+```
+
+## Reduced-motion variant
+
+The sections retain their different background colours — the inversion is a layout
+choice, not purely a motion effect. The transition on the header is removed so the
+switch is instant rather than animated.
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  .site-header {
+    transition: none;
+  }
+}
+```
+
+The IntersectionObserver continues to run and update the `data-theme` attribute (correct
+behaviour — the sections genuinely have different themes). Only the animated transition
+is removed.
+
+## Performance note
+
+Background colour transitions on a sticky header trigger the paint step but not the
+layout step — the dimensions of the header do not change. On modern browsers this is
+GPU-composited for elements with `will-change: transform` already applied (a sticky
+element implicitly gets this in most implementations). The transition is not on
+`transform` or `opacity`, so it is not off-thread, but the paint cost for a single
+header background colour change is negligible.
+
+Do not animate `color` on large blocks of text — at scale this triggers text-specific
+paint operations on every frame. The inversion pattern here transitions only the header's
+colour; section backgrounds switch instantly (no transition on `.section` itself).