niahere 0.2.61 → 0.2.63

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

package/skills/userinterface-wiki/rules/visual-border-alpha-colors.md

@@ -0,0 +1,25 @@
+---
+title: Use Semi-Transparent Borders for Subtle Separation
+impact: MEDIUM
+tags: visual, border, alpha, separation
+---
+
+## Use Semi-Transparent Borders for Subtle Separation
+
+Semi-transparent borders adapt to any background color and create subtle, non-jarring separation.
+
+**Incorrect (hardcoded border color):**
+
+```css
+.card {
+  border: 1px solid #e5e5e5;
+}
+```
+
+**Correct (alpha border):**
+
+```css
+.card {
+  border: 1px solid var(--gray-a4);
+}
+```

package/skills/userinterface-wiki/rules/visual-button-shadow-anatomy.md

@@ -0,0 +1,49 @@
+---
+title: Use Full Shadow Anatomy on Buttons
+impact: HIGH
+tags: visual, shadow, button, depth, gradient
+---
+
+## Use Full Shadow Anatomy on Buttons
+
+A polished button uses six layered techniques, not just a single box-shadow.
+
+1. **Outer cut shadow** — 0.5px dark box-shadow to "cut" the button into the surface
+2. **Inner ambient highlight** — 1px inset box-shadow on all sides for environmental light reflections
+3. **Inner top highlight** — 1px inset top highlight for the primary light source from above
+4. **Layered depth shadows** — At least 3 external shadows for natural lighting
+5. **Text drop-shadow** — Drop-shadow on text/icons for better contrast against the button background
+6. **Subtle gradient background** — If you can tell there's a gradient, it's too much
+
+**Incorrect (flat button):**
+
+```css
+.button {
+  background: var(--gray-12);
+  color: var(--gray-1);
+  box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
+}
+```
+
+**Correct (full shadow anatomy):**
+
+```css
+.button {
+  background: linear-gradient(
+    to bottom,
+    color-mix(in srgb, var(--gray-12) 100%, white 4%),
+    var(--gray-12)
+  );
+  color: var(--gray-1);
+  box-shadow:
+    0 0 0 0.5px rgba(0, 0, 0, 0.3),
+    inset 0 0 0 1px rgba(255, 255, 255, 0.04),
+    inset 0 1px 0 rgba(255, 255, 255, 0.07),
+    0 1px 2px rgba(0, 0, 0, 0.1),
+    0 2px 4px rgba(0, 0, 0, 0.06),
+    0 4px 8px rgba(0, 0, 0, 0.03);
+  text-shadow: 0 1px 1px rgba(0, 0, 0, 0.15);
+}
+```
+
+Reference: [@PixelJanitor](https://threadreaderapp.com/thread/1623358514440859649)

package/skills/userinterface-wiki/rules/visual-concentric-radius.md

@@ -0,0 +1,40 @@
+---
+title: Concentric Border Radius for Nested Elements
+impact: HIGH
+tags: visual, border-radius, concentric, nesting
+---
+
+## Concentric Border Radius for Nested Elements
+
+When nesting rounded elements, inner radius must equal outer radius minus the gap. Same radius on both creates uneven curves.
+
+**Incorrect (same radius on both):**
+
+```css
+.outer {
+  border-radius: 16px;
+  padding: 8px;
+}
+
+.inner {
+  border-radius: 16px;
+}
+```
+
+**Correct (concentric radius):**
+
+```css
+.outer {
+  --padding: 8px;
+  --inner-radius: 8px;
+
+  border-radius: calc(var(--inner-radius) + var(--padding));
+  padding: var(--padding);
+}
+
+.inner {
+  border-radius: var(--inner-radius);
+}
+```
+
+Reference: [Concentric Border Radius](https://jakub.kr/work/concentric-border-radius)

package/skills/userinterface-wiki/rules/visual-consistent-spacing-scale.md

@@ -0,0 +1,35 @@
+---
+title: Use a Consistent Spacing Scale
+impact: HIGH
+tags: visual, spacing, scale, consistency
+---
+
+## Use a Consistent Spacing Scale
+
+Don't use arbitrary pixel values for spacing. Define a scale and stick to it throughout the UI.
+
+**Incorrect (arbitrary values):**
+
+```css
+.header { padding: 17px; }
+.card { margin-bottom: 13px; }
+.section { gap: 22px; }
+```
+
+**Correct (consistent scale):**
+
+```css
+:root {
+  --space-1: 4px;
+  --space-2: 8px;
+  --space-3: 12px;
+  --space-4: 16px;
+  --space-5: 24px;
+  --space-6: 32px;
+  --space-7: 48px;
+}
+
+.header { padding: var(--space-4); }
+.card { margin-bottom: var(--space-3); }
+.section { gap: var(--space-5); }
+```

package/skills/userinterface-wiki/rules/visual-layered-shadows.md

@@ -0,0 +1,30 @@
+---
+title: Layer Multiple Shadows for Realistic Depth
+impact: HIGH
+tags: visual, shadow, layered, depth
+---
+
+## Layer Multiple Shadows for Realistic Depth
+
+A single box-shadow looks flat. Layer multiple shadows with increasing blur and decreasing opacity to mimic real light.
+
+**Incorrect (single flat shadow):**
+
+```css
+.card {
+  box-shadow: 0 4px 16px rgba(0, 0, 0, 0.2);
+}
+```
+
+**Correct (layered shadows):**
+
+```css
+.card {
+  box-shadow:
+    0 1px 2px rgba(0, 0, 0, 0.06),
+    0 4px 8px rgba(0, 0, 0, 0.04),
+    0 12px 24px rgba(0, 0, 0, 0.03);
+}
+```
+
+Reference: [Designing Beautiful Shadows in CSS](https://www.joshwcomeau.com/css/designing-shadows/)

package/skills/userinterface-wiki/rules/visual-no-pure-black-shadow.md

@@ -0,0 +1,25 @@
+---
+title: Use Neutral Colors for Shadows, Not Pure Black
+impact: MEDIUM
+tags: visual, shadow, color, neutral
+---
+
+## Use Neutral Colors for Shadows, Not Pure Black
+
+Pure black shadows look harsh and artificial. Use deep neutrals or semi-transparent dark colors.
+
+**Incorrect (pure black):**
+
+```css
+.card {
+  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.25);
+}
+```
+
+**Correct (neutral shadow):**
+
+```css
+.card {
+  box-shadow: 0 4px 12px rgba(17, 24, 39, 0.08);
+}
+```

package/skills/userinterface-wiki/rules/visual-shadow-direction.md

@@ -0,0 +1,25 @@
+---
+title: Consistent Shadow Direction Across UI
+impact: HIGH
+tags: visual, shadow, direction, light-source
+---
+
+## Consistent Shadow Direction Across UI
+
+All shadows must share the same offset direction to imply a single light source. Mixed directions feel broken.
+
+**Incorrect (conflicting light sources):**
+
+```css
+.card { box-shadow: 0 4px 8px rgba(0, 0, 0, 0.1); }
+.modal { box-shadow: 4px 0 8px rgba(0, 0, 0, 0.1); }
+.tooltip { box-shadow: 0 -4px 8px rgba(0, 0, 0, 0.1); }
+```
+
+**Correct (consistent top-down light):**
+
+```css
+.card { box-shadow: 0 2px 8px rgba(0, 0, 0, 0.08); }
+.modal { box-shadow: 0 8px 24px rgba(0, 0, 0, 0.12); }
+.tooltip { box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1); }
+```

package/skills/userinterface-wiki/rules/visual-shadow-matches-elevation.md

@@ -0,0 +1,23 @@
+---
+title: Shadow Size Indicates Elevation
+impact: MEDIUM
+tags: visual, shadow, elevation, hierarchy
+---
+
+## Shadow Size Indicates Elevation
+
+Larger blur and offset means higher elevation. Use a consistent shadow scale across your UI.
+
+**Correct (elevation scale):**
+
+```css
+:root {
+  --shadow-1: 0 1px 2px rgba(0, 0, 0, 0.05);
+  --shadow-2: 0 2px 8px rgba(0, 0, 0, 0.08);
+  --shadow-3: 0 8px 24px rgba(0, 0, 0, 0.12);
+}
+
+.card { box-shadow: var(--shadow-1); }
+.dropdown { box-shadow: var(--shadow-2); }
+.modal { box-shadow: var(--shadow-3); }
+```

package/skills/userinterface-wiki/rules/weight-duration-matches-action.md

@@ -0,0 +1,29 @@
+---
+title: Sound Duration Matches Action Duration
+impact: MEDIUM
+tags: weight, duration, action
+---
+
+## Sound Duration Matches Action Duration
+
+Sound duration should match action duration.
+
+**Incorrect (long sound for instant action):**
+
+```tsx
+function handleClick() {
+  playSound("long-whoosh"); // 2000ms
+}
+```
+
+**Correct (matched duration):**
+
+```tsx
+function handleClick() {
+  playSound("click"); // 50ms
+}
+
+function handleUpload() {
+  playSound("upload-progress"); // Matches upload duration
+}
+```

package/skills/userinterface-wiki/rules/weight-match-action.md

@@ -0,0 +1,32 @@
+---
+title: Match Sound Weight to Action
+impact: MEDIUM
+tags: weight, action, importance
+---
+
+## Match Sound Weight to Action
+
+Sound weight should match action importance.
+
+**Incorrect (fanfare for toggle):**
+
+```tsx
+function handleToggle() {
+  playSound("triumphant-fanfare");
+  setEnabled(!enabled);
+}
+```
+
+**Correct (weight matches action):**
+
+```tsx
+function handleToggle() {
+  playSound("soft-click");
+  setEnabled(!enabled);
+}
+
+function handlePurchase() {
+  playSound("success-chime");
+  completePurchase();
+}
+```