feat(react-best-practices): add Server Action & Form pattern rules

Add 5 new rules covering Server Action and Form patterns:
- server-useoptimistic: instant UI feedback with useOptimistic (HIGH)
- server-action-revalidation: granular cache invalidation (HIGH)
- server-action-error-handling: return error state, don't throw (MEDIUM-HIGH)
- server-progressive-enhancement: forms that work without JS (MEDIUM)
- rerender-useformstatus: pending state without prop drilling (MEDIUM)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: mvanhorn

skills/react-best-practices/SKILL.md

@@ -9,7 +9,7 @@ metadata:
 
 # Vercel React Best Practices
 
-Comprehensive performance optimization guide for React and Next.js applications, maintained by Vercel. Contains 64 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.
+Comprehensive performance optimization guide for React and Next.js applications, maintained by Vercel. Contains 69 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.
 
 ## When to Apply
 
@@ -61,6 +61,10 @@ Reference these guidelines when:
 - `server-serialization` - Minimize data passed to client components
 - `server-parallel-fetching` - Restructure components to parallelize fetches
 - `server-after-nonblocking` - Use after() for non-blocking operations
+- `server-useoptimistic` - Use useOptimistic for instant UI feedback
+- `server-action-revalidation` - Granular cache revalidation after mutations
+- `server-action-error-handling` - Return error state instead of throwing
+- `server-progressive-enhancement` - Forms that work without JavaScript
 
 ### 4. Client-Side Data Fetching (MEDIUM-HIGH)
 
@@ -86,6 +90,7 @@ Reference these guidelines when:
 - `rerender-use-deferred-value` - Defer expensive renders to keep input responsive
 - `rerender-use-ref-transient-values` - Use refs for transient frequent values
 - `rerender-no-inline-components` - Don't define components inside components
+- `rerender-useformstatus` - Use useFormStatus for pending state without prop drilling
 
 ### 6. Rendering Performance (MEDIUM)
 

skills/react-best-practices/rules/rerender-useformstatus.md

@@ -0,0 +1,88 @@
+---
+title: Use useFormStatus for Pending State Without Prop Drilling
+impact: MEDIUM
+impactDescription: cleaner form components, no manual pending state tracking
+tags: rerender, forms, useFormStatus, pending-state, server-actions
+---
+
+## Use useFormStatus for Pending State Without Prop Drilling
+
+**Impact: MEDIUM (cleaner form components, no manual pending state tracking)**
+
+Use `useFormStatus` inside a child component of a `<form>` to access the pending state directly. This avoids threading `isPending` through props or lifting state to coordinate between the form and its submit button.
+
+**Incorrect (prop drilling pending state):**
+
+```tsx
+'use client'
+
+import { useState } from 'react'
+import { submitOrder } from './actions'
+
+function OrderForm() {
+  const [isPending, setIsPending] = useState(false)
+
+  async function handleSubmit(formData: FormData) {
+    setIsPending(true)
+    await submitOrder(formData)
+    setIsPending(false)
+  }
+
+  return (
+    <form action={handleSubmit}>
+      <input name="item" />
+      <OrderSummary />
+      <SubmitButton isPending={isPending} />
+    </form>
+  )
+}
+
+function SubmitButton({ isPending }: { isPending: boolean }) {
+  return (
+    <button type="submit" disabled={isPending}>
+      {isPending ? 'Placing order...' : 'Place Order'}
+    </button>
+  )
+}
+```
+
+**Correct (useFormStatus reads pending state from the form):**
+
+```tsx
+import { submitOrder } from './actions'
+import { SubmitButton } from './submit-button'
+
+function OrderForm() {
+  return (
+    <form action={submitOrder}>
+      <input name="item" />
+      <OrderSummary />
+      <SubmitButton />
+    </form>
+  )
+}
+```
+
+```tsx
+'use client'
+
+import { useFormStatus } from 'react-dom'
+
+export function SubmitButton() {
+  const { pending } = useFormStatus()
+
+  return (
+    <button type="submit" disabled={pending}>
+      {pending ? 'Placing order...' : 'Place Order'}
+    </button>
+  )
+}
+```
+
+`useFormStatus` reads the status of the parent `<form>`, so the component must be rendered as a child of the form element. It cannot be called in the same component that renders the `<form>`.
+
+**Reuse across forms:**
+
+Because `SubmitButton` doesn't depend on any specific form's props, it works as a shared component across your entire app.
+
+Reference: [React useFormStatus](https://react.dev/reference/react-dom/hooks/useFormStatus)

skills/react-best-practices/rules/server-action-error-handling.md

@@ -0,0 +1,83 @@
+---
+title: Return Error State From Server Actions Instead of Throwing
+impact: MEDIUM-HIGH
+impactDescription: 60-80% better error UX by keeping forms functional on failure
+tags: server, server-actions, error-handling, forms, useActionState
+---
+
+## Return Error State From Server Actions Instead of Throwing
+
+**Impact: MEDIUM-HIGH (60-80% better error UX by keeping forms functional on failure)**
+
+When a Server Action encounters a validation or business logic error, return an error object instead of throwing. Thrown errors trigger the nearest `error.tsx` boundary, which replaces the entire UI. Returned errors let you show inline feedback while keeping the form usable.
+
+**Incorrect (throw replaces the form with error.tsx):**
+
+```tsx
+'use server'
+
+export async function createAccount(prevState: unknown, formData: FormData) {
+  const email = formData.get('email') as string
+
+  const existing = await db.user.findUnique({ where: { email } })
+  if (existing) {
+    // This triggers error.tsx - user loses their form input
+    throw new Error('Email already exists')
+  }
+
+  await db.user.create({ data: { email } })
+  return { success: true }
+}
+```
+
+**Correct (return error state for inline display):**
+
+```tsx
+'use server'
+
+type ActionState = { error?: string; success?: boolean }
+
+export async function createAccount(
+  prevState: ActionState,
+  formData: FormData
+): Promise<ActionState> {
+  const email = formData.get('email') as string
+
+  const existing = await db.user.findUnique({ where: { email } })
+  if (existing) {
+    // Form stays intact, error shows inline
+    return { error: 'An account with this email already exists.' }
+  }
+
+  await db.user.create({ data: { email } })
+  return { success: true }
+}
+```
+
+```tsx
+'use client'
+
+import { useActionState } from 'react'
+import { createAccount } from './actions'
+
+function SignupForm() {
+  const [state, action, isPending] = useActionState(createAccount, {})
+
+  return (
+    <form action={action}>
+      <input name="email" type="email" />
+      {state.error && <p role="alert">{state.error}</p>}
+      <button type="submit" disabled={isPending}>
+        {isPending ? 'Creating...' : 'Create Account'}
+      </button>
+    </form>
+  )
+}
+```
+
+**When to throw vs return:**
+
+- **Return errors** for expected failures: validation, duplicates, rate limits, permissions
+- **Throw errors** only for unexpected failures: database connection lost, unrecoverable state. These should hit `error.tsx` because the page genuinely can't function.
+
+Reference: [Next.js Server Action error handling](https://nextjs.org/docs/app/building-your-application/data-fetching/server-actions-and-mutations#error-handling)

skills/react-best-practices/rules/server-action-revalidation.md

@@ -0,0 +1,64 @@
+---
+title: Use Granular Cache Revalidation After Mutations
+impact: HIGH
+impactDescription: prevents stale data without over-invalidating cache
+tags: server, server-actions, revalidation, cache, mutations
+---
+
+## Use Granular Cache Revalidation After Mutations
+
+**Impact: HIGH (prevents stale data without over-invalidating cache)**
+
+After a Server Action mutates data, choose the most specific revalidation strategy. Using `revalidatePath('/')` or no revalidation at all are the two most common bugs in Next.js apps.
+
+**Incorrect (invalidates entire cache):**
+
+```tsx
+'use server'
+
+import { revalidatePath } from 'next/cache'
+
+export async function updatePost(id: string, data: FormData) {
+  await db.post.update({ where: { id }, data: { title: data.get('title') } })
+
+  // Blows away ALL cached data across the entire app
+  revalidatePath('/')
+}
+```
+
+**Correct (invalidates only affected data):**
+
+```tsx
+'use server'
+
+import { revalidateTag } from 'next/cache'
+
+export async function updatePost(id: string, data: FormData) {
+  await db.post.update({ where: { id }, data: { title: data.get('title') } })
+
+  // Only invalidates fetches tagged with this post
+  revalidateTag(`post-${id}`)
+}
+```
+
+Tag your fetches so revalidation is precise:
+
+```tsx
+// In a Server Component or data layer
+const post = await fetch(`https://api.example.com/posts/${id}`, {
+  next: { tags: [`post-${id}`, 'posts'] }
+})
+```
+
+**Choosing the right strategy:**
+
+| Strategy | Use when | Precision |
+|----------|----------|-----------|
+| `revalidateTag(tag)` | You tagged your fetch calls | High - only matching fetches |
+| `revalidatePath('/posts/[id]')` | Specific page needs fresh data | Medium - all data on that route |
+| `revalidatePath('/posts', 'layout')` | Section of the app changed | Low - entire layout subtree |
+| `redirect('/posts')` | User should navigate after mutation | N/A - new page fetches fresh |
+
+**Common mistake:** Forgetting to revalidate at all. The mutation succeeds on the server, but the user still sees stale cached data until they hard-refresh.
+
+Reference: [Next.js revalidateTag](https://nextjs.org/docs/app/api-reference/functions/revalidateTag)

skills/react-best-practices/rules/server-progressive-enhancement.md

@@ -0,0 +1,75 @@
+---
+title: Build Forms That Work Without JavaScript
+impact: MEDIUM
+impactDescription: forms functional before hydration and with JS disabled
+tags: server, server-actions, forms, progressive-enhancement, accessibility
+---
+
+## Build Forms That Work Without JavaScript
+
+**Impact: MEDIUM (forms functional before hydration and with JS disabled)**
+
+Use the `action` prop on `<form>` to invoke Server Actions natively. This makes forms work before React hydrates and when JavaScript is disabled, improving both performance and accessibility.
+
+**Incorrect (requires JavaScript to submit):**
+
+```tsx
+'use client'
+
+import { createComment } from './actions'
+
+function CommentForm() {
+  async function handleClick() {
+    const input = document.getElementById('comment') as HTMLInputElement
+    await createComment(input.value)
+  }
+
+  return (
+    <div>
+      <input id="comment" />
+      <button onClick={handleClick}>Post</button>
+    </div>
+  )
+}
+```
+
+**Correct (works with or without JavaScript):**
+
+```tsx
+import { createComment } from './actions'
+
+function CommentForm() {
+  return (
+    <form action={createComment}>
+      <input name="comment" required />
+      <button type="submit">Post</button>
+    </form>
+  )
+}
+```
+
+The form submits as a native HTML form before hydration. After hydration, React intercepts the submission and handles it client-side with transition support.
+
+**For actions that need additional data, use hidden inputs:**
+
+```tsx
+import { deletePost } from './actions'
+
+function DeleteButton({ postId }: { postId: string }) {
+  return (
+    <form action={deletePost}>
+      <input type="hidden" name="postId" value={postId} />
+      <button type="submit">Delete</button>
+    </form>
+  )
+}
+```
+
+**Why this matters:**
+
+- Forms work during the gap between page load and hydration
+- Users on slow connections or devices can interact immediately
+- Screen readers and assistive technologies work with native forms out of the box
+- Reduces client-side JavaScript needed for basic form handling
+
+Reference: [React form action](https://react.dev/reference/react-dom/components/form)