REQUIREMENTS.md Template

# REQUIREMENTS.md

## Functional Requirements

### Core Features
**[Feature Name]**
- User can [action]
- When [condition], system should [behavior]
- [Specific interaction or rule]

### Responsive Behavior
**Mobile (375px)**
- [Mobile-specific behavior]
- [Touch interactions]
- [Layout adjustments]

**Tablet (768px)**
- [Tablet-specific behavior]
- [Layout changes]

**Desktop (1440px)**
- [Desktop-specific behavior]
- [Full feature set]

## UI States (Critical - AI often misses these)

### Loading State
- Show [spinner/skeleton/message] while data loads
- Disable [buttons/interactions] during loading
- Display "Loading..." text for accessibility

### Empty State
- When no data exists, show [helpful message]
- Include [illustration or icon]
- Provide [call-to-action or next step]

### Error State
- If request fails, display [error message]
- Show [retry button or alternative action]
- Log error to console for debugging

### Success State
- After successful action, show [confirmation]
- Update UI to reflect [new state]
- Provide [next action or dismiss option]

## Component Requirements

**[Component Name]** (e.g., ProjectCard)
- **Props**: title (string), image (url), description (string)
- **States**: default, hover, loading, error
- **Behavior**:
  - On hover, [show overlay/scale/change opacity]
  - On click, [navigate to/open modal/trigger action]
  - If image fails to load, [show placeholder]

## Data Requirements
- [What data do you need?]
- [Where does it come from?]
- [What format should it be in?]
- [What happens if data is missing?]

## Design Requirements
- Must match [design system/mockup/brand guidelines]
- Typography: [specific fonts and sizes]
- Colors: [specific hex values]
- Spacing: [specific measurements]
- Animations: [transition timing and effects]

## Accessibility Requirements
- All images have alt text
- Buttons have descriptive labels
- Color contrast meets WCAG AA standards
- Keyboard navigation works for all interactive elements
- Screen reader announcements for dynamic content

## Performance Requirements
- Page load time: [target in seconds]
- Image optimization: [format and size limits]
- Code splitting: [if bundle size exceeds X]

Example: Analytics Dashboard

# REQUIREMENTS.md

## Functional Requirements

### Core Features
**Dashboard Overview**
- User can view key metrics: total users, revenue, conversion rate
- Metrics update every 5 seconds with live data
- User can select date range (today, 7 days, 30 days, custom)
- Charts display data for selected date range

**User Table**
- Display list of users with: name, email, signup date, status
- User can search by name or email
- User can filter by status (active, inactive, pending)
- User can sort by any column
- Show 20 users per page with pagination

### Responsive Behavior
**Mobile (375px)**
- Stack metric cards vertically
- Show simplified chart (line chart only, no bar chart)
- Table shows only name and status (hide email and date)
- Hamburger menu for filters

**Tablet (768px)**
- Show 2 metric cards per row
- Full chart with legend
- Table shows all columns
- Sidebar filters

**Desktop (1440px)**
- Show 4 metric cards per row
- Full dashboard with side-by-side charts
- Complete table with all features
- Persistent sidebar

## UI States (Critical - AI often misses these)

### Loading State
- Show skeleton screens for metric cards (gray rectangles pulsing)
- Display "Loading dashboard..." in chart area
- Disable date picker during data fetch
- Table shows loading spinner with "Fetching users..." message

### Empty State
- When no data exists for date range: "No data for selected period"
- Show illustration of empty chart with message "Try selecting a different date range"
- Include button: "Reset to last 7 days"
- Empty table shows: "No users found. Try adjusting your filters."

### Error State
- If API fails: "Unable to load dashboard data. Please try again."
- Show red alert box with error icon
- Include "Retry" button that refetches data
- Log full error to console: `console.error('Dashboard fetch failed:', error)`
- Table error: "Failed to load users" with "Refresh" button

### Success State
- After filter applied: Brief green checkmark animation
- After date range changed: Smooth transition to new data
- After user action (e.g., status update): Toast notification "Status updated successfully"

## Component Requirements

**MetricCard**
- **Props**: title (string), value (number), trend (number), trendDirection ('up' | 'down')
- **States**: default, loading, error
- **Behavior**:
  - Shows title in gray-600
  - Displays value in large font (text-3xl)
  - Shows trend percentage with up/down arrow (green for up, red for down)
  - On loading: shows skeleton (gray rectangle pulsing)
  - On error: shows "--" with red text

**UserTable**
- **Props**: users (array), onSort (function), onFilter (function), loading (boolean)
- **States**: default, loading, empty, error, row-hover
- **Behavior**:
  - Each row highlights on hover (bg-gray-50)
  - Click column header to sort (shows up/down arrow)
  - Search input filters in real-time (debounced by 300ms)
  - Empty state shows centered message with illustration
  - Loading state shows 5 skeleton rows

## Data Requirements
- **Metrics API**: `/api/dashboard/metrics?from={date}&to={date}`
  - Returns: `{ totalUsers: number, revenue: number, conversionRate: number, trends: {...} }`
  - If fails: use cached data or show error
- **Users API**: `/api/users?page={num}&search={query}&status={filter}`
  - Returns: `{ users: [...], total: number, page: number }`
  - Each user: `{ id, name, email, signupDate, status }`
  - If user data missing: show "N/A" for empty fields

## Design Requirements
- Must match Tailwind UI design system
- Typography: Inter for all text
- Colors:
  - Primary: #3b82f6 (blue-500)
  - Success: #10b981 (green-500)
  - Error: #ef4444 (red-500)
  - Text: #1f2937 (gray-800)
  - Background: #f9fafb (gray-50)
- Spacing: Consistent 4px base unit
- Animations: 200ms ease-in-out for all transitions
- Border radius: 8px for cards, 4px for buttons

## Accessibility Requirements
- All metric cards have aria-labels: "Total users: 1,234"
- Chart has descriptive title and summary for screen readers
- Table has proper th/td structure with scope attributes
- All buttons have visible focus states (blue outline)
- Error messages announced by screen reader
- Loading states announced: "Loading dashboard data"

## Performance Requirements
- Initial page load: under 2 seconds
- Chart renders: under 500ms
- Table pagination: instant (no loading delay)
- Images: WebP format, max 200KB per image
- Bundle size: under 500KB (use code splitting for chart library)