update 'component-guide/SKILL.md' and add 'react-rerender-mental-models (#1995)

Author: jeesunikim

.claude/skills/component-guide/SKILL.md

@@ -102,7 +102,9 @@ export const ComponentName = ({ propName }: ComponentNameProps) => {
 ### Do
 - Use design system components for all standard UI elements
 - Use SCSS with BEM-ish class naming (`ComponentName__element--modifier`)
-- Use `pxToRem()` for spacing values in SCSS
+- Use `pxToRem()` for spacing values in SCSS (skip for trivial values like
+  `1px` or `-1px` — e.g., borders, outlines, offsets — where rem scaling is
+  not meaningful)
 - Use SDS CSS custom properties for colors/fonts/gaps: `var(--sds-clr-gray-06)`,
   `var(--sds-ff-monospace)`, `var(--sds-gap-md)`
 - Use `data-*` attributes for state-driven styling instead of modifier classes:

.claude/skills/react-rerender-mental-models/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: react-rerender-mental-models
+description: Correct mental models for React re-renders and memoization. Use this skill when writing, reviewing, or optimizing React components to avoid common misconceptions about performance. Debunks the myth that "props cause re-renders" and teaches when memoization actually helps.
+license: MIT
+metadata:
+  author: freighter
+  version: "1.0.0"
+---
+
+# React Re-render Mental Models
+
+A practical guide to understanding how React re-renders actually work, debunking common misconceptions, and knowing when optimization is truly needed.
+
+## Core Philosophy
+
+> "Trust React to be fast. Write simple code. Measure when something actually feels slow. Optimize based on data, not fear."
+
+## When to Apply
+
+Reference these guidelines when:
+- Writing new React components
+- Reviewing code for performance issues
+- Deciding whether to add React.memo, useCallback, or useMemo
+- Debugging perceived "slowness" in React apps
+- Refactoring component architecture
+
+## Rule Categories
+
+| Category | Prefix | Description |
+|----------|--------|-------------|
+| Mental Models | `mental-model-` | Correct understanding of how React works |
+| Anti-Patterns | `anti-pattern-` | Common mistakes to avoid |
+| When to Memoize | `when-to-memo-` | Profile-driven optimization guidance |
+| Architecture | `architecture-` | Component structure patterns |
+
+## Quick Reference
+
+### Mental Models (Foundational)
+
+- `mental-model-parent-triggers` - Props don't trigger re-renders; parent re-renders do
+- `mental-model-render-vs-commit` - Render ≠ Commit; renders are cheap, commits touch DOM
+
+### Anti-Patterns (Avoid These)
+
+- `anti-pattern-premature-memo` - Don't memoize without profiling first
+- `anti-pattern-memoization-trap` - Real bottlenecks are often not re-renders
+
+### When to Memoize (Use Sparingly)
+
+- `when-to-memo-context-values` - Stabilize context object references
+- `when-to-usecallback` - Only needed when child is already memoized
+
+### Architecture (Prefer These)
+
+- `architecture-local-state` - Keep state close to where it's used
+- `architecture-composition` - Component structure prevents re-renders naturally
+
+## What Actually Triggers Re-renders
+
+1. **Component's own state changes** (useState, useReducer)
+2. **Parent component re-renders** (cascades to all children)
+3. **Context value changes** (for consumers of that context)
+
+**Props are NOT on this list.** Props are inputs to a render that's already happening—they don't schedule one.
+
+## The Performance Debugging Flow
+
+```
+1. Something feels slow
+2. Open React DevTools Profiler
+3. Record the interaction
+4. Look for components with 50ms+ render times
+5. If found → consider memoization
+6. If not found → the problem is elsewhere:
+   - API calls firing too often
+   - Unoptimized images
+   - Too many DOM nodes
+   - CSS animations triggering layout
+```
+
+## React 19 Compiler
+
+This project runs React 19. The **React Compiler** (formerly React Forget) is
+an opt-in build-time tool that statically analyzes components and automatically
+inserts the equivalent of `useMemo`, `useCallback`, and `React.memo`. It is
+**not enabled by default** — it requires `babel-plugin-react-compiler` (or the
+SWC equivalent) to be installed and configured.
+
+- If the compiler is **enabled in this project**: skip manual memoization. The
+  compiler tracks data flow within each component and caches results at a more
+  granular level than hand-written hooks. If the compiler opts out a specific
+  component (e.g. due to side effects during render), fix the component rather
+  than adding manual memo.
+- If the compiler is **not enabled** (current default): follow the rules below,
+  but prefer architecture fixes (local state, composition) over adding
+  memo/useCallback.
+
+Regardless of compiler status, the mental models and architecture rules in this
+skill still apply — composition and local state are always better than relying
+on memoization (auto or manual). Re-render triggers remain the same either way.
+
+## How to Use
+
+Read individual rule files for detailed explanations and code examples:
+
+```
+rules/mental-model-parent-triggers.md
+rules/anti-pattern-premature-memo.md
+rules/architecture-local-state.md
+```
+
+Each rule file contains:
+- Brief explanation of why it matters
+- Incorrect code example with explanation
+- Correct code example with explanation

.claude/skills/react-rerender-mental-models/rules/anti-pattern-memoization-trap.md

@@ -0,0 +1,78 @@
+---
+title: The Memoization Trap
+impact: HIGH
+impactDescription: identifies real performance bottlenecks
+tags: anti-pattern, debugging, bottlenecks, profiling
+---
+
+## The Memoization Trap
+
+You see slowness, assume it's re-renders, add memoization, feel productive—meanwhile the real issue is something else entirely.
+
+### Real-World Example
+
+A search input feels laggy. Every keystroke has a noticeable delay.
+
+```tsx
+// The "obvious" fix that doesn't work
+const ProductList = () => {
+  const [search, setSearch] = useState("");
+  const [products, setProducts] = useState([]);
+
+  // ❌ Added useMemo - still laggy
+  const filteredProducts = useMemo(
+    () => products.filter((p) =>
+      p.name.toLowerCase().includes(search.toLowerCase())
+    ),
+    [products, search]
+  );
+
+  // ❌ Added useCallback - still laggy
+  const handleChange = useCallback((value) => {
+    setSearch(value);
+  }, []);
+
+  return (
+    <>
+      <SearchInput value={search} onChange={handleChange} />
+      {filteredProducts.map((product) => (
+        <MemoizedProductCard key={product.id} product={product} />
+      ))}
+    </>
+  );
+};
+```
+
+### The Actual Problem
+
+After profiling:
+- The `.filter()` call: ~0.3ms on 200 products
+- Re-rendering ProductCards: ~8ms total
+- **A useEffect hitting analytics API on every keystroke: 200ms+ blocking**
+
+```tsx
+// ✅ The real fix
+useEffect(() => {
+  // Debounce the analytics call
+  const timer = setTimeout(() => {
+    analytics.track("search", { query: search });
+  }, 300);
+  return () => clearTimeout(timer);
+}, [search]);
+```
+
+### Common Real Bottlenecks (Not Re-renders)
+
+| Symptom | Likely Cause | Fix |
+|---------|--------------|-----|
+| Laggy input | API calls on every keystroke | Debounce |
+| Slow initial load | Large unoptimized images | Lazy load, compress |
+| Scroll jank | Too many DOM nodes (1000+) | Virtualization |
+| Animation stutter | CSS triggering layout recalc | Use transform/opacity only |
+| Memory issues | Event listeners not cleaned up | Proper useEffect cleanup |
+
+### Key Takeaway
+
+If the React DevTools Profiler shows render times under 16ms, re-renders aren't
+the problem — look at network calls, DOM node count, and CSS layout thrashing
+instead.

.claude/skills/react-rerender-mental-models/rules/anti-pattern-premature-memo.md

@@ -0,0 +1,78 @@
+---
+title: Don't Memoize Without Profiling
+impact: HIGH
+impactDescription: prevents unnecessary complexity
+tags: anti-pattern, memo, useCallback, useMemo, profiling
+---
+
+## Don't Memoize Without Profiling
+
+Adding `React.memo`, `useCallback`, and `useMemo` without profiling first is premature optimization. For cheap components (most of them), the memo check itself costs more than just re-rendering.
+
+### The Problem
+
+```tsx
+// ❌ Incorrect: Memoizing without knowing if it helps
+const ProductCard = React.memo(({ product, onSelect }) => {
+  return (
+    <div onClick={() => onSelect(product.id)}>
+      <h3>{product.name}</h3>
+      <p>${product.price}</p>
+    </div>
+  );
+});
+
+const ProductList = ({ products }) => {
+  // ❌ useCallback "just in case"
+  const handleSelect = useCallback((id) => {
+    console.log("Selected:", id);
+  }, []);
+
+  return products.map((p) => (
+    <ProductCard key={p.id} product={p} onSelect={handleSelect} />
+  ));
+};
+```
+
+This adds complexity with no proven benefit. The memo check happens every render, comparing props that probably haven't changed.
+
+### The Correct Approach
+
+**Step 1: Write simple code first**
+
+```tsx
+// ✅ Correct: Simple, readable, no premature optimization
+const ProductCard = ({ product, onSelect }) => {
+  return (
+    <div onClick={() => onSelect(product.id)}>
+      <h3>{product.name}</h3>
+      <p>${product.price}</p>
+    </div>
+  );
+};
+
+const ProductList = ({ products }) => {
+  const handleSelect = (id) => {
+    console.log("Selected:", id);
+  };
+
+  return products.map((p) => (
+    <ProductCard key={p.id} product={p} onSelect={handleSelect} />
+  ));
+};
+```
+
+**Step 2: Profile when something feels slow** — only add memoization for
+components with **50ms+ render times** that re-render frequently with unchanged
+props.
+
+### The Real Cost of Premature Memoization
+
+- **Cognitive overhead**: More code to read and maintain
+- **Hidden bugs**: Stale closures from incorrect dependency arrays
+- **False confidence**: "I optimized it" when the real issue is elsewhere
+- **Memo overhead**: The comparison check runs every render
+
+> **Note:** If the React Compiler is enabled, it handles memoization
+> automatically — manual `memo`/`useMemo`/`useCallback` becomes unnecessary for
+> most components.