dreative 0.1.0 → 0.2.0

package/skill/dreative/skills/interaction.md

@@ -1,126 +1,129 @@
-# Dreative Specialist Skill — Micro-interactions & Effect Craft
-
-Load this file when `plan.skills` includes `interaction`, or the brief/prompt asks
-for hover effects, cursor work, tilt, glow, "make it feel alive/tactile/premium".
-It EXTENDS DESIGN.md §6/§9/§10 — every ban there still stands (no hover-scale on
-`<img>`, custom cursors only on explicit request, one marquee max). This skill is
-about the last 5% of feel: small, physical, consistent responses to input.
-
-## 0. The feel system
-
-Micro-interactions are a SYSTEM, not garnish. Before adding any, fix three global
-constants and apply them everywhere: one hover response vocabulary, one press
-response, one focus style. A page where every card hovers differently reads as
-assembled, not designed.
-
-- **Press** (all clickables): `active:scale-[0.98]` (buttons) or
-  `active:scale-[0.99]` (large cards) + 100ms ease-out. This single rule adds more
-  perceived quality per byte than anything else in this file.
-- **Hover** (pick ONE per element class): background tint shift, border-color
-  lift, shadow deepen (tinted to bg hue), or underline draw. 150-200ms.
-- **Focus**: `:focus-visible` ring, 2px, offset 2px, accent color — identical on
-  every interactive element, never removed.
-- Everything targets the 80ms "feels instant" threshold for input feedback.
-
-## 1. Pointer-tracking effects (the premium tier)
-
-All pointer tracking is springs/damping (Motion `useSpring` on `useMotionValue`,
-or lerp in rAF: `x += (target - x) * 0.12`) — raw 1:1 tracking feels robotic.
-Desktop-only: gate behind `@media (hover: hover) and (pointer: fine)`; touch gets
-the static design, not a broken half-effect. All of these are decoration — cap at
-1-2 distinct pointer effects per page, on the signature element's territory.
-
-- **Magnetic elements**: on pointer-move within a proximity zone, translate the
-  element toward the cursor at 15-25% of offset (buttons) with the LABEL moving
-  a further ~10% for parallax depth; spring back on leave
-  (`stiffness 150, damping 15`). Reserve for 1-2 primary CTAs or nav items.
-- **Spotlight cards**: radial-gradient that follows the pointer —
-  `background: radial-gradient(240px circle at var(--x) var(--y),
-  <accent 6-10% alpha>, transparent 65%)` on an overlay div; update CSS vars in
-  rAF. For grids, track on the CONTAINER and light borders of all cards from one
-  listener (the Aceternity/Linear look). Alpha ≤ 0.1; visible-but-subtle.
-- **3D tilt**: perspective 800-1000px, max tilt 4-8° (10°+ is 2015 flash),
-  computed from pointer offset to card center, damped; add a moving specular
-  `linear-gradient` highlight at low alpha for material realism. Cards with text:
-  ≤ 5° or readability suffers.
-- **Image distortion / lens effects** need WebGL — that's `skills/3d.md` §4
-  territory; don't fake them with CSS filters.
-
-## 2. Hover reveals and state morphs
-
-- **Underline draw**: `background-image: linear-gradient(accent, accent)` sized
-  `0% 1.5px → 100% 1.5px` on hover, 250ms expo-out, origin left. The correct link
-  hover for editorial registers.
-- **Text swap/scramble**: label slides up revealing a duplicate from below
-  (wrap in `overflow-hidden`, translateY both spans). Scramble/decode effects
-  only on dark-tech/playful briefs, ≤ 600ms, never on body copy.
-- **Card reveals**: secondary info (arrow, meta row, CTA) slides/fades in ON TOP
-  of a stable layout — the card must never change size on hover (layout shift =
-  amateur tell). Arrows translate 2-4px on hover (`group-hover:translate-x-1`),
-  they don't appear from nothing.
-- **Icon morphs**: hamburger↔close, play↔pause as two-path SVG morphs or rotated
-  strokes, 200ms. Icons that rotate/bounce on every hover = noise; icons respond
-  only when the response means something (chevron rotates because the section
-  opened).
-- Checkbox/toggle/radio: hand-styled with an SVG check that draws in
-  (`stroke-dashoffset` 200ms) — the native-looking-but-smoother tier. Toggles
-  slide with a spring, thumb squashes slightly at rest ends.
-
-## 3. Surface effects (no pointer needed)
-
-- **Glow borders**: `conic-gradient` rotating behind a masked 1px border
-  (`@property --angle` + animation, or padding-box/border-box double background).
-  One element per page, dark surfaces only, accent-hued — this is a signature
-  move, not a card default.
-- **Border beam / tracer**: an accent segment orbiting a card border via
-  `offset-path: border-box` (or rect()) — same rationing as glow.
-- **Gradient shift**: oversized `background-size: 200%` + position animation on
-  a CTA, ≤ 2 hues from the palette. Never on text (gradient text is banned).
-- **Noise/grain**: a tiled 128px PNG/data-URI at 2-4% opacity as a fixed overlay
-  can kill flat-gradient banding on brand pages; `feTurbulence` inline SVG is
-  banned (DESIGN.md §7) — use a pre-baked texture.
-- **Blend modes**: `mix-blend-mode: difference` for text crossing light/dark
-  boundaries (fixed nav over sections); `multiply/screen` to sit imagery into
-  tinted surfaces. Test in both themes; blend modes are the #1 source of
-  invisible-text bugs.
-- Shadows that feel physical: 2-3 stacked layers, tinted to the background hue,
-  y-offset ≈ blur/2 (`0 1px 2px, 0 4px 8px, 0 16px 32px` at descending alpha).
-  One elevation scale page-wide.
-
-## 4. Scroll-adjacent feel
-
-(Choreography lives in `skills/motion.md`; these are ambient behaviors.)
-
-- **Sticky nav transform**: past ~80px scroll, nav gains blur backdrop
-  (`backdrop-blur-md` + bg at 70-85% alpha + hairline border-b), height eases
-  72→60px. Drive from IntersectionObserver on a sentinel, not scroll position.
-- **Scroll progress**: thin accent bar (2px) via `scroll-timeline` /
-  `animation-timeline: scroll()`, CSS-only. Long-form articles only.
-- **Hide-on-scroll-down nav**: product register only, translate ±100% with 300ms
-  ease, 8px hysteresis so it doesn't flicker.
-
-## 5. Feedback micro-moments (product register)
-
-- Button loading: label crossfades to spinner INSIDE the button at fixed width
-  (measure or `min-w`), never a layout jump; success flashes a check 600ms before
-  reverting.
-- Copy-to-clipboard: icon morphs to check + 1.2s revert; optional 150ms
-  background pulse. No toast for copy.
-- Form errors: input border→error color + one 4px x-axis shake (3 oscillations,
-  250ms total, reduced-motion: none) + message fades in below. Shake ONCE per
-  submit, never loop.
-- Optimistic toggles (likes, stars): fill instantly with a 1→1.2→1 spring pop on
-  the icon; reconcile silently on failure with an inline note.
-- Skeletons: shaped like the real layout, shimmer via one masked gradient sweep
-  (1.4s linear infinite), same radius system as the content it becomes.
-
-## 6. Guardrails
-
-- Decorative pointer effects: max 1-2 distinct kinds per page, desktop-only,
-  `prefers-reduced-motion` disables tracking (element stays styled, static).
-- Nothing in this file may cause layout shift, block scrolling, steal focus, or
-  attach a raw `scroll`/`mousemove` listener without rAF batching + cleanup.
-- Every effect must survive keyboard use: whatever hover reveals, focus reveals.
-- Effects use palette tokens (accent/neutral), never introduce new hues.
-- If an effect can't be justified in one sentence of communication value
-  (affordance, state, hierarchy, brand voice), it's noise — cut it (DESIGN.md §6).
+# Dreative Specialist Skill — Micro-interactions & Effect Craft
+
+Load this file when `plan.skills` includes `interaction`, or the brief/prompt asks
+for hover effects, cursor work, tilt, glow, "make it feel alive/tactile/premium".
+It EXTENDS DESIGN.md §6/§9/§10 — every ban there still stands (no hover-scale on
+`<img>`, custom cursors only on explicit request, one marquee max). This skill is
+about the last 5% of feel: small, physical, consistent responses to input.
+If an effect needs different markup (wrappers, layers, split spans), follow
+DESIGN.md §11's transformation-depth ladder — offer the restructure and, once
+confirmed, change the structure rather than approximating the effect in CSS.
+
+## 0. The feel system
+
+Micro-interactions are a SYSTEM, not garnish. Before adding any, fix three global
+constants and apply them everywhere: one hover response vocabulary, one press
+response, one focus style. A page where every card hovers differently reads as
+assembled, not designed.
+
+- **Press** (all clickables): `active:scale-[0.98]` (buttons) or
+  `active:scale-[0.99]` (large cards) + 100ms ease-out. This single rule adds more
+  perceived quality per byte than anything else in this file.
+- **Hover** (pick ONE per element class): background tint shift, border-color
+  lift, shadow deepen (tinted to bg hue), or underline draw. 150-200ms.
+- **Focus**: `:focus-visible` ring, 2px, offset 2px, accent color — identical on
+  every interactive element, never removed.
+- Everything targets the 80ms "feels instant" threshold for input feedback.
+
+## 1. Pointer-tracking effects (the premium tier)
+
+All pointer tracking is springs/damping (Motion `useSpring` on `useMotionValue`,
+or lerp in rAF: `x += (target - x) * 0.12`) — raw 1:1 tracking feels robotic.
+Desktop-only: gate behind `@media (hover: hover) and (pointer: fine)`; touch gets
+the static design, not a broken half-effect. All of these are decoration — cap at
+1-2 distinct pointer effects per page, on the signature element's territory.
+
+- **Magnetic elements**: on pointer-move within a proximity zone, translate the
+  element toward the cursor at 15-25% of offset (buttons) with the LABEL moving
+  a further ~10% for parallax depth; spring back on leave
+  (`stiffness 150, damping 15`). Reserve for 1-2 primary CTAs or nav items.
+- **Spotlight cards**: radial-gradient that follows the pointer —
+  `background: radial-gradient(240px circle at var(--x) var(--y),
+  <accent 6-10% alpha>, transparent 65%)` on an overlay div; update CSS vars in
+  rAF. For grids, track on the CONTAINER and light borders of all cards from one
+  listener (the Aceternity/Linear look). Alpha ≤ 0.1; visible-but-subtle.
+- **3D tilt**: perspective 800-1000px, max tilt 4-8° (10°+ is 2015 flash),
+  computed from pointer offset to card center, damped; add a moving specular
+  `linear-gradient` highlight at low alpha for material realism. Cards with text:
+  ≤ 5° or readability suffers.
+- **Image distortion / lens effects** need WebGL — that's `skills/3d.md` §4
+  territory; don't fake them with CSS filters.
+
+## 2. Hover reveals and state morphs
+
+- **Underline draw**: `background-image: linear-gradient(accent, accent)` sized
+  `0% 1.5px → 100% 1.5px` on hover, 250ms expo-out, origin left. The correct link
+  hover for editorial registers.
+- **Text swap/scramble**: label slides up revealing a duplicate from below
+  (wrap in `overflow-hidden`, translateY both spans). Scramble/decode effects
+  only on dark-tech/playful briefs, ≤ 600ms, never on body copy.
+- **Card reveals**: secondary info (arrow, meta row, CTA) slides/fades in ON TOP
+  of a stable layout — the card must never change size on hover (layout shift =
+  amateur tell). Arrows translate 2-4px on hover (`group-hover:translate-x-1`),
+  they don't appear from nothing.
+- **Icon morphs**: hamburger↔close, play↔pause as two-path SVG morphs or rotated
+  strokes, 200ms. Icons that rotate/bounce on every hover = noise; icons respond
+  only when the response means something (chevron rotates because the section
+  opened).
+- Checkbox/toggle/radio: hand-styled with an SVG check that draws in
+  (`stroke-dashoffset` 200ms) — the native-looking-but-smoother tier. Toggles
+  slide with a spring, thumb squashes slightly at rest ends.
+
+## 3. Surface effects (no pointer needed)
+
+- **Glow borders**: `conic-gradient` rotating behind a masked 1px border
+  (`@property --angle` + animation, or padding-box/border-box double background).
+  One element per page, dark surfaces only, accent-hued — this is a signature
+  move, not a card default.
+- **Border beam / tracer**: an accent segment orbiting a card border via
+  `offset-path: border-box` (or rect()) — same rationing as glow.
+- **Gradient shift**: oversized `background-size: 200%` + position animation on
+  a CTA, ≤ 2 hues from the palette. Never on text (gradient text is banned).
+- **Noise/grain**: a tiled 128px PNG/data-URI at 2-4% opacity as a fixed overlay
+  can kill flat-gradient banding on brand pages; `feTurbulence` inline SVG is
+  banned (DESIGN.md §7) — use a pre-baked texture.
+- **Blend modes**: `mix-blend-mode: difference` for text crossing light/dark
+  boundaries (fixed nav over sections); `multiply/screen` to sit imagery into
+  tinted surfaces. Test in both themes; blend modes are the #1 source of
+  invisible-text bugs.
+- Shadows that feel physical: 2-3 stacked layers, tinted to the background hue,
+  y-offset ≈ blur/2 (`0 1px 2px, 0 4px 8px, 0 16px 32px` at descending alpha).
+  One elevation scale page-wide.
+
+## 4. Scroll-adjacent feel
+
+(Choreography lives in `skills/motion.md`; these are ambient behaviors.)
+
+- **Sticky nav transform**: past ~80px scroll, nav gains blur backdrop
+  (`backdrop-blur-md` + bg at 70-85% alpha + hairline border-b), height eases
+  72→60px. Drive from IntersectionObserver on a sentinel, not scroll position.
+- **Scroll progress**: thin accent bar (2px) via `scroll-timeline` /
+  `animation-timeline: scroll()`, CSS-only. Long-form articles only.
+- **Hide-on-scroll-down nav**: product register only, translate ±100% with 300ms
+  ease, 8px hysteresis so it doesn't flicker.
+
+## 5. Feedback micro-moments (product register)
+
+- Button loading: label crossfades to spinner INSIDE the button at fixed width
+  (measure or `min-w`), never a layout jump; success flashes a check 600ms before
+  reverting.
+- Copy-to-clipboard: icon morphs to check + 1.2s revert; optional 150ms
+  background pulse. No toast for copy.
+- Form errors: input border→error color + one 4px x-axis shake (3 oscillations,
+  250ms total, reduced-motion: none) + message fades in below. Shake ONCE per
+  submit, never loop.
+- Optimistic toggles (likes, stars): fill instantly with a 1→1.2→1 spring pop on
+  the icon; reconcile silently on failure with an inline note.
+- Skeletons: shaped like the real layout, shimmer via one masked gradient sweep
+  (1.4s linear infinite), same radius system as the content it becomes.
+
+## 6. Guardrails
+
+- Decorative pointer effects: max 1-2 distinct kinds per page, desktop-only,
+  `prefers-reduced-motion` disables tracking (element stays styled, static).
+- Nothing in this file may cause layout shift, block scrolling, steal focus, or
+  attach a raw `scroll`/`mousemove` listener without rAF batching + cleanup.
+- Every effect must survive keyboard use: whatever hover reveals, focus reveals.
+- Effects use palette tokens (accent/neutral), never introduce new hues.
+- If an effect can't be justified in one sentence of communication value
+  (affordance, state, hierarchy, brand voice), it's noise — cut it (DESIGN.md §6).

package/skill/dreative/skills/motion.md

@@ -1,125 +1,137 @@
-# Dreative Specialist Skill — Motion & Scroll Choreography
-
-Load this file when `plan.skills` includes `motion`, or the brief/prompt asks for
-animation, parallax, scroll storytelling, kinetic type, or "cinematic" feel.
-It EXTENDS DESIGN.md §6 (which still applies: 100/300/500 durations, ease-out
-exponential curves, reduced-motion fallbacks, no scroll listeners, no bounce).
-This file is about doing ambitious motion WELL, not about adding more of it.
-
-## 0. Pick the tool by the job, not by habit
-
-- **CSS only** — hover/focus/press states, one-shot entrances, marquees, simple
-  scroll reveals via `animation-timeline: view()`. Zero JS cost; always first choice.
-- **Motion (`motion/react`, formerly Framer Motion)** — React apps: presence
-  (`AnimatePresence`), layout animation (`layout` prop = free FLIP), springs,
-  `whileInView`, gesture props. The default for React product+brand pages.
-- **GSAP + ScrollTrigger** — timeline choreography: multiple elements coordinated
-  over one scroll range, scrubbed sequences, pinned sections, kinetic type.
-  Use when a Motion version would need 4+ manually-synced `useScroll` hooks.
-- **Lenis** — smooth scroll wrapper for scroll-driven brand pages. Only on brand
-  register with motion dial ≥7; never in product UI. Sync ScrollTrigger with
-  `lenis.on('scroll', ScrollTrigger.update)`.
-
-One animation system per page. Motion AND GSAP on the same page = two spring
-vocabularies fighting; pick one and commit.
-
-## 1. Springs beat durations for anything interactive
-
-Duration+easing is for one-shot choreography (entrances, exits). Anything that
-tracks input or can be interrupted (drag, hover follow, toggles, layout shifts)
-uses springs — they redirect mid-flight without a visible restart.
-
-- Motion defaults: `{ type: "spring", stiffness: 300, damping: 30 }` = snappy UI;
-  `stiffness: 120, damping: 20` = soft brand movement. Overshoot (`damping < 15`)
-  only on playful briefs, and only on small elements — never on layout.
-- `visualDuration` (Motion ≥11.13) sets spring feel by time: easier to reason about.
-- Never spring opacity or color; springs are for transform. Crossfade those.
-
-## 2. Orchestration: one timeline, one story
-
-The scattered-reveals look (every section fades up independently) is the #1 motion
-tell. Instead:
-
-- **Hero entrance** = ONE composed sequence: parent `staggerChildren: 0.08`,
-  `delayChildren` after nav settles; elements enter in reading order; total ≤ 900ms.
-  Nothing else on the page gets entrance choreography.
-- **Below the fold**: at most 2-3 sections get `whileInView` reveals (`once: true`,
-  `margin: "-20% 0px"`), and they should differ (a clip reveal here, a stagger
-  there) — not the same fade-and-rise stamped on everything.
-- Stagger direction carries meaning: top-down for lists, center-out for grids
-  (`delay: Math.abs(i - mid) * 0.05`), left-right only for horizontal sequences.
-- Exits are faster than entrances (~75%) and simpler (fade + small offset; never
-  reverse the full entrance).
-
-## 3. Scroll choreography (motion dial ≥ 7)
-
-- **Scrub vs trigger**: scrub (`scrub: 0.5–1` or Motion `useScroll`+`useTransform`)
-  for progress-bound narrative (a product rotating, a number counting, a diagram
-  assembling). Triggered one-shots for everything else. Scrubbed text reveals are
-  worn out; scrub things that MOVE, trigger things that APPEAR.
-- **Pinning**: max ONE pinned sequence per page (`ScrollTrigger pin: true`, or
-  `position: sticky` + a tall parent — prefer sticky, it's free and un-janks).
-  Pin length ≤ 2.5 viewport heights; past that users feel trapped.
-- **Parallax**: subtle = 8-15% differential (`useTransform(scrollYProgress, [0,1],
-  ["-8%","8%"])`); apply to media/decoration, never body text. 2-3 layers max.
-- **CSS scroll-driven animations** (`animation-timeline: view(); animation-range:
-  entry 0% cover 40%`) handle simple reveals/parallax with zero JS — use for
-  progressive enhancement, gate with `@supports (animation-timeline: view())`.
-- Progress-linked values snap to keyframes users can feel: use eased ranges
-  (`useTransform` with cubic arrays), not raw linear mapping.
-- Never scroll-jack (hijacking wheel delta into slide-snapping). `scroll-snap` on
-  a horizontal strip is fine; taking over vertical page scroll is not.
-
-## 4. Kinetic type and text reveal
-
-- Split text with `SplitText` (GSAP, now free) or manual word-`<span>` wrapping;
-  animate **words or lines, not characters** for readability (chars only for short
-  display words ≤ 12 chars). Wrap split parents in `overflow-hidden` line masks and
-  slide lines up `y: "110%" → 0` — the line-mask reveal reads as premium; per-char
-  fade reads as 2021 template.
-- `aria-label` the original string on the split container; split spans get
-  `aria-hidden`. Re-splitting on resize: debounce, or use `SplitText`'s autoSplit.
-- Counters: animate with `useSpring`/gsap `snap: 1`, `tabular-nums` mandatory,
-  duration ≤ 1.2s, trigger once in view.
-
-## 5. Layout & presence
-
-- Motion `layout` prop for reflow (filtering grids, expanding cards, reordering) —
-  it's FLIP under the hood, transform-only. `layoutId` for shared-element morphs
-  (card → modal). Wrap conditional trees in `AnimatePresence mode="popLayout"`.
-- Accordion/height: `grid-template-rows: 0fr → 1fr` (CSS, cheap) or Motion
-  `height: "auto"` (it measures for you). Never `max-height: 9999px`.
-- **View Transitions API** for page-level transitions (`document.startViewTransition`,
-  or the framework wrapper e.g. Next `<ViewTransition>`): name persistent elements
-  with `view-transition-name` so they morph across routes. Feature-gate; fall back
-  to instant navigation, not a JS fade.
-
-## 6. Performance and accessibility (non-negotiable)
-
-- Transform/opacity only in hot paths; promote animating layers sparingly
-  (`will-change` set just-in-time, removed after). > 6 simultaneously-animating
-  elements = re-choreograph.
-- All scroll work driven by IntersectionObserver / ScrollTrigger / `useScroll`
-  (rAF-batched) — a raw `scroll` listener is a hard ban (DESIGN.md).
-- Test the tab hidden→visible case: loops must not accumulate; `whileInView` must
-  not re-fire (`once: true`).
-- `prefers-reduced-motion`: scrubbed narratives get a static end-state, entrances
-  become plain fades ≤ 200ms, marquees stop. In Motion use `useReducedMotion()`
-  and branch the variants — don't just shorten durations.
-- Content exists without JS: initial styles are the VISIBLE state; animation
-  libraries then hide/offset from JS before first paint (`gsap.set`, Motion
-  `initial`). An SSR'd page must never flash-then-hide.
-
-## 7. Recipes (copy the shape, restyle the skin)
-
-- **Hero sequence**: nav fades in (150ms) → headline lines mask-slide up, 80ms
-  stagger → subtext + CTA fade-rise together → hero media scales 1.04→1 with 6px
-  blur→0. Total 900ms, expo-out.
-- **Sticky product walkthrough**: `sticky` media column + scrolling step copy;
-  step index from IntersectionObserver on copy blocks; media crossfades/transforms
-  per step (springy, 300ms).
-- **Marquee**: duplicated track, `animation: scroll Xs linear infinite`,
-  `width: max-content`, pause on hover, speed from content width (px/s constant,
-  ~60-90px/s), masked edges with `mask-image: linear-gradient`.
-- **Scrub showcase**: sticky canvas/image sequence, `useScroll` on the wrapper,
-  map progress to frame index / rotation; preload frames; ≤ 2.5 viewports tall.
+# Dreative Specialist Skill — Motion & Scroll Choreography
+
+Load this file when `plan.skills` includes `motion`, or the brief/prompt asks for
+animation, parallax, scroll storytelling, kinetic type, or "cinematic" feel.
+It EXTENDS DESIGN.md §6 (which still applies: 100/300/500 durations, ease-out
+exponential curves, reduced-motion fallbacks, no scroll listeners, no bounce).
+This file is about doing ambitious motion WELL, not about adding more of it.
+If the requested motion needs structure the current markup can't express (pinned
+sections, split text, persistent stages), use DESIGN.md §11's transformation-depth
+ladder: offer restructure as an option and, once confirmed, rebuild the markup —
+don't fake choreography onto the old skeleton.
+
+## 0. Pick the tool by the job, not by habit
+
+- **CSS only** — hover/focus/press states, one-shot entrances, marquees, simple
+  scroll reveals via `animation-timeline: view()`. Zero JS cost; always first choice.
+- **Motion (`motion/react`, formerly Framer Motion)** — React apps: presence
+  (`AnimatePresence`), layout animation (`layout` prop = free FLIP), springs,
+  `whileInView`, gesture props. The default for React product+brand pages.
+- **GSAP + ScrollTrigger** — timeline choreography: multiple elements coordinated
+  over one scroll range, scrubbed sequences, pinned sections, kinetic type.
+  Use when a Motion version would need 4+ manually-synced `useScroll` hooks.
+- **Lenis** — smooth scroll wrapper for scroll-driven brand pages. Only on brand
+  register with motion dial ≥7; never in product UI. Sync ScrollTrigger with
+  `lenis.on('scroll', ScrollTrigger.update)`.
+
+One animation system per page. Motion AND GSAP on the same page = two spring
+vocabularies fighting; pick one and commit.
+
+## 1. Springs beat durations for anything interactive
+
+Duration+easing is for one-shot choreography (entrances, exits). Anything that
+tracks input or can be interrupted (drag, hover follow, toggles, layout shifts)
+uses springs — they redirect mid-flight without a visible restart.
+
+- Motion defaults: `{ type: "spring", stiffness: 300, damping: 30 }` = snappy UI;
+  `stiffness: 120, damping: 20` = soft brand movement. Overshoot (`damping < 15`)
+  only on playful briefs, and only on small elements — never on layout.
+- `visualDuration` (Motion ≥11.13) sets spring feel by time: easier to reason about.
+- Never spring opacity or color; springs are for transform. Crossfade those.
+
+## 2. Orchestration: one timeline, one story
+
+The scattered-reveals look (every section fades up independently) is the #1 motion
+tell. Instead:
+
+- **Hero entrance** = ONE composed sequence: parent `staggerChildren: 0.08`,
+  `delayChildren` after nav settles; elements enter in reading order; total ≤ 900ms.
+  Nothing else on the page gets entrance choreography.
+- **Below the fold**: at most 2-3 sections get `whileInView` reveals (`once: true`,
+  `margin: "-20% 0px"`), and they should differ (a clip reveal here, a stagger
+  there) — not the same fade-and-rise stamped on everything.
+- Stagger direction carries meaning: top-down for lists, center-out for grids
+  (`delay: Math.abs(i - mid) * 0.05`), left-right only for horizontal sequences.
+- Exits are faster than entrances (~75%) and simpler (fade + small offset; never
+  reverse the full entrance).
+
+## 3. Scroll choreography (motion dial ≥ 7)
+
+- **Scrub vs trigger**: scrub (`scrub: 0.5–1` or Motion `useScroll`+`useTransform`)
+  for progress-bound narrative (a product rotating, a number counting, a diagram
+  assembling). Triggered one-shots for everything else. Scrubbed text reveals are
+  worn out; scrub things that MOVE, trigger things that APPEAR.
+- **Pinning**: max ONE pinned sequence per page (`ScrollTrigger pin: true`, or
+  `position: sticky` + a tall parent — prefer sticky, it's free and un-janks).
+  Pin length ≤ 2.5 viewport heights; past that users feel trapped.
+- **Parallax**: subtle = 8-15% differential (`useTransform(scrollYProgress, [0,1],
+  ["-8%","8%"])`); apply to media/decoration, never body text. 2-3 layers max.
+- **CSS scroll-driven animations** (`animation-timeline: view(); animation-range:
+  entry 0% cover 40%`) handle simple reveals/parallax with zero JS — use for
+  progressive enhancement, gate with `@supports (animation-timeline: view())`.
+- Progress-linked values snap to keyframes users can feel: use eased ranges
+  (`useTransform` with cubic arrays), not raw linear mapping.
+- Never scroll-jack (hijacking wheel delta into slide-snapping). `scroll-snap` on
+  a horizontal strip is fine; taking over vertical page scroll is not.
+
+## 4. Kinetic type and text reveal
+
+- Split text with `SplitText` (GSAP, now free) or manual word-`<span>` wrapping;
+  animate **words or lines, not characters** for readability (chars only for short
+  display words ≤ 12 chars). Wrap split parents in `overflow-hidden` line masks and
+  slide lines up `y: "110%" → 0` — the line-mask reveal reads as premium; per-char
+  fade reads as 2021 template.
+- `aria-label` the original string on the split container; split spans get
+  `aria-hidden`. Re-splitting on resize: debounce, or use `SplitText`'s autoSplit.
+- Counters: animate with `useSpring`/gsap `snap: 1`, `tabular-nums` mandatory,
+  duration ≤ 1.2s, trigger once in view.
+
+## 5. Layout & presence
+
+- Motion `layout` prop for reflow (filtering grids, expanding cards, reordering) —
+  it's FLIP under the hood, transform-only. `layoutId` for shared-element morphs
+  (card → modal). Wrap conditional trees in `AnimatePresence mode="popLayout"`.
+- Accordion/height: `grid-template-rows: 0fr → 1fr` (CSS, cheap) or Motion
+  `height: "auto"` (it measures for you). Never `max-height: 9999px`.
+- **View Transitions API** for page-level transitions (`document.startViewTransition`,
+  or the framework wrapper e.g. Next `<ViewTransition>`): name persistent elements
+  with `view-transition-name` so they morph across routes. Feature-gate; fall back
+  to instant navigation, not a JS fade.
+
+## 6. Performance and accessibility (non-negotiable)
+
+- Transform/opacity only in hot paths; promote animating layers sparingly
+  (`will-change` set just-in-time, removed after). > 6 simultaneously-animating
+  elements = re-choreograph.
+- All scroll work driven by IntersectionObserver / ScrollTrigger / `useScroll`
+  (rAF-batched) — a raw `scroll` listener is a hard ban (DESIGN.md).
+- Test the tab hidden→visible case: loops must not accumulate; `whileInView` must
+  not re-fire (`once: true`).
+- `prefers-reduced-motion`: scrubbed narratives get a static end-state, entrances
+  become plain fades ≤ 200ms, marquees stop. In Motion use `useReducedMotion()`
+  and branch the variants — don't just shorten durations.
+- Content exists without JS: initial styles are the VISIBLE state; animation
+  libraries then hide/offset from JS before first paint (`gsap.set`, Motion
+  `initial`). An SSR'd page must never flash-then-hide.
+
+## 7. Recipes (copy the shape, restyle the skin)
+
+- **Hero sequence**: nav fades in (150ms) → headline lines mask-slide up, 80ms
+  stagger → subtext + CTA fade-rise together → hero media scales 1.04→1 with 6px
+  blur→0. Total 900ms, expo-out.
+- **Sticky product walkthrough**: `sticky` media column + scrolling step copy;
+  step index from IntersectionObserver on copy blocks; media crossfades/transforms
+  per step (springy, 300ms).
+- **Marquee**: duplicated track, `animation: scroll Xs linear infinite`,
+  `width: max-content`, pause on hover, speed from content width (px/s constant,
+  ~60-90px/s), masked edges with `mask-image: linear-gradient`.
+- **Scrub showcase**: sticky canvas/image sequence, `useScroll` on the wrapper,
+  map progress to frame index / rotation; preload frames; ≤ 2.5 viewports tall.
+- **Text on a path** (verified on epic.net): a manifesto paragraph flows along a
+  curved SVG path (`<textPath>` or per-word transforms sampled from a curve) and
+  relaxes toward straight lines as scroll progress advances — the curve
+  amplitude is the scrubbed value. One per site; body text elsewhere stays flat.
+- **Orbiting cursor label** (epic.net's video CTA): a circular text ring
+  ("PLAY VIDEO ⟲") slowly rotates around the pointer while it's over the media
+  region — SVG `<textPath>` on a circle, damped position follow, constant
+  rotation. Replaces the play button; fine pointers only, real button fallback.