gsd-pi 2.28.0 → 2.29.0-dev.23d50d0

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

package/src/resources/skills/userinterface-wiki/rules/spring-for-gestures.md

@@ -0,0 +1,27 @@
+---
+title: Springs for Gesture-Driven Motion
+impact: HIGH
+tags: spring, gesture, drag
+---
+
+## Springs for Gesture-Driven Motion
+
+Gesture-driven motion (drag, flick, swipe) must use springs.
+
+**Incorrect (easing for drag):**
+
+```tsx
+<motion.div
+  drag="x"
+  transition={{ duration: 0.3, ease: "easeOut" }}
+/>
+```
+
+**Correct (spring for drag):**
+
+```tsx
+<motion.div
+  drag="x"
+  transition={{ type: "spring", stiffness: 500, damping: 30 }}
+/>
+```

package/src/resources/skills/userinterface-wiki/rules/spring-for-interruptible.md

@@ -0,0 +1,27 @@
+---
+title: Springs for Interruptible Motion
+impact: HIGH
+tags: spring, interruptible, animation
+---
+
+## Springs for Interruptible Motion
+
+Motion that can be interrupted must use springs.
+
+**Incorrect (easing for interruptible):**
+
+```tsx
+<motion.div
+  animate={{ x: isOpen ? 200 : 0 }}
+  transition={{ duration: 0.3 }}
+/>
+```
+
+**Correct (spring for interruptible):**
+
+```tsx
+<motion.div
+  animate={{ x: isOpen ? 200 : 0 }}
+  transition={{ type: "spring", stiffness: 400, damping: 25 }}
+/>
+```

package/src/resources/skills/userinterface-wiki/rules/spring-params-balanced.md

@@ -0,0 +1,29 @@
+---
+title: Balanced Spring Parameters
+impact: MEDIUM
+tags: spring, stiffness, damping
+---
+
+## Balanced Spring Parameters
+
+Spring parameters must be balanced; avoid excessive oscillation.
+
+**Incorrect (too bouncy):**
+
+```tsx
+transition={{
+  type: "spring",
+  stiffness: 1000,
+  damping: 5,
+}}
+```
+
+**Correct (balanced):**
+
+```tsx
+transition={{
+  type: "spring",
+  stiffness: 500,
+  damping: 30,
+}}
+```

package/src/resources/skills/userinterface-wiki/rules/spring-preserves-velocity.md

@@ -0,0 +1,28 @@
+---
+title: Springs Preserve Input Velocity
+impact: MEDIUM
+tags: spring, velocity, drag
+---
+
+## Springs Preserve Input Velocity
+
+When velocity matters, use springs to preserve input energy.
+
+**Incorrect (velocity ignored):**
+
+```tsx
+onDragEnd={(e, info) => {
+  animate(target, { x: 0 }, { duration: 0.3 });
+}}
+```
+
+**Correct (velocity preserved):**
+
+```tsx
+onDragEnd={(e, info) => {
+  animate(target, { x: 0 }, {
+    type: "spring",
+    velocity: info.velocity.x,
+  });
+}}
+```

package/src/resources/skills/userinterface-wiki/rules/staging-dim-background.md

@@ -0,0 +1,22 @@
+---
+title: Dim Background for Focus
+impact: MEDIUM
+impactDescription: Transparent overlays fail to direct focus; dimmed backgrounds isolate the modal and reduce distraction.
+tags: staging, modal, overlay
+---
+
+## Dim Background for Focus
+
+Modal/dialog backgrounds should dim to direct focus.
+
+**Incorrect (transparent overlay):**
+
+```css
+.overlay { background: transparent; }
+```
+
+**Correct (dimmed overlay):**
+
+```css
+.overlay { background: var(--black-a6); }
+```

package/src/resources/skills/userinterface-wiki/rules/staging-one-focal-point.md

@@ -0,0 +1,24 @@
+---
+title: Single Focal Point
+impact: MEDIUM
+impactDescription: Competing animations split attention and reduce clarity; one focal point guides the user effectively.
+tags: staging, focus, attention
+---
+
+## Single Focal Point
+
+Only one element should animate prominently at a time.
+
+**Incorrect (competing animations):**
+
+```tsx
+<motion.div animate={{ scale: 1.1 }} />
+<motion.div animate={{ scale: 1.1 }} />
+```
+
+**Correct (single focal point):**
+
+```tsx
+<motion.div animate={{ scale: 1.1 }} />
+<motion.div animate={{ scale: 1 }} />
+```

package/src/resources/skills/userinterface-wiki/rules/staging-z-index-hierarchy.md

@@ -0,0 +1,22 @@
+---
+title: Z-Index Layering for Animated Elements
+impact: MEDIUM
+impactDescription: Missing z-index causes tooltips and overlays to render behind other content, breaking the visual hierarchy.
+tags: staging, z-index, layering
+---
+
+## Z-Index Layering for Animated Elements
+
+Animated elements must respect z-index layering.
+
+**Incorrect (no z-index):**
+
+```css
+.tooltip { /* No z-index, may render behind other elements */ }
+```
+
+**Correct (explicit z-index):**
+
+```css
+.tooltip { z-index: 50; }
+```

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

@@ -0,0 +1,24 @@
+---
+title: Consistent Timing for Similar Elements
+impact: CRITICAL
+impactDescription: Inconsistent timing across similar elements creates a disjointed, unpolished feel and undermines design system coherence.
+tags: timing, consistency, animation
+---
+
+## Consistent Timing for Similar Elements
+
+Similar elements must use identical timing values.
+
+**Incorrect (inconsistent timing):**
+
+```css
+.button-primary { transition: 200ms; }
+.button-secondary { transition: 150ms; }
+```
+
+**Correct (consistent timing):**
+
+```css
+.button-primary { transition: 200ms; }
+.button-secondary { transition: 200ms; }
+```

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

@@ -0,0 +1,22 @@
+---
+title: No Entrance Animation on Context Menus
+impact: HIGH
+impactDescription: Entrance animations on context menus delay access to options and feel unnecessary for ephemeral UI.
+tags: timing, context-menu, entrance
+---
+
+## No Entrance Animation on Context Menus
+
+Context menus should not animate on entrance (exit only).
+
+**Incorrect (animates entrance):**
+
+```tsx
+<motion.div initial={{ opacity: 0 }} animate={{ opacity: 1 }} />
+```
+
+**Correct (exit only):**
+
+```tsx
+<motion.div exit={{ opacity: 0 }} />
+```

package/src/resources/skills/userinterface-wiki/rules/timing-under-300ms.md

@@ -0,0 +1,22 @@
+---
+title: User Animations Under 300ms
+impact: CRITICAL
+impactDescription: Exceeding 300ms for user-initiated actions degrades perceived responsiveness and makes the interface feel sluggish.
+tags: timing, duration, animation
+---
+
+## User Animations Under 300ms
+
+User-initiated animations must complete within 300ms.
+
+**Incorrect (exceeds 300ms limit):**
+
+```css
+.button { transition: transform 400ms; }
+```
+
+**Correct (within 300ms):**
+
+```css
+.button { transition: transform 200ms; }
+```

package/src/resources/skills/userinterface-wiki/rules/transition-name-cleanup.md

@@ -0,0 +1,28 @@
+---
+title: Clean Up View Transition Names
+impact: MEDIUM
+tags: view-transition, cleanup
+---
+
+## Clean Up View Transition Names
+
+Remove view-transition-name after transition completes.
+
+**Incorrect (stale name):**
+
+```ts
+sourceImg.style.viewTransitionName = "card";
+document.startViewTransition(() => {
+  targetImg.style.viewTransitionName = "card";
+});
+```
+
+**Correct (name cleaned up):**
+
+```ts
+sourceImg.style.viewTransitionName = "card";
+document.startViewTransition(() => {
+  sourceImg.style.viewTransitionName = "";
+  targetImg.style.viewTransitionName = "card";
+});
+```

package/src/resources/skills/userinterface-wiki/rules/transition-name-required.md

@@ -0,0 +1,27 @@
+---
+title: View Transition Name Required
+impact: HIGH
+tags: view-transition, transition-name
+---
+
+## View Transition Name Required
+
+Elements participating in view transitions need view-transition-name.
+
+**Incorrect (no transition name):**
+
+```ts
+document.startViewTransition(() => {
+  targetImg.src = newSrc;
+});
+```
+
+**Correct (transition name assigned):**
+
+```ts
+sourceImg.style.viewTransitionName = "card";
+document.startViewTransition(() => {
+  sourceImg.style.viewTransitionName = "";
+  targetImg.style.viewTransitionName = "card";
+});
+```

package/src/resources/skills/userinterface-wiki/rules/transition-name-unique.md

@@ -0,0 +1,24 @@
+---
+title: Unique View Transition Names
+impact: HIGH
+tags: view-transition, unique, naming
+---
+
+## Unique View Transition Names
+
+Each view-transition-name must be unique on the page during transition.
+
+**Incorrect (duplicate names):**
+
+```css
+.card {
+  view-transition-name: card;
+}
+/* Multiple cards with same name */
+```
+
+**Correct (unique per element):**
+
+```ts
+element.style.viewTransitionName = `card-${id}`;
+```

package/src/resources/skills/userinterface-wiki/rules/transition-over-js-library.md

@@ -0,0 +1,32 @@
+---
+title: View Transitions Over JS Libraries
+impact: MEDIUM
+tags: view-transition, native, performance
+---
+
+## View Transitions Over JS Libraries
+
+Prefer View Transitions API over JavaScript animation libraries for page transitions.
+
+**Incorrect (JS-based transition):**
+
+```tsx
+import { motion } from "motion/react";
+
+function ImageLightbox() {
+  return (
+    <motion.img layoutId="hero" />
+  );
+}
+```
+
+**Correct (native View Transition):**
+
+```ts
+function openLightbox(img: HTMLImageElement) {
+  img.style.viewTransitionName = "hero";
+  document.startViewTransition(() => {
+    // Native browser transition
+  });
+}
+```

package/src/resources/skills/userinterface-wiki/rules/transition-style-pseudo-elements.md

@@ -0,0 +1,24 @@
+---
+title: Style View Transition Pseudo-Elements
+impact: MEDIUM
+tags: view-transition, pseudo, styling
+---
+
+## Style View Transition Pseudo-Elements
+
+Style view transition pseudo-elements for custom animations.
+
+**Incorrect (default crossfade only):**
+
+```ts
+document.startViewTransition(() => { /* ... */ });
+```
+
+**Correct (custom animation):**
+
+```css
+::view-transition-group(card) {
+  animation-duration: 300ms;
+  animation-timing-function: cubic-bezier(0.215, 0.61, 0.355, 1);
+}
+```

package/src/resources/skills/userinterface-wiki/rules/type-antialiased-on-retina.md

@@ -0,0 +1,18 @@
+---
+title: Use Antialiased Font Smoothing
+impact: MEDIUM
+tags: type, rendering, antialiased
+---
+
+## Use Antialiased Font Smoothing
+
+Set -webkit-font-smoothing: antialiased on retina displays. The default subpixel rendering looks thicker and fuzzier.
+
+**Correct:**
+
+```css
+body {
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+```

package/src/resources/skills/userinterface-wiki/rules/type-disambiguation-stylistic-set.md

@@ -0,0 +1,15 @@
+---
+title: Use Disambiguation Stylistic Set for UI
+impact: MEDIUM
+tags: type, stylistic-set, disambiguation
+---
+
+## Use Disambiguation Stylistic Set for UI
+
+Enable ss02 (or your font's disambiguation set) in code-facing UIs to distinguish I, l, 1 and 0, O.
+
+**Correct:**
+
+```css
+.code-ui { font-feature-settings: "ss02"; }
+```