/web-framework-react

name: web-framework-react
description: Component architecture, hooks, patterns

React Components

> **Quick Guide:** Tiered components (Primitives -> Components -> Patterns -> Templates). React 19: pass `ref` as a prop directly (no `forwardRef` needed). Expose `className` prop for styling flexibility. Use `useActionState` for forms, `useOptimistic` for instant feedback, `use()` for conditional promise/context reading. Ref callbacks can return cleanup functions.

---

<critical_requirements>

CRITICAL: Before Using This Skill

> **All code must follow project conventions in CLAUDE.md** (kebab-case, named exports, import ordering, `import type`, named constants)

**(You MUST pass `ref` as a regular prop in React 19 - `forwardRef` is deprecated)**

**(You MUST expose `className` prop on ALL reusable components for customization)**

**(You MUST use `useActionState` for form submissions with pending/error state)**

**(You MUST call `useFormStatus` from a child component inside `<form>`, NOT in the component that renders the form)**

</critical_requirements>

---

**Auto-detection:** React 19, components, hooks, use(), useActionState, useFormStatus, useOptimistic, Actions, ref as prop, ref cleanup, forwardRef migration, component variants, error boundary

**When to use:**

• Building React components with type-safe props
• Migrating from forwardRef to React 19 ref-as-prop
• Handling form submissions with React 19 Actions API
• Creating custom hooks for reusable logic
• Implementing error boundaries with retry

**When NOT to use:**

• Simple one-off components without variants (skip variant abstractions)
• Static content without interactivity

**Key patterns covered:**

• Component architecture tiers and variant props
• React 19 ref as prop (replaces forwardRef)
• React 19 hooks: `use()`, `useActionState`, `useFormStatus`, `useOptimistic`
• Ref callback cleanup functions
• Error boundaries with retry and custom fallbacks
• Custom hooks (pagination, debounce, localStorage)
• Event handler naming conventions

---

<philosophy>

Philosophy

React components follow a tiered architecture from low-level primitives to high-level templates. Components should be composable, type-safe, and expose necessary customization points (`className`, refs). Use variant abstractions only when components have multiple variant dimensions to avoid over-engineering. React is styling-agnostic -- apply styles via the `className` prop.

**React 19 Changes:** `forwardRef` is deprecated -- pass `ref` as a regular prop directly. New hooks (`use()`, `useActionState`, `useFormStatus`, `useOptimistic`) simplify data fetching and form handling with the Actions API. Ref callbacks can return cleanup functions, eliminating the need for separate `useEffect` cleanup.

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: Component Architecture Tiers

Components are organized in a tiered hierarchy:

1. **Primitives** (`src/primitives/`) - Low-level building blocks (skeleton) 2. **Components** (`src/components/`) - Reusable UI (button, switch, select) 3. **Patterns** (`src/patterns/`) - Composed patterns (feature, navigation) 4. **Templates** (`src/templates/`) - Page layouts (frame)

// React 19: ref as a regular prop, no forwardRef needed
export type ButtonProps = React.ComponentProps<"button"> & {
  variant?: "default" | "ghost" | "link";
  size?: "default" | "large" | "icon";
  asChild?: boolean;
  ref?: React.Ref<HTMLButtonElement>;
};

export function Button({ variant = "default", size = "default", className, ref, ...props }: ButtonProps) {
  return <button className={className} data-variant={variant} data-size={size} ref={ref} {...props} />;
}

**Why good:** ref as regular prop eliminates forwardRef boilerplate, className enables external styling, data-attributes enable CSS selectors for variants

See [examples/core.md](examples/core.md) for complete component examples with good/bad comparisons.

---

Pattern 2: Component Variant Props

Components with 2+ visual dimensions (variant, size) should expose type-safe variant props via TypeScript unions. Use `data-*` attributes so any styling solution can target them.

export type AlertVariant = "info" | "warning" | "error" | "success";

export function Alert({ variant = "info", className, ref, ...props }: AlertProps) {
  return <div ref={ref} className={className} data-variant={variant} {...props} />;
}

**When not to use:** Components with a single visual style -- skip variant abstraction.

See [examples/core.md](examples/core.md) for variant props with good/bad examples.

---

Pattern 3: Event Handler Naming

• `handle` prefix for internal handlers: `handleSubmit`, `handleNameChange`
• `on` prefix for callback props: `onClick`, `onSubmit`
• Type events explicitly: `FormEvent<HTMLFormElement>`, `ChangeEvent<HTMLInputElement>`

const handleSubmit = (e: FormEvent<HTMLFormElement>) => {
  e.preventDefault();
};

const handleNameChange = (e: ChangeEvent<HTMLInputElement>) => {
  setName(e.target.value);
};

See [examples/core.md](examples/core.md) for full event handler examples.

---

Pattern 4: Custom Hooks

Extract reusable logic into custom hooks following the `use` prefix convention.

• `usePagination` - Pagination state and navigation
• `useDebounce` - Debounce values for search inputs
• `useLocalStorage` - Type-safe localStorage persistence with SSR safety

See [examples/hooks.md](examples/hooks.md) for complete implementations.

---

Pattern 5: Error Boundaries with Retry

Error boundaries catch render errors and provide retry capability. Place them around feature sections, not just the root.

// Key interface -- accepts custom fallback and error callback
interface Props {
  children: ReactNode;
  fallback?: (error: Error, reset: () => void) => ReactNode;
  onError?: (error: Error, errorInfo: ErrorInfo) => void;
}

**Limitation:** Error boundaries do not catch event