@3xhaust/oh-my-design 0.16.1

package/core/motion/recipes/marquee.md

@@ -0,0 +1,202 @@
+# Marquee
+
+A marquee scrolls a sequence of items continuously across the viewport — a brand phrase
+repeated, a list of client names, a scrolling ticker. The motion is constant and
+low-velocity; it creates peripheral activity that reinforces the concept without
+competing with primary content.
+
+## When it earns its place / When it does not
+
+Condition: the marquee carries a message that is part of the concept — a repeated claim
+whose repetition is the point ("Fast. Fast. Fast."), a rhythmic brand phrase, a roster
+of names whose accumulation communicates scale. The content loops because looping is
+meaningful, not because the list is too long for a static layout.
+
+Condition against: navigation areas and any context where the user is reading or
+interacting with nearby content. Peripheral motion competes with focal attention —
+`expressive.md`: "A marquee adjacent to a form field splits attention between peripheral
+motion and the focal task — vestibular disruption for users with motion sensitivity."
+Also: a marquee used because the designer ran out of content. If the marquee stops and
+the page still makes sense, the marquee was decoration. If the list it contains would
+fit in a single static row, it should be a static row.
+
+The technique has a ceiling: one marquee per page. Two marquees, especially running at
+different speeds or in opposite directions, produce a kinetic noise floor that
+undermines everything around it.
+
+## Parameters
+
+```css
+:root {
+  /* Time for one full loop at the content's natural width. Longer = slower.
+     A comfortable reading velocity: viewers can parse items at ~80px/s.
+     For a 1200px-wide content block: 1200 / 80 ≈ 15 seconds. */
+  --marquee-duration: 18s;
+
+  /* Gap between each item in the marquee track. */
+  --marquee-gap: 4rem;
+
+  /* Direction: normal = left to right; reverse = right to left. */
+  --marquee-direction: normal;
+
+  /* Pause on hover: enables on interactive marquees, disables on ambient ones. */
+  --marquee-play-state: running;
+}
+```
+
+## Implementation
+
+The technique: duplicate the content so the seam is never visible. The duplicate starts
+immediately after the first copy; when the first copy has scrolled fully off-screen, the
+duplicate has arrived at the start position and the loop is seamless.
+
+```html
+<div class="marquee" aria-hidden="true">
+  <div class="marquee-track">
+    <ul class="marquee-content" aria-label="Client roster">
+      <li>Acme</li>
+      <li>Globex</li>
+      <li>Initech</li>
+      <!-- … items … -->
+    </ul>
+    <!-- Duplicate for seamless loop. Aria-hidden on the duplicate. -->
+    <ul class="marquee-content" aria-hidden="true">
+      <li>Acme</li>
+      <li>Globex</li>
+      <li>Initech</li>
+    </ul>
+  </div>
+</div>
+```
+
+```css
+.marquee {
+  overflow: hidden;
+  white-space: nowrap;
+}
+
+.marquee-track {
+  display: flex;
+  width: max-content;
+  animation: marquee-scroll var(--marquee-duration) linear infinite;
+  animation-direction: var(--marquee-direction);
+  animation-play-state: var(--marquee-play-state);
+}
+
+/* Pause on hover (interactive marquees only — remove for ambient ones) */
+.marquee:hover .marquee-track {
+  animation-play-state: paused;
+}
+
+.marquee-content {
+  display: flex;
+  gap: var(--marquee-gap);
+  list-style: none;
+  padding: 0;
+  margin: 0;
+  /* Second copy immediately follows the first — no gap between copies needed
+     because the animation moves the entire track exactly one copy-width. */
+  padding-inline-end: var(--marquee-gap);
+}
+
+@keyframes marquee-scroll {
+  from { transform: translateX(0); }
+  to   { transform: translateX(-50%); }
+  /* -50%: moves the track by exactly one copy's width, bringing the duplicate
+     to the start position. The loop is seamless. */
+}
+```
+
+## React
+
+```tsx
+import { useRef } from 'react';
+import { motion } from 'framer-motion';
+
+function Marquee({
+  items,
+  duration = 18,
+  direction = 1, // 1 = left-to-right, -1 = right-to-left
+  pauseOnHover = false,
+}: {
+  items: string[];
+  duration?: number;
+  direction?: 1 | -1;
+  pauseOnHover?: boolean;
+}) {
+  const trackRef = useRef<HTMLDivElement>(null);
+
+  // Duplicate items for seamless loop.
+  const allItems = [...items, ...items];
+
+  return (
+    <div style={{ overflow: 'hidden', whiteSpace: 'nowrap' }}>
+      <motion.div
+        ref={trackRef}
+        style={{ display: 'flex', width: 'max-content' }}
+        animate={{ x: direction === 1 ? [0, '-50%'] : ['-50%', 0] }}
+        transition={{
+          duration,
+          ease: 'linear',
+          repeat: Infinity,
+          repeatType: 'loop',
+        }}
+        whileHover={pauseOnHover ? { animationPlayState: 'paused' } : undefined}
+      >
+        {allItems.map((item, i) => (
+          <span
+            key={i}
+            style={{ paddingInlineEnd: 'var(--marquee-gap, 4rem)' }}
+            aria-hidden={i >= items.length ? 'true' : undefined}
+          >
+            {item}
+          </span>
+        ))}
+      </motion.div>
+    </div>
+  );
+}
+```
+
+## Reduced-motion variant
+
+In reduced-motion context, the marquee must stop. A moving marquee for users with
+vestibular disorders can trigger nausea even at low velocity. The content is shown as a
+static, wrapped list — the information is preserved, the motion is removed.
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  .marquee-track {
+    animation: none;
+    width: auto;
+    flex-wrap: wrap;
+  }
+
+  /* Hide the duplicate copy — only needed for the loop illusion. */
+  .marquee-content:last-child {
+    display: none;
+  }
+
+  .marquee {
+    overflow: visible;
+    white-space: normal;
+  }
+}
+```
+
+## Performance note
+
+`transform: translateX()` is a compositor-only property — the browser moves the layer
+on the GPU without touching layout. The animation runs at 60fps on all reasonable
+hardware with no main-thread involvement.
+
+The `animation-duration` drives perceived velocity, not the actual pixel distance per
+frame. As items are added to the marquee, the content becomes wider; the same duration
+now produces a faster apparent motion (more pixels per second). Recalculate the duration
+when the content changes: `duration = contentWidth / targetPixelsPerSecond`. A JavaScript
+observer on the marquee-content can handle this dynamically.
+
+Do not use `marquee-gap` so large that the duplicate's arrival is visible before the
+original departs — there should be no visible gap between copies at the seam. The
+`padding-inline-end` on `.marquee-content` absorbs this gap, but verify on your actual
+content widths.

package/core/motion/recipes/number-counter.md

@@ -0,0 +1,242 @@
+# Number counter
+
+A number counter animates a numeric value from a starting point to its final value —
+`0 → 4,200` or `12% → 98%` — when the element enters the viewport. The motion is
+eased so the count accelerates at first and decelerates as it approaches the target,
+reading as accumulation rather than mechanical increment.
+
+## When it earns its place / When it does not
+
+Condition: a stat whose magnitude is the point — the scale of a number communicates
+something the number alone at rest does not. "4,200 customers" has more weight arriving
+from zero than landing at rest. The counter is appropriate when the count duration
+aligns with reading speed: the user sees the number rising and understands its scale
+before it settles.
+
+Condition against: tables, data grids, or any context where numbers change due to
+user interaction or live data. Animating numbers that the user is trying to read or
+compare makes reading impossible. Also: very small numbers — `0 → 5` counts through
+all six values visibly; this reads as a spinner rather than an accumulation. Use a
+simple fade-in for numbers under 10. Also: numbers that update repeatedly — a live
+dashboard counter that re-animates on each update is a usability failure.
+
+The counter must complete quickly enough that the user does not wait for it: 600–1000ms
+is the legible range. Beyond 1000ms the user has moved on and the animation resolves
+for no one.
+
+## Parameters
+
+```css
+:root {
+  /* Total duration of the count animation. */
+  --counter-duration: 800ms;
+
+  /* The easing is applied to the animation progress, not to a CSS property.
+     Described here for documentation; actual implementation is in JS via a
+     cubic-bezier computation over the progress value. */
+  --counter-ease: ease-out-quint; /* see easing.md for the cubic-bezier values */
+
+  /* Optional: hold before counting starts (e.g., after the element fades in). */
+  --counter-delay: 80ms;
+}
+```
+
+## Implementation
+
+```html
+<div class="stat-block">
+  <span class="counter" data-target="4200" data-prefix="" data-suffix=" customers">0</span>
+</div>
+```
+
+```css
+/* The counter fades in as counting begins. The value animation is JS-driven
+   (requestAnimationFrame), but the entrance uses opacity — a compositor-only
+   property — so both axes animate without touching layout. */
+.counter {
+  font-variant-numeric: tabular-nums;
+  opacity: 0;
+  transition: opacity 180ms var(--ease-out-quint, ease-out);
+}
+
+.counter.is-counting {
+  opacity: 1;
+}
+```
+
+```js
+// Easing function: ease-out-quint approximation over [0..1].
+// Equivalent to --ease-out-quint: cubic-bezier(0.22, 1, 0.36, 1).
+function easeOutQuint(t) {
+  return 1 - Math.pow(1 - t, 5);
+}
+
+function animateCounter(el) {
+  const target = parseFloat(el.dataset.target ?? '0');
+  const prefix = el.dataset.prefix ?? '';
+  const suffix = el.dataset.suffix ?? '';
+  const start = parseFloat(el.dataset.from ?? '0');
+  const duration = parseFloat(
+    getComputedStyle(document.documentElement).getPropertyValue('--counter-duration')
+  ) || 800;
+  const delay = parseFloat(
+    getComputedStyle(document.documentElement).getPropertyValue('--counter-delay')
+  ) || 0;
+
+  // Format numbers with locale-aware separators.
+  function format(n) {
+    return prefix + Math.round(n).toLocaleString() + suffix;
+  }
+
+  // Fade in as counting begins.
+  el.classList.add('is-counting');
+
+  let startTime = null;
+
+  function frame(now) {
+    if (!startTime) startTime = now + delay;
+    const elapsed = Math.max(0, now - startTime);
+    const progress = Math.min(1, elapsed / duration);
+    const eased = easeOutQuint(progress);
+    el.textContent = format(start + (target - start) * eased);
+
+    if (progress < 1) {
+      requestAnimationFrame(frame);
+    } else {
+      el.textContent = format(target); // ensure exact final value
+    }
+  }
+
+  requestAnimationFrame(frame);
+}
+
+// Trigger on intersection — count fires once when the stat enters the viewport.
+const observer = new IntersectionObserver(
+  (entries) => {
+    entries.forEach((entry) => {
+      if (entry.isIntersecting) {
+        animateCounter(entry.target);
+        observer.unobserve(entry.target);
+      }
+    });
+  },
+  { threshold: 0.5 }
+);
+
+document.querySelectorAll('.counter').forEach((el) => observer.observe(el));
+```
+
+## React
+
+```tsx
+import { useEffect, useRef, useState } from 'react';
+import { useInView } from 'framer-motion';
+
+function easeOutQuint(t: number) {
+  return 1 - Math.pow(1 - t, 5);
+}
+
+function useCounter(target: number, duration = 800, enabled = true) {
+  const [value, setValue] = useState(0);
+
+  useEffect(() => {
+    if (!enabled) {
+      setValue(target);
+      return;
+    }
+
+    let startTime: number | null = null;
+    let rafId: number;
+
+    function frame(now: number) {
+      if (!startTime) startTime = now;
+      const progress = Math.min(1, (now - startTime) / duration);
+      setValue(Math.round(target * easeOutQuint(progress)));
+      if (progress < 1) {
+        rafId = requestAnimationFrame(frame);
+      } else {
+        setValue(target);
+      }
+    }
+
+    rafId = requestAnimationFrame(frame);
+    return () => cancelAnimationFrame(rafId);
+  }, [target, duration, enabled]);
+
+  return value;
+}
+
+function StatCounter({
+  target,
+  prefix = '',
+  suffix = '',
+  duration = 800,
+}: {
+  target: number;
+  prefix?: string;
+  suffix?: string;
+  duration?: number;
+}) {
+  const ref = useRef<HTMLSpanElement>(null);
+  const isInView = useInView(ref, { once: true, margin: '-20% 0px' });
+  const value = useCounter(target, duration, isInView);
+
+  return (
+    <span ref={ref} style={{ fontVariantNumeric: 'tabular-nums' }}>
+      {prefix}{value.toLocaleString()}{suffix}
+    </span>
+  );
+}
+```
+
+## Reduced-motion variant
+
+In reduced-motion context, the final number is shown immediately — no counting
+animation. The value is present and readable from the moment the element enters
+the viewport.
+
+```css
+/* No CSS to add — the counter is entirely JS-driven.
+   The JS check below handles the reduced-motion case. */
+```
+
+```js
+const prefersReduced = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+
+if (prefersReduced) {
+  // Show final values immediately without animation.
+  document.querySelectorAll('.counter').forEach((el) => {
+    const target = el.dataset.target ?? '0';
+    const prefix = el.dataset.prefix ?? '';
+    const suffix = el.dataset.suffix ?? '';
+    el.textContent = prefix + parseFloat(target).toLocaleString() + suffix;
+  });
+} else {
+  // ... observer setup
+}
+```
+
+In the React hook, `useCounter` already accepts an `enabled` flag — pass `false` when
+`prefers-reduced-motion` is active:
+
+```tsx
+const prefersReduced = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+const value = useCounter(target, duration, isInView && !prefersReduced);
+```
+
+## Performance note
+
+`requestAnimationFrame` is the correct animation driver for JS-computed value changes —
+it aligns updates to the browser's paint schedule and is automatically throttled on
+background tabs. Do not use `setInterval` for counter animation; it runs off the paint
+schedule and produces visible frame drops.
+
+The counter updates `textContent` — a DOM write — on every frame. This triggers a
+text-specific paint on the element but not a layout reflow, provided the element's
+dimensions are stable. `font-variant-numeric: tabular-nums` is required for this:
+proportional numerals change width on each digit change, triggering layout reflow on
+every frame. Tabular numerals are fixed-width; the element's width is constant.
+
+For multiple counters on one page, each runs its own `requestAnimationFrame` loop.
+The browser batches these into one paint per frame; there is no penalty for multiple
+concurrent loops.

package/core/motion/recipes/page-loader.md

@@ -0,0 +1,240 @@
+# Page loader
+
+A page loader covers the initial render while assets load, then exits — revealing the
+page underneath as an entrance rather than a progressive paint. It is the opening
+sentence of the experience: the palette commits, the type register declares itself, the
+motion vocabulary introduces itself. Done well, the loader adds nothing to the perceived
+wait time; done badly, it is the first thing the user resents.
+
+## When it earns its place / When it does not
+
+Condition: a showpiece page where the entrance is part of the experience — a campaign
+microsite, an agency portfolio, a product launch with a single CTA. The loader must do
+something with its time: commit the palette, reveal the type register, establish that
+this is not a default page. `expressive.md`: "What the entrance must do in those
+seconds: commit the palette, declare the type register, establish the motion vocabulary.
+A loader that is only a spinner followed by a page reveal has wasted the three seconds
+it consumed."
+
+Condition against: product UI, tools, documentation, any page the user came to operate
+rather than experience. A dashboard that holds the user behind a loader for 300ms on
+every visit is spending attention budget the user did not agree to spend. Also: any page
+where asset load time is variable and potentially fast — a loader on a sub-100ms page
+load adds the only delay the user experiences.
+
+The hard rule: the loader must exit no later than 300ms after the `load` event fires.
+`expressive.md` and `core/theory/motion.md` both state the outer bound: three seconds
+total, under one second as the performance target. A loader that runs independent of
+asset load time — a fixed-duration animation that plays regardless — is spending the
+user's attention against an arbitrary clock. Tie the exit to the `load` event with a
+minimum hold of 300ms (so the entrance reads as intentional, not as a flash) and a
+maximum of 3000ms (absolute outer bound).
+
+## Parameters
+
+```css
+:root {
+  /* Minimum time the loader holds even if the page loads faster.
+     Below this, the loader reads as a flash rather than an entrance. */
+  --loader-hold-min: 300ms;
+
+  /* Maximum time before the loader forces exit regardless of load state. */
+  --loader-hold-max: 2400ms;
+
+  /* Duration of the loader's exit animation. */
+  --loader-exit-duration: 480ms;
+
+  /* Easing for the exit. ease-in reads as deliberate departure. */
+  --loader-exit-ease: var(--ease-in-expo);
+
+  /* Duration for the page's entrance after the loader exits. */
+  --loader-page-enter-duration: 360ms;
+  --loader-page-enter-ease: var(--ease-out-quint);
+}
+```
+
+## Implementation
+
+```html
+<!-- Loader sits above the page content. -->
+<div class="page-loader" id="loader" aria-live="polite" aria-label="Loading">
+  <div class="loader-inner">
+    <!-- Commit the brand: a logotype, a single word, a colour field.
+         Not a spinner — a statement. -->
+    <span class="loader-wordmark">Studio</span>
+  </div>
+</div>
+
+<main class="page-content" id="page" style="opacity: 0;">
+  <!-- page content -->
+</main>
+```
+
+```css
+.page-loader {
+  position: fixed;
+  inset: 0;
+  z-index: 1000;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background-color: var(--color-bg-dark, #0a0a0a);
+  color: var(--color-text-dark, #fff);
+}
+
+.page-loader.is-exiting {
+  animation: loader-exit var(--loader-exit-duration) var(--loader-exit-ease) forwards;
+}
+
+@keyframes loader-exit {
+  to {
+    opacity: 0;
+    /* Slide up or clip — choose one and wire it to the concept. */
+    transform: translateY(-100%);
+  }
+}
+
+.page-content {
+  transition: opacity var(--loader-page-enter-duration) var(--loader-page-enter-ease);
+}
+
+.page-content.is-visible {
+  opacity: 1;
+}
+```
+
+```js
+(function () {
+  const loader = document.getElementById('loader');
+  const page = document.getElementById('page');
+  if (!loader || !page) return;
+
+  // Read token values from :root.
+  const root = document.documentElement;
+  const minHold = parseFloat(getComputedStyle(root).getPropertyValue('--loader-hold-min')) || 300;
+  const maxHold = parseFloat(getComputedStyle(root).getPropertyValue('--loader-hold-max')) || 2400;
+  const exitDuration = parseFloat(getComputedStyle(root).getPropertyValue('--loader-exit-duration')) || 480;
+
+  let loadFired = false;
+  let startTime = Date.now();
+
+  function exit() {
+    loader.classList.add('is-exiting');
+    loader.setAttribute('aria-hidden', 'true');
+    page.classList.add('is-visible');
+    setTimeout(() => loader.remove(), exitDuration);
+  }
+
+  function maybeExit() {
+    const elapsed = Date.now() - startTime;
+    const remaining = Math.max(0, minHold - elapsed);
+    setTimeout(exit, remaining);
+  }
+
+  // Absolute outer bound — never hold longer than --loader-hold-max.
+  const maxTimer = setTimeout(exit, maxHold);
+
+  window.addEventListener('load', () => {
+    clearTimeout(maxTimer);
+    maybeExit();
+  });
+})();
+```
+
+## React
+
+```tsx
+import { motion, AnimatePresence } from 'framer-motion';
+import { useState, useEffect } from 'react';
+
+function PageLoader({ minHold = 300 }: { minHold?: number }) {
+  const [visible, setVisible] = useState(true);
+
+  useEffect(() => {
+    const start = Date.now();
+
+    function handleLoad() {
+      const elapsed = Date.now() - start;
+      const delay = Math.max(0, minHold - elapsed);
+      setTimeout(() => setVisible(false), delay);
+    }
+
+    if (document.readyState === 'complete') {
+      handleLoad();
+    } else {
+      window.addEventListener('load', handleLoad, { once: true });
+    }
+
+    // Absolute maximum — never hold beyond 2.4s
+    const timeout = setTimeout(() => setVisible(false), 2400);
+    return () => clearTimeout(timeout);
+  }, [minHold]);
+
+  return (
+    <AnimatePresence>
+      {visible && (
+        <motion.div
+          key="loader"
+          style={{ position: 'fixed', inset: 0, zIndex: 1000,
+                   display: 'flex', alignItems: 'center', justifyContent: 'center',
+                   backgroundColor: 'var(--color-bg-dark)' }}
+          exit={{
+            opacity: 0,
+            y: '-100%',
+            transition: { duration: 0.48, ease: [0.7, 0, 0.84, 0] }, // ease-in-expo
+          }}
+          aria-label="Loading"
+          role="status"
+        >
+          <span style={{ color: 'var(--color-text-dark)' }}>Studio</span>
+        </motion.div>
+      )}
+    </AnimatePresence>
+  );
+}
+```
+
+## Reduced-motion variant
+
+In reduced-motion context, the loader exits immediately without an animated transition.
+The page is visible from the start — no hold, no entrance animation.
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  .page-loader {
+    display: none;
+  }
+
+  .page-content {
+    opacity: 1;
+    transition: none;
+  }
+}
+```
+
+In the JS, check before adding any classes:
+
+```js
+const prefersReduced = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+if (prefersReduced) {
+  loader.remove();
+  page.style.opacity = '1';
+  return; // skip the entire loader
+}
+```
+
+## Performance note
+
+The loader is `position: fixed`, covering the entire viewport. While it is visible, the
+content beneath it does not need to paint — the browser can defer content paint until
+the loader exits. In practice this is a performance advantage: the actual page content
+renders in parallel with the loader's animation and is ready when the loader clears.
+
+The exit animation uses `transform: translateY(-100%)` and `opacity` — both compositor
+properties. The loader exits smoothly even if the main thread is busy parsing content
+beneath it.
+
+Remove the loader element from the DOM (`loader.remove()`) after the exit transition
+completes. A `position: fixed; z-index: 1000` element left in the DOM blocks pointer
+events on the content below it even when visually transparent, which produces
+interactions that appear broken without any visible explanation.