gsd-pi 2.28.0 → 2.29.0-dev.7612840

package/dist/resources/skills/userinterface-wiki/rules/ux-fitts-hit-area.md

@@ -0,0 +1,32 @@
+---
+title: Expand Hit Areas with Invisible Padding
+impact: HIGH
+tags: ux, fitts, hit-area, pseudo
+---
+
+## Expand Hit Areas with Invisible Padding
+
+Use pseudo-elements or invisible padding to expand clickable areas beyond visible bounds.
+
+**Incorrect (visible size equals hit area):**
+
+```css
+.link {
+  font-size: 14px;
+  /* Hit area matches text only */
+}
+```
+
+**Correct (expanded invisible hit area):**
+
+```css
+.link {
+  position: relative;
+}
+
+.link::before {
+  content: "";
+  position: absolute;
+  inset: -8px -12px;
+}
+```

package/dist/resources/skills/userinterface-wiki/rules/ux-fitts-target-size.md

@@ -0,0 +1,31 @@
+---
+title: Size Interactive Targets for Easy Clicking
+impact: HIGH
+tags: ux, fitts, target-size
+---
+
+## Size Interactive Targets for Easy Clicking
+
+The bigger something is, the easier it is to click. Make interactive elements large enough to hit comfortably.
+
+**Incorrect (tiny click target):**
+
+```css
+.icon-button {
+  width: 16px;
+  height: 16px;
+  padding: 0;
+}
+```
+
+**Correct (comfortable target):**
+
+```css
+.icon-button {
+  width: 32px;
+  height: 32px;
+  padding: 8px;
+}
+```
+
+Reference: Fitts, P. M. (1954). The information capacity of the human motor system.

package/dist/resources/skills/userinterface-wiki/rules/ux-goal-gradient-progress.md

@@ -0,0 +1,33 @@
+---
+title: Show Progress Toward Completion
+impact: HIGH
+tags: ux, goal-gradient, progress, motivation
+---
+
+## Show Progress Toward Completion
+
+People accelerate behavior as they approach a goal. Show how close they are to finishing.
+
+**Incorrect (no sense of progress):**
+
+```tsx
+function Onboarding({ step }) {
+  return <OnboardingStep step={step} />;
+}
+```
+
+**Correct (progress visible):**
+
+```tsx
+function Onboarding({ step, totalSteps }) {
+  return (
+    <div>
+      <ProgressBar value={step} max={totalSteps} />
+      <span>Step {step} of {totalSteps}</span>
+      <OnboardingStep step={step} />
+    </div>
+  );
+}
+```
+
+Reference: [Goal-Gradient Effect](https://lawsofux.com/goal-gradient-effect/)

package/dist/resources/skills/userinterface-wiki/rules/ux-hicks-minimize-choices.md

@@ -0,0 +1,45 @@
+---
+title: Minimize Choices to Reduce Decision Time
+impact: HIGH
+tags: ux, hicks, choices, cognitive-load
+---
+
+## Minimize Choices to Reduce Decision Time
+
+Decision time increases logarithmically with the number of choices. Use progressive disclosure.
+
+**Incorrect (all options at once):**
+
+```tsx
+function Settings() {
+  return (
+    <div>
+      {allSettings.map(setting => (
+        <SettingRow key={setting.id} {...setting} />
+      ))}
+    </div>
+  );
+}
+```
+
+**Correct (progressive disclosure):**
+
+```tsx
+function Settings() {
+  return (
+    <div>
+      {commonSettings.map(setting => (
+        <SettingRow key={setting.id} {...setting} />
+      ))}
+      <details>
+        <summary>Advanced</summary>
+        {advancedSettings.map(setting => (
+          <SettingRow key={setting.id} {...setting} />
+        ))}
+      </details>
+    </div>
+  );
+}
+```
+
+Reference: Hick, W. E. (1952). On the rate of gain of information.

package/dist/resources/skills/userinterface-wiki/rules/ux-jakobs-familiar-patterns.md

@@ -0,0 +1,37 @@
+---
+title: Use Familiar UI Patterns
+impact: HIGH
+tags: ux, jakobs, familiarity, patterns
+---
+
+## Use Familiar UI Patterns
+
+Users spend most of their time on other sites. They expect yours to work the same way (Jakob's Law).
+
+**Incorrect (custom unconventional navigation):**
+
+```tsx
+function Nav() {
+  return (
+    <nav>
+      <button onClick={() => navigate("/")}>⬡</button>
+      <button onClick={() => navigate("/search")}>⬢</button>
+    </nav>
+  );
+}
+```
+
+**Correct (standard recognizable patterns):**
+
+```tsx
+function Nav() {
+  return (
+    <nav>
+      <Link href="/">Home</Link>
+      <Link href="/search">Search</Link>
+    </nav>
+  );
+}
+```
+
+Reference: [Jakob's Law](https://lawsofux.com/jakobs-law/)

package/dist/resources/skills/userinterface-wiki/rules/ux-millers-chunking.md

@@ -0,0 +1,23 @@
+---
+title: Chunk Data into Groups of 5-9
+impact: HIGH
+tags: ux, millers, chunking, memory
+---
+
+## Chunk Data into Groups of 5-9
+
+Working memory holds about 7 items. Group and chunk large data sets so they're scannable.
+
+**Incorrect (raw unformatted data):**
+
+```tsx
+<span>4532015112830366</span>
+```
+
+**Correct (chunked for readability):**
+
+```tsx
+<span>4532 0151 1283 0366</span>
+```
+
+Reference: Miller, G. A. (1956). The magical number seven, plus or minus two.

package/dist/resources/skills/userinterface-wiki/rules/ux-pareto-prioritize-features.md

@@ -0,0 +1,36 @@
+---
+title: Prioritize the Critical 20% of Features
+impact: MEDIUM
+tags: ux, pareto, prioritization, features
+---
+
+## Prioritize the Critical 20% of Features
+
+80% of users use 20% of features (Pareto Principle). Optimize the critical path first.
+
+**Incorrect (all features equally prominent):**
+
+```tsx
+function Toolbar() {
+  return (
+    <div>
+      {allFeatures.map(f => <Button key={f.id}>{f.label}</Button>)}
+    </div>
+  );
+}
+```
+
+**Correct (critical features prominent, rest accessible):**
+
+```tsx
+function Toolbar() {
+  return (
+    <div>
+      {criticalFeatures.map(f => <Button key={f.id}>{f.label}</Button>)}
+      <MoreMenu features={secondaryFeatures} />
+    </div>
+  );
+}
+```
+
+Reference: [Pareto Principle](https://lawsofux.com/pareto-principle/)

package/dist/resources/skills/userinterface-wiki/rules/ux-peak-end-finish-strong.md

@@ -0,0 +1,35 @@
+---
+title: End Experiences with Clear Success States
+impact: MEDIUM
+tags: ux, peak-end, success, completion
+---
+
+## End Experiences with Clear Success States
+
+People judge experiences by their peak moment and their end. Invest in success and completion states.
+
+**Incorrect (abrupt end after action):**
+
+```tsx
+async function handleSubmit() {
+  await submitForm(data);
+  router.push("/");
+}
+```
+
+**Correct (satisfying completion state):**
+
+```tsx
+async function handleSubmit() {
+  await submitForm(data);
+  setStatus("success");
+}
+
+return status === "success" ? (
+  <SuccessScreen message="You're all set." />
+) : (
+  <Form onSubmit={handleSubmit} />
+);
+```
+
+Reference: [Peak-End Rule](https://lawsofux.com/peak-end-rule/)

package/dist/resources/skills/userinterface-wiki/rules/ux-postels-accept-messy-input.md

@@ -0,0 +1,45 @@
+---
+title: Accept Messy Input, Output Clean Data
+impact: MEDIUM
+tags: ux, postels, input, validation
+---
+
+## Accept Messy Input, Output Clean Data
+
+Inputs should accept messy human data and normalize it. Validate generously, format strictly.
+
+**Incorrect (rigid format required):**
+
+```tsx
+function DateInput({ onChange }) {
+  return (
+    <input
+      type="text"
+      placeholder="YYYY-MM-DD"
+      pattern="\d{4}-\d{2}-\d{2}"
+      onChange={onChange}
+    />
+  );
+}
+```
+
+**Correct (accepts multiple formats):**
+
+```tsx
+function DateInput({ onChange }) {
+  function handleChange(e) {
+    const parsed = parseFlexibleDate(e.target.value);
+    if (parsed) onChange(parsed);
+  }
+
+  return (
+    <input
+      type="text"
+      placeholder="Any date format"
+      onChange={handleChange}
+    />
+  );
+}
+```
+
+Reference: Postel, J. (1980). RFC 761 — Transmission Control Protocol.

package/dist/resources/skills/userinterface-wiki/rules/ux-pragnanz-simplify.md

@@ -0,0 +1,33 @@
+---
+title: Simplify Complex Visuals into Clear Forms
+impact: MEDIUM
+tags: ux, pragnanz, simplicity, clarity
+---
+
+## Simplify Complex Visuals into Clear Forms
+
+People interpret complex visuals as the simplest form possible. Reduce visual noise to aid comprehension.
+
+**Incorrect (visually noisy layout):**
+
+```css
+.card {
+  border: 2px dashed red;
+  background: linear-gradient(45deg, #f0f, #0ff);
+  box-shadow: 5px 5px 0 black, 10px 10px 0 gray;
+  outline: 3px dotted blue;
+}
+```
+
+**Correct (clear, simple form):**
+
+```css
+.card {
+  background: var(--gray-2);
+  border: 1px solid var(--gray-a4);
+  border-radius: 12px;
+  box-shadow: var(--shadow-1);
+}
+```
+
+Reference: [Law of Prägnanz](https://lawsofux.com/law-of-pragnanz/)

package/dist/resources/skills/userinterface-wiki/rules/ux-progressive-disclosure.md

@@ -0,0 +1,41 @@
+---
+title: Show What Matters Now, Reveal Complexity Later
+impact: HIGH
+tags: ux, progressive-disclosure, complexity
+---
+
+## Show What Matters Now, Reveal Complexity Later
+
+Don't overwhelm users with everything at once. Reveal complexity incrementally as needed.
+
+**Incorrect (all controls visible):**
+
+```tsx
+function Editor() {
+  return (
+    <div>
+      <BasicTools />
+      <AdvancedTools />
+      <ExpertTools />
+      <DebugTools />
+    </div>
+  );
+}
+```
+
+**Correct (progressive disclosure):**
+
+```tsx
+function Editor() {
+  const [showAdvanced, setShowAdvanced] = useState(false);
+  return (
+    <div>
+      <BasicTools />
+      {showAdvanced && <AdvancedTools />}
+      <button onClick={() => setShowAdvanced(!showAdvanced)}>
+        Toggle
+      </button>
+    </div>
+  );
+}
+```

package/dist/resources/skills/userinterface-wiki/rules/ux-proximity-grouping.md

@@ -0,0 +1,38 @@
+---
+title: Group Related Elements Spatially
+impact: HIGH
+tags: ux, proximity, grouping, layout
+---
+
+## Group Related Elements Spatially
+
+Elements near each other are perceived as related. Use spacing to create visual groups.
+
+**Incorrect (uniform spacing between unrelated items):**
+
+```css
+.form label,
+.form input,
+.form .hint,
+.form .divider {
+  margin-bottom: 16px;
+}
+```
+
+**Correct (tighter spacing within groups, larger between):**
+
+```css
+.form label {
+  margin-bottom: 4px;
+}
+
+.form input {
+  margin-bottom: 2px;
+}
+
+.form .hint {
+  margin-bottom: 24px;
+}
+```
+
+Reference: [Law of Proximity](https://lawsofux.com/law-of-proximity/)

package/dist/resources/skills/userinterface-wiki/rules/ux-serial-position.md

@@ -0,0 +1,31 @@
+---
+title: Place Key Items First or Last
+impact: MEDIUM
+tags: ux, serial-position, navigation, order
+---
+
+## Place Key Items First or Last
+
+Users best remember the first and last items in a sequence. Place the most important actions at these positions.
+
+**Incorrect (important action buried in middle):**
+
+```tsx
+<nav>
+  <Link href="/settings">Settings</Link>
+  <Link href="/">Home</Link>
+  <Link href="/about">About</Link>
+</nav>
+```
+
+**Correct (key items at edges):**
+
+```tsx
+<nav>
+  <Link href="/">Home</Link>
+  <Link href="/about">About</Link>
+  <Link href="/settings">Settings</Link>
+</nav>
+```
+
+Reference: [Serial Position Effect](https://lawsofux.com/serial-position-effect/)

package/dist/resources/skills/userinterface-wiki/rules/ux-similarity-consistency.md

@@ -0,0 +1,35 @@
+---
+title: Similar Elements Should Look Alike
+impact: HIGH
+tags: ux, similarity, consistency, visual
+---
+
+## Similar Elements Should Look Alike
+
+Elements that function the same should look the same. Visual consistency signals functional consistency.
+
+**Incorrect (same function, different appearance):**
+
+```css
+.save-button {
+  background: blue;
+  border-radius: 8px;
+}
+
+.submit-button {
+  background: green;
+  border-radius: 0;
+}
+```
+
+**Correct (same function, same appearance):**
+
+```css
+.primary-action {
+  background: var(--gray-12);
+  color: var(--gray-1);
+  border-radius: 8px;
+}
+```
+
+Reference: [Law of Similarity](https://lawsofux.com/law-of-similarity/)

package/dist/resources/skills/userinterface-wiki/rules/ux-teslers-complexity.md

@@ -0,0 +1,28 @@
+---
+title: Move Complexity, Don't Hide It
+impact: MEDIUM
+tags: ux, teslers, complexity, simplicity
+---
+
+## Move Complexity, Don't Hide It
+
+Every system has irreducible complexity. The question is who handles it — the user or the system.
+
+**Incorrect (complexity pushed to user):**
+
+```tsx
+<input
+  type="text"
+  placeholder="Enter date as YYYY-MM-DDTHH:mm:ss.sssZ"
+/>
+```
+
+**Correct (system absorbs complexity):**
+
+```tsx
+<DatePicker
+  onChange={(date) => setDate(date.toISOString())}
+/>
+```
+
+Reference: [Tesler's Law](https://lawsofux.com/teslers-law/)

package/dist/resources/skills/userinterface-wiki/rules/ux-uniform-connectedness.md

@@ -0,0 +1,43 @@
+---
+title: Visually Connect Related Elements
+impact: MEDIUM
+tags: ux, connectedness, grouping, visual
+---
+
+## Visually Connect Related Elements
+
+Elements that are visually connected (by lines, color, or frames) are perceived as more related.
+
+**Incorrect (steps with no visual connection):**
+
+```tsx
+function Steps({ current }) {
+  return (
+    <div>
+      <span>Step 1</span>
+      <span>Step 2</span>
+      <span>Step 3</span>
+    </div>
+  );
+}
+```
+
+**Correct (connected with a visual line):**
+
+```tsx
+function Steps({ current }) {
+  return (
+    <div className={styles.steps}>
+      {steps.map((step, i) => (
+        <div key={step.id} className={styles.step} data-active={i <= current}>
+          <div className={styles.dot} />
+          {i < steps.length - 1 && <div className={styles.connector} />}
+          <span>{step.label}</span>
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+Reference: [Law of Uniform Connectedness](https://lawsofux.com/law-of-uniform-connectedness/)

package/dist/resources/skills/userinterface-wiki/rules/ux-von-restorff-emphasis.md

@@ -0,0 +1,29 @@
+---
+title: Make Important Elements Visually Distinct
+impact: HIGH
+tags: ux, von-restorff, emphasis, distinction
+---
+
+## Make Important Elements Visually Distinct
+
+When multiple similar elements are present, the one that differs is most likely to be remembered.
+
+**Incorrect (primary action blends in):**
+
+```tsx
+<div className={styles.actions}>
+  <button className={styles.button}>Cancel</button>
+  <button className={styles.button}>Delete Account</button>
+</div>
+```
+
+**Correct (destructive action stands out):**
+
+```tsx
+<div className={styles.actions}>
+  <button className={styles["button-secondary"]}>Cancel</button>
+  <button className={styles["button-danger"]}>Delete Account</button>
+</div>
+```
+
+Reference: [Von Restorff Effect](https://lawsofux.com/von-restorff-effect/)

package/dist/resources/skills/userinterface-wiki/rules/ux-zeigarnik-show-incomplete.md

@@ -0,0 +1,36 @@
+---
+title: Show Incomplete State to Drive Completion
+impact: MEDIUM
+tags: ux, zeigarnik, incomplete, engagement
+---
+
+## Show Incomplete State to Drive Completion
+
+People remember incomplete tasks better than completed ones. Use this to drive engagement.
+
+**Incorrect (no indication of incomplete profile):**
+
+```tsx
+function Dashboard() {
+  return <DashboardContent />;
+}
+```
+
+**Correct (incomplete state visible):**
+
+```tsx
+function Dashboard({ profile }) {
+  return (
+    <div>
+      {!profile.isComplete && (
+        <Banner>
+          Complete your profile — {profile.completionPercent}% done
+        </Banner>
+      )}
+      <DashboardContent />
+    </div>
+  );
+}
+```
+
+Reference: [Zeigarnik Effect](https://lawsofux.com/zeigarnik-effect/)

package/dist/resources/skills/userinterface-wiki/rules/visual-animate-shadow-pseudo.md

@@ -0,0 +1,49 @@
+---
+title: Animate Shadows via Pseudo-Element Opacity
+impact: MEDIUM
+tags: visual, shadow, animation, performance
+---
+
+## Animate Shadows via Pseudo-Element Opacity
+
+Transitioning box-shadow directly forces expensive repaints. Instead, put the target shadow on a pseudo-element and animate its opacity.
+
+**Incorrect (animating box-shadow):**
+
+```css
+.card {
+  box-shadow: var(--shadow-1);
+  transition: box-shadow 0.2s ease;
+}
+
+.card:hover {
+  box-shadow: var(--shadow-3);
+}
+```
+
+**Correct (pseudo-element opacity):**
+
+```css
+.card {
+  position: relative;
+  box-shadow: var(--shadow-1);
+}
+
+.card::after {
+  content: "";
+  position: absolute;
+  inset: 0;
+  border-radius: inherit;
+  box-shadow: var(--shadow-3);
+  opacity: 0;
+  transition: opacity 0.2s ease;
+  pointer-events: none;
+  z-index: -1;
+}
+
+.card:hover::after {
+  opacity: 1;
+}
+```
+
+Reference: [Designing Beautiful Shadows in CSS](https://www.joshwcomeau.com/css/designing-shadows/)