React Writing Plans

⚠️ Spelling: It's saurun: (with U), not "sauron"

React Writing Plans

Overview

Plans are architectural blueprints, not copy-paste code. Each task references contracts defined in the architecture doc. Implementers use TDD skills to fill in the actual code.

Announce at start: "I'm using the react-writing-plans skill to create the implementation plan."

Save plans to: _docs/plans/YYYY-MM-DD-<feature-name>.md

When to Use

• Multi-step React feature requiring new components, stores, or API integration
• PRD or spec exists but no implementation plan
• Feature touches 3+ files or requires coordinated changes
• Need to hand off implementation to another engineer or subagent

When NOT to Use

• Single-file bug fix with obvious cause and fix
• Config/environment changes (vite.config, tsconfig, tailwind.config)
• Renaming or moving files without logic changes
• Adding an npm package with no code changes beyond the import

Plan Document Header

Every plan MUST start with this header:

# [Feature Name] Implementation Plan

> **For Claude:** **REQUIRED SUB-SKILL:** Use `saurun:react-tdd` to implement this plan task-by-task with TDD.

**Goal:** [One sentence describing what this builds]

**Architecture:** `_docs/specs/{DATE}-{feature}-architecture.md`

**Tech Stack:** React 19, Vite, TypeScript, Tailwind CSS v4, Zustand, Vitest, React Testing Library, MSW

---

Task Structure

### Task N: [Name]

**Implements:** [Contract reference from Architecture doc, e.g., "AddItemForm (Architecture §Component Tree)"]

**Files:**
- Create: `src/components/exact/path/Component.tsx`
- Test: `src/components/exact/path/__tests__/Component.test.tsx`

**Behaviors:**
- [Happy path behavior]
- [Error case 1]
- [Error case 2]

**Dependencies:** Task X (if applicable)

Frontend Task Examples

Form Component (validation grouped by field)

### Task 3: RegisterForm component

**Implements:** RegisterForm (Architecture §Components - Auth)

**Files:**
- Create: `src/components/auth/RegisterForm.tsx`
- Test: `src/components/auth/__tests__/RegisterForm.test.tsx`

**Behaviors:**
- Email: required, valid format
- Password: required, min 8, uppercase + lowercase + digit
- DisplayName: required, 2-50 chars
- Valid submit calls onSubmit with RegisterRequest
- Invalid submit shows field errors

Complex Form (many fields)

### Task 12: RecipeForm component

**Implements:** RecipeForm (Architecture §Components - Recipe Form)

**Files:**
- Create: `src/components/recipe-form/RecipeForm.tsx`
- Test: `src/components/recipe-form/__tests__/RecipeForm.test.tsx`

**Behaviors:**
- Title: required, 1-200 chars
- Description: required, 1-2000 chars
- Servings: required, 1-100
- PrepTime/CookTime: required, 0-1440 min
- CategoryId: required, must exist
- Ingredients: min 1 item (validated by IngredientInput)
- Steps: min 1 item (validated by StepInput)
- Populates fields from initialData when editing
- Valid submit calls onSubmit with CreateRecipeRequest

**Dependencies:** Task 9-11 (form sub-components)

Display Component (concise)

### Task 5: RecipeCard component

**Implements:** RecipeCard (Architecture §Components - Recipe)

**Files:**
- Create: `src/components/recipe/RecipeCard.tsx`
- Test: `src/components/recipe/__tests__/RecipeCard.test.tsx`

**Behaviors:**
- Displays image, title, time, and author from RecipeListItemDto
- Click navigates to /opskrift/{id}
- Save button calls onSave when authenticated

Page (concise with edge cases)

### Task 8: RecipeDetailPage

**Implements:** /opskrift/{id} → RecipeDetailPage (Architecture §Pages)

**Files:**
- Create: `src/pages/RecipeDetailPage.tsx`
- Test: `src/pages/__tests__/RecipeDetailPage.test.tsx`

**Behaviors:**
- Fetches and renders RecipeDetail component
- 404 when recipe not found
- Owner sees edit/delete buttons

**Dependencies:** Task 6 (RecipeDetail)

Store (state transitions)

### Task 2: useAuthStore

**Implements:** useAuthStore (Architecture §Stores)

**Files:**
- Create: `src/stores/authStore.ts`
- Test: `src/stores/__tests__/authStore.test.ts`

**Behaviors:**
- login stores user/token and persists to localStorage
- logout clears state and localStorage
- isAuthenticated derived from token presence

Conciseness Rules

Plans are for autonomous agents, not humans. Every word costs tokens.

The Core Rule

If it needs a test case, it needs a behavior line.

This distinguishes testable behaviors (KEEP) from implementation details (DELETE).

What to KEEP (Testable Behaviors)

These become test cases — always include them:

What to DELETE (Implementation Details)

These are NOT test cases — never include them:

Form Validation: Group by Field

List each field's validation constraints on ONE line. Don't split min/max into separate behaviors.

# ❌ TOO VERBOSE (splits constraints into separate lines)
**Behaviors:**
- Title field: required, shows error when empty
- Title field: max 200 chars, shows error when exceeded
- Description field: required, shows error when empty
- Description field: max 2000 chars, shows error when exceeded

# ❌ TOO CONCISE (agent won't know what to test)
**Behaviors:**
- Shows validation errors per field requirements

# ✓ CORRECT (one line per field, all constraints grouped)
**Behaviors:**
- Title: required, 1-200 chars
- Description: required, 1-2000 chars
- Password: required, min 8, uppercase + lowercase + digit
- Valid submit calls onSubmit with request DTO
- Invalid submit shows field errors

Note: "Shows error when X" is implied — just list the constraint.

Combining Non-Validation Behaviors

For non-form components, combine related states:

# ❌ VERBOSE
- Shows loading spinner while fetching
- Displays data when loaded
- Shows error message on failure

# ✓ COMBINED
- Handles loading/error/success states
- Renders data per architecture DTO

Hard Limits

• Forms: 1 behavior per field + 2-3 for submit/populate = roughly (field count + 3)
• Other components: Max 4 behaviors
• If over limit → split task or combine related behaviors

What Plans Include

What Plans Do NOT Include

Test Infrastructure Task

Task 1 of every plan MUST set up test infrastructure:

### Task 1: Test infrastructure setup

**Implements:** Shared test helpers (N/A - infrastructure)

**Files:**
- Create: `src/test-utils.tsx`
- Create: `src/mocks/server.ts`
- Create: `src/mocks/handlers.ts`
- Modify: `vitest.setup.ts`

**Behaviors:**
- renderWithProviders wraps components with necessary providers
- MSW server configured with onUnhandledRequest: 'error'
- Zustand store reset in beforeEach

Tailwind v4 Compliance

Implementers MUST follow these rules (remind in plan if UI-heavy):

• CSS variables use parentheses: bg-(--brand-color) NOT bg-[--brand-color]
• Use renamed utilities: shadow-xs, rounded-xs (not shadow-sm, rounded-sm for smallest)
• Class merging: always cn(), never template literals
• No theme() in arbitrary values — use var(--color-*) instead

Common Mistakes

Completion

After saving the plan, report:

"Plan saved to _docs/plans/<filename>.md. Ready for execution."