Spec-Driven Planning for React

Spec-Driven Planning for React

Overview

Spec-driven development separates PLANNING from IMPLEMENTATION. This skill defines how to create implementation specifications that enable reliable, predictable React component development.

Why Spec-Driven Development?

1. Reduces errors: Planning catches design issues before coding
2. Enables parallelization: Multiple implementers can work from specs
3. Improves quality: Tests are designed upfront, not afterthought
4. Documents decisions: Specs serve as implementation record
5. Ensures accessibility: A11y is planned, not retrofitted

Specification Structure

Required Sections

# Implementation Specification

## Task Type
NEW_FEATURE | BUG_FIX | ENHANCEMENT

## Summary
One paragraph describing the deliverable.

## Requirements
Numbered list of what must be achieved.

## Design Reference
(For NEW_FEATURE with Figma)
- Extracted colors, typography, spacing
- Component states

## Existing Code Analysis
(Required for BUG_FIX and ENHANCEMENT)
- Files analyzed with line references
- Current behavior description
- Patterns to follow

## Implementation Plan
### Phase 1: Test Specification (RED)
Exact test code to write.

### Phase 2: Implementation (GREEN)
File-by-file checklist of changes.

### Phase 3: Verification
Commands to run and expected results.

## Accessibility Checklist
Specific a11y requirements for this component.

## Acceptance Criteria Mapping
Table linking requirements → tests → implementation.

Planning by Task Type

NEW_FEATURE Planning

Focus on:

• Component hierarchy design
• Props interface definition
• State management approach
• Accessibility requirements
• Test scenarios for all states

Figma Extraction Process:

1. Get file structure: mcp__figma__get_file
2. Get specific components: mcp__figma__get_node
3. Extract and document:
   • Colors (map to Tailwind or CSS vars)
   • Typography (font size, weight, line height)
   • Spacing (padding, margin, gap)
   • Border radius, shadows
   • Component states (hover, active, disabled, focus)

Do NOT:

• Over-engineer component structure
• Add features not in requirements
• Plan more than what's needed

BUG_FIX Planning

Critical: Must analyze existing code before planning fix.

1. Reproduce understanding

   • Document EXPECTED vs ACTUAL behavior
   • Identify browser/device specifics
   • Note user actions that trigger bug

2. Code analysis

   • Find the bug location (file, component, line)
   • Trace component tree
   • Trace state/props flow
   • Identify root cause

3. Fix design

   • Specify exact code changes
   • Design regression test
   • Consider side effects on parent/child components

ENHANCEMENT Planning

Critical: Must deeply understand existing code before extending.

1. Existing code inventory

   • List all files that will be touched
   • Document current props interface
   • Note styling patterns (Tailwind classes)
   • Identify test patterns

2. Extension design

   • Add new optional props (with defaults)
   • Maintain backward compatibility
   • Follow existing naming conventions
   • Match existing styling approach

3. Test design

   • New tests only (don't modify existing)
   • Follow existing test patterns
   • Test new functionality in isolation

Test Specification Guidelines

Test Structure

it('should [expectedBehavior] when [condition]', async () => {
  // Given - setup
  render(<Component {...props} />);

  // When - action
  await userEvent.click(screen.getByRole('button'));

  // Then - assertions
  expect(screen.getByText('Result')).toBeInTheDocument();
});

Coverage Requirements

• Rendering: Component renders with default props
• Props: Component responds to different prop values
• Interactions: Click, type, hover behaviors
• Accessibility: Keyboard nav, screen reader support
• Edge cases: Empty states, loading, error states

Query Priority (Testing Library)

1. getByRole - accessible queries
2. getByLabelText - form elements
3. getByText - visible text
4. getByTestId - last resort only

Specificity Level

BAD (too vague):
- Write tests for the button

GOOD (specific):
- Test: should render button with correct text
  - Given: Button component with label="Submit"
  - When: Rendered
  - Then: Button with role="button" and text "Submit" visible

- Test: should call onClick when clicked
  - Given: Button with onClick handler
  - When: User clicks button
  - Then: onClick called once

Implementation Checklist Guidelines

File Change Format

#### File: `src/components/Button.tsx`
- [ ] Define interface: `interface ButtonProps { ... }`
- [ ] Create functional component with props destructuring
- [ ] Add className with Tailwind: `bg-blue-500 hover:bg-blue-600 ...`
- [ ] Add ARIA: `aria-label`, `aria-disabled` if needed
- [ ] Handle onClick with proper typing
- [ ] Export as default

Component Order

List implementation tasks in logical order:

1. Shared types/interfaces
2. Smaller components first
3. Parent components that compose children
4. Index exports

Verification Specification

Always include exact commands:

### Phase 3: Verification
```bash
# 1. TypeScript check
npx tsc --noEmit

# 2. Run specific tests
npm test -- Button.test.tsx --run

# 3. Run all tests
npm test -- --run

# 4. Run with coverage
npm test -- --coverage --run
# Expected: >80% coverage on new code

# 5. Lint check
npm run lint

# 6. Build check
npm run build

## Accessibility Planning

Every component spec MUST include:

```markdown
## Accessibility Checklist

### Semantic HTML
- [ ] Use `<button>` not `<div onClick>`
- [ ] Use `<a>` for navigation
- [ ] Use heading hierarchy correctly

### ARIA
- [ ] `aria-label` for icon-only buttons
- [ ] `aria-expanded` for toggles
- [ ] `aria-describedby` for complex elements

### Keyboard
- [ ] Tab navigation works
- [ ] Enter/Space activates buttons
- [ ] Escape closes modals
- [ ] Focus trap in modals

### Visual
- [ ] Focus indicator visible
- [ ] Color contrast 4.5:1 minimum
- [ ] Don't rely on color alone

Common Planning Mistakes

Mistake	Impact	Prevention
Skipping code analysis for bugs	Wrong fix	Always read existing code first
Vague test descriptions	Tests miss cases	Use Given/When/Then
Missing accessibility	Inaccessible UI	Include a11y checklist always
Ignoring existing patterns	Inconsistent code	Document patterns before planning
Not extracting from Figma	Design mismatch	Use Figma MCP tools

Quality Checklist for Plans

Before finalizing a plan, verify:

• Task type is clearly identified
• All requirements are listed and numbered
• For new features: Figma values extracted
• For bugs/enhancements: existing code analyzed
• Test cases have Given/When/Then structure
• Implementation checklist is file-by-file
• Verification commands are exact
• Accessibility checklist is complete
• Acceptance criteria maps to tests
• No ambiguous instructions