diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md
new file mode 100644
index 0000000..3b408c8
--- /dev/null
+++ b/.planning/REQUIREMENTS.md
@@ -0,0 +1,83 @@
+# Requirements: Kimai Heatmap Plugin v1.1
+
+**Defined:** 2026-04-08
+**Core Value:** At a glance, see where your time went — a visual map of tracking activity that makes patterns obvious
+
+## v1.1 Requirements
+
+Requirements for Modes & Filtering milestone. Each maps to roadmap phases.
+
+### Visualization Modes
+
+- [ ] **VIZ-01**: Mode switcher UI allows toggling between year, week, day, and combined views
+- [ ] **VIZ-02**: Week-mode renders day-of-week aggregation showing which weekdays are busiest
+- [ ] **VIZ-03**: Day-mode renders time-of-day heatmap showing when during the day work happens
+- [ ] **VIZ-04**: Combined mode renders 7x24 day/hour punchcard matrix
+- [ ] **VIZ-05**: Hours vs entry-count toggle switches color scale metric across all modes
+
+### Entity Pickers & Filtering
+
+- [ ] **FILT-01**: Customer→project→activity cascading TomSelect pickers replace plain <select>
+- [ ] **FILT-02**: Activity filtering narrows heatmap data to a specific activity
+- [ ] **FILT-03**: Customer filtering narrows heatmap data to all projects under a customer
+
+### Backend
+
+- [ ] **API-01**: API endpoint accepts mode param returning hour-level and day/hour aggregation data
+- [ ] **API-02**: API endpoint accepts activity and customer filter params with own controller endpoints
+
+### Polish
+
+- [ ] **POL-01**: Color scale legend gradient bar showing value range for current mode/metric
+
+### Testing
+
+- [ ] **TEST-01**: Vitest tests for mode switcher, each renderer, and display toggle
+- [ ] **TEST-02**: Vitest tests for TomSelect cascade behavior and filter integration
+- [ ] **TEST-03**: PHPUnit tests for hour-level and day/hour aggregation queries
+
+## Future Requirements
+
+- Configurable time range selector (3 months, 6 months, year, custom)
+- Persistent filter/mode state via URL params or localStorage
+- Animated transitions between visualization modes
+- Responsive widget sizing adapting to dashboard column width
+
+## Out of Scope
+
+| Feature | Reason |
+|---------|--------|
+| Billable vs non-billable split | Personal time tracking, not client billing |
+| Real-time / live updates | Page reload sufficient for daily-granularity data |
+| Export/share heatmap as image | No audience for personal use |
+| Multi-user comparison | Personal tracking tool |
+| Mobile-specific layout | Desktop Kimai dashboard only |
+| Reuse Kimai's KimaiFormSelect.js | Coupled to Kimai's plugin container, cannot work in widget context |
+| Reuse Kimai's API routes for pickers | Require IsGranted('API') permission, need own endpoints |
+
+## Traceability
+
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| VIZ-01 | - | Pending |
+| VIZ-02 | - | Pending |
+| VIZ-03 | - | Pending |
+| VIZ-04 | - | Pending |
+| VIZ-05 | - | Pending |
+| FILT-01 | - | Pending |
+| FILT-02 | - | Pending |
+| FILT-03 | - | Pending |
+| API-01 | - | Pending |
+| API-02 | - | Pending |
+| POL-01 | - | Pending |
+| TEST-01 | - | Pending |
+| TEST-02 | - | Pending |
+| TEST-03 | - | Pending |
+
+**Coverage:**
+- v1.1 requirements: 14 total
+- Mapped to phases: 0
+- Unmapped: 14
+
+---
+*Requirements defined: 2026-04-08*