npm - wizz-method - Versions diffs - 1.3.1 → 1.4.0 - Mend

wizz-method 1.3.1 → 1.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (183) hide show

package/src/skills-lib/design-motion-principles/references/demo-shell.html ADDED Viewed

@@ -0,0 +1,275 @@
+<!--
+  Demo Shell — design-motion-principles
+  =====================================
+  Minimal, isolated reference for a single demo card. The agent reads this
+  during STEP 3 of the audit workflow (see ../SKILL.md) and uses it as the
+  per-finding template — one .demo block per Critical or Important finding
+  (Opportunities don't get demo cards).
+  The full worked example with five demo cards in context lives in
+  references/report-template.html. This file is intentionally minimal:
+  one card, every contract visible, no report scaffolding.
+  How the agent uses this file
+  ----------------------------
+  1. Copy the entire <style> block into the report's <head>. The shell's
+     tokens, .demo layout, stage colors, segmented control, and the
+     prefers-reduced-motion guard are SHARED across every demo card in the
+     report and must not be duplicated per finding.
+  2. For each finding {n} (1-indexed across the whole report):
+     a. Replace the MOTION-CODE-SLOT-{n} comment with the per-finding
+        @keyframes m{n} block AND the .demo-{n}__mt selector rule.
+        Suffix {n} so multiple findings cannot collide on keyframe
+        names or selectors.
+     b. Replace the DEMO-CARD-MOTION-SLOT-{n} comment in the .demo__stage
+        markup with the actual motion-target element. Its class must be
+        .demo-{n}__mt so it matches the rules above.
+     c. Set .demo__title to a short title for the recommended motion
+        (e.g., "Quick tab crossfade", "Sheet enter (mirror for exit)").
+     d. Set .demo__timing to the duration plus easing (e.g.,
+        "180ms · ease-out", "300ms · ease-out-quint"). The subhead
+        ALWAYS renders — populate it for every demo so card heights
+        stay consistent across the report.
+     e. Renumber the four radio ids from st1-* to st{n}-*, and the
+        labels' for= attributes to match.
+  3. Per-finding code MUST honor these contracts:
+     - Do NOT redefine the shell's tokens (--ink, --paper, --surface-2,
+       --line, --line-strong, --st-bg, --st-fg, --st-line, --st-dim,
+       --sans, --mono). Use them via var().
+     - Do NOT modify the prefers-reduced-motion block. The shell's
+       guard collapses all .demo-{n}__mt animations to none. The
+       per-finding @keyframes 100% state MUST match the motion-target
+       element's default static rendering so the reduce-motion fallback
+       shows the correct final visual.
+     - Per-finding @keyframes use the 0% / ~60% / 100% cadence:
+       0% = start state, ~60% = motion complete (~1.8s in),
+       100% = hold (~1.2s). The shell uses animation-duration: 3s.
+  4. Motion targets and ANY UI primitives inside the stage (.ui-btn,
+     .ui-card, .ui-row, .ui-check, .ui-num, .ui-label, badge, etc.)
+     use --st-bg / --st-fg / --st-line / --st-dim — NEVER --accent or
+     other page tokens. This guarantees the demo contrasts correctly
+     when its stage is locked to a different theme than the report.
+  5. Demo cards are non-interactive. The stage toggle radios are the
+     only interactive element. tabindex on the radios is fine; the
+     stage itself stays out of focus order.
+  Loop pacing
+  -----------
+  animation-duration: 3s. Keyframes 0% / ~60% / 100%. Motion 0–60% ≈ 1.8s,
+  hold 60–100% ≈ 1.2s, then restart. Every demo in a report uses this
+  cadence so all cards share the same rhythm.
+  Standalone preview
+  ------------------
+  Opening this file directly in a browser shows one .demo card with the
+  loop indicator, the segmented Auto/Light/Dark stage toggle, and a
+  placeholder motion target (a simple shape that fades in). No real
+  per-finding motion plays — the agent injects motion per finding when
+  this template is embedded in a report. The shell also honors the
+  viewer's prefers-color-scheme for standalone rendering.
+-->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Demo Shell — design-motion-principles</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=Familjen+Grotesk:wght@400;500;600;700&family=Public+Sans:wght@400;500;600;700&family=Geist+Mono:wght@400;500;600&display=swap" rel="stylesheet">
+  <style>
+    :root {
+      /* Cool slate-graphite neutrals (hue 255). In the full report these
+         are overridden by a global theme toggle; here the shell flips via
+         prefers-color-scheme for standalone preview. */
+      --ink:        oklch(0.155 0.006 255);
+      --surface:    oklch(0.195 0.007 255);
+      --surface-2:  oklch(0.235 0.008 255);
+      --paper:      oklch(0.945 0.004 255);
+      --paper-dim:  oklch(0.800 0.006 255);
+      --muted:      oklch(0.680 0.008 255);
+      --faint:      oklch(0.505 0.008 255);
+      --line:       oklch(0.95 0.01 255 / 0.09);
+      --line-strong:oklch(0.95 0.01 255 / 0.16);
+      --display: "Familjen Grotesk", "Hanken Grotesk", system-ui, sans-serif;
+      --sans: "Public Sans", -apple-system, BlinkMacSystemFont, "Segoe UI", system-ui, sans-serif;
+      --mono: "Geist Mono", ui-monospace, "SF Mono", Menlo, monospace;
+    }
+    @media (prefers-color-scheme: light) {
+      :root {
+        --ink:        oklch(0.985 0.003 255);
+        --surface:    oklch(0.965 0.004 255);
+        --surface-2:  oklch(0.940 0.005 255);
+        --paper:      oklch(0.180 0.006 255);
+        --paper-dim:  oklch(0.330 0.008 255);
+        --muted:      oklch(0.475 0.010 255);
+        --faint:      oklch(0.640 0.009 255);
+        --line:       oklch(0.180 0.010 255 / 0.12);
+        --line-strong:oklch(0.180 0.010 255 / 0.22);
+      }
+    }
+    * { box-sizing: border-box; }
+    body {
+      background: var(--ink);
+      color: var(--paper);
+      font-family: var(--sans);
+      margin: 0;
+      padding: 48px;
+      display: flex;
+      justify-content: center;
+    }
+    /* visually-hidden (stage-toggle radios) */
+    .vh { position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip: rect(0 0 0 0); white-space: nowrap; border: 0; }
+    /* ───────────── Demo card ───────────── */
+    .demo { position: relative; width: 380px; }
+    .demo__bar { display: flex; align-items: flex-start; justify-content: space-between; gap: 12px; margin-bottom: 12px; }
+    .demo__meta { min-width: 0; }
+    .demo__title { display: block; font-size: 13.5px; font-weight: 600; color: var(--paper); line-height: 1.3; }
+    .demo__timing { display: block; font-family: var(--mono); font-size: 11px; color: var(--muted); margin-top: 2px; font-variant-numeric: tabular-nums; }
+    .demo__controls { display: flex; align-items: center; gap: 12px; flex-shrink: 0; }
+    .demo__loop { font-family: var(--mono); font-size: 12px; color: var(--faint); }
+    /* segmented Auto / Light / Dark stage toggle (pure CSS).
+       Auto = follow ambient theme via --surface-2 + --paper.
+       Light / Dark = locked overrides (hardcoded values, ignore ambient). */
+    .seg { display: inline-flex; border: 1px solid var(--line-strong); border-radius: 100px; overflow: hidden; }
+    .seg label { font-family: var(--mono); font-size: 9.5px; letter-spacing: 0.1em; text-transform: uppercase; color: var(--muted); padding: 4px 9px; cursor: pointer; user-select: none; transition: background 0.15s ease, color 0.15s ease; }
+    .demo input[id$="-a"]:checked ~ .demo__bar .seg label[for$="-a"],
+    .demo input[id$="-l"]:checked ~ .demo__bar .seg label[for$="-l"],
+    .demo input[id$="-d"]:checked ~ .demo__bar .seg label[for$="-d"] {
+      background: color-mix(in oklch, var(--paper) 12%, transparent);
+      color: var(--paper);
+    }
+    .demo__stage {
+      /* AUTO default — stage uses the ambient elevated surface */
+      --st-bg: var(--surface-2);
+      --st-fg: var(--paper);
+      --st-line: var(--line-strong);
+      --st-dim: color-mix(in oklch, var(--paper) 55%, transparent);
+      background: var(--st-bg); color: var(--st-fg);
+      border: 1px solid var(--line); border-radius: 10px;
+      padding: 32px 24px; min-height: 168px;
+      display: flex; align-items: center; justify-content: center; overflow: hidden;
+    }
+    /* Locked Light: hardcoded light, regardless of ambient theme */
+    .demo input[id$="-l"]:checked ~ .demo__stage {
+      --st-bg: oklch(0.985 0.003 255);
+      --st-fg: oklch(0.180 0.006 255);
+      --st-line: oklch(0.180 0.010 255 / 0.18);
+      --st-dim: oklch(0.180 0.010 255 / 0.45);
+    }
+    /* Locked Dark: hardcoded dark, regardless of ambient theme */
+    .demo input[id$="-d"]:checked ~ .demo__stage {
+      --st-bg: oklch(0.180 0.006 255);
+      --st-fg: oklch(0.985 0.003 255);
+      --st-line: oklch(0.985 0.010 255 / 0.18);
+      --st-dim: oklch(0.985 0.010 255 / 0.50);
+    }
+    /* Generic UI primitives for use inside motion targets. All theme via
+       stage tokens, NEVER page tokens — so they contrast correctly when a
+       stage is locked to a different theme than the report. */
+    .ui-btn { display: inline-flex; align-items: center; justify-content: center; padding: 9px 18px; border-radius: 8px; background: var(--st-fg); color: var(--st-bg); font-family: var(--sans); font-size: 13px; font-weight: 600; }
+    .ui-card { background: var(--st-bg); border: 1px solid var(--st-line); border-radius: 10px; padding: 14px 16px; min-width: 180px; box-shadow: 0 8px 24px oklch(0 0 0 / 0.12); }
+    .ui-row { display: flex; align-items: center; gap: 10px; font-size: 13px; color: var(--st-fg); }
+    .ui-check { width: 22px; height: 22px; border-radius: 7px; background: var(--st-fg); display: inline-flex; align-items: center; justify-content: center; flex-shrink: 0; }
+    .ui-check svg { width: 13px; height: 13px; stroke: var(--st-bg); }
+    .ui-num { font-family: var(--display); font-size: 34px; font-weight: 700; color: var(--st-fg); font-variant-numeric: tabular-nums; letter-spacing: -0.02em; }
+    .ui-label { font-family: var(--mono); font-size: 10px; letter-spacing: 0.12em; text-transform: uppercase; color: var(--st-dim); }
+    /* prefers-reduced-motion — disables every per-finding animation and
+       hides the loop indicator. The per-finding @keyframes 100% state
+       must match the motion-target's default rendering so the reduce
+       fallback shows the correct final visual. */
+    @media (prefers-reduced-motion: reduce) {
+      .demo__loop { display: none; }
+      [class*="__mt"], [class*="__mt"] * { animation: none !important; transition: none !important; }
+    }
+    /* MOTION-CODE-SLOT-{n}
+       Per-finding @keyframes and .demo-{n}__mt rules go here. {n} is the
+       finding's 1-indexed position across the report.
+       Example shape (replace per finding — wrap in
+       @media (prefers-reduced-motion: no-preference) { ... }):
+       @media (prefers-reduced-motion: no-preference) {
+         @keyframes m1 {
+           0%   { opacity: 0; transform: translateY(8px); filter: blur(4px); }
+           60%  { opacity: 1; transform: translateY(0);   filter: blur(0);  }
+           100% { opacity: 1; transform: translateY(0);   filter: blur(0);  }
+         }
+         .demo-1__mt {
+           animation: m1 3s cubic-bezier(0.22, 1, 0.36, 1) infinite;
+         }
+       }
+    */
+    /* Placeholder motion for standalone preview only — agent strips this
+       when composing the report. Demonstrates the 0 / 60 / 100 cadence. */
+    @media (prefers-reduced-motion: no-preference) {
+      @keyframes m-placeholder {
+        0%   { opacity: 0; transform: translateY(8px); filter: blur(4px); }
+        60%  { opacity: 1; transform: translateY(0);   filter: blur(0);  }
+        100% { opacity: 1; transform: translateY(0);   filter: blur(0);  }
+      }
+      .demo-1__mt {
+        animation: m-placeholder 3s cubic-bezier(0.22, 1, 0.36, 1) infinite;
+      }
+    }
+  </style>
+</head>
+<body>
+  <div class="demo">
+    <input class="vh" type="radio" name="st1" id="st1-a" checked>
+    <input class="vh" type="radio" name="st1" id="st1-l">
+    <input class="vh" type="radio" name="st1" id="st1-d">
+    <div class="demo__bar">
+      <div class="demo__meta">
+        <span class="demo__title">Recommended motion title</span>
+        <span class="demo__timing">300ms · ease-out</span>
+      </div>
+      <div class="demo__controls">
+        <div class="seg">
+          <label for="st1-a">Auto</label>
+          <label for="st1-l">Light</label>
+          <label for="st1-d">Dark</label>
+        </div>
+        <span class="demo__loop">↻</span>
+      </div>
+    </div>
+    <div class="demo__stage">
+      <!-- DEMO-CARD-MOTION-SLOT-{n}
+           Per-finding motion-target element goes here. Its class must
+           match the rules in MOTION-CODE-SLOT-{n} above:
+             <div class="demo-{n}__mt">...content...</div>
+           The element's contents are agent-determined (a button shape,
+           a card, an icon, a row of items for stagger demos, a number,
+           a badge, etc.). All inner UI primitives use the stage tokens
+           (--st-fg / --st-bg / --st-line / --st-dim) — NEVER page tokens. -->
+      <div class="demo-1__mt">
+        <div class="ui-card">
+          <div class="ui-label" style="margin-bottom: 6px;">Placeholder</div>
+          <div class="ui-row">
+            <span class="ui-check"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="3.5"><path d="M5 13l4 4L19 7"/></svg></span>
+            <span>(motion preview renders here per finding)</span>
+          </div>
+        </div>
+      </div>
+    </div>
+  </div>
+</body>
+</html>

package/src/skills-lib/design-motion-principles/references/emil-kowalski.md ADDED Viewed

@@ -0,0 +1,121 @@
+# Emil Kowalski's Animation Principles
+Emil Kowalski is a Design Engineer at Linear (previously Vercel). Creator of Sonner, Vaul, and the "Animations on the Web" course. His approach emphasizes **restraint, speed, and purposeful motion**.
+This file is Emil's **philosophy and decision frameworks** — the judgment for *whether* and *when* to animate. Implementation code lives in `motion-cookbook.md` (cross-referenced below).
+---
+## Core Philosophy: Restraint & Purpose
+Emil's defining contribution to motion design thinking is knowing **when NOT to animate**.
+> "The goal is not to animate for animation's sake, it's to build great user interfaces."
+His key question for any interaction: **"Should this animate at all?"**
+### The Frequency Rule
+Animation appropriateness depends on interaction frequency:
+| Frequency | Recommendation |
+|-----------|----------------|
+| Rare (monthly) | Delightful, morphing animations welcome |
+| Occasional (daily) | Subtle, fast animations |
+| Frequent (100s/day) | No animation or instant transitions |
+| Keyboard-initiated | Never animate |
+**The Raycast example**: A tool used constantly throughout the day benefits from zero animation. Users with clear goals "don't expect to be delighted" and prioritize frictionless workflow.
+### Speed is Non-Negotiable
+> "UI animations should generally stay under 300ms."
+A 180ms animation feels more responsive than 400ms. Speed creates perceived performance. When in doubt, go faster.
+---
+## The 7 Practical Animation Tips
+Emil's decision checklist. Code for each is in the cookbook section noted.
+1. **Scale your buttons** — Subtle `scale(0.97)` on `:active` for immediate tactile feedback. → cookbook §10
+2. **Don't animate from `scale(0)`** — It creates unnatural motion. Start from `scale(0.9)` or higher. → cookbook §10
+3. **Tooltip delay patterns** — First tooltip in a group: delay + animation. Subsequent: instant. → cookbook §10
+4. **Custom easing is essential** — *"Easing is the most important part of any animation. It can make a bad animation feel great."* Built-in `ease`/`ease-in-out` lack strength; use custom Bézier curves (easing.dev, easings.co). → cookbook §2
+5. **Origin-aware animations** — Motion should originate from its logical source; a dropdown expands from its trigger, not from center. → cookbook §13
+6. **Keep animations fast** — Under 300ms for UI; remove animation entirely for high-frequency interactions.
+7. **Use blur when nothing else works** — `filter: blur(2px)` masks imperfections during rough state transitions. → cookbook §10
+---
+## Signature Techniques (decision context — code in cookbook)
+| Technique | When Emil reaches for it | Cookbook |
+|-----------|--------------------------|----------|
+| Clip-path animations | Reveals and tab transitions — hardware-accelerated, no layout shift, no extra DOM | §9 |
+| Spring physics | Any value that should interpolate smoothly rather than snap (e.g. mouse position) | §12 |
+| CSS transitions over keyframes | Anything the user can rapidly re-trigger — keyframes can't retarget mid-flight | §11 |
+| Direct style updates | Frequent updates like drag — CSS variables cause cascade recalculation | §11 |
+| Momentum-based dismissal | Swipe-to-dismiss — use velocity, not distance thresholds | §11 |
+---
+## Interruptibility
+Great animations can be interrupted mid-play and respond naturally. Framer Motion supports this natively; CSS transitions allow smooth interruption before completion. **Test by clicking rapidly** — animations should blend, not queue.
+---
+## When to Use Each Approach
+| Context | Approach |
+|---------|----------|
+| Keyboard shortcuts | No animation |
+| High-frequency tool | Minimal or no animation |
+| Daily-use feature | Fast, subtle animation (180-250ms) |
+| Onboarding/first-time | Delightful animations welcome |
+| Marketing/landing page | Full creative expression |
+| Banking/serious UI | Minimal, functional motion |
+| Playful brand | Bouncy, elastic easing appropriate |
+---
+## Invisible Quality: Lessons from Sonner & Vaul
+Emil's open-source libraries (Sonner for toasts, Vaul for drawers) reveal his philosophy in shipped code. The throughline: every detail serves **invisible quality** — users shouldn't notice polished interactions, they should just feel right.
+> "When a feature functions as you assume it should, you proceed without giving it a second thought, which is our goal."
+Details that matter: matching native motion curves for familiarity (Vaul uses iOS's `cubic-bezier(0.32, 0.72, 0, 1)`), damping near boundaries (*"things in real life don't suddenly stop, they slow down first"*), multi-touch protection, pointer capture during drags, pausing timers when the tab is inactive.
+### Sonner Defaults
+| Setting | Value | Rationale |
+|---------|-------|-----------|
+| Duration | 4000ms | Long enough to read, short enough to not annoy |
+| Animation | 400ms ease | Smooth but snappy |
+| Position | bottom-right | Convention, out of primary content |
+| Dismissible | true | User control by default |
+### Vaul Defaults
+| Setting | Value | Rationale |
+|---------|-------|-----------|
+| Duration | 500ms | Match iOS sheet feel |
+| Easing | cubic-bezier(0.32, 0.72, 0, 1) | iOS-native curve |
+| Modal | true | Focus management, overlay |
+| Direction | bottom | Convention for mobile sheets |
+---
+## Emil vs. Jakub vs. Jhey
+| Aspect | Emil | Jakub | Jhey |
+|--------|------|-------|------|
+| **Focus** | Restraint & speed | Subtle polish | Playful experimentation |
+| **Key question** | "Should this animate?" | "Is this subtle enough?" | "What could this become?" |
+| **Signature technique** | Frequency-based decisions | Blur + opacity + translateY | CSS custom properties |
+| **Ideal context** | High-frequency tools | Production polish | Learning & exploration |
+**Synthesis**: Use Emil's framework to decide IF you should animate. Use Jakub's techniques for HOW to animate in production. Use Jhey's approach for learning and experimentation.

package/src/skills-lib/design-motion-principles/references/jakub-krehel.md ADDED Viewed

@@ -0,0 +1,80 @@
+# Jakub Krehel's Animation Principles
+Jakub Krehel is a design engineer known for his work at jakub.kr. His approach emphasizes **subtle production polish** — animations that enhance the experience invisibly, designed for real client work where users interact repeatedly.
+This file is Jakub's **philosophy and decision frameworks** — the judgment for *how polished* and *how subtle* motion should be. Implementation code lives in `motion-cookbook.md` (cross-referenced below).
+---
+## Core Philosophy: Invisible Enhancement
+> "The best animation is that which goes unnoticed."
+His key question for any interaction: **"Is this subtle and polished enough for production?"**
+Jakub's work embodies **refinement for production use**. His animations are:
+- **Barely noticeable** — If users consciously notice the animation, it's probably too much
+- **Production-ready** — Designed for real client work, not demos
+- **Contextually appropriate** — Adapts to light mode, varied backgrounds, real content
+- **Subtle over flashy** — The goal is to make interfaces feel smooth and responsive, not impressive
+**The best compliment**: "This feels really nice" — not "cool animation!"
+**The test**: If you remove the animation, do users feel something is missing? Good. If users comment "nice animation!" every time they see it? Too prominent.
+---
+## When to Apply Jakub's Mindset
+- Production applications and client work
+- Professional/enterprise interfaces
+- When users will interact repeatedly (animations must not get tiresome)
+- When accessibility and performance are critical
+- When you need polish without distraction
+---
+## Signature Techniques (decision context — code in cookbook)
+| Technique | When Jakub reaches for it | Cookbook |
+|-----------|---------------------------|----------|
+| Enter recipe (opacity + translateY + blur) | Any element appearing — blur creates a "materializing" feel more physical than fade alone | §1 |
+| Subtler exits | Always — exits don't need the same movement or attention as enters; the user is moving on | §1 |
+| Spring animations (`bounce: 0`) | Production motion — smooth deceleration without overshoot; reserve `bounce > 0` for playful contexts | §2 |
+| Shadows instead of borders | Light mode on varied backgrounds — shadows adapt via transparency where solid borders clash | §3 |
+| oklch gradients | Any gradient — interpolates through perceptually uniform space, avoiding muddy midpoints | §3 |
+| Blur as a signal | Materializing in/out — blur→sharp = entering focus, sharp→blur = losing relevance | §3 |
+| Optical alignment | Buttons with icons, play buttons, asymmetric shapes — trust your eyes over math | §4 |
+| Animated icon swaps (opacity + scale + blur) | Contextual icon changes (copy→check) — instant swaps feel jarring and get missed | §5 |
+| Shared layout via `layoutId` | Smooth FLIP transitions between different components (card→modal) | §6 |
+| Targeted `will-change` | Specific properties about to animate — never global | see `performance.md` |
+**Decision rules baked into the techniques:**
+- Exits should always be subtler than enters — smaller movement, same blur.
+- `bounce: 0` is the production default; bounce above zero reads as playful.
+- Borders are fine in dark mode or when you want intentional hard edges.
+---
+## Common Mistakes (Jakub's Perspective)
+- **Making enter and exit animations equally prominent** — Exits should be subtler
+- **Using solid borders when shadows would adapt better** — Especially on varied backgrounds
+- **Forgetting optical alignment** — Buttons with icons, play buttons, asymmetric shapes
+- **Over-animating** — If users notice the animation itself, it's too much
+- **Using the same animation everywhere** — Context should drive timing and easing choices
+- **Ignoring hover state transitions** — Even small transitions (150-200ms) feel more polished than instant changes
+---
+## Jakub vs. Emil vs. Jhey
+| Aspect | Jakub | Emil | Jhey |
+|--------|-------|------|------|
+| **Focus** | Subtle polish | Restraint & speed | Playful experimentation |
+| **Key question** | "Is this subtle enough?" | "Should this animate?" | "What could this become?" |
+| **Signature technique** | Blur + opacity + translateY | Frequency-based decisions | CSS custom properties |
+| **Ideal context** | Production polish | High-frequency tools | Learning & exploration |
+**When to use Jakub**: You've decided something should animate (passed Emil's gate) and need to make it production-ready and polished.

package/src/skills-lib/design-motion-principles/references/jhey-tompkins.md ADDED Viewed

@@ -0,0 +1,122 @@
+# Jhey Tompkins' Animation Principles
+Jhey Tompkins (@jh3yy) is a design engineer known for pushing the boundaries of CSS and creative coding. His approach emphasizes **playful experimentation** — learning through building whimsical projects where the joy of creation drives skill development.
+This file is Jhey's **philosophy and decision frameworks** — the judgment for *creative expression* and *easing personality*. Implementation code lives in `motion-cookbook.md` (cross-referenced below).
+---
+## Core Philosophy: Learn Through Play
+> "I went from 'I want to learn X, so how do I fit it into Y' to 'I want to make Y, can I learn X to do it?'"
+His key question for any interaction: **"What could this become?"**
+**The motivation should be making something cool — learning is a happy side effect.**
+### Core Beliefs
+- **No idea is a bad idea** — Document every spark, however weird
+- **Don't ask "Why?" or "Is this practical?"** — Make what brings you joy first
+- **"Useless" demos teach real skills** — CSS art teaches clip-path mastery, border-radius tricks, stacking contexts
+- **Lateral learning** — Building diverse demos trains you to switch contexts and rise to challenges
+- **You'll never have time to make everything** — And that's okay. The act of documenting ideas matters.
+**Keep notebooks everywhere** — including by your bed. Creative sparks happen at random times.
+---
+## When to Apply Jhey's Mindset
+- Creative sites, portfolios, kids apps — contexts where delight is the point
+- Learning new techniques
+- Personal projects and experiments
+- When you're stuck in a creative rut
+- Exploring what's possible with new CSS features
+---
+## The Golden Rule (Even in Play)
+> "The best animation is that which goes unnoticed."
+Even in playful contexts, effective motion enhances the experience without demanding attention, feels natural and expected, serves a functional purpose, and doesn't fatigue users on repeated interactions.
+---
+## Easing Has Personality (Decision Framework)
+> "Duration is all about timing, and timing has a big impact on the movement's naturalness."
+Each easing curve communicates something. **Context matters more than rules.**
+> "You wouldn't use 'Elastic' for a bank's website, but it might work perfectly for an energetic site for children."
+Brand personality should drive easing choices — a playful brand can use bouncy/elastic easing, a professional brand should use subtle springs or `ease-out`.
+**When NOT to use bouncy/elastic easing:**
+- Professional/enterprise applications
+- Frequently repeated interactions (gets tiresome)
+- Error states or serious UI
+- When users need to complete tasks quickly
+(Easing-feel reference table and the `linear()` recipe for pure-CSS bounce/elastic/spring → cookbook §2.)
+---
+## Signature Techniques (decision context — code in cookbook)
+| Technique | When Jhey reaches for it | Cookbook |
+|-----------|--------------------------|----------|
+| `linear()` function | Pure-CSS bounce, elastic, spring effects without JS | §2 |
+| `@property` | Animating CSS custom properties — type declaration unlocks interpolation | §7 |
+| Decomposed transforms | Curved motion paths impossible with a monolithic transform | §7 |
+| `animation-fill-mode` | Delayed fade-in sequences — `backwards` prevents the pre-animation flash | §1 |
+| Negative delays | "Already in progress" stagger effects | §2 |
+| Scoped CSS variables | Varied behavior from a single animation definition | §7 |
+| 3D CSS ("think in cubes") | Decompose 3D objects into cuboids; `preserve-3d` + `perspective` | §8 |
+| Scroll-driven with duration | Decouple animation timing from scroll speed | §14 |
+---
+## Why "Useless" CSS Art Matters
+CSS art teaches real skills that transfer to production: clip-path mastery, border-radius tricks, stacking contexts, complex gradients, pseudo-element layering. For complex illustrations — break into simple shapes, use pseudo-elements liberally, layer with z-index carefully, use CSS variables for repeated values, don't fear many elements.
+---
+## When to Experiment vs. Ship
+| Situation | Approach |
+|-----------|----------|
+| Learning a new CSS feature | Build something weird and fun |
+| Portfolio piece | Push boundaries, show creativity |
+| Personal project | Follow your joy |
+| Client work | Apply Jakub's production polish instead |
+| High-frequency tool | Apply Emil's restraint instead |
+The playful approach is for **learning and exploration**. For production, switch to Jakub or Emil's mindset.
+---
+## Common Mistakes (Jhey's Perspective)
+- **Filtering ideas based on "usefulness" too early** — Make first, judge later
+- **Not documenting random creative sparks** — Keep notebooks everywhere
+- **Thinking CSS art is useless** — It teaches real skills
+- **Focusing on "How do I learn X?" instead of "How do I make Y?"** — Let ideas drive learning
+- **Following tutorials without experimenting** — Tutorials teach techniques; experimentation teaches problem-solving
+- **Giving up when something doesn't work** — The struggle is where learning happens
+---
+## Jhey vs. Emil vs. Jakub
+| Aspect | Jhey | Emil | Jakub |
+|--------|------|------|-------|
+| **Focus** | Playful experimentation | Restraint & speed | Subtle polish |
+| **Key question** | "What could this become?" | "Should this animate?" | "Is this subtle enough?" |
+| **Signature technique** | CSS custom properties | Frequency-based decisions | Blur + opacity + translateY |
+| **Ideal context** | Learning & exploration | High-frequency tools | Production polish |
+**When to use Jhey**: You're building something where delight is the goal, exploring what's possible, or learning a new technique. The skills transfer to production work later.