@hegemonart/get-design-done 1.16.0 → 1.18.0

package/reference/motion-spring.md

@@ -0,0 +1,234 @@
+<!-- Source: React Native — Libraries/Animated/SpringConfig.js (MIT License) -->
+<!-- Attribution: Facebook, Inc. and its affiliates -->
+
+# Motion Springs
+
+Spring animations model physical mass-spring-damper systems. Unlike tween animations, springs are driven by physics rather than duration — they respond to velocity and settle naturally, making them ideal for interactions that require a sense of weight.
+
+---
+
+## The Spring Parameter Triad
+
+Every spring is defined by three parameters:
+
+### Stiffness (`k`)
+
+The spring constant — how strongly the spring pulls toward the target.
+
+- **Low stiffness** (80–150): soft, gentle, slow to accelerate
+- **Medium stiffness** (150–300): standard UI feel
+- **High stiffness** (300–600): snappy, responsive, fast
+
+Higher stiffness = faster animation, more acceleration. Does not affect whether the spring overshoots.
+
+---
+
+### Damping (`c`)
+
+The friction coefficient — how quickly oscillation energy is removed.
+
+- **Low damping relative to stiffness**: spring oscillates (undershooted)
+- **Damping at critical value**: spring settles exactly without oscillation
+- **High damping**: spring creeps slowly to target (overdamped)
+
+Damping controls the *character* of the settle. Lower damping = more bounce.
+
+---
+
+### Mass (`m`)
+
+The simulated mass attached to the spring.
+
+- **Low mass** (< 1): snappy, light feel
+- **Mass = 1**: standard (most presets)
+- **High mass** (> 1): heavy, sluggish, long tail
+
+Mass scales settle time proportionally. Doubling mass approximately doubles settle time.
+
+---
+
+## Critical Damping Condition
+
+A spring is critically damped when:
+
+```
+c = 2 * sqrt(k * m)
+```
+
+At this value, the spring reaches its target in minimum time without oscillating. Below this threshold, the spring overshoots. Above it, the spring is overdamped (sluggish).
+
+```js
+const { criticalDamping } = require('./scripts/lib/spring.cjs');
+
+const c = criticalDamping(400, 1);   // stiffness=400, mass=1 → c ≈ 40
+```
+
+Most UI springs use damping *below* the critical value to add character and life to motion.
+
+---
+
+## Canonical Presets
+
+### `gentle`
+
+```
+stiffness: 120  |  damping: 14  |  mass: 1
+settle time: ~400ms  |  overshoots: yes (mild)
+```
+
+A soft, friendly spring. Overshoots slightly. Good for content reveals, cards expanding, or any motion that should feel unhurried.
+
+```js
+// Framer Motion
+<motion.div animate={{ y: 0 }} transition={{ type: 'spring', stiffness: 120, damping: 14, mass: 1 }} />
+
+// React Spring
+useSpring({ from: { y: -40 }, to: { y: 0 }, config: { tension: 120, friction: 14, mass: 1 } });
+```
+
+---
+
+### `wobbly`
+
+```
+stiffness: 180  |  damping: 12  |  mass: 1
+settle time: ~600ms  |  overshoots: yes (pronounced, 2–3 cycles)
+```
+
+High energy, bouncy. Use for playful or expressive interactions — celebratory states, game-like UIs, avatar reactions. Not appropriate for productivity or enterprise UIs.
+
+```js
+// Framer Motion
+<motion.div animate={{ scale: 1 }} transition={{ type: 'spring', stiffness: 180, damping: 12, mass: 1 }} />
+
+// React Spring
+useSpring({ from: { scale: 0.8 }, to: { scale: 1 }, config: { tension: 180, friction: 12, mass: 1 } });
+```
+
+---
+
+### `stiff`
+
+```
+stiffness: 400  |  damping: 30  |  mass: 1
+settle time: ~200ms  |  overshoots: minimal
+```
+
+Fast and tight. Feels responsive and precise. Good for small UI elements: toggles, checkboxes, icon state changes, cursor-tracking components. Near-critical damping means it barely overshoots.
+
+```js
+// Framer Motion
+<motion.div animate={{ opacity: 1 }} transition={{ type: 'spring', stiffness: 400, damping: 30, mass: 1 }} />
+
+// React Spring
+useSpring({ from: { opacity: 0 }, to: { opacity: 1 }, config: { tension: 400, friction: 30, mass: 1 } });
+```
+
+---
+
+### `slow`
+
+```
+stiffness: 280  |  damping: 60  |  mass: 1
+settle time: ~800ms  |  overshoots: no (overdamped)
+```
+
+Overdamped spring — creeps gently to target with no oscillation. Feels heavy and deliberate. Good for large layout changes, full-screen transitions, onboarding sequences.
+
+```js
+// Framer Motion
+<motion.div animate={{ x: 0 }} transition={{ type: 'spring', stiffness: 280, damping: 60, mass: 1 }} />
+
+// React Spring
+useSpring({ from: { x: -200 }, to: { x: 0 }, config: { tension: 280, friction: 60, mass: 1 } });
+```
+
+---
+
+## Preset Summary Table
+
+| Name | Stiffness | Damping | Mass | Settle | Character |
+|---|---|---|---|---|---|
+| `gentle` | 120 | 14 | 1 | ~400ms | Soft, mild overshoot |
+| `wobbly` | 180 | 12 | 1 | ~600ms | Bouncy, 2–3 cycles |
+| `stiff` | 400 | 30 | 1 | ~200ms | Snappy, minimal bounce |
+| `slow` | 280 | 60 | 1 | ~800ms | Heavy, no overshoot |
+
+---
+
+## CSS `linear()` Approximation
+
+CSS does not have a native spring primitive, but the `linear()` timing function (Chrome 113+, Firefox 112+) can approximate a spring by sampling it at many points.
+
+```js
+// scripts/lib/spring.cjs — bake a spring to CSS linear()
+const { step, settleTime } = require('./scripts/lib/spring.cjs');
+
+function bakeSpringToCSS(stiffness, damping, mass, samples = 60) {
+  const duration = settleTime(stiffness, damping, mass);
+  const dt = duration / samples / 1000;  // convert ms to seconds
+  const points = [];
+
+  let pos = 0, vel = 0;
+  for (let i = 0; i <= samples; i++) {
+    points.push(pos.toFixed(4));
+    const result = step(stiffness, damping, mass, vel, dt);
+    pos = result.position;
+    vel = result.velocity;
+  }
+
+  return `linear(${points.join(', ')})`;
+}
+```
+
+```css
+/* Example output for stiff preset (stiffness=400, damping=30, mass=1) */
+:root {
+  --spring-stiff: linear(
+    0, 0.081, 0.301, 0.567, 0.789, 0.913, 0.972, 0.997, 1.006,
+    1.004, 1.001, 1.000, 1.000 100%
+  );
+}
+
+.toggle {
+  transition: transform 200ms var(--spring-stiff);
+}
+```
+
+The baked approximation loses velocity responsiveness (a real spring reacts to initial velocity; a CSS timing function does not), but is acceptable for state-driven transitions.
+
+---
+
+## When to Use Spring vs Tween
+
+### Use spring when:
+
+- **Drag release / throw** — the animation should carry the momentum from the gesture. Springs naturally handle initial velocity; tweens cannot.
+- **Toggle state** — a checkbox, switch, or button that needs to feel responsive and alive. The `stiff` preset is standard here.
+- **Interactive hover / follow** — cursor-tracking, magnetic elements. Springs give a sense of physical weight.
+- **Interrupt-safe sequences** — if the user reverses a motion mid-way, springs handle the reversal gracefully by inheriting the current velocity.
+
+### Use tween (eased duration) when:
+
+- **Navigation transitions** — page or route changes should complete in a fixed, predictable time. A spring may not settle in time if interrupted.
+- **Data-driven state changes** — tab switches, accordion open/close, tooltip appear. A 200–300ms cubic-out tween is predictable and familiar.
+- **Reduced motion** — when `prefers-reduced-motion` is active, replace all springs with short (150ms) linear or ease-out tweens. Springs are inherently bouncy; motion-sensitive users should never see oscillation.
+- **Synchronized choreography** — when multiple elements must start and end together (e.g., a staggered list entrance), tweens with explicit durations are easier to coordinate.
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  .animated {
+    transition-timing-function: var(--ease-linear);
+    transition-duration: 150ms;
+    /* override any spring-based JS animation via a CSS signal */
+  }
+}
+```
+
+---
+
+## Pairs With
+
+- Easing functions for tween-based alternatives: [motion-easings.md](./motion-easings.md)
+- Interpolation for mapping spring output to CSS values: [motion-interpolate.md](./motion-interpolate.md)
+- The `scripts/lib/spring.cjs` module exposes `PRESETS`, `criticalDamping`, `settleTime`, and `step` for programmatic use.

package/reference/motion-transition-taxonomy.md

@@ -0,0 +1,155 @@
+<!-- Source: hyperframes registry/blocks/transitions-* (Apache License 2.0) -->
+<!-- See: reference/external/NOTICE.hyperframes for full attribution -->
+
+# Motion Transition Taxonomy
+
+Eight controlled transition families derived from the hyperframes registry. Each family describes a distinct visual strategy for moving between UI states. Use this taxonomy to select, name, and constrain transitions consistently across the design system.
+
+---
+
+## 1. 3d
+
+The 3d family covers transitions driven by depth and perspective. Elements rotate or flip along a spatial axis so the viewer perceives them moving through three-dimensional space rather than sliding across a flat surface. The visual character is physical and mechanical — content feels like it has mass, faces, and hinge points. Timing curves should emphasize the acceleration and deceleration of a real object rotating under gravity.
+
+**Canonical examples:** `flip-x`, `flip-y`, `rotate-3d-left`, `cube-left`
+
+### When to use
+
+- **Page flips in book or document viewers** — the metaphor of a literal page turning reinforces the reading model.
+- **Card flip interactions** — revealing the back of a card (e.g., a flashcard, a product tile showing detail) benefits from the physical flip metaphor.
+- **Onboarding carousel slides** — a cube or rotating panel transition communicates sequential steps with a stronger sense of progression than a flat slide.
+
+---
+
+## 2. blur
+
+The blur family transitions content by shifting focus: the outgoing element loses sharpness while the incoming element sharpens into clarity. The motion resembles a camera rack-focus — attention narrows onto a single point and then expands to the new content. Unlike most transition families, blur operates in the depth-of-field axis rather than the spatial or temporal axis, making it feel intimate and selective.
+
+**Canonical examples:** `blur-in`, `blur-out`, `blur-in-up`, `blur-in-down`
+
+### When to use
+
+- **Focus-mode overlays** — blurring underlying content when a modal, drawer, or spotlight opens communicates that the rest of the UI has receded.
+- **Photo gallery lightbox opens** — racking focus from thumbnail to full image reinforces the zoom metaphor without a disorienting scale jump.
+- **Loading skeleton to content** — blurring out a skeleton and sharpening in the real content feels more organic than an abrupt swap or a flat cross-fade.
+
+---
+
+## 3. cover
+
+The cover family uses a fill or wipe that expands from one edge to conceal the outgoing content and simultaneously reveal the incoming content behind it. The transition is directional — left, right, up, or down — giving users a strong spatial cue about where they are navigating. The incoming content is already fully rendered beneath the cover layer, so there is no compositional ambiguity mid-transition.
+
+**Canonical examples:** `cover-left`, `cover-right`, `cover-up`, `cover-down`
+
+### When to use
+
+- **Route transitions in marketing sites** — a cover wipe from the current page edge toward the next reinforces the left-to-right or top-to-bottom navigation model.
+- **Section reveals on scroll** — covering the previous section as the next one rises into view creates a satisfying page-turning rhythm for long-form content.
+- **Slide-panel opens** — a drawer or side panel that covers the main content from its natural edge feels grounded rather than floating.
+
+---
+
+## 4. destruction
+
+The destruction family fragments outgoing content before new content appears. Elements shatter, explode, pixelate, or break apart into constituent pieces that scatter or dissolve. The transition is intentionally dramatic and high-entropy — it signals a decisive, irreversible state change rather than a soft navigation event. Because of its visual weight, destruction transitions should be reserved for moments where the drama is earned.
+
+**Canonical examples:** `shatter`, `explode`, `pixelate-out`, `break-apart`
+
+### When to use
+
+- **Onboarding celebrations** — completing a significant setup milestone (connecting an account, finishing a profile) can warrant a brief destruction-style break of the previous step.
+- **Error states (use sparingly)** — a pixelate-out or shatter on a failed action can reinforce the severity of the error without a generic fade, but overuse deadens the signal.
+- **Game-style transitions** — level completions, score reveals, or achievement unlocks in game-adjacent products match the genre conventions users already associate with this visual language.
+
+---
+
+## 5. dissolve
+
+The dissolve family cross-fades both the outgoing and incoming content so they overlap during the transition period. Neither element is hidden at the midpoint — the viewer sees a superimposition of both states. This creates a sense of continuity and blending rather than replacement. Dissolves feel gentle and temporal: time is passing, but the context is preserved.
+
+**Canonical examples:** `dissolve`, `fade-through-black`, `fade-through-white`, `morph-dissolve`
+
+### When to use
+
+- **Content replacement where continuity matters** — updating a detail panel or a card's content without navigating away benefits from dissolve so the user understands they are still in the same location.
+- **Photo slideshows** — the classic cross-dissolve between images preserves the sense of a continuous viewing experience.
+- **Wizard step changes** — stepping through a multi-step form where each step occupies the same spatial region reads more clearly with a dissolve than a directional slide, because the user has not navigated anywhere.
+
+---
+
+## 6. distortion
+
+The distortion family applies mesh warping, ripple, stretch, or liquid deformation to content during the transition. Rather than moving content spatially or temporally, distortion transitions make the pixels themselves behave like a physical medium — rubber, water, or fabric — that stretches and snaps back. The effect is visceral and tactile. Used well, it adds a signature moment that makes a product feel materially distinct.
+
+**Canonical examples:** `warp`, `ripple`, `stretch-in`, `liquid`
+
+### When to use
+
+- **Creative and editorial contexts** — design portfolios, editorial publications, and art-directed landing pages where differentiation is a primary goal.
+- **Unique brand moments** — a single, well-timed warp or ripple on a hero image transition can become a brand signature without overwhelming the interface.
+- **Hero section transitions on marketing sites** — distortion applied at the seam between a full-bleed hero and the next section creates a visceral scroll reward that flat transitions cannot match.
+
+---
+
+## 7. grid
+
+The grid family breaks content into a regular matrix of tiles that animate independently — entering, exiting, flipping, or fading in a choreographed sequence. The grid subdivision can be dense (many small tiles for a mosaic effect) or coarse (a few large panels). The transition communicates that the content is composed of discrete pieces, which suits imagery and portfolio work where the grid metaphor is already meaningful.
+
+**Canonical examples:** `grid-in`, `grid-out`, `checkerboard`, `tile-flip`
+
+### When to use
+
+- **Portfolio galleries** — revealing a new set of work by animating each thumbnail cell independently reinforces the gallery grid metaphor.
+- **Image reveals** — a grid-in where tiles appear in a wave pattern draws the eye across the composition before the full image settles.
+- **Dramatic content transitions in editorial contexts** — a checkerboard or tile-flip between major sections of an editorial layout creates a theatrical reveal suited to magazine-style layouts.
+
+---
+
+## 8. light
+
+The light family uses luminosity effects — flash, glow, lens flare, or bloom — to punctuate the moment of transition. Rather than moving content spatially, light transitions overwhelm the frame briefly with brightness or radiant energy before the new content resolves. The effect is momentary and climactic, borrowed from cinematic language where a burst of light signals a revelation, a completion, or the passage of significance.
+
+**Canonical examples:** `flash`, `whiteout`, `bloom`, `lens-flare`
+
+### When to use
+
+- **Onboarding completions** — a flash or bloom when the user finishes setup signals that something important has happened.
+- **Achievement unlocks** — reward moments in any product (reaching a milestone, earning a badge) suit light transitions because brightness is universally read as positive and celebratory.
+- **Brand-moment animations and moments of delight** — a subtle lens-flare or glow on a signature interaction (e.g., hitting a streak, confirming a purchase) adds warmth without disrupting flow.
+
+---
+
+## Choosing a Family
+
+Quick-reference guide for selecting the right transition family based on visual weight and primary use context.
+
+| Family | Visual Weight | Best For |
+|-------------|--------------|--------------------------------------------------|
+| 3d | Medium–Heavy | Physical metaphors, card reveals, sequential steps |
+| blur | Light–Medium | Focus shifts, depth cues, content materialising |
+| cover | Light–Medium | Directional navigation, drawer/panel opens |
+| destruction | Heavy | Celebratory moments, dramatic state changes |
+| dissolve | Light | Soft content replacement, continuity of place |
+| distortion | Medium–Heavy | Brand signatures, editorial hero moments |
+| grid | Medium | Gallery reveals, tile-based image layouts |
+| light | Medium–Heavy | Reward moments, completions, delight beats |
+
+---
+
+## Combining with Duration Classes
+
+Transition family choice constrains the appropriate duration range. The duration system (defined in `reference/motion.md`) maps timing to semantic classes: narrative, slow, standard, quick, and instant.
+
+**3d and destruction** require slow-to-narrative durations (400–700 ms). Their visual complexity — rotating geometry, fragmenting particles — needs time to resolve clearly. At quick durations they read as broken or glitchy rather than intentional.
+
+**distortion** works best in the slow-to-standard range (300–500 ms). Warping too fast looks like an artifact; too slow it becomes self-indulgent. The sweet spot is long enough to feel physical but short enough to feel responsive.
+
+**grid** tolerates a wider range depending on tile count. Coarse grids (2×2 or 3×3) can run at standard (200–300 ms); dense mosaics need slow (350–500 ms) so individual tile motion is legible.
+
+**light** transitions are typically the shortest of the heavy-weight families. A flash or whiteout at 150–250 ms (standard-to-quick) feels like a camera flash — instantaneous and climactic. Extending it past 400 ms turns a flash into a fade.
+
+**dissolve and cover** are the workhorses of the system. Both operate comfortably at standard (200–300 ms) and can be compressed to quick (100–150 ms) for secondary navigation without losing legibility. They are the default choice when in doubt.
+
+**blur** sits in the quick-to-standard range (150–300 ms). Longer blur transitions feel like a loading state rather than a deliberate motion.
+
+When stacking a transition family choice against the rest of the design: if the moment warrants narrative pacing (slow, deliberate), reach for 3d, destruction, or distortion. If the moment should feel effortless and recede from attention, dissolve and cover at quick or standard are correct. Blur is the right default for focus-management transitions at any speed.

package/reference/motion.md

@@ -385,3 +385,23 @@ Remove `will-change` after the animation completes if applied dynamically:
 ```js
 element.addEventListener('transitionend', () => element.style.willChange = 'auto')
 ```
+
+---
+
+## Advanced Patterns
+
+For spring physics, scroll-driven animation, FLIP, View Transitions API, gesture & drag mechanics, clip-path animation patterns, blur-to-mask crossfades, WAAPI, Framer Motion hardware-acceleration gotcha, motion cohesion & personality, and the next-day slow-motion review process, see:
+
+→ **`reference/motion-advanced.md`** (Phase 18)
+
+For the canonical easing catalog (`--ease-*` tokens, cubic-bezier equivalents, 60fps settle-times):
+
+→ **`reference/motion-easings.md`** (Phase 18)
+
+For spring parameter presets (gentle / wobbly / stiff / slow):
+
+→ **`reference/motion-spring.md`** (Phase 18)
+
+For transition family taxonomy (8 families: 3d / blur / cover / destruction / dissolve / distortion / grid / light):
+
+→ **`reference/motion-transition-taxonomy.md`** (Phase 18)

package/reference/output-contracts/motion-map.schema.json

@@ -0,0 +1,135 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "motion-map.schema.json",
+  "title": "Motion Map Output Contract",
+  "description": "Schema for the structured JSON block emitted by motion-mapper at the top of .design/map/motion.md. Every detected animation binding must conform to this schema.",
+  "type": "object",
+  "required": ["schema_version", "generated_at", "animations"],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "const": "1.0.0",
+      "description": "Schema version — bump when adding required fields"
+    },
+    "generated_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO-8601 timestamp of when this map was generated"
+    },
+    "summary": {
+      "type": "object",
+      "description": "Aggregate counts for quick review",
+      "properties": {
+        "total_animations": { "type": "integer", "minimum": 0 },
+        "custom_easings": { "type": "integer", "minimum": 0 },
+        "reduced_motion_compliant": { "type": "boolean" },
+        "libraries": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Animation libraries detected (e.g., framer-motion, gsap, css-only)"
+        }
+      }
+    },
+    "animations": {
+      "type": "array",
+      "description": "One entry per detected animation binding",
+      "items": {
+        "$ref": "#/definitions/AnimationBinding"
+      }
+    }
+  },
+  "definitions": {
+    "AnimationBinding": {
+      "type": "object",
+      "required": ["id", "location", "easing", "duration_class", "trigger"],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Unique identifier for this binding, e.g., 'toast-enter-opacity'"
+        },
+        "location": {
+          "type": "object",
+          "required": ["file", "line"],
+          "properties": {
+            "file": { "type": "string", "description": "Relative path from project root" },
+            "line": { "type": "integer", "minimum": 1 }
+          }
+        },
+        "description": {
+          "type": "string",
+          "description": "Human-readable description of what this animation does"
+        },
+        "easing": {
+          "oneOf": [
+            {
+              "type": "string",
+              "enum": [
+                "linear",
+                "quad", "quad-in", "quad-out", "quad-in-out",
+                "cubic", "cubic-in", "cubic-out", "cubic-in-out",
+                "poly", "poly-in", "poly-out", "poly-in-out",
+                "sin", "sin-in", "sin-out", "sin-in-out",
+                "circle", "circle-in", "circle-out", "circle-in-out",
+                "exp", "exp-in", "exp-out", "exp-in-out",
+                "elastic", "elastic-in", "elastic-out", "elastic-in-out",
+                "back", "back-in", "back-out", "back-in-out",
+                "bounce", "bounce-in", "bounce-out", "bounce-in-out",
+                "bezier"
+              ],
+              "description": "One of the 12 canonical easing presets from reference/motion-easings.md"
+            },
+            {
+              "type": "object",
+              "required": ["type", "justification"],
+              "properties": {
+                "type": { "type": "string", "const": "custom" },
+                "value": {
+                  "type": "string",
+                  "description": "The actual easing value (cubic-bezier string, spring config, etc.)"
+                },
+                "justification": {
+                  "type": "string",
+                  "description": "Why a canonical easing was not sufficient. Must be non-empty."
+                }
+              }
+            }
+          ]
+        },
+        "transition_family": {
+          "type": "string",
+          "enum": ["3d", "blur", "cover", "destruction", "dissolve", "distortion", "grid", "light"],
+          "description": "Optional: one of the 8 transition families from reference/motion-transition-taxonomy.md. Omit for micro-interactions where no family applies."
+        },
+        "duration_class": {
+          "type": "string",
+          "enum": ["instant", "quick", "standard", "slow", "narrative"],
+          "description": "Duration classification. instant: <100ms, quick: 100-200ms, standard: 200-400ms, slow: 400-800ms, narrative: >800ms"
+        },
+        "duration_ms": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Actual duration in milliseconds, if known"
+        },
+        "trigger": {
+          "type": "string",
+          "enum": ["user-gesture", "state-change", "scroll-progress", "time", "loop"],
+          "description": "What drives this animation"
+        },
+        "reduced_motion_handled": {
+          "type": "boolean",
+          "description": "Whether this animation respects prefers-reduced-motion"
+        },
+        "library": {
+          "type": "string",
+          "description": "Animation library used, e.g., 'framer-motion', 'gsap', 'css-transition', 'waapi'"
+        },
+        "notes": {
+          "type": "string",
+          "description": "Optional free-form notes for the reviewer"
+        }
+      }
+    }
+  }
+}