gsd-pi 2.28.0 → 2.29.0-dev.2ccf3fb

package/src/resources/skills/userinterface-wiki/rules/morphing-use-collapsed.md

@@ -0,0 +1,33 @@
+---
+title: Use Collapsed Constant for Unused Lines
+impact: HIGH
+tags: morphing, collapsed, structure
+---
+
+## Use Collapsed Constant for Unused Lines
+
+Unused lines must use the collapsed constant, not omission or null.
+
+**Incorrect (null for unused):**
+
+```ts
+const minusIcon = {
+  lines: [
+    { x1: 2, y1: 7, x2: 12, y2: 7 },
+    null,
+    null,
+  ],
+};
+```
+
+**Correct (collapsed constant):**
+
+```ts
+const minusIcon = {
+  lines: [
+    { x1: 2, y1: 7, x2: 12, y2: 7 },
+    collapsed,
+    collapsed,
+  ],
+};
+```

package/src/resources/skills/userinterface-wiki/rules/native-backdrop-styling.md

@@ -0,0 +1,27 @@
+---
+title: Use ::backdrop for Dialog Backgrounds
+impact: MEDIUM
+tags: native, backdrop, dialog
+---
+
+## Use ::backdrop for Dialog Backgrounds
+
+Use ::backdrop pseudo-element for dialog/popover backgrounds.
+
+**Incorrect (extra overlay node):**
+
+```tsx
+<>
+  <div className={styles.overlay} onClick={close} />
+  <dialog className={styles.dialog}>{children}</dialog>
+</>
+```
+
+**Correct (native ::backdrop):**
+
+```css
+dialog::backdrop {
+  background: var(--black-a6);
+  backdrop-filter: blur(4px);
+}
+```

package/src/resources/skills/userinterface-wiki/rules/native-placeholder-styling.md

@@ -0,0 +1,27 @@
+---
+title: Use ::placeholder for Input Styling
+impact: LOW
+tags: native, placeholder, input
+---
+
+## Use ::placeholder for Input Styling
+
+Use ::placeholder for input placeholder styling, not wrapper elements.
+
+**Incorrect (custom placeholder node):**
+
+```tsx
+<div className={styles.inputWrapper}>
+  {!value && <span className={styles.placeholder}>Enter text...</span>}
+  <input value={value} />
+</div>
+```
+
+**Correct (native ::placeholder):**
+
+```css
+input::placeholder {
+  color: var(--gray-9);
+  opacity: 1;
+}
+```

package/src/resources/skills/userinterface-wiki/rules/native-selection-styling.md

@@ -0,0 +1,18 @@
+---
+title: Use ::selection for Text Styling
+impact: LOW
+tags: native, selection, text
+---
+
+## Use ::selection for Text Styling
+
+Use ::selection for text selection styling.
+
+**Correct:**
+
+```css
+::selection {
+  background: var(--blue-a5);
+  color: var(--gray-12);
+}
+```

package/src/resources/skills/userinterface-wiki/rules/nested-consistent-timing.md

@@ -0,0 +1,25 @@
+---
+title: Coordinated Parent-Child Exit Timing
+impact: MEDIUM
+tags: nested, timing, exit
+---
+
+## Coordinated Parent-Child Exit Timing
+
+Parent and child exit durations should be coordinated.
+
+**Incorrect (parent too fast):**
+
+```tsx
+<motion.div exit={{ opacity: 0 }} transition={{ duration: 0.1 }}>
+  <motion.div exit={{ scale: 0 }} transition={{ duration: 0.5 }} />
+</motion.div>
+```
+
+**Correct (coordinated timing):**
+
+```tsx
+<motion.div exit={{ opacity: 0 }} transition={{ duration: 0.2 }}>
+  <motion.div exit={{ scale: 0 }} transition={{ duration: 0.15 }} />
+</motion.div>
+```

package/src/resources/skills/userinterface-wiki/rules/nested-propagate-required.md

@@ -0,0 +1,41 @@
+---
+title: Propagate Prop for Nested AnimatePresence
+impact: HIGH
+tags: nested, propagate, exit
+---
+
+## Propagate Prop for Nested AnimatePresence
+
+Nested AnimatePresence must use propagate prop for coordinated exits.
+
+**Incorrect (children vanish instantly):**
+
+```tsx
+<AnimatePresence>
+  {isOpen && (
+    <motion.div exit={{ opacity: 0 }}>
+      <AnimatePresence>
+        {items.map(item => (
+          <motion.div key={item.id} exit={{ scale: 0 }} />
+        ))}
+      </AnimatePresence>
+    </motion.div>
+  )}
+</AnimatePresence>
+```
+
+**Correct (propagate on both):**
+
+```tsx
+<AnimatePresence propagate>
+  {isOpen && (
+    <motion.div exit={{ opacity: 0 }}>
+      <AnimatePresence propagate>
+        {items.map(item => (
+          <motion.div key={item.id} exit={{ scale: 0 }} />
+        ))}
+      </AnimatePresence>
+    </motion.div>
+  )}
+</AnimatePresence>
+```

package/src/resources/skills/userinterface-wiki/rules/none-context-menu-entrance.md

@@ -0,0 +1,25 @@
+---
+title: No Entrance Animation for Context Menus
+impact: MEDIUM
+tags: none, context-menu, entrance
+---
+
+## No Entrance Animation for Context Menus
+
+Context menus should not animate on entrance (exit only).
+
+**Incorrect (entrance animation):**
+
+```tsx
+<motion.div
+  initial={{ opacity: 0, scale: 0.95 }}
+  animate={{ opacity: 1, scale: 1 }}
+  exit={{ opacity: 0 }}
+/>
+```
+
+**Correct (exit only):**
+
+```tsx
+<motion.div exit={{ opacity: 0, scale: 0.95 }} />
+```

package/src/resources/skills/userinterface-wiki/rules/none-high-frequency.md

@@ -0,0 +1,29 @@
+---
+title: No Animation for High-Frequency Interactions
+impact: HIGH
+tags: none, high-frequency, performance
+---
+
+## No Animation for High-Frequency Interactions
+
+High-frequency interactions should have no animation.
+
+**Incorrect (animated on every keystroke):**
+
+```tsx
+function SearchInput() {
+  return (
+    <motion.div animate={{ scale: [1, 1.02, 1] }}>
+      <input onChange={handleSearch} />
+    </motion.div>
+  );
+}
+```
+
+**Correct (no animation):**
+
+```tsx
+function SearchInput() {
+  return <input onChange={handleSearch} />;
+}
+```

package/src/resources/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/src/resources/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/src/resources/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/src/resources/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/src/resources/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/src/resources/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/src/resources/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/src/resources/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/src/resources/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/src/resources/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/src/resources/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/src/resources/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/src/resources/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/src/resources/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/src/resources/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/src/resources/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/src/resources/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} />;
+}
+```