niahere 0.2.61 → 0.2.63

package/skills/userinterface-wiki/rules/none-keyboard-navigation.md

@@ -0,0 +1,32 @@
+---
+title: No Animation for Keyboard Navigation
+impact: MEDIUM
+tags: none, keyboard, a11y
+---
+
+## No Animation for Keyboard Navigation
+
+Keyboard navigation should be instant, no animation.
+
+**Incorrect (animated focus):**
+
+```tsx
+function Menu() {
+  return items.map(item => (
+    <motion.li
+      whileFocus={{ scale: 1.05 }}
+      transition={{ duration: 0.2 }}
+    />
+  ));
+}
+```
+
+**Correct (CSS focus-visible only):**
+
+```tsx
+function Menu() {
+  return items.map(item => (
+    <li className={styles.menuItem} />
+  ));
+}
+```

package/skills/userinterface-wiki/rules/param-click-duration.md

@@ -0,0 +1,21 @@
+---
+title: Click Duration 5-15ms
+impact: MEDIUM
+tags: param, click, duration
+---
+
+## Click Duration 5-15ms
+
+Click/tap sounds should be 5-15ms duration.
+
+**Incorrect (too long):**
+
+```ts
+const buffer = ctx.createBuffer(1, ctx.sampleRate * 0.1, ctx.sampleRate);
+```
+
+**Correct (appropriate duration):**
+
+```ts
+const buffer = ctx.createBuffer(1, ctx.sampleRate * 0.008, ctx.sampleRate);
+```

package/skills/userinterface-wiki/rules/param-filter-frequency-range.md

@@ -0,0 +1,21 @@
+---
+title: Click Filter 3000-6000Hz
+impact: LOW
+tags: param, filter, frequency
+---
+
+## Click Filter 3000-6000Hz
+
+Bandpass filter for clicks should be 3000-6000Hz.
+
+**Incorrect (too low):**
+
+```ts
+filter.frequency.value = 500;
+```
+
+**Correct (crisp range):**
+
+```ts
+filter.frequency.value = 4000;
+```

package/skills/userinterface-wiki/rules/param-q-value-range.md

@@ -0,0 +1,21 @@
+---
+title: Filter Q Value 2-5
+impact: LOW
+tags: param, q-value, filter
+---
+
+## Filter Q Value 2-5
+
+Filter Q for clicks should be 2-5 for focused but not harsh sound.
+
+**Incorrect (too resonant):**
+
+```ts
+filter.Q.value = 15;
+```
+
+**Correct (balanced Q):**
+
+```ts
+filter.Q.value = 3;
+```

package/skills/userinterface-wiki/rules/param-reasonable-gain.md

@@ -0,0 +1,21 @@
+---
+title: Gain Under 1.0
+impact: MEDIUM
+tags: param, gain, clipping
+---
+
+## Gain Under 1.0
+
+Gain values should not exceed 1.0 to prevent clipping.
+
+**Incorrect (clipping):**
+
+```ts
+gain.gain.setValueAtTime(1.5, t);
+```
+
+**Correct (safe gain):**
+
+```ts
+gain.gain.setValueAtTime(0.3, t);
+```

package/skills/userinterface-wiki/rules/physics-active-state.md

@@ -0,0 +1,23 @@
+---
+title: Active State Scale Transform
+impact: HIGH
+impactDescription: Missing active state makes interactive elements feel unresponsive and reduces tactile feedback.
+tags: physics, interaction, active-state
+---
+
+## Active State Scale Transform
+
+Interactive elements must have active/pressed state with scale transform.
+
+**Incorrect (no active state):**
+
+```css
+.button:hover { background: var(--gray-3); }
+/* Missing :active state */
+```
+
+**Correct (active state present):**
+
+```css
+.button:active { transform: scale(0.98); }
+```

package/skills/userinterface-wiki/rules/physics-no-excessive-stagger.md

@@ -0,0 +1,22 @@
+---
+title: Stagger Under 50ms Per Item
+impact: MEDIUM
+impactDescription: Excessive stagger delays list readiness and feels sluggish; keep per-item delay minimal.
+tags: physics, stagger, list-animation
+---
+
+## Stagger Under 50ms Per Item
+
+Stagger delays must not exceed 50ms per item.
+
+**Incorrect (excessive stagger):**
+
+```tsx
+transition={{ staggerChildren: 0.15 }}
+```
+
+**Correct (reasonable stagger):**
+
+```tsx
+transition={{ staggerChildren: 0.03 }}
+```

package/skills/userinterface-wiki/rules/physics-spring-for-overshoot.md

@@ -0,0 +1,23 @@
+---
+title: Springs for Overshoot and Settle
+impact: HIGH
+impactDescription: Easing cannot produce natural overshoot; springs are required for organic bounce-and-settle motion.
+tags: physics, spring, overshoot
+---
+
+## Springs for Overshoot and Settle
+
+Use springs (not easing) when overshoot-and-settle is needed.
+
+**Incorrect (easing for bounce):**
+
+```tsx
+<motion.div transition={{ duration: 0.3, ease: "easeOut" }} />
+// When element should bounce/settle
+```
+
+**Correct (spring physics):**
+
+```tsx
+<motion.div transition={{ type: "spring", stiffness: 500, damping: 30 }} />
+```

package/skills/userinterface-wiki/rules/physics-subtle-deformation.md

@@ -0,0 +1,22 @@
+---
+title: Subtle Squash and Stretch
+impact: MEDIUM
+impactDescription: Excessive squash/stretch feels cartoonish and distracts from the interface; subtle deformation adds polish.
+tags: physics, squash-stretch, deformation
+---
+
+## Subtle Squash and Stretch
+
+Squash/stretch deformation must be subtle (0.95-1.05 range).
+
+**Incorrect (excessive deformation):**
+
+```tsx
+<motion.div whileTap={{ scale: 0.8 }} />
+```
+
+**Correct (subtle deformation):**
+
+```tsx
+<motion.div whileTap={{ scale: 0.98 }} />
+```

package/skills/userinterface-wiki/rules/prefetch-hit-slop.md

@@ -0,0 +1,27 @@
+---
+title: Use hitSlop to Trigger Predictions Earlier
+impact: MEDIUM
+tags: prefetch, hit-slop, target
+---
+
+## Use hitSlop to Trigger Predictions Earlier
+
+Expand the invisible prediction area around elements with hitSlop to start loading sooner.
+
+**Incorrect (tight prediction area):**
+
+```tsx
+const { elementRef } = useForesight({
+  callback: () => prefetch(),
+  hitSlop: 0,
+});
+```
+
+**Correct (expanded prediction area):**
+
+```tsx
+const { elementRef } = useForesight({
+  callback: () => prefetch(),
+  hitSlop: 20,
+});
+```

package/skills/userinterface-wiki/rules/prefetch-keyboard-tab.md

@@ -0,0 +1,19 @@
+---
+title: Prefetch on Keyboard Navigation
+impact: MEDIUM
+tags: prefetch, keyboard, tab, a11y
+---
+
+## Prefetch on Keyboard Navigation
+
+Monitor focus changes and prefetch when the user is a few tab stops away from a registered element.
+
+**Correct (tab-aware prefetching):**
+
+```tsx
+const { elementRef } = useForesight({
+  callback: () => router.prefetch("/settings"),
+  name: "settings-link",
+  // Tab prediction fires when focus approaches
+});
+```

package/skills/userinterface-wiki/rules/prefetch-not-everything.md

@@ -0,0 +1,22 @@
+---
+title: Prefetch by Intent, Not Viewport
+impact: HIGH
+tags: prefetch, viewport, intent, bundle-size
+---
+
+## Prefetch by Intent, Not Viewport
+
+Don't prefetch everything visible in the viewport. Prefetch based on user intent to avoid wasted bandwidth.
+
+**Incorrect (prefetch all visible links):**
+
+```tsx
+<Link href="/page" prefetch={true}>Page</Link>
+```
+
+**Correct (intent-based prefetching):**
+
+```tsx
+<Link href="/page" prefetch={false}>Page</Link>
+// Let trajectory/hover prediction handle it
+```

package/skills/userinterface-wiki/rules/prefetch-touch-fallback.md

@@ -0,0 +1,34 @@
+---
+title: Fall Back Gracefully on Touch Devices
+impact: MEDIUM
+tags: prefetch, touch, mobile, fallback
+---
+
+## Fall Back Gracefully on Touch Devices
+
+Touch devices have no cursor. Fall back to viewport or touch-start strategies automatically.
+
+**Incorrect (assumes cursor exists):**
+
+```tsx
+function PrefetchLink({ href, children }) {
+  return (
+    <Link
+      href={href}
+      onMouseMove={() => prefetch(href)}
+    >
+      {children}
+    </Link>
+  );
+}
+```
+
+**Correct (device-aware strategy):**
+
+```tsx
+const { elementRef } = useForesight({
+  callback: () => router.prefetch(href),
+  hitSlop: 20,
+});
+// Automatically falls back to touch-start on mobile
+```

package/skills/userinterface-wiki/rules/prefetch-trajectory-over-hover.md

@@ -0,0 +1,32 @@
+---
+title: Trajectory Prediction Over Hover Prefetching
+impact: HIGH
+tags: prefetch, trajectory, hover, performance
+---
+
+## Trajectory Prediction Over Hover Prefetching
+
+Hover prefetching starts too late. Trajectory prediction fires while the cursor is still in motion, reclaiming 100-200ms.
+
+**Incorrect (waits for hover):**
+
+```tsx
+<Link
+  href="/about"
+  onMouseEnter={() => router.prefetch("/about")}
+>
+  About
+</Link>
+```
+
+**Correct (trajectory-based):**
+
+```tsx
+const { elementRef } = useForesight({
+  callback: () => router.prefetch("/about"),
+  hitSlop: 20,
+  name: "about-link",
+});
+
+<Link ref={elementRef} href="/about">About</Link>
+```

package/skills/userinterface-wiki/rules/prefetch-use-selectively.md

@@ -0,0 +1,13 @@
+---
+title: Use Predictive Prefetching Selectively
+impact: MEDIUM
+tags: prefetch, selective, performance
+---
+
+## Use Predictive Prefetching Selectively
+
+Predictive prefetching doesn't belong in every project. Use it where navigation latency is noticeable.
+
+**Good use cases:** data-heavy dashboards, multi-page apps with slow API responses, e-commerce product pages.
+
+**Bad use cases:** static sites with instant navigation, single-page apps with all data preloaded.

package/skills/userinterface-wiki/rules/presence-disable-interactions.md

@@ -0,0 +1,31 @@
+---
+title: Disable Interactions on Exiting Elements
+impact: MEDIUM
+tags: presence, interaction, exit
+---
+
+## Disable Interactions on Exiting Elements
+
+Disable interactions on exiting elements using isPresent.
+
+**Incorrect (clickable during exit):**
+
+```tsx
+function Card() {
+  const isPresent = useIsPresent();
+  return <button onClick={handleClick}>Click</button>;
+}
+```
+
+**Correct (disabled during exit):**
+
+```tsx
+function Card() {
+  const isPresent = useIsPresent();
+  return (
+    <button onClick={handleClick} disabled={!isPresent}>
+      Click
+    </button>
+  );
+}
+```

package/skills/userinterface-wiki/rules/presence-hook-in-child.md

@@ -0,0 +1,31 @@
+---
+title: useIsPresent in Child Component
+impact: HIGH
+tags: presence, hook, component-hierarchy
+---
+
+## useIsPresent in Child Component
+
+useIsPresent must be called from child of AnimatePresence, not parent.
+
+**Incorrect (hook in parent):**
+
+```tsx
+function Parent() {
+  const isPresent = useIsPresent();
+  return (
+    <AnimatePresence>
+      {show && <Child />}
+    </AnimatePresence>
+  );
+}
+```
+
+**Correct (hook in child):**
+
+```tsx
+function Child() {
+  const isPresent = useIsPresent();
+  return <motion.div data-exiting={!isPresent} />;
+}
+```

package/skills/userinterface-wiki/rules/presence-safe-to-remove.md

@@ -0,0 +1,37 @@
+---
+title: Call safeToRemove After Async Work
+impact: HIGH
+tags: presence, safe-to-remove, async
+---
+
+## Call safeToRemove After Async Work
+
+When using usePresence, always call safeToRemove after async work.
+
+**Incorrect (missing safeToRemove):**
+
+```tsx
+function AsyncComponent() {
+  const [isPresent, safeToRemove] = usePresence();
+
+  useEffect(() => {
+    if (!isPresent) {
+      cleanup();
+    }
+  }, [isPresent]);
+}
+```
+
+**Correct (safeToRemove called):**
+
+```tsx
+function AsyncComponent() {
+  const [isPresent, safeToRemove] = usePresence();
+
+  useEffect(() => {
+    if (!isPresent) {
+      cleanup().then(safeToRemove);
+    }
+  }, [isPresent, safeToRemove]);
+}
+```

package/skills/userinterface-wiki/rules/pseudo-content-required.md

@@ -0,0 +1,28 @@
+---
+title: Content Property Required for Pseudo-Elements
+impact: HIGH
+tags: pseudo, content, before-after
+---
+
+## Content Property Required for Pseudo-Elements
+
+::before and ::after require content property to render.
+
+**Incorrect (missing content):**
+
+```css
+.button::before {
+  position: absolute;
+  background: var(--gray-3);
+}
+```
+
+**Correct (content set):**
+
+```css
+.button::before {
+  content: "";
+  position: absolute;
+  background: var(--gray-3);
+}
+```

package/skills/userinterface-wiki/rules/pseudo-first-line-styling.md

@@ -0,0 +1,27 @@
+---
+title: Use ::first-line for Typographic Treatments
+impact: LOW
+tags: pseudo, first-line, typography
+---
+
+## Use ::first-line for Typographic Treatments
+
+Use ::first-line for drop-cap-adjacent styling without JavaScript or hardcoded spans.
+
+**Incorrect (manual span):**
+
+```tsx
+<p>
+  <span className={styles["first-line"]}>The opening line of this paragraph</span>
+  is styled differently from the rest.
+</p>
+```
+
+**Correct (native ::first-line):**
+
+```css
+.article p:first-of-type::first-line {
+  font-variant-caps: small-caps;
+  font-weight: var(--font-weight-medium);
+}
+```

package/skills/userinterface-wiki/rules/pseudo-hit-target-expansion.md

@@ -0,0 +1,31 @@
+---
+title: Hit Target Expansion with Pseudo-Elements
+impact: MEDIUM
+tags: pseudo, hit-target, accessibility
+---
+
+## Hit Target Expansion with Pseudo-Elements
+
+Use negative inset values to expand hit targets without extra markup.
+
+**Incorrect (wrapper for hit target):**
+
+```tsx
+<div className={styles.wrapper}>
+  <a className={styles.link}>Link</a>
+</div>
+```
+
+**Correct (pseudo-element expansion):**
+
+```css
+.link {
+  position: relative;
+}
+
+.link::before {
+  content: "";
+  position: absolute;
+  inset: -8px -12px;
+}
+```

package/skills/userinterface-wiki/rules/pseudo-marker-styling.md

@@ -0,0 +1,28 @@
+---
+title: Use ::marker for Custom List Bullets
+impact: LOW
+tags: pseudo, marker, list, bullets
+---
+
+## Use ::marker for Custom List Bullets
+
+Use ::marker to style list bullets without extra elements or background-image hacks.
+
+**Incorrect (background image hack):**
+
+```css
+li {
+  list-style: none;
+  background: url("bullet.svg") no-repeat 0 4px;
+  padding-left: 20px;
+}
+```
+
+**Correct (native ::marker):**
+
+```css
+li::marker {
+  color: var(--gray-8);
+  font-size: 0.8em;
+}
+```

package/skills/userinterface-wiki/rules/pseudo-over-dom-node.md

@@ -0,0 +1,32 @@
+---
+title: Pseudo-Elements Over DOM Nodes
+impact: MEDIUM
+tags: pseudo, dom, decorative
+---
+
+## Pseudo-Elements Over DOM Nodes
+
+Use pseudo-elements for decorative content instead of extra DOM nodes.
+
+**Incorrect (extra DOM node):**
+
+```tsx
+<button className={styles.button}>
+  <span className={styles.background} />
+  Click me
+</button>
+```
+
+**Correct (pseudo-element):**
+
+```tsx
+<button className={styles.button}>
+  Click me
+</button>
+```
+```css
+.button::before {
+  content: "";
+  /* decorative background */
+}
+```

package/skills/userinterface-wiki/rules/pseudo-position-relative-parent.md

@@ -0,0 +1,33 @@
+---
+title: Position Relative Parent for Pseudo-Elements
+impact: HIGH
+tags: pseudo, position, relative
+---
+
+## Position Relative Parent for Pseudo-Elements
+
+Parent must have position: relative for absolute pseudo-elements.
+
+**Incorrect (no position on parent):**
+
+```css
+.button::before {
+  content: "";
+  position: absolute;
+  inset: 0;
+}
+```
+
+**Correct (parent positioned):**
+
+```css
+.button {
+  position: relative;
+}
+
+.button::before {
+  content: "";
+  position: absolute;
+  inset: 0;
+}
+```

package/skills/userinterface-wiki/rules/pseudo-z-index-layering.md

@@ -0,0 +1,37 @@
+---
+title: Z-Index Layering for Pseudo-Elements
+impact: MEDIUM
+tags: pseudo, z-index, layering
+---
+
+## Z-Index Layering for Pseudo-Elements
+
+Pseudo-elements need z-index to layer correctly with content.
+
+**Incorrect (covers text):**
+
+```css
+.button::before {
+  content: "";
+  position: absolute;
+  inset: 0;
+  background: var(--gray-3);
+}
+```
+
+**Correct (layered behind):**
+
+```css
+.button {
+  position: relative;
+  z-index: 1;
+}
+
+.button::before {
+  content: "";
+  position: absolute;
+  inset: 0;
+  background: var(--gray-3);
+  z-index: -1;
+}
+```