niahere 0.2.61 → 0.2.63

package/skills/userinterface-wiki/rules/container-no-excessive-use.md

@@ -0,0 +1,13 @@
+---
+title: Use Animated Bounds Sparingly
+impact: MEDIUM
+tags: container, performance, restraint
+---
+
+## Use Animated Bounds Sparingly
+
+Animated bounds is a subtle effect. Use it for buttons, accordions, and interactive elements — not everywhere.
+
+**Good use cases:** loading state buttons, expandable sections, accordions, FAQs, content reveals.
+
+**Bad use cases:** every container on the page, static layouts, elements that don't change size.

package/skills/userinterface-wiki/rules/container-overflow-hidden.md

@@ -0,0 +1,25 @@
+---
+title: Overflow Hidden on Animated Container
+impact: MEDIUM
+tags: container, overflow, clip
+---
+
+## Overflow Hidden on Animated Container
+
+Set overflow: hidden on the animated outer container to clip content during size transitions.
+
+**Incorrect (content overflows during animation):**
+
+```tsx
+<motion.div animate={{ height: bounds.height }}>
+  <div ref={ref}>{children}</div>
+</motion.div>
+```
+
+**Correct (clipped during transition):**
+
+```tsx
+<motion.div animate={{ height: bounds.height }} style={{ overflow: "hidden" }}>
+  <div ref={ref}>{children}</div>
+</motion.div>
+```

package/skills/userinterface-wiki/rules/container-transition-delay.md

@@ -0,0 +1,21 @@
+---
+title: Add Delay for Natural Container Transitions
+impact: LOW
+tags: container, delay, transition, natural
+---
+
+## Add Delay for Natural Container Transitions
+
+Add a small delay to container size animations so the transition feels like it's catching up to the content.
+
+**Correct:**
+
+```tsx
+<motion.div
+  animate={{ height: bounds.height }}
+  transition={{ duration: 0.2, delay: 0.05 }}
+  style={{ overflow: "hidden" }}
+>
+  <div ref={ref}>{children}</div>
+</motion.div>
+```

package/skills/userinterface-wiki/rules/container-two-div-pattern.md

@@ -0,0 +1,35 @@
+---
+title: Two-Div Pattern for Animated Bounds
+impact: HIGH
+tags: container, measure, motion
+---
+
+## Two-Div Pattern for Animated Bounds
+
+Use an outer animated div and an inner measured div. Never measure and animate the same element.
+
+**Incorrect (measure and animate same element — creates feedback loop):**
+
+```tsx
+function AnimatedContainer({ children }) {
+  const [ref, bounds] = useMeasure();
+  return (
+    <motion.div ref={ref} animate={{ height: bounds.height }}>
+      {children}
+    </motion.div>
+  );
+}
+```
+
+**Correct (separate measure and animate targets):**
+
+```tsx
+function AnimatedContainer({ children }) {
+  const [ref, bounds] = useMeasure();
+  return (
+    <motion.div animate={{ height: bounds.height }}>
+      <div ref={ref}>{children}</div>
+    </motion.div>
+  );
+}
+```

package/skills/userinterface-wiki/rules/container-use-resize-observer.md

@@ -0,0 +1,48 @@
+---
+title: Use ResizeObserver for Measurement
+impact: MEDIUM
+tags: container, resize-observer, performance
+---
+
+## Use ResizeObserver for Measurement
+
+Use ResizeObserver to track element dimensions. It fires on resize without causing layout thrashing.
+
+**Incorrect (measuring on every render):**
+
+```tsx
+function useMeasure(ref) {
+  const [bounds, setBounds] = useState({ width: 0, height: 0 });
+  useEffect(() => {
+    if (ref.current) {
+      const rect = ref.current.getBoundingClientRect();
+      setBounds({ width: rect.width, height: rect.height });
+    }
+  });
+  return bounds;
+}
+```
+
+**Correct (ResizeObserver):**
+
+```tsx
+function useMeasure() {
+  const [element, setElement] = useState(null);
+  const [bounds, setBounds] = useState({ width: 0, height: 0 });
+  const ref = useCallback((node) => setElement(node), []);
+
+  useEffect(() => {
+    if (!element) return;
+    const observer = new ResizeObserver(([entry]) => {
+      setBounds({
+        width: entry.contentRect.width,
+        height: entry.contentRect.height,
+      });
+    });
+    observer.observe(element);
+    return () => observer.disconnect();
+  }, [element]);
+
+  return [ref, bounds];
+}
+```

package/skills/userinterface-wiki/rules/context-cleanup-nodes.md

@@ -0,0 +1,25 @@
+---
+title: Clean Up Audio Nodes After Playback
+impact: MEDIUM
+tags: context, cleanup, disconnect
+---
+
+## Clean Up Audio Nodes After Playback
+
+Disconnect and clean up audio nodes after playback.
+
+**Incorrect (nodes remain connected):**
+
+```ts
+source.start();
+```
+
+**Correct (cleaned up on end):**
+
+```ts
+source.start();
+source.onended = () => {
+  source.disconnect();
+  gain.disconnect();
+};
+```

package/skills/userinterface-wiki/rules/context-resume-suspended.md

@@ -0,0 +1,28 @@
+---
+title: Resume Suspended AudioContext
+impact: HIGH
+tags: context, resume, suspended
+---
+
+## Resume Suspended AudioContext
+
+Check and resume suspended AudioContext before playing.
+
+**Incorrect (plays without checking):**
+
+```ts
+function playSound() {
+  const ctx = getAudioContext();
+}
+```
+
+**Correct (resumes if suspended):**
+
+```ts
+function playSound() {
+  const ctx = getAudioContext();
+  if (ctx.state === "suspended") {
+    ctx.resume();
+  }
+}
+```

package/skills/userinterface-wiki/rules/context-reuse-single.md

@@ -0,0 +1,30 @@
+---
+title: Reuse Single AudioContext
+impact: HIGH
+tags: context, audio-context, singleton
+---
+
+## Reuse Single AudioContext
+
+Reuse a single AudioContext instance; do not create new ones per sound.
+
+**Incorrect (new context per call):**
+
+```ts
+function playSound() {
+  const ctx = new AudioContext();
+}
+```
+
+**Correct (singleton):**
+
+```ts
+let audioContext: AudioContext | null = null;
+
+function getAudioContext(): AudioContext {
+  if (!audioContext) {
+    audioContext = new AudioContext();
+  }
+  return audioContext;
+}
+```

package/skills/userinterface-wiki/rules/design-filter-for-character.md

@@ -0,0 +1,25 @@
+---
+title: Bandpass Filter for Sound Character
+impact: MEDIUM
+tags: design, filter, bandpass
+---
+
+## Bandpass Filter for Sound Character
+
+Apply bandpass filter to shape percussive sounds.
+
+**Incorrect (raw noise):**
+
+```ts
+source.connect(gain).connect(ctx.destination);
+```
+
+**Correct (filtered noise):**
+
+```ts
+const filter = ctx.createBiquadFilter();
+filter.type = "bandpass";
+filter.frequency.value = 4000;
+filter.Q.value = 3;
+source.connect(filter).connect(gain).connect(ctx.destination);
+```

package/skills/userinterface-wiki/rules/design-noise-for-percussion.md

@@ -0,0 +1,26 @@
+---
+title: Noise for Percussive Sounds
+impact: MEDIUM
+tags: design, noise, percussion
+---
+
+## Noise for Percussive Sounds
+
+Use filtered noise for clicks/taps, not oscillators.
+
+**Incorrect (oscillator for click):**
+
+```ts
+const osc = ctx.createOscillator();
+osc.type = "sine";
+```
+
+**Correct (noise burst for click):**
+
+```ts
+const buffer = ctx.createBuffer(1, ctx.sampleRate * 0.008, ctx.sampleRate);
+const data = buffer.getChannelData(0);
+for (let i = 0; i < data.length; i++) {
+  data[i] = (Math.random() * 2 - 1) * Math.exp(-i / 50);
+}
+```

package/skills/userinterface-wiki/rules/design-oscillator-for-tonal.md

@@ -0,0 +1,22 @@
+---
+title: Oscillators for Tonal Sounds
+impact: MEDIUM
+tags: design, oscillator, tonal
+---
+
+## Oscillators for Tonal Sounds
+
+Use oscillators with pitch movement for tonal sounds (pops, confirmations).
+
+**Incorrect (static frequency):**
+
+```ts
+osc.frequency.value = 400;
+```
+
+**Correct (pitch sweep):**
+
+```ts
+osc.frequency.setValueAtTime(400, t);
+osc.frequency.exponentialRampToValueAtTime(600, t + 0.04);
+```

package/skills/userinterface-wiki/rules/duration-max-300ms.md

@@ -0,0 +1,21 @@
+---
+title: Max 300ms for User Actions
+impact: HIGH
+tags: duration, max, user-action
+---
+
+## Max 300ms for User Actions
+
+User-initiated animations must not exceed 300ms.
+
+**Incorrect (exceeds limit):**
+
+```tsx
+<motion.div transition={{ duration: 0.5 }} />
+```
+
+**Correct (within limit):**
+
+```tsx
+<motion.div transition={{ duration: 0.25 }} />
+```

package/skills/userinterface-wiki/rules/duration-press-hover.md

@@ -0,0 +1,21 @@
+---
+title: Press and Hover 120-180ms
+impact: MEDIUM
+tags: duration, press, hover
+---
+
+## Press and Hover 120-180ms
+
+Press and hover interactions should use 120-180ms duration.
+
+**Incorrect (too slow):**
+
+```css
+.button:hover { transition: background-color 400ms; }
+```
+
+**Correct (appropriate duration):**
+
+```css
+.button:hover { transition: background-color 150ms; }
+```

package/skills/userinterface-wiki/rules/duration-shorten-before-curve.md

@@ -0,0 +1,21 @@
+---
+title: Shorten Duration Before Adjusting Curve
+impact: MEDIUM
+tags: duration, optimization
+---
+
+## Shorten Duration Before Adjusting Curve
+
+If animation feels slow, shorten duration before adjusting curve.
+
+**Incorrect (adjusting curve instead):**
+
+```css
+.element { transition: 400ms cubic-bezier(0, 0.9, 0.1, 1); }
+```
+
+**Correct (shorter duration):**
+
+```css
+.element { transition: 200ms ease-out; }
+```

package/skills/userinterface-wiki/rules/duration-small-state.md

@@ -0,0 +1,15 @@
+---
+title: Small State Changes 180-260ms
+impact: MEDIUM
+tags: duration, state-change
+---
+
+## Small State Changes 180-260ms
+
+Small state changes should use 180-260ms duration.
+
+**Correct:**
+
+```css
+.toggle { transition: transform 200ms ease; }
+```

package/skills/userinterface-wiki/rules/easing-entrance-ease-out.md

@@ -0,0 +1,21 @@
+---
+title: Ease-Out for Entrances
+impact: HIGH
+tags: easing, entrance, ease-out
+---
+
+## Ease-Out for Entrances
+
+Entrances must use ease-out (arrive fast, settle gently).
+
+**Incorrect (ease-in for entrance):**
+
+```css
+.modal-enter { animation-timing-function: ease-in; }
+```
+
+**Correct (ease-out for entrance):**
+
+```css
+.modal-enter { animation-timing-function: ease-out; }
+```

package/skills/userinterface-wiki/rules/easing-exit-ease-in.md

@@ -0,0 +1,21 @@
+---
+title: Ease-In for Exits
+impact: HIGH
+tags: easing, exit, ease-in
+---
+
+## Ease-In for Exits
+
+Exits must use ease-in (build momentum before departure).
+
+**Incorrect (ease-out for exit):**
+
+```css
+.modal-exit { animation-timing-function: ease-out; }
+```
+
+**Correct (ease-in for exit):**
+
+```css
+.modal-exit { animation-timing-function: ease-in; }
+```

package/skills/userinterface-wiki/rules/easing-for-state-change.md

@@ -0,0 +1,27 @@
+---
+title: Easing for System State Changes
+impact: HIGH
+tags: easing, state-change, system
+---
+
+## Easing for System State Changes
+
+System-initiated state changes should use easing curves.
+
+**Incorrect (spring for announcement):**
+
+```tsx
+<motion.div
+  animate={{ y: 0 }}
+  transition={{ type: "spring" }}
+/>
+```
+
+**Correct (easing for announcement):**
+
+```tsx
+<motion.div
+  animate={{ y: 0 }}
+  transition={{ duration: 0.2, ease: "easeOut" }}
+/>
+```

package/skills/userinterface-wiki/rules/easing-linear-only-progress.md

@@ -0,0 +1,21 @@
+---
+title: Linear Easing Only for Progress
+impact: MEDIUM
+tags: easing, linear, progress
+---
+
+## Linear Easing Only for Progress
+
+Linear easing only for progress bars and time representation.
+
+**Incorrect (linear for motion):**
+
+```css
+.card-slide { transition: transform 200ms linear; }
+```
+
+**Correct (linear for progress):**
+
+```css
+.progress-bar { transition: width 100ms linear; }
+```

package/skills/userinterface-wiki/rules/easing-natural-decay.md

@@ -0,0 +1,22 @@
+---
+title: Exponential Ramps for Natural Decay
+impact: MEDIUM
+impactDescription: Linear ramps for decay produce abrupt, unnatural cutoffs; exponential ramps match perceptual expectations.
+tags: easing, decay, audio, animation
+---
+
+## Exponential Ramps for Natural Decay
+
+Use exponential ramps, not linear, for natural decay.
+
+**Incorrect (linear ramp):**
+
+```ts
+gain.gain.linearRampToValueAtTime(0, t + 0.05);
+```
+
+**Correct (exponential ramp):**
+
+```ts
+gain.gain.exponentialRampToValueAtTime(0.001, t + 0.05);
+```

package/skills/userinterface-wiki/rules/easing-no-linear-motion.md

@@ -0,0 +1,22 @@
+---
+title: No Linear Easing for Motion
+impact: MEDIUM
+impactDescription: Linear easing for motion feels mechanical; reserve it for progress indicators where uniform speed is expected.
+tags: easing, linear, animation
+---
+
+## No Linear Easing for Motion
+
+Linear easing should only be used for progress indicators, not motion.
+
+**Incorrect (linear for motion):**
+
+```css
+.card { transition: transform 200ms linear; }
+```
+
+**Correct (linear for progress only):**
+
+```css
+.progress-bar { transition: width 100ms linear; }
+```

package/skills/userinterface-wiki/rules/easing-transition-ease-in-out.md

@@ -0,0 +1,15 @@
+---
+title: Ease-In-Out for View Transitions
+impact: MEDIUM
+tags: easing, transition, ease-in-out
+---
+
+## Ease-In-Out for View Transitions
+
+View/mode transitions use ease-in-out for neutral attention.
+
+**Correct:**
+
+```css
+.page-transition { animation-timing-function: ease-in-out; }
+```

package/skills/userinterface-wiki/rules/envelope-exponential-decay.md

@@ -0,0 +1,21 @@
+---
+title: Exponential Decay for Natural Sound
+impact: HIGH
+tags: envelope, decay, exponential
+---
+
+## Exponential Decay for Natural Sound
+
+Use exponential ramps for natural decay, not linear.
+
+**Incorrect (linear ramp):**
+
+```ts
+gain.gain.linearRampToValueAtTime(0, t + 0.05);
+```
+
+**Correct (exponential ramp):**
+
+```ts
+gain.gain.exponentialRampToValueAtTime(0.001, t + 0.05);
+```

package/skills/userinterface-wiki/rules/envelope-no-zero-target.md

@@ -0,0 +1,21 @@
+---
+title: No Zero Target for Exponential Ramps
+impact: HIGH
+tags: envelope, exponential, zero
+---
+
+## No Zero Target for Exponential Ramps
+
+Exponential ramps cannot target 0; use 0.001 or similar small value.
+
+**Incorrect (targets zero):**
+
+```ts
+gain.gain.exponentialRampToValueAtTime(0, t + 0.05);
+```
+
+**Correct (targets near-zero):**
+
+```ts
+gain.gain.exponentialRampToValueAtTime(0.001, t + 0.05);
+```

package/skills/userinterface-wiki/rules/envelope-set-initial-value.md

@@ -0,0 +1,22 @@
+---
+title: Set Initial Value Before Ramp
+impact: MEDIUM
+tags: envelope, initial, glitch
+---
+
+## Set Initial Value Before Ramp
+
+Set initial value before ramping to avoid glitches.
+
+**Incorrect (no initial value):**
+
+```ts
+gain.gain.exponentialRampToValueAtTime(0.001, t + 0.05);
+```
+
+**Correct (initial value set):**
+
+```ts
+gain.gain.setValueAtTime(0.3, t);
+gain.gain.exponentialRampToValueAtTime(0.001, t + 0.05);
+```

package/skills/userinterface-wiki/rules/exit-key-required.md

@@ -0,0 +1,29 @@
+---
+title: Unique Keys in AnimatePresence Lists
+impact: HIGH
+tags: exit, key, list
+---
+
+## Unique Keys in AnimatePresence Lists
+
+Dynamic lists inside AnimatePresence must have unique keys.
+
+**Incorrect (index as key):**
+
+```tsx
+<AnimatePresence>
+  {items.map((item, index) => (
+    <motion.div key={index} exit={{ opacity: 0 }} />
+  ))}
+</AnimatePresence>
+```
+
+**Correct (stable unique key):**
+
+```tsx
+<AnimatePresence>
+  {items.map((item) => (
+    <motion.div key={item.id} exit={{ opacity: 0 }} />
+  ))}
+</AnimatePresence>
+```

package/skills/userinterface-wiki/rules/exit-matches-initial.md

@@ -0,0 +1,29 @@
+---
+title: Exit Mirrors Initial for Symmetry
+impact: MEDIUM
+tags: exit, initial, symmetry
+---
+
+## Exit Mirrors Initial for Symmetry
+
+Exit animation should mirror initial for symmetry.
+
+**Incorrect (asymmetric exit):**
+
+```tsx
+<motion.div
+  initial={{ opacity: 0, y: 20 }}
+  animate={{ opacity: 1, y: 0 }}
+  exit={{ scale: 0 }}
+/>
+```
+
+**Correct (symmetric exit):**
+
+```tsx
+<motion.div
+  initial={{ opacity: 0, y: 20 }}
+  animate={{ opacity: 1, y: 0 }}
+  exit={{ opacity: 0, y: 20 }}
+/>
+```