gsd-pi 2.28.0 → 2.29.0-dev.2ccf3fb

package/dist/resources/skills/make-interfaces-feel-better/animations.md

@@ -0,0 +1,379 @@
+# Animations
+
+Interruptible animations, enter/exit transitions, and contextual icon animations.
+
+## Interruptible Animations
+
+Users change intent mid-interaction. If animations aren't interruptible, the interface feels broken.
+
+### CSS Transitions vs. Keyframes
+
+| | CSS Transitions | CSS Keyframe Animations |
+| --- | --- | --- |
+| **Behavior** | Interpolate toward latest state | Run on a fixed timeline |
+| **Interruptible** | Yes — retargets mid-animation | No — restarts from beginning |
+| **Use for** | Interactive state changes (hover, toggle, open/close) | Staged sequences that run once (enter animations, loading) |
+| **Duration** | Adapts to remaining distance | Fixed regardless of state |
+
+```css
+/* Good — interruptible transition for a toggle */
+.drawer {
+  transform: translateX(-100%);
+  transition: transform 200ms ease-out;
+}
+.drawer.open {
+  transform: translateX(0);
+}
+
+/* Clicking again mid-animation smoothly reverses — no jank */
+```
+
+```css
+/* Bad — keyframe animation for interactive element */
+.drawer.open {
+  animation: slideIn 200ms ease-out forwards;
+}
+
+/* Closing mid-animation snaps or restarts — feels broken */
+```
+
+**Rule:** Always prefer CSS transitions for interactive elements. Reserve keyframes for one-shot sequences.
+
+## Enter Animations: Split and Stagger
+
+Don't animate a single large container. Break content into semantic chunks and animate each individually.
+
+### Step by Step
+
+1. **Split** into logical groups (title, description, buttons)
+2. **Stagger** with ~100ms delay between groups
+3. **For titles**, consider splitting into individual words with ~80ms stagger
+4. **Combine** `opacity`, `blur`, and `translateY` for the enter effect
+
+### Code Example
+
+```tsx
+// Motion (Framer Motion) — staggered enter
+function PageHeader() {
+  return (
+    <motion.div
+      initial="hidden"
+      animate="visible"
+      variants={{
+        visible: { transition: { staggerChildren: 0.1 } },
+      }}
+    >
+      <motion.h1
+        variants={{
+          hidden: { opacity: 0, y: 12, filter: "blur(4px)" },
+          visible: { opacity: 1, y: 0, filter: "blur(0px)" },
+        }}
+      >
+        Welcome
+      </motion.h1>
+
+      <motion.p
+        variants={{
+          hidden: { opacity: 0, y: 12, filter: "blur(4px)" },
+          visible: { opacity: 1, y: 0, filter: "blur(0px)" },
+        }}
+      >
+        A description of the page.
+      </motion.p>
+
+      <motion.div
+        variants={{
+          hidden: { opacity: 0, y: 12, filter: "blur(4px)" },
+          visible: { opacity: 1, y: 0, filter: "blur(0px)" },
+        }}
+      >
+        <Button>Get started</Button>
+      </motion.div>
+    </motion.div>
+  );
+}
+```
+
+### CSS-Only Stagger
+
+```css
+.stagger-item {
+  opacity: 0;
+  transform: translateY(12px);
+  filter: blur(4px);
+  animation: fadeInUp 400ms ease-out forwards;
+}
+
+.stagger-item:nth-child(1) { animation-delay: 0ms; }
+.stagger-item:nth-child(2) { animation-delay: 100ms; }
+.stagger-item:nth-child(3) { animation-delay: 200ms; }
+
+@keyframes fadeInUp {
+  to {
+    opacity: 1;
+    transform: translateY(0);
+    filter: blur(0);
+  }
+}
+```
+
+## Exit Animations
+
+Exit animations should be softer and less attention-grabbing than enter animations. The user's focus is moving to the next thing — don't fight for attention.
+
+### Subtle Exit (Recommended)
+
+```tsx
+// Small fixed translateY — indicates direction without drama
+<motion.div
+  exit={{
+    opacity: 0,
+    y: -12,
+    filter: "blur(4px)",
+    transition: { duration: 0.15, ease: "easeIn" },
+  }}
+>
+  {content}
+</motion.div>
+```
+
+### Full Exit (When Context Matters)
+
+```tsx
+// Slide fully out — use when spatial context is important
+// (e.g., a card returning to a list, a drawer closing)
+<motion.div
+  exit={{
+    opacity: 0,
+    x: "-100%",
+    transition: { duration: 0.2, ease: "easeIn" },
+  }}
+>
+  {content}
+</motion.div>
+```
+
+### Good vs. Bad
+
+```css
+/* Good — subtle exit */
+.item-exit {
+  opacity: 0;
+  transform: translateY(-12px);
+  transition: opacity 150ms ease-in, transform 150ms ease-in;
+}
+
+/* Bad — dramatic exit that steals focus */
+.item-exit {
+  opacity: 0;
+  transform: translateY(-100%) scale(0.5);
+  transition: all 400ms ease-in;
+}
+
+/* Bad — no exit animation at all (element just vanishes) */
+.item-exit {
+  display: none;
+}
+```
+
+**Key points:**
+- Use a small fixed `translateY` (e.g., `-12px`) instead of the full container height
+- Keep some directional movement to indicate where the element went
+- Exit duration should be shorter than enter duration (150ms vs 300ms)
+- Don't remove exit animations entirely — subtle motion preserves context
+
+## Contextual Icon Animations
+
+When icons appear or disappear contextually (on hover, on state change), animate them with `opacity`, `scale`, and `blur` rather than just toggling visibility.
+
+### Motion Example
+
+```tsx
+import { AnimatePresence, motion } from "motion/react";
+
+function IconButton({ isActive, icon: Icon }) {
+  return (
+    <button>
+      <AnimatePresence mode="popLayout">
+        <motion.span
+          key={isActive ? "active" : "inactive"}
+          initial={{ opacity: 0, scale: 0.25, filter: "blur(4px)" }}
+          animate={{ opacity: 1, scale: 1, filter: "blur(0px)" }}
+          exit={{ opacity: 0, scale: 0.25, filter: "blur(4px)" }}
+          transition={{ type: "spring", duration: 0.3, bounce: 0 }}
+        >
+          <Icon />
+        </motion.span>
+      </AnimatePresence>
+    </button>
+  );
+}
+```
+
+### CSS Transition Approach (No Motion)
+
+If the project doesn't use Motion (Framer Motion), keep both icons in the DOM and cross-fade them with CSS transitions. Because neither icon unmounts, both enter and exit animate smoothly.
+
+The trick: one icon is absolutely positioned on top of the other. Toggling state cross-fades them — the entering icon scales up from `0.25` while the exiting icon scales down to `0.25`, both with opacity and blur.
+
+```tsx
+function IconButton({ isActive, ActiveIcon, InactiveIcon }) {
+  return (
+    <button>
+      <div className="relative">
+        <div
+          className={cn(
+            "absolute inset-0 flex items-center justify-center",
+            "transition-[opacity,filter,scale] duration-300",
+            "cubic-bezier(0.2, 0, 0, 1)",
+            isActive
+              ? "scale-100 opacity-100 blur-0"
+              : "scale-[0.25] opacity-0 blur-[4px]"
+          )}
+        >
+          <ActiveIcon />
+        </div>
+        <div
+          className={cn(
+            "transition-[opacity,filter,scale] duration-300",
+            "cubic-bezier(0.2, 0, 0, 1)",
+            isActive
+              ? "scale-[0.25] opacity-0 blur-[4px]"
+              : "scale-100 opacity-100 blur-0"
+          )}
+        >
+          <InactiveIcon />
+        </div>
+      </div>
+    </button>
+  );
+}
+```
+
+The non-absolute icon (InactiveIcon) defines the layout size. The absolute icon (ActiveIcon) overlays it without affecting flow.
+
+### Choosing Between Motion and CSS
+
+| | Motion (Framer Motion) | CSS transitions (both icons in DOM) |
+| --- | --- | --- |
+| **Enter animation** | Yes | Yes |
+| **Exit animation** | Yes (via `AnimatePresence`) | Yes (cross-fade — icon never unmounts) |
+| **Spring physics** | Yes | No — use `cubic-bezier(0.2, 0, 0, 1)` as approximation |
+| **When to use** | Project already uses `motion/react` | No motion dependency, or keeping bundle small |
+
+**Rule:** Check the project's `package.json` for `motion` or `framer-motion`. If present, use the Motion approach. If not, use the CSS cross-fade pattern — don't add a dependency just for icon transitions.
+
+### When to Animate Icons
+
+| Animate | Don't animate |
+| --- | --- |
+| Icons that appear on hover (action buttons) | Static navigation icons |
+| State change icons (play → pause, like → liked) | Decorative icons |
+| Icons in contextual toolbars | Icons that are always visible |
+| Loading/success state indicators | Icon labels (text next to icon) |
+
+**Important:** Always use exactly these values for contextual icon animations — do not deviate:
+- `scale`: `0.25` → `1` (never use `0.5` or `0.6`)
+- `opacity`: `0` → `1`
+- `filter`: `"blur(4px)"` → `"blur(0px)"`
+- `transition`: `{ type: "spring", duration: 0.3, bounce: 0 }` — **bounce must always be `0`**, never `0.1` or any other value
+
+## Scale on Press
+
+A subtle scale-down on click gives buttons tactile feedback. Always use `scale(0.96)`. Never use a value smaller than `0.95` — anything below feels exaggerated. Use CSS transitions for interruptibility — if the user releases mid-press, it should smoothly return.
+
+Not every button needs this. Add a `static` prop to your button component that disables the scale effect when the motion would be distracting.
+
+### CSS Example
+
+```css
+.button {
+  transition-property: scale;
+  transition-duration: 150ms;
+  transition-timing-function: ease-out;
+}
+
+.button:active {
+  scale: 0.96;
+}
+```
+
+### Tailwind Example
+
+```tsx
+<button className="transition-transform duration-150 ease-out active:scale-[0.96]">
+  Click me
+</button>
+```
+
+### Motion Example
+
+```tsx
+<motion.button whileTap={{ scale: 0.96 }}>
+  Click me
+</motion.button>
+```
+
+### Static Prop Pattern
+
+Extract the scale class into a variable and conditionally apply it based on a `static` prop:
+
+```tsx
+const tapScale = "active:not-disabled:scale-[0.96]";
+
+function Button({ static: isStatic, className, children, ...props }) {
+  return (
+    <button
+      className={cn(
+        "transition-transform duration-150 ease-out",
+        !isStatic && tapScale,
+        className,
+      )}
+      {...props}
+    >
+      {children}
+    </button>
+  );
+}
+
+// Usage
+<Button>Click me</Button>           {/* scales on press */}
+<Button static>Submit</Button>       {/* no scale */}
+```
+
+## Skip Animation on Page Load
+
+Use `initial={false}` on `AnimatePresence` to prevent enter animations from firing on first render. Elements that are already in their default state shouldn't animate in on page load — only on subsequent state changes.
+
+### When It Works
+
+```tsx
+// Good — icon doesn't animate in on mount, only on state change
+<AnimatePresence initial={false} mode="popLayout">
+  <motion.span
+    key={isActive ? "active" : "inactive"}
+    initial={{ opacity: 0, scale: 0.25, filter: "blur(4px)" }}
+    animate={{ opacity: 1, scale: 1, filter: "blur(0px)" }}
+    exit={{ opacity: 0, scale: 0.25, filter: "blur(4px)" }}
+  >
+    <Icon />
+  </motion.span>
+</AnimatePresence>
+```
+
+Works well for: icon swaps, toggles, tabs, segmented controls — anything that has a default state on page load.
+
+### When It Breaks
+
+Don't use `initial={false}` when the component relies on its `initial` prop to set up a first-time enter animation, like a staggered page hero or a loading state. In those cases, removing the initial animation skips the entire entrance.
+
+```tsx
+// Bad — initial={false} would skip the staggered page enter entirely
+<AnimatePresence initial={false}>
+  <motion.div initial="hidden" animate="visible" variants={...}>
+    ...
+  </motion.div>
+</AnimatePresence>
+```
+
+Verify the component still looks right on a full page refresh before applying this.

package/dist/resources/skills/make-interfaces-feel-better/performance.md

@@ -0,0 +1,88 @@
+# Performance
+
+Transition specificity and GPU compositing hints.
+
+## Transition Only What Changes
+
+Never use `transition: all` or Tailwind's `transition` shorthand (which maps to `transition-property: all`). Always specify the exact properties that change.
+
+### Why
+
+- `transition: all` forces the browser to watch every property for changes
+- Causes unexpected transitions on properties you didn't intend to animate (colors, padding, shadows)
+- Prevents browser optimizations
+
+### CSS Example
+
+```css
+/* Good — only transition what changes */
+.button {
+  transition-property: scale, background-color;
+  transition-duration: 150ms;
+  transition-timing-function: ease-out;
+}
+
+/* Bad — transition everything */
+.button {
+  transition: all 150ms ease-out;
+}
+```
+
+### Tailwind
+
+```tsx
+// Good — explicit properties
+<button className="transition-[scale,background-color] duration-150 ease-out">
+
+// Bad — transition all
+<button className="transition duration-150 ease-out">
+```
+
+### Tailwind `transition-transform` Note
+
+`transition-transform` in Tailwind maps to `transition-property: transform, translate, scale, rotate` — it covers all transform-related properties, not just `transform`. Use this when you're only animating transforms. For multiple non-transform properties, use the bracket syntax: `transition-[scale,opacity,filter]`.
+
+## Use `will-change` Sparingly
+
+`will-change` hints the browser to pre-promote an element to its own GPU compositing layer. Without it, the browser promotes the element only when the animation starts — that one-time layer promotion can cause a micro-stutter on the first frame.
+
+This particularly helps when an element is changing `scale`, `rotation`, or moving around with `transform`. For other properties, it doesn't help much — the browser can't composite them on the GPU anyway.
+
+### Rules
+
+```css
+/* Good — specific property that benefits from GPU compositing */
+.animated-card {
+  will-change: transform;
+}
+
+/* Good — multiple compositor-friendly properties */
+.animated-card {
+  will-change: transform, opacity;
+}
+
+/* Bad — never use will-change: all */
+.animated-card {
+  will-change: all;
+}
+
+/* Bad — properties that can't be GPU-composited anyway */
+.animated-card {
+  will-change: background-color, padding;
+}
+```
+
+### Useful Properties
+
+| Property | GPU-compositable | Worth using `will-change` |
+| --- | --- | --- |
+| `transform` | Yes | Yes |
+| `opacity` | Yes | Yes |
+| `filter` (blur, brightness) | Yes | Yes |
+| `clip-path` | Yes | Yes |
+| `top`, `left`, `width`, `height` | No | No |
+| `background`, `border`, `color` | No | No |
+
+### When to Skip
+
+Modern browsers are already good at optimizing on their own. Only add `will-change` when you notice first-frame stutter — Safari in particular benefits from it. Don't add it preemptively to every animated element; each extra compositing layer costs memory.

package/dist/resources/skills/make-interfaces-feel-better/surfaces.md

@@ -0,0 +1,247 @@
+# Surfaces
+
+Border radius, optical alignment, shadows, and image outlines.
+
+## Concentric Border Radius
+
+When nesting rounded elements, the outer radius must equal the inner radius plus the padding between them:
+
+```
+outerRadius = innerRadius + padding
+```
+
+This rule is most useful when nested surfaces are close together. If padding is larger than `24px`, treat the layers as separate surfaces and choose each radius independently instead of forcing strict concentric math.
+
+### Example
+
+```css
+/* Good — concentric radii */
+.card {
+  border-radius: 20px; /* 12 + 8 */
+  padding: 8px;
+}
+.card-inner {
+  border-radius: 12px;
+}
+
+/* Bad — same radius on both */
+.card {
+  border-radius: 12px;
+  padding: 8px;
+}
+.card-inner {
+  border-radius: 12px;
+}
+```
+
+### Tailwind Example
+
+```tsx
+// Good — outer radius accounts for padding
+<div className="rounded-2xl p-2">       {/* 16px radius, 8px padding */}
+  <div className="rounded-lg">          {/* 8px radius = 16 - 8 ✓ */}
+    ...
+  </div>
+</div>
+
+// Bad — same radius on both
+<div className="rounded-xl p-2">
+  <div className="rounded-xl">          {/* same radius, looks off */}
+    ...
+  </div>
+</div>
+```
+
+Mismatched border radii on nested elements is one of the most common things that makes interfaces feel off. Always calculate concentrically.
+
+## Optical Alignment
+
+When geometric centering looks off, align optically instead.
+
+### Buttons with Text + Icon
+
+Use slightly less padding on the icon side to make the button feel balanced. A reliable rule of thumb is:
+`icon-side padding = text-side padding - 2px`.
+
+```css
+/* Good — less padding on icon side */
+.button-with-icon {
+  padding-left: 16px;
+  padding-right: 14px; /* icon side = text side - 2px */
+}
+
+/* Bad — equal padding looks like icon is pushed too far right */
+.button-with-icon {
+  padding: 0 16px;
+}
+```
+
+```tsx
+// Tailwind
+<button className="pl-4 pr-3.5 flex items-center gap-2">
+  <span>Continue</span>
+  <ArrowRightIcon />
+</button>
+```
+
+### Play Button Triangles
+
+Play icons are triangular and their geometric center is not their visual center. Shift slightly right:
+
+```css
+/* Good — optically centered */
+.play-button svg {
+  margin-left: 2px; /* shift right to account for triangle shape */
+}
+
+/* Bad — geometrically centered but looks off */
+.play-button svg {
+  /* no adjustment */
+}
+```
+
+### Asymmetric Icons (Stars, Arrows, Carets)
+
+Some icons have uneven visual weight. The best fix is adjusting the SVG directly so no extra margin/padding is needed in the component code.
+
+```tsx
+// Best — fix in the SVG itself
+// Adjust the viewBox or path to visually center the icon
+
+// Fallback — adjust with margin
+<span className="ml-px">
+  <StarIcon />
+</span>
+```
+
+## Shadows Instead of Borders
+
+For **buttons, cards, and containers** that use a border for depth or elevation, prefer replacing it with a subtle `box-shadow`. Shadows adapt to any background since they use transparency; solid borders don't. This also helps when using images or multiple colors as backgrounds — solid border colors don't work well on backgrounds other than the ones they were designed for.
+
+**Do not apply this to dividers** (`border-b`, `border-t`, side borders) or any border whose purpose is layout separation rather than element depth. Those should stay as borders.
+
+### Shadow as Border (Light Mode)
+
+The shadow is comprised of three layers. The first acts as a 1px border ring, the second adds subtle lift, and the third provides ambient depth:
+
+```css
+:root {
+  --shadow-border:
+    0px 0px 0px 1px rgba(0, 0, 0, 0.06),
+    0px 1px 2px -1px rgba(0, 0, 0, 0.06),
+    0px 2px 4px 0px rgba(0, 0, 0, 0.04);
+  --shadow-border-hover:
+    0px 0px 0px 1px rgba(0, 0, 0, 0.08),
+    0px 1px 2px -1px rgba(0, 0, 0, 0.08),
+    0px 2px 4px 0px rgba(0, 0, 0, 0.06);
+}
+```
+
+### Shadow as Border (Dark Mode)
+
+In dark mode, simplify to a single white ring — layered depth shadows aren't visible on dark backgrounds:
+
+```css
+/* Dark mode — adapt to whatever setup the project uses
+   (prefers-color-scheme, class, data attribute, etc.) */
+--shadow-border: 0 0 0 1px rgba(255, 255, 255, 0.08);
+--shadow-border-hover: 0 0 0 1px rgba(255, 255, 255, 0.13);
+```
+
+### Usage with Hover Transition
+
+Apply the variable and add `transition-[box-shadow]` for a smooth hover:
+
+```css
+.card {
+  box-shadow: var(--shadow-border);
+  transition-property: box-shadow;
+  transition-duration: 150ms;
+  transition-timing-function: ease-out;
+}
+
+.card:hover {
+  box-shadow: var(--shadow-border-hover);
+}
+```
+
+### When to Use Shadows vs. Borders
+
+| Use shadows | Use borders |
+| --- | --- |
+| Cards, containers with depth | Dividers between list items |
+| Buttons with bordered styles | Table cell boundaries |
+| Elevated elements (dropdowns, modals) | Form input outlines (for accessibility) |
+| Elements on varied backgrounds | Hairline separators in dense UI |
+| Hover/focus states for lift effect | |
+
+## Image Outlines
+
+Add a subtle `1px` outline with low opacity to images. This creates consistent depth, especially in design systems where other elements use borders or shadows.
+
+### Light Mode
+
+```css
+img {
+  outline: 1px solid rgba(0, 0, 0, 0.1);
+  outline-offset: -1px; /* inset so it doesn't add to layout */
+}
+```
+
+### Dark Mode
+
+```css
+img {
+  outline: 1px solid rgba(255, 255, 255, 0.1);
+  outline-offset: -1px;
+}
+```
+
+### Tailwind with Dark Mode
+
+```tsx
+<img
+  className="outline outline-1 -outline-offset-1 outline-black/10 dark:outline-white/10"
+  src={src}
+  alt={alt}
+/>
+```
+
+**Why outline instead of border?** `outline` doesn't affect layout (no added width/height), and `outline-offset: -1px` keeps it inset so images stay their intended size.
+
+## Minimum Hit Area
+
+Interactive elements should have a minimum hit area of 44×44px (WCAG) or at least 40×40px. If the visible element is smaller (e.g., a 20×20 checkbox), extend the hit area with a pseudo-element.
+
+### CSS Example
+
+```css
+/* Small checkbox with expanded hit area */
+.checkbox {
+  position: relative;
+  width: 20px;
+  height: 20px;
+}
+
+.checkbox::after {
+  content: "";
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  transform: translate(-50%, -50%);
+  width: 40px;
+  height: 40px;
+}
+```
+
+### Tailwind Example
+
+```tsx
+<button className="relative size-5 after:absolute after:top-1/2 after:left-1/2 after:size-10 after:-translate-1/2">
+  <CheckIcon />
+</button>
+```
+
+### Collision Rule
+
+If the extended hit area overlaps another interactive element, shrink the pseudo-element — but make it as large as possible without colliding. Two interactive elements should never have overlapping hit areas.