lsd-pi 1.2.0 → 1.2.1

package/src/resources/skills/userinterface-wiki/rules/_sections.md

@@ -1,66 +0,0 @@
-# Sections
-
-This file defines all sections, their ordering, impact levels, and descriptions.
-The section ID (in parentheses) is the filename prefix used to group rules.
-
----
-
-## 1. Animation Principles (timing, physics, staging)
-
-**Impact:** CRITICAL
-**Description:** Disney's 12 principles adapted for web. Timing, physics, and staging rules ensure animations feel natural and purposeful. Violations here produce the most noticeable quality issues.
-
-## 2. Timing Functions (spring, easing, duration, none)
-
-**Impact:** HIGH
-**Description:** Choosing the right timing function—spring, easing curve, or no animation—based on whether motion is user-driven, system-driven, or high-frequency.
-
-## 3. Exit Animations (exit, presence, mode, nested)
-
-**Impact:** HIGH
-**Description:** AnimatePresence and exit animation patterns in Motion/Framer Motion. Correct usage prevents layout shifts, stale interactions, and orphaned elements.
-
-## 4. CSS Pseudo Elements (pseudo, transition, native)
-
-**Impact:** MEDIUM
-**Description:** Leveraging ::before, ::after, View Transitions API, and native pseudo-elements (::backdrop, ::placeholder, ::selection) to reduce DOM nodes and improve transitions.
-
-## 5. Audio Feedback (a11y, appropriate, impl, weight)
-
-**Impact:** MEDIUM
-**Description:** When and how to use sound in UI. Covers accessibility, appropriateness heuristics, implementation patterns, and matching sound weight to action importance.
-
-## 6. Sound Synthesis (context, envelope, design, param)
-
-**Impact:** MEDIUM
-**Description:** Web Audio API best practices for procedural sound generation. Covers AudioContext management, envelope shaping, sound design patterns, and parameter ranges.
-
-## 7. Morphing Icons (morphing)
-
-**Impact:** LOW
-**Description:** Building icon components that morph between any two icons through SVG line transformation. All icons share a 3-line structure enabling seamless transitions.
-
-## 8. Container Animation (container)
-
-**Impact:** MEDIUM
-**Description:** Animating container width and height using a measure-and-animate pattern with ResizeObserver and Motion. The two-div pattern separates measurement from animation to avoid feedback loops.
-
-## 9. Laws of UX (ux)
-
-**Impact:** HIGH
-**Description:** Psychological principles behind interfaces that feel right. Covers Fitts's Law (target sizing), Hick's Law (choice reduction), Miller's Law (chunking), Doherty Threshold (response time), and Postel's Law (input tolerance).
-
-## 10. Predictive Prefetching (prefetch)
-
-**Impact:** MEDIUM
-**Description:** Loading content before the user clicks by analyzing cursor trajectory, reducing perceived latency by 100-200ms. Covers trajectory vs hover vs click strategies and device-aware fallbacks.
-
-## 11. Typography (type)
-
-**Impact:** MEDIUM
-**Description:** CSS font and text properties most developers overlook. OpenType features, numeric variants, variable font axes, text rendering, wrapping, and decoration controls that make typography feel considered.
-
-## 12. Visual Design (visual)
-
-**Impact:** HIGH
-**Description:** CSS design fundamentals that compound into visual polish. Concentric border radius, layered shadows, consistent spacing scales, and alpha borders. Small details that separate considered interfaces from default ones.

package/src/resources/skills/userinterface-wiki/rules/_template.md

@@ -1,24 +0,0 @@
----
-title: Rule Title Here
-impact: MEDIUM
-impactDescription: Optional description of impact
-tags: tag1, tag2
----
-
-## Rule Title Here
-
-Brief explanation of the rule and why it matters.
-
-**Incorrect (description of what's wrong):**
-
-```tsx
-// Bad code example here
-```
-
-**Correct (description of what's right):**
-
-```tsx
-// Good code example here
-```
-
-Reference: [Link to documentation or resource](https://example.com)

package/src/resources/skills/userinterface-wiki/rules/a11y-reduced-motion-check.md

@@ -1,30 +0,0 @@
----
-title: Respect prefers-reduced-motion for Sound
-impact: HIGH
-tags: a11y, reduced-motion, sound
----
-
-## Respect prefers-reduced-motion for Sound
-
-Respect prefers-reduced-motion as proxy for sound sensitivity.
-
-**Incorrect (ignores preference):**
-
-```tsx
-function playSound(name: string) {
-  audio.play();
-}
-```
-
-**Correct (checks preference):**
-
-```tsx
-function playSound(name: string) {
-  const prefersReducedMotion = window.matchMedia(
-    "(prefers-reduced-motion: reduce)"
-  ).matches;
-  
-  if (prefersReducedMotion) return;
-  audio.play();
-}
-```

package/src/resources/skills/userinterface-wiki/rules/a11y-toggle-setting.md

@@ -1,30 +0,0 @@
----
-title: Toggle Setting to Disable Sounds
-impact: HIGH
-tags: a11y, settings, toggle
----
-
-## Toggle Setting to Disable Sounds
-
-Provide explicit toggle to disable sounds in settings.
-
-**Incorrect (no way to disable):**
-
-```tsx
-function App() {
-  return <SoundProvider>{children}</SoundProvider>;
-}
-```
-
-**Correct (toggle available):**
-
-```tsx
-function App() {
-  const { soundEnabled } = usePreferences();
-  return (
-    <SoundProvider enabled={soundEnabled}>
-      {children}
-    </SoundProvider>
-  );
-}
-```

package/src/resources/skills/userinterface-wiki/rules/a11y-visual-equivalent.md

@@ -1,36 +0,0 @@
----
-title: Visual Equivalent for Every Sound
-impact: HIGH
-tags: a11y, visual, sound
----
-
-## Visual Equivalent for Every Sound
-
-Every audio cue must have a visual equivalent; sound never replaces visual feedback.
-
-**Incorrect (sound without visual):**
-
-```tsx
-function SubmitButton({ onClick }) {
-  const handleClick = () => {
-    playSound("success");
-    onClick();
-  };
-}
-```
-
-**Correct (sound with visual):**
-
-```tsx
-function SubmitButton({ onClick }) {
-  const [status, setStatus] = useState("idle");
-  
-  const handleClick = () => {
-    playSound("success");
-    setStatus("success");
-    onClick();
-  };
-  
-  return <button data-status={status}>Submit</button>;
-}
-```

package/src/resources/skills/userinterface-wiki/rules/a11y-volume-control.md

@@ -1,28 +0,0 @@
----
-title: Independent Volume Control
-impact: MEDIUM
-tags: a11y, volume, settings
----
-
-## Independent Volume Control
-
-Allow volume adjustment independent of system volume.
-
-**Incorrect (always full volume):**
-
-```tsx
-function playSound() {
-  audio.volume = 1;
-  audio.play();
-}
-```
-
-**Correct (user-controlled volume):**
-
-```tsx
-function playSound() {
-  const { volume } = usePreferences();
-  audio.volume = volume;
-  audio.play();
-}
-```

package/src/resources/skills/userinterface-wiki/rules/appropriate-confirmations-only.md

@@ -1,19 +0,0 @@
----
-title: Sound for Confirmations
-impact: MEDIUM
-tags: appropriate, confirmation, payment
----
-
-## Sound for Confirmations
-
-Sound is appropriate for confirmations: payments, uploads, form submissions.
-
-**Correct:**
-
-```tsx
-async function handlePayment() {
-  await processPayment();
-  playSound("success");
-  showConfirmation();
-}
-```

package/src/resources/skills/userinterface-wiki/rules/appropriate-errors-warnings.md

@@ -1,18 +0,0 @@
----
-title: Sound for Errors and Warnings
-impact: MEDIUM
-tags: appropriate, error, warning
----
-
-## Sound for Errors and Warnings
-
-Sound is appropriate for errors and warnings that can't be overlooked.
-
-**Correct:**
-
-```tsx
-function handleError(error: Error) {
-  playSound("error");
-  showErrorToast(error.message);
-}
-```

package/src/resources/skills/userinterface-wiki/rules/appropriate-no-decorative.md

@@ -1,21 +0,0 @@
----
-title: No Decorative Sound
-impact: MEDIUM
-tags: appropriate, decorative, hover
----
-
-## No Decorative Sound
-
-Do not add sound to decorative moments with no informational value.
-
-**Incorrect (hover sound):**
-
-```tsx
-function Card({ onHover }) {
-  return (
-    <div onMouseEnter={() => playSound("hover")}>
-      {children}
-    </div>
-  );
-}
-```

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

@@ -1,28 +0,0 @@
----
-title: No Sound on High-Frequency Interactions
-impact: HIGH
-tags: appropriate, frequency, typing
----
-
-## No Sound on High-Frequency Interactions
-
-Do not add sound to high-frequency interactions (typing, keyboard navigation).
-
-**Incorrect (sound on every keystroke):**
-
-```tsx
-function Input({ onChange }) {
-  const handleChange = (e) => {
-    playSound("keystroke");
-    onChange(e);
-  };
-}
-```
-
-**Correct (no sound on typing):**
-
-```tsx
-function Input({ onChange }) {
-  return <input onChange={onChange} />;
-}
-```

package/src/resources/skills/userinterface-wiki/rules/appropriate-no-punishing.md

@@ -1,27 +0,0 @@
----
-title: Informative Not Punishing Sound
-impact: MEDIUM
-tags: appropriate, error, tone
----
-
-## Informative Not Punishing Sound
-
-Sound should inform, not punish; avoid harsh sounds for user mistakes.
-
-**Incorrect (harsh buzzer):**
-
-```tsx
-function ValidationError() {
-  playSound("loud-buzzer");
-  return <span>Invalid input</span>;
-}
-```
-
-**Correct (gentle alert):**
-
-```tsx
-function ValidationError() {
-  playSound("gentle-alert");
-  return <span>Invalid input</span>;
-}
-```

package/src/resources/skills/userinterface-wiki/rules/container-callback-ref.md

@@ -1,31 +0,0 @@
----
-title: Use Callback Ref for Measurement
-impact: MEDIUM
-tags: container, ref, callback
----
-
-## Use Callback Ref for Measurement
-
-Use a callback ref (not useRef) for measurement hooks so the observer attaches when the DOM node is ready.
-
-**Incorrect (useRef may be null on first effect):**
-
-```tsx
-const ref = useRef(null);
-useEffect(() => {
-  if (!ref.current) return;
-  observer.observe(ref.current);
-}, []);
-```
-
-**Correct (callback ref guarantees node):**
-
-```tsx
-const [element, setElement] = useState(null);
-const ref = useCallback((node) => setElement(node), []);
-useEffect(() => {
-  if (!element) return;
-  observer.observe(element);
-  return () => observer.disconnect();
-}, [element]);
-```

package/src/resources/skills/userinterface-wiki/rules/container-guard-initial-zero.md

@@ -1,25 +0,0 @@
----
-title: Guard Against Zero on Initial Render
-impact: HIGH
-tags: container, measure, initial-render
----
-
-## Guard Against Zero on Initial Render
-
-On initial render, measured bounds are 0. Guard against this to prevent animating from 0 to actual size.
-
-**Incorrect (animates from 0 on mount):**
-
-```tsx
-<motion.div animate={{ width: bounds.width }}>
-  <div ref={ref}>{children}</div>
-</motion.div>
-```
-
-**Correct (falls back to auto on first frame):**
-
-```tsx
-<motion.div animate={{ width: bounds.width > 0 ? bounds.width : "auto" }}>
-  <div ref={ref}>{children}</div>
-</motion.div>
-```

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

@@ -1,13 +0,0 @@
----
-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/src/resources/skills/userinterface-wiki/rules/container-overflow-hidden.md

@@ -1,25 +0,0 @@
----
-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/src/resources/skills/userinterface-wiki/rules/container-transition-delay.md

@@ -1,21 +0,0 @@
----
-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/src/resources/skills/userinterface-wiki/rules/container-two-div-pattern.md

@@ -1,35 +0,0 @@
----
-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/src/resources/skills/userinterface-wiki/rules/container-use-resize-observer.md

@@ -1,48 +0,0 @@
----
-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/src/resources/skills/userinterface-wiki/rules/context-cleanup-nodes.md

@@ -1,25 +0,0 @@
----
-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/src/resources/skills/userinterface-wiki/rules/context-resume-suspended.md

@@ -1,28 +0,0 @@
----
-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/src/resources/skills/userinterface-wiki/rules/context-reuse-single.md

@@ -1,30 +0,0 @@
----
-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/src/resources/skills/userinterface-wiki/rules/design-filter-for-character.md

@@ -1,25 +0,0 @@
----
-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/src/resources/skills/userinterface-wiki/rules/design-noise-for-percussion.md

@@ -1,26 +0,0 @@
----
-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);
-}
-```