@ranimontagna/agent-toolkit 0.1.6 → 0.1.9

package/skills/frontend/design/ui-ux-pro-max/scripts/search.py

@@ -0,0 +1,114 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+UI/UX Pro Max Search - BM25 search engine for UI/UX style guides
+Usage: python search.py "<query>" [--domain <domain>] [--stack <stack>] [--max-results 3]
+       python search.py "<query>" --design-system [-p "Project Name"]
+       python search.py "<query>" --design-system --persist [-p "Project Name"] [--page "dashboard"]
+
+Domains: style, prompt, color, chart, landing, product, ux, typography, google-fonts
+Stacks: react, nextjs, vue, svelte, astro, swiftui, react-native, flutter, nuxtjs, nuxt-ui, html-tailwind, shadcn, jetpack-compose, threejs
+
+Persistence (Master + Overrides pattern):
+  --persist    Save design system to design-system/MASTER.md
+  --page       Also create a page-specific override file in design-system/pages/
+"""
+
+import argparse
+import sys
+import io
+from core import CSV_CONFIG, AVAILABLE_STACKS, MAX_RESULTS, search, search_stack
+from design_system import generate_design_system, persist_design_system
+
+# Force UTF-8 for stdout/stderr to handle emojis on Windows (cp1252 default)
+if sys.stdout.encoding and sys.stdout.encoding.lower() != 'utf-8':
+    sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')
+if sys.stderr.encoding and sys.stderr.encoding.lower() != 'utf-8':
+    sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding='utf-8')
+
+
+def format_output(result):
+    """Format results for Claude consumption (token-optimized)"""
+    if "error" in result:
+        return f"Error: {result['error']}"
+
+    output = []
+    if result.get("stack"):
+        output.append(f"## UI Pro Max Stack Guidelines")
+        output.append(f"**Stack:** {result['stack']} | **Query:** {result['query']}")
+    else:
+        output.append(f"## UI Pro Max Search Results")
+        output.append(f"**Domain:** {result['domain']} | **Query:** {result['query']}")
+    output.append(f"**Source:** {result['file']} | **Found:** {result['count']} results\n")
+
+    for i, row in enumerate(result['results'], 1):
+        output.append(f"### Result {i}")
+        for key, value in row.items():
+            value_str = str(value)
+            if len(value_str) > 300:
+                value_str = value_str[:300] + "..."
+            output.append(f"- **{key}:** {value_str}")
+        output.append("")
+
+    return "\n".join(output)
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="UI Pro Max Search")
+    parser.add_argument("query", help="Search query")
+    parser.add_argument("--domain", "-d", choices=list(CSV_CONFIG.keys()), help="Search domain")
+    parser.add_argument("--stack", "-s", choices=AVAILABLE_STACKS, help=f"Stack-specific search. Available: {', '.join(AVAILABLE_STACKS)}")
+    parser.add_argument("--max-results", "-n", type=int, default=MAX_RESULTS, help="Max results (default: 3)")
+    parser.add_argument("--json", action="store_true", help="Output as JSON")
+    # Design system generation
+    parser.add_argument("--design-system", "-ds", action="store_true", help="Generate complete design system recommendation")
+    parser.add_argument("--project-name", "-p", type=str, default=None, help="Project name for design system output")
+    parser.add_argument("--format", "-f", choices=["ascii", "markdown"], default="ascii", help="Output format for design system")
+    # Persistence (Master + Overrides pattern)
+    parser.add_argument("--persist", action="store_true", help="Save design system to design-system/MASTER.md (creates hierarchical structure)")
+    parser.add_argument("--page", type=str, default=None, help="Create page-specific override file in design-system/pages/")
+    parser.add_argument("--output-dir", "-o", type=str, default=None, help="Output directory for persisted files (default: current directory)")
+
+    args = parser.parse_args()
+
+    # Design system takes priority
+    if args.design_system:
+        result = generate_design_system(
+            args.query, 
+            args.project_name, 
+            args.format,
+            persist=args.persist,
+            page=args.page,
+            output_dir=args.output_dir
+        )
+        print(result)
+        
+        # Print persistence confirmation
+        if args.persist:
+            project_slug = args.project_name.lower().replace(' ', '-') if args.project_name else "default"
+            print("\n" + "=" * 60)
+            print(f"✅ Design system persisted to design-system/{project_slug}/")
+            print(f"   📄 design-system/{project_slug}/MASTER.md (Global Source of Truth)")
+            if args.page:
+                page_filename = args.page.lower().replace(' ', '-')
+                print(f"   📄 design-system/{project_slug}/pages/{page_filename}.md (Page Overrides)")
+            print("")
+            print(f"📖 Usage: When building a page, check design-system/{project_slug}/pages/[page].md first.")
+            print(f"   If exists, its rules override MASTER.md. Otherwise, use MASTER.md.")
+            print("=" * 60)
+    # Stack search
+    elif args.stack:
+        result = search_stack(args.query, args.stack, args.max_results)
+        if args.json:
+            import json
+            print(json.dumps(result, indent=2, ensure_ascii=False))
+        else:
+            print(format_output(result))
+    # Domain search
+    else:
+        result = search(args.query, args.domain, args.max_results)
+        if args.json:
+            import json
+            print(json.dumps(result, indent=2, ensure_ascii=False))
+        else:
+            print(format_output(result))

package/skills/frontend/react/react-patterns/SKILL.md

@@ -52,7 +52,7 @@ React has no inheritance model for components. Compose with `children`, render p
 
 ## Hooks Discipline
 
-See [rules/react/hooks.md](../../rules/react/hooks.md) for the full ruleset. Highlights:
+See [rules/react/hooks.md](rules/react/hooks.md) for the full ruleset. Highlights:
 
 - Top-level only, never conditional
 - Cleanup every subscription, interval, listener
@@ -250,7 +250,7 @@ Wrap a component in `React.memo` only when:
 - Form inputs need labels — `<label htmlFor>` or `aria-label` if visually labeled by an icon
 - Manage focus on route changes and modal open/close
 - Run `axe` in component tests (see [skills/react-testing](../react-testing/SKILL.md))
-- Cross-link: [skills/accessibility/SKILL.md](../accessibility/SKILL.md) covers WCAG criteria and pattern libraries
+- Cross-link: skills/accessibility covers WCAG criteria and pattern libraries when that optional skill is installed
 
 ## Routing
 
@@ -264,8 +264,8 @@ This skill is router-agnostic. The patterns above work with React Router, TanSta
 
 ## Related
 
-- Rules: [rules/react/](../../rules/react/) — coding-style, hooks, patterns, security, testing
-- Skills: [react-performance](../react-performance/SKILL.md) for the Vercel-derived performance ruleset, [frontend-patterns](../frontend-patterns/SKILL.md) for cross-framework UI concerns, [accessibility](../accessibility/SKILL.md), [angular-developer](../angular-developer/SKILL.md) for framework comparison
+- Rules: [rules/react/](rules/react/) — coding-style, hooks, patterns, security, testing
+- Skills: [react-performance](../react-performance/SKILL.md) for the Vercel-derived performance ruleset; frontend-patterns for cross-framework UI concerns; accessibility; angular-developer for framework comparison
 - Agents: `react-reviewer` for code review, `react-build-resolver` for build/bundler errors
 - Commands: `/react-review`, `/react-build`, `/react-test`
 

package/skills/frontend/react/react-patterns/rules/react/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Affaan Mustafa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/frontend/react/react-patterns/rules/react/NOTICE.md

@@ -0,0 +1,11 @@
+# Third-party notice
+
+This directory contains React rule references copied from Affaan Mustafa's ECC
+repository.
+
+- Source: https://github.com/affaan-m/ECC/tree/main/rules/react
+- Source commit: 0f84c0e2796703fbda87d577b2636351418c7442
+- License: MIT
+- Copyright: Copyright (c) 2026 Affaan Mustafa
+
+The upstream MIT license is included in `LICENSE`.

package/skills/frontend/react/react-patterns/rules/react/coding-style.md

@@ -0,0 +1,109 @@
+---
+paths:
+  - "**/*.tsx"
+  - "**/*.jsx"
+  - "**/components/**/*.ts"
+  - "**/components/**/*.js"
+  - "**/hooks/**/*.ts"
+  - "**/hooks/**/*.js"
+---
+# React Coding Style
+
+> This file extends the upstream `typescript/coding-style.md` and `common/coding-style.md` rules with React specific content.
+
+## File Extensions
+
+- `.tsx` for any file containing JSX, even one-liner snippets
+- `.ts` for pure logic, custom hooks without JSX, type definitions, utilities
+- `.test.tsx` / `.test.ts` mirroring the source file
+- Use `.jsx` only when the project intentionally avoids TypeScript — flag every new untyped React file in review
+
+## Naming
+
+- Components: `PascalCase` for both the symbol and the file (`UserCard.tsx`, default export `UserCard`)
+- Custom hooks: `useCamelCase` for the symbol, kebab-case for the file when the project convention is kebab-case (`use-debounce.ts` exports `useDebounce`)
+- Context: `<Domain>Context` symbol, `<Domain>Provider` provider component, `use<Domain>` consumer hook
+- Event handlers: `handleClick`, `handleSubmit` inside the component; the prop that receives it is `onClick`, `onSubmit`
+- Boolean props: `isLoading`, `hasError`, `canSubmit` — never `loading` or `error` alone for booleans
+
+## Component Shape
+
+```tsx
+type Props = {
+  user: User;
+  onSelect: (id: string) => void;
+};
+
+export function UserCard({ user, onSelect }: Props) {
+  return (
+    <button type="button" onClick={() => onSelect(user.id)}>
+      {user.name}
+    </button>
+  );
+}
+```
+
+- Prefer `type Props = {}` for closed component prop shapes
+- Use `interface` only when the prop type is extended via declaration merging or exported as a public API extension point
+- Always destructure props in the parameter list — no `props.user` access inside the body
+- Type the return implicitly through JSX (`function Foo(): JSX.Element` only when the function returns conditionally and the union confuses inference)
+
+## JSX
+
+- Self-close tags with no children: `<img />`, `<UserCard user={u} />`
+- Use fragments `<>...</>` over wrapper `<div>` when no DOM element is needed
+- Conditional rendering: `{condition && <Foo />}` for booleans, ternary for either/or, early return for guard clauses
+- Never put logic inline in JSX when it reads as multi-line — extract to a const above the return or a function
+
+```tsx
+// Prefer
+const greeting = user.isAdmin ? "Welcome, admin" : `Hello ${user.name}`;
+return <h1>{greeting}</h1>;
+
+// Over
+return <h1>{user.isAdmin ? "Welcome, admin" : `Hello ${user.name}`}</h1>;
+```
+
+## Server / Client Boundary (Next.js App Router, RSC)
+
+- Default a new file to Server Component — only add `"use client"` when the file uses state, effects, refs, browser APIs, or event handlers
+- Place the `"use client"` directive on line 1, before any imports
+- Never import a Client Component file from inside a `"use server"` action file
+- Never re-export server-only code through a client module — the bundler will silently include it
+
+## Imports
+
+- React imports first: `import { useState } from "react"`
+- Then third-party libs, then absolute project imports, then relative
+- Type-only imports: `import type { ReactNode } from "react"` — never mix runtime and type imports in one statement when ESLint's `consistent-type-imports` is configured
+
+## Hooks Discipline
+
+See [hooks.md](./hooks.md) for the full ruleset. Style highlights:
+
+- Custom hooks must start with `use` — enforced by `eslint-plugin-react-hooks`
+- Group all hook calls at the top of the component, before any conditional logic
+- Avoid creating ad-hoc hooks for one-line wrappers — inline the call instead
+
+## State
+
+- Local first (`useState`), lift only when shared
+- Context for cross-cutting state read by many components (theme, auth, i18n) — not for high-frequency updates
+- External store (Zustand, Jotai, Redux Toolkit) when state must persist across route changes, sync across tabs, or be debugged via devtools
+- Never duplicate state that can be derived — compute during render
+
+## Class Components
+
+Forbidden in new code. Convert legacy class components to function components when touching them for non-trivial changes.
+
+## File Layout per Component
+
+```
+components/UserCard/
+  UserCard.tsx
+  UserCard.module.css   # or styled-components, or Tailwind classes inline
+  UserCard.test.tsx
+  index.ts              # re-export only
+```
+
+Inline single-file components are fine for trivial presentational pieces.

package/skills/frontend/react/react-patterns/rules/react/hooks.md

@@ -0,0 +1,187 @@
+---
+paths:
+  - "**/*.tsx"
+  - "**/*.jsx"
+  - "**/hooks/**/*.ts"
+  - "**/hooks/**/*.js"
+  - "**/use-*.ts"
+  - "**/use-*.tsx"
+---
+# React Hooks
+
+> This file covers **React hooks** (`useState`, `useEffect`, `useMemo`, `useCallback`, custom hooks) — NOT the Claude Code `hooks/` runtime system. Naming matches the per-language convention `rules/<lang>/hooks.md` used across this repo.
+>
+> Extends the upstream `typescript/patterns.md` and `common/patterns.md` rules.
+
+## Rules of Hooks
+
+Enforce `eslint-plugin-react-hooks` with `react-hooks/rules-of-hooks` set to error.
+
+1. Hooks only at the top level of a function component or another hook
+2. Never in loops, conditionals, nested functions, or after early returns
+3. Always called in the same order on every render
+4. Only inside React function components or custom hooks (functions starting with `use`)
+
+```tsx
+// WRONG: conditional hook
+function Foo({ enabled }: { enabled: boolean }) {
+  if (enabled) {
+    const [x, setX] = useState(0); // rule violation
+  }
+}
+
+// CORRECT: hook unconditional, condition inside
+function Foo({ enabled }: { enabled: boolean }) {
+  const [x, setX] = useState(0);
+  if (!enabled) return null;
+  return <span>{x}</span>;
+}
+```
+
+## `useEffect` — When NOT to Use
+
+`useEffect` is for synchronizing with external systems (subscriptions, browser APIs, third-party libraries). It is **not** the right tool for:
+
+- Derived state — compute it during render
+- Transforming data for rendering — compute it during render
+- Resetting state when a prop changes — use a `key` on the parent or derive from props
+- Notifying parents of state changes — call the callback in the event handler
+- Initializing app-level singletons — call the function module-side or in `main.tsx`
+
+```tsx
+// WRONG: effect for derived state
+const [fullName, setFullName] = useState("");
+useEffect(() => {
+  setFullName(`${first} ${last}`);
+}, [first, last]);
+
+// CORRECT: derive during render
+const fullName = `${first} ${last}`;
+```
+
+## Dependency Arrays
+
+- Always include every reactive value referenced inside the effect/callback
+- Enable `react-hooks/exhaustive-deps` lint rule — never silence it without a comment explaining why
+- If the dep array grows unwieldy, the effect is doing too much — split it
+- Stable identity for functions passed in deps: wrap in `useCallback` only when the function is itself a dependency of another hook or passed to a memoized child
+
+## Cleanup
+
+Every subscription, interval, listener, or in-flight request must clean up.
+
+```tsx
+useEffect(() => {
+  const controller = new AbortController();
+  fetch(url, { signal: controller.signal }).then(handleResponse);
+  return () => controller.abort();
+}, [url]);
+```
+
+```tsx
+useEffect(() => {
+  const id = setInterval(tick, 1000);
+  return () => clearInterval(id);
+}, []);
+```
+
+Missing cleanup = race conditions when deps change, memory leaks on unmount.
+
+## `useMemo` and `useCallback` — When Worth It
+
+Default position: **do not memoize**. Add `useMemo` / `useCallback` only when:
+
+1. The value is passed to a `React.memo`-wrapped child as a prop, and identity matters
+2. The value is a dependency of another `useEffect` / `useMemo` / `useCallback`
+3. The computation is measurably expensive (profile before assuming)
+
+Premature memoization adds noise, hides bugs, and can be slower than the recompute it replaces.
+
+## Custom Hooks
+
+Extract a custom hook when:
+
+- The same hook sequence (state + effect + computed) appears in 2+ components
+- The logic has a clear, nameable purpose (`useDebounce`, `useOnClickOutside`, `useLocalStorage`)
+- You want to test the logic independently of any component
+
+Do NOT extract when:
+
+- It would have a single caller — inline it
+- The "hook" is just `useState` with a different name — adds indirection, no value
+
+```tsx
+export function useDebounce<T>(value: T, delay: number): T {
+  const [debounced, setDebounced] = useState(value);
+  useEffect(() => {
+    const id = setTimeout(() => setDebounced(value), delay);
+    return () => clearTimeout(id);
+  }, [value, delay]);
+  return debounced;
+}
+```
+
+## `useState` Patterns
+
+- Initial state from prop only at mount: pass a function `useState(() => computeInitial(prop))` when computation is expensive
+- Functional updater when the new state depends on the old: `setCount(c => c + 1)` — never `setCount(count + 1)` inside async or batched contexts
+- Group related state into one object only when they always change together; otherwise split into multiple `useState` calls
+- Use `useReducer` once state transitions are conditional on the previous state or there are 3+ related values
+
+## `useRef` Patterns
+
+- DOM refs for imperative APIs (focus, scroll, third-party libs)
+- Mutable container that does not trigger re-render (timer ids, previous values, "is mounted" flags)
+- Never read or write `ref.current` during render — only inside effects or event handlers
+- `useImperativeHandle` only when exposing a child API to a parent ref — last-resort escape hatch
+
+## `useSyncExternalStore`
+
+Use this hook to subscribe to any external store (browser API, third-party state lib, custom event emitter). It is the supported way to make external state safe with concurrent rendering.
+
+```tsx
+const isOnline = useSyncExternalStore(
+  (cb) => {
+    window.addEventListener("online", cb);
+    window.addEventListener("offline", cb);
+    return () => {
+      window.removeEventListener("online", cb);
+      window.removeEventListener("offline", cb);
+    };
+  },
+  () => navigator.onLine,
+  () => true,
+);
+```
+
+## React 19 Additions
+
+- `use()` — unwrap promises and contexts inline; usable conditionally (only hook with that property)
+- `useFormStatus()` / `useFormState()` (or `useActionState`) — form submission state without prop drilling
+- `useOptimistic()` — optimistic UI updates while a server action is pending
+- `useTransition()` — mark non-urgent state updates so urgent ones stay responsive
+
+When the project targets React 19+, prefer these over hand-rolled equivalents.
+
+## Stale Closure Trap
+
+Async handlers and intervals capture the values from the render where they were created. Fix by:
+
+1. Using the functional updater form of `setState`
+2. Putting the changing value in the dep array of `useEffect` and rebuilding the handler
+3. Reading from a ref that is kept in sync
+
+## Lint Configuration
+
+Required rules:
+
+```json
+{
+  "rules": {
+    "react-hooks/rules-of-hooks": "error",
+    "react-hooks/exhaustive-deps": "warn"
+  }
+}
+```
+
+Treat `exhaustive-deps` warnings as errors in CI for new code.

package/skills/frontend/react/react-patterns/rules/react/patterns.md

@@ -0,0 +1,194 @@
+---
+paths:
+  - "**/*.tsx"
+  - "**/*.jsx"
+  - "**/components/**/*.ts"
+  - "**/components/**/*.js"
+  - "**/app/**/*.tsx"
+  - "**/pages/**/*.tsx"
+---
+# React Patterns
+
+> This file extends the upstream `typescript/patterns.md` and `common/patterns.md` rules with React specific content. For hook-specific rules see [hooks.md](./hooks.md).
+
+## Container / Presentational Split
+
+Container components own data fetching, state, and side effects. Presentational components receive props and render — no service calls, no hooks beyond local UI state.
+
+```tsx
+// Container — owns data
+export function UserPage({ userId }: { userId: string }) {
+  const { data: user, isLoading } = useUser(userId);
+  if (isLoading) return <Spinner />;
+  if (!user) return <NotFound />;
+  return <UserCard user={user} onSelect={handleSelect} />;
+}
+
+// Presentational — pure
+export function UserCard({ user, onSelect }: { user: User; onSelect: (id: string) => void }) {
+  return <button onClick={() => onSelect(user.id)}>{user.name}</button>;
+}
+```
+
+## State Location Decision Tree
+
+1. Used by one component → `useState` inside it
+2. Used by parent + a few children → lift to nearest common ancestor, pass via props
+3. Used across distant branches → React Context **for low-frequency reads only** (theme, auth, locale)
+4. High-frequency updates shared across the tree → external store (Zustand, Jotai, Redux Toolkit)
+5. Server-derived data → server-state library (TanStack Query, SWR, RSC fetch) — not application state
+
+Context misused for frequently changing values causes every consumer to re-render on every update.
+
+## Server / Client Component Boundary (RSC, Next.js App Router)
+
+- Server Components are the default — they run on the server, do not ship to the client, and can `await` directly
+- Client Components opt in with `"use client"` at the top of the file
+- Data flows down: a Server Component can render a Client Component and pass serializable props
+- A Client Component cannot import a Server Component, but it can receive one via `children` or named slots
+
+```tsx
+// Server (default)
+export default async function Page() {
+  const user = await fetchUser();
+  return <UserClient user={user} />;
+}
+
+// Client
+"use client";
+export function UserClient({ user }: { user: User }) {
+  const [tab, setTab] = useState("profile");
+  return <Tabs value={tab} onChange={setTab}>{user.name}</Tabs>;
+}
+```
+
+- Never import `"server-only"` packages (DB clients, secrets) from a Client Component file — wrap them in a Server Component or Server Action
+- Mark sensitive modules with `import "server-only"` so the bundler errors if a client file imports them
+
+## Suspense + Error Boundaries
+
+Every Suspense boundary needs an Error Boundary above it. The pair handles both states.
+
+```tsx
+<ErrorBoundary fallback={<ErrorView />}>
+  <Suspense fallback={<Skeleton />}>
+    <UserDetails id={id} />
+  </Suspense>
+</ErrorBoundary>
+```
+
+- Place Suspense boundaries close to where data is needed, not at the route root
+- Multiple narrower boundaries reveal loaded content progressively
+- Error Boundary must be a Class Component (React 19 has no functional equivalent yet) OR use a library wrapper such as `react-error-boundary`
+
+## Forms
+
+### Uncontrolled (React 19 + form actions)
+
+Prefer uncontrolled inputs with form actions when the form has a clear submit step. The browser owns the value; React reads it via `FormData` on submit.
+
+```tsx
+async function action(formData: FormData) {
+  "use server";
+  await saveUser({ name: String(formData.get("name")) });
+}
+
+export function UserForm() {
+  return (
+    <form action={action}>
+      <input name="name" required />
+      <button type="submit">Save</button>
+    </form>
+  );
+}
+```
+
+### Controlled
+
+Use controlled inputs when the value drives other UI, requires real-time validation, or formatting.
+
+```tsx
+const [email, setEmail] = useState("");
+return <input value={email} onChange={(e) => setEmail(e.target.value)} />;
+```
+
+### Form Libraries
+
+For complex forms (multi-step, dynamic field arrays, cross-field validation), use a library:
+
+- React Hook Form — minimal re-renders, uncontrolled-first
+- TanStack Form — typed, framework-agnostic
+- Final Form — when subscription-based re-renders matter
+
+## Data Fetching
+
+| Strategy | When |
+|---|---|
+| RSC fetch (`await` in Server Component) | Per-request data in Next.js App Router, no client-side cache needed |
+| TanStack Query | Client-side cache, mutations, optimistic updates, polling |
+| SWR | Lightweight cache + revalidation, simpler than TanStack Query |
+| `fetch` in `useEffect` | Avoid — race conditions, no cache, no retry. Only acceptable for one-off fire-and-forget |
+
+Never fetch in a `useEffect` when a real cache library is available — they handle deduping, cache invalidation, error retry, and Suspense integration.
+
+## Lists and Keys
+
+- `key` must be stable across renders — never `index` for any list that can reorder, insert, or delete
+- `key` must be unique among siblings, not globally
+- A reordered list with index keys causes state in child components to attach to the wrong row
+
+## Composition over Inheritance
+
+- Pass `children` for slot-style composition
+- Pass render-prop functions for parameterized rendering
+- Pass component types for plug-in points: `renderItem={UserRow}`
+- Never extend a component class to specialize behavior
+
+## Compound Components
+
+For related controls (Tabs, Accordion, Menu), use compound components sharing state via Context:
+
+```tsx
+<Tabs defaultValue="profile">
+  <Tabs.List>
+    <Tabs.Trigger value="profile">Profile</Tabs.Trigger>
+    <Tabs.Trigger value="settings">Settings</Tabs.Trigger>
+  </Tabs.List>
+  <Tabs.Panel value="profile"><ProfileForm /></Tabs.Panel>
+  <Tabs.Panel value="settings"><SettingsForm /></Tabs.Panel>
+</Tabs>
+```
+
+## Portals
+
+Use `createPortal` for modals, tooltips, toast containers — anything that must escape the parent's `overflow: hidden` or `z-index` stacking context. Render to a stable DOM node mounted in `index.html`.
+
+## Refs and Forwarding (React 19+)
+
+React 19 lets function components accept `ref` as a regular prop — `forwardRef` is no longer required.
+
+```tsx
+export function Input({ ref, ...rest }: { ref?: React.Ref<HTMLInputElement> } & InputProps) {
+  return <input ref={ref} {...rest} />;
+}
+```
+
+Older codebases on React 18 still need `forwardRef`.
+
+## Out of Scope (Pointer Sections)
+
+### Next.js (App Router)
+
+- Server Actions, Route Handlers, Middleware, Parallel/Intercepted Routes, streaming Metadata
+- Treated as a separate framework concern — when adding deep Next-specific patterns, propose a dedicated `rules/nextjs/` track
+- For now follow Next.js official docs for App Router specifics
+
+### React Native
+
+- Platform-specific imports (`Platform.OS`, `.ios.tsx` / `.android.tsx`), `StyleSheet`, navigation libraries (React Navigation, Expo Router)
+- Treated as a separate track — `rules/react-native/` is not yet present
+- React core hooks/patterns from this file still apply
+
+## Skill Reference
+
+For React-specific deep dives see `skills/react-patterns/SKILL.md`. For cross-framework frontend concerns see `skills/frontend-patterns/SKILL.md`. For accessibility see `skills/accessibility/SKILL.md`.