gsd-pi 2.28.0 → 2.29.0-dev.2ccf3fb

package/src/resources/skills/userinterface-wiki/rules/type-font-display-swap.md

@@ -0,0 +1,28 @@
+---
+title: Use font-display swap to Avoid Invisible Text
+impact: MEDIUM
+tags: type, font-display, loading, FOIT
+---
+
+## Use font-display swap to Avoid Invisible Text
+
+Set font-display: swap so text renders immediately with a fallback font while the custom font loads.
+
+**Incorrect (invisible text during load):**
+
+```css
+@font-face {
+  font-family: "Inter";
+  src: url("/fonts/inter.woff2") format("woff2");
+}
+```
+
+**Correct (text visible immediately):**
+
+```css
+@font-face {
+  font-family: "Inter";
+  src: url("/fonts/inter.woff2") format("woff2");
+  font-display: swap;
+}
+```

package/src/resources/skills/userinterface-wiki/rules/type-justify-with-hyphens.md

@@ -0,0 +1,24 @@
+---
+title: Pair Justified Text with Hyphens
+impact: MEDIUM
+tags: type, justify, hyphens, rivers
+---
+
+## Pair Justified Text with Hyphens
+
+Justified text without hyphens creates rivers of whitespace. Always pair with hyphens: auto.
+
+**Incorrect (rivers of whitespace):**
+
+```css
+.article { text-align: justify; }
+```
+
+**Correct (hyphenation prevents rivers):**
+
+```css
+.article {
+  text-align: justify;
+  hyphens: auto;
+}
+```

package/src/resources/skills/userinterface-wiki/rules/type-letter-spacing-uppercase.md

@@ -0,0 +1,28 @@
+---
+title: Add Letter Spacing to Uppercase Text
+impact: MEDIUM
+tags: type, letter-spacing, uppercase, small-caps
+---
+
+## Add Letter Spacing to Uppercase Text
+
+Uppercase and small-caps text needs positive letter-spacing to feel open and readable.
+
+**Incorrect (tight uppercase):**
+
+```css
+.label {
+  text-transform: uppercase;
+  font-size: 12px;
+}
+```
+
+**Correct (opened up):**
+
+```css
+.label {
+  text-transform: uppercase;
+  font-size: 12px;
+  letter-spacing: 0.05em;
+}
+```

package/src/resources/skills/userinterface-wiki/rules/type-no-font-synthesis.md

@@ -0,0 +1,18 @@
+---
+title: Disable Font Synthesis for Missing Styles
+impact: LOW
+tags: type, synthesis, italic, bold
+---
+
+## Disable Font Synthesis for Missing Styles
+
+Set font-synthesis: none to prevent the browser from faking bold or italic. Browser-generated faux styles look terrible.
+
+**Correct:**
+
+```css
+.icon-font,
+.display-font {
+  font-synthesis: none;
+}
+```

package/src/resources/skills/userinterface-wiki/rules/type-oldstyle-nums-for-prose.md

@@ -0,0 +1,21 @@
+---
+title: Oldstyle Numbers for Body Text
+impact: MEDIUM
+tags: type, numeric, oldstyle, prose
+---
+
+## Oldstyle Numbers for Body Text
+
+Use oldstyle-nums in body text so numbers blend with lowercase letters. Use lining-nums in tables and headings.
+
+**Correct (prose):**
+
+```css
+.body-text { font-variant-numeric: oldstyle-nums; }
+```
+
+**Correct (data):**
+
+```css
+.data-table { font-variant-numeric: lining-nums tabular-nums; }
+```

package/src/resources/skills/userinterface-wiki/rules/type-opentype-contextual-alternates.md

@@ -0,0 +1,15 @@
+---
+title: Enable Contextual Alternates
+impact: MEDIUM
+tags: type, opentype, calt
+---
+
+## Enable Contextual Alternates
+
+Keep contextual alternates enabled (calt). They adjust punctuation and glyph shapes based on surrounding characters.
+
+**Correct (usually on by default, don't disable):**
+
+```css
+body { font-feature-settings: "calt" 1; }
+```

package/src/resources/skills/userinterface-wiki/rules/type-optical-sizing-auto.md

@@ -0,0 +1,25 @@
+---
+title: Keep Optical Sizing Auto
+impact: MEDIUM
+tags: type, variable-font, optical-sizing
+---
+
+## Keep Optical Sizing Auto
+
+Leave font-optical-sizing at auto. The font adjusts glyph shapes for the current size — thicker strokes at small sizes, finer details at large sizes.
+
+**Incorrect (forced optical size):**
+
+```css
+body {
+  font-optical-sizing: none;
+}
+```
+
+**Correct (automatic adjustment):**
+
+```css
+body {
+  font-optical-sizing: auto;
+}
+```

package/src/resources/skills/userinterface-wiki/rules/type-proper-fractions.md

@@ -0,0 +1,15 @@
+---
+title: Use Typographic Fractions
+impact: LOW
+tags: type, fractions, numeric, opentype
+---
+
+## Use Typographic Fractions
+
+Enable diagonal-fractions to convert 1/2, 1/3, etc. into proper typographic fractions.
+
+**Correct:**
+
+```css
+.recipe { font-variant-numeric: diagonal-fractions; }
+```

package/src/resources/skills/userinterface-wiki/rules/type-slashed-zero.md

@@ -0,0 +1,17 @@
+---
+title: Slashed Zero for Disambiguation
+impact: MEDIUM
+tags: type, zero, disambiguation
+---
+
+## Slashed Zero for Disambiguation
+
+Enable slashed zero in code-adjacent UIs so users never confuse 0 with O.
+
+**Correct:**
+
+```css
+.code { font-variant-numeric: slashed-zero; }
+/* or */
+.code { font-feature-settings: "zero"; }
+```

package/src/resources/skills/userinterface-wiki/rules/type-tabular-nums-for-data.md

@@ -0,0 +1,21 @@
+---
+title: Tabular Numbers for Data Display
+impact: HIGH
+tags: type, numeric, tabular, alignment
+---
+
+## Tabular Numbers for Data Display
+
+Use tabular-nums for any numeric data that should align in columns (tables, dashboards, pricing).
+
+**Incorrect (proportional numbers misalign):**
+
+```css
+.price { font-variant-numeric: proportional-nums; }
+```
+
+**Correct (tabular numbers align):**
+
+```css
+.price { font-variant-numeric: tabular-nums; }
+```

package/src/resources/skills/userinterface-wiki/rules/type-text-wrap-balance-headings.md

@@ -0,0 +1,21 @@
+---
+title: Balance Headings with text-wrap
+impact: MEDIUM
+tags: type, text-wrap, balance, headings
+---
+
+## Balance Headings with text-wrap
+
+Use text-wrap: balance on headings to make lines roughly equal length instead of one long line and a short orphan.
+
+**Incorrect (unbalanced heading):**
+
+```css
+h1 { /* default text-wrap */ }
+```
+
+**Correct (balanced):**
+
+```css
+h1 { text-wrap: balance; }
+```

package/src/resources/skills/userinterface-wiki/rules/type-text-wrap-pretty.md

@@ -0,0 +1,16 @@
+---
+title: Use text-wrap pretty for Body Text
+impact: MEDIUM
+tags: type, text-wrap, orphans, pretty
+---
+
+## Use text-wrap pretty for Body Text
+
+Use text-wrap: pretty for body text to reduce orphans. Use text-wrap: balance for headings.
+
+**Correct:**
+
+```css
+p { text-wrap: pretty; }
+h1, h2, h3 { text-wrap: balance; }
+```

package/src/resources/skills/userinterface-wiki/rules/type-underline-offset.md

@@ -0,0 +1,25 @@
+---
+title: Offset Underlines from Descenders
+impact: MEDIUM
+tags: type, underline, offset, decoration
+---
+
+## Offset Underlines from Descenders
+
+Use text-underline-offset to push underlines below descenders so they look intentional.
+
+**Incorrect (underline collides with descenders):**
+
+```css
+a { text-decoration: underline; }
+```
+
+**Correct (offset underline):**
+
+```css
+a {
+  text-decoration: underline;
+  text-underline-offset: 3px;
+  text-decoration-skip-ink: auto;
+}
+```

package/src/resources/skills/userinterface-wiki/rules/type-variable-weight-continuous.md

@@ -0,0 +1,23 @@
+---
+title: Use Continuous Weight Values with Variable Fonts
+impact: LOW
+tags: type, variable-font, weight
+---
+
+## Use Continuous Weight Values with Variable Fonts
+
+Variable fonts accept any integer from 100-900, not just the standard stops at 400, 500, 600, 700.
+
+**Incorrect (limited to standard stops):**
+
+```css
+.medium { font-weight: 500; }
+.semibold { font-weight: 600; }
+```
+
+**Correct (precise weight control):**
+
+```css
+.medium { font-weight: 450; }
+.semibold { font-weight: 550; }
+```

package/src/resources/skills/userinterface-wiki/rules/ux-aesthetic-usability.md

@@ -0,0 +1,32 @@
+---
+title: Visual Polish Increases Perceived Usability
+impact: MEDIUM
+tags: ux, aesthetic, usability, polish
+---
+
+## Visual Polish Increases Perceived Usability
+
+Users perceive aesthetically pleasing design as more usable. Small visual details compound into trust.
+
+**Incorrect (unstyled, raw elements):**
+
+```css
+.card {
+  border: 1px solid black;
+  padding: 10px;
+}
+```
+
+**Correct (considered visual treatment):**
+
+```css
+.card {
+  padding: 16px;
+  background: var(--gray-2);
+  border: 1px solid var(--gray-a4);
+  border-radius: 12px;
+  box-shadow: var(--shadow-1);
+}
+```
+
+Reference: [Aesthetic-Usability Effect](https://lawsofux.com/aesthetic-usability-effect/)

package/src/resources/skills/userinterface-wiki/rules/ux-cognitive-load-reduce.md

@@ -0,0 +1,49 @@
+---
+title: Minimize Extraneous Cognitive Load
+impact: HIGH
+tags: ux, cognitive-load, simplicity, noise
+---
+
+## Minimize Extraneous Cognitive Load
+
+Remove anything that doesn't help the user complete their task. Decoration, redundant labels, and unnecessary options all add load.
+
+**Incorrect (extraneous elements):**
+
+```tsx
+function DeleteDialog() {
+  return (
+    <dialog>
+      <Icon name="warning" size={64} />
+      <h2>Warning!</h2>
+      <p>Are you absolutely sure you want to delete?</p>
+      <p>This action is permanent and cannot be undone.</p>
+      <p>All associated data will be lost forever.</p>
+      <div>
+        <button>Cancel</button>
+        <button>Delete</button>
+        <button>Learn More</button>
+      </div>
+    </dialog>
+  );
+}
+```
+
+**Correct (essential information only):**
+
+```tsx
+function DeleteDialog() {
+  return (
+    <dialog>
+      <h2>Delete this item?</h2>
+      <p>This can't be undone.</p>
+      <div>
+        <button>Cancel</button>
+        <button>Delete</button>
+      </div>
+    </dialog>
+  );
+}
+```
+
+Reference: [Cognitive Load](https://lawsofux.com/cognitive-load/)

package/src/resources/skills/userinterface-wiki/rules/ux-common-region-boundaries.md

@@ -0,0 +1,50 @@
+---
+title: Use Boundaries to Group Related Content
+impact: MEDIUM
+tags: ux, common-region, boundaries, grouping
+---
+
+## Use Boundaries to Group Related Content
+
+Elements sharing a clearly defined boundary are perceived as a group.
+
+**Incorrect (flat list with no visual grouping):**
+
+```tsx
+function Settings() {
+  return (
+    <div>
+      <Toggle label="Dark mode" />
+      <Toggle label="Notifications" />
+      <Input label="Email" />
+      <Input label="Password" />
+    </div>
+  );
+}
+```
+
+**Correct (bounded sections):**
+
+```tsx
+function Settings() {
+  return (
+    <div>
+      <section className={styles.group}>
+        <h3>Appearance</h3>
+        <Toggle label="Dark mode" />
+      </section>
+      <section className={styles.group}>
+        <h3>Notifications</h3>
+        <Toggle label="Notifications" />
+      </section>
+      <section className={styles.group}>
+        <h3>Account</h3>
+        <Input label="Email" />
+        <Input label="Password" />
+      </section>
+    </div>
+  );
+}
+```
+
+Reference: [Law of Common Region](https://lawsofux.com/law-of-common-region/)

package/src/resources/skills/userinterface-wiki/rules/ux-doherty-perceived-speed.md

@@ -0,0 +1,29 @@
+---
+title: Fake Speed When Actual Speed Isn't Possible
+impact: HIGH
+tags: ux, doherty, perceived-speed, skeleton
+---
+
+## Fake Speed When Actual Speed Isn't Possible
+
+If you can't make something fast, make it feel fast with optimistic UI, skeletons, or progress indicators.
+
+**Incorrect (blank screen during load):**
+
+```tsx
+function Page() {
+  const { data, isLoading } = useFetch("/api/data");
+  if (isLoading) return null;
+  return <Content data={data} />;
+}
+```
+
+**Correct (skeleton during load):**
+
+```tsx
+function Page() {
+  const { data, isLoading } = useFetch("/api/data");
+  if (isLoading) return <Skeleton />;
+  return <Content data={data} />;
+}
+```

package/src/resources/skills/userinterface-wiki/rules/ux-doherty-under-400ms.md

@@ -0,0 +1,30 @@
+---
+title: Respond Within 400ms
+impact: CRITICAL
+tags: ux, doherty, latency, response-time
+---
+
+## Respond Within 400ms
+
+Interactions must respond within 400ms to feel instant. Above this threshold, users notice delay.
+
+**Incorrect (no feedback during loading):**
+
+```tsx
+async function handleClick() {
+  const data = await fetchData();
+  setResult(data);
+}
+```
+
+**Correct (immediate optimistic feedback):**
+
+```tsx
+async function handleClick() {
+  setResult(optimisticData);
+  const data = await fetchData();
+  setResult(data);
+}
+```
+
+Reference: Doherty, W. J. (1979). Managing VM/CMS systems for user effectiveness.

package/src/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/src/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/src/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/src/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/src/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/)