# Implementation Plan ## Validation Checklist - [x] All specification file paths are correct and exist - [x] Context priming section is complete - [x] All implementation phases are defined - [x] Each phase follows TDD: Prime → Test → Implement → Validate - [x] Dependencies between phases are clear (no circular dependencies) - [x] Parallel work is properly tagged with `[parallel: true]` - [x] Activity hints provided for specialist selection `[activity: type]` - [x] Every phase references relevant SDD sections - [x] Every test references PRD acceptance criteria - [x] Integration & E2E tests defined in final phase - [x] Project commands match actual project setup - [x] A developer could follow this plan independently --- ## Specification Compliance Guidelines ### How to Ensure Specification Adherence 1. **Before Each Phase**: Complete the Pre-Implementation Specification Gate 2. **During Implementation**: Reference specific SDD sections in each task 3. **After Each Task**: Run Specification Compliance checks 4. **Phase Completion**: Verify all specification requirements are met ### Deviation Protocol If implementation cannot follow specification exactly: 1. Document the deviation and reason 2. Get approval before proceeding 3. Update SDD if the deviation is an improvement 4. Never deviate without documentation ## Metadata Reference - `[parallel: true]` - Tasks that can run concurrently - `[component: component-name]` - For multi-component features - `[ref: document/section; lines: 1, 2-3]` - Links to specifications, patterns, or interfaces and (if applicable) line(s) - `[activity: type]` - Activity hint for specialist agent selection --- ## Context Priming *GATE: You MUST fully read all files mentioned in this section before starting any implementation.* **Specification**: - `docs/specs/002-survey-results-redesign/product-requirements.md` - Product Requirements - `docs/specs/002-survey-results-redesign/solution-design.md` - Solution Design **Key Design Decisions**: - Create new `survey-results.css` file (not modify existing CSS) - Scope all styles under `.survey-results-page` body class - Keep JavaScript inline in template (matches codebase convention) - Keep existing Chart.js library, update colors/options only - Preserve all existing JavaScript function signatures - No backend or API changes **Implementation Context**: - Commands to run: `cd userfrosting && composer install` (setup), `./deploy.sh` (deploy) - Patterns to follow: - `docs/guides/style-guide.md` - Brand colors, typography, spacing - `public_html/css/backstock-home.css` - Component patterns to replicate - Interfaces to implement: - No new interfaces - use existing survey API endpoints - `POST /api/:typeNum/survey/results/getByDateRange` - data fetch - `POST /api/:typeNum/survey/analysis` - AI analysis --- ## Implementation Phases ### Phase 1: CSS Foundation - [x] T1 **Phase 1: Create CSS Foundation** [Core styling framework for all components] - [x] T1.1 Prime Context - [x] T1.1.1 Read backstock-home.css for stat-card pattern `[ref: public_html/css/backstock-home.css; lines: stat-card section]` - [x] T1.1.2 Read backstock-home.css for table-wrapper pattern `[ref: public_html/css/backstock-home.css; lines: backstock-table-wrapper section]` - [x] T1.1.3 Read style-guide.md for color palette and typography `[ref: docs/guides/style-guide.md]` - [x] T1.1.4 Read current results.html template structure `[ref: userfrosting/templates/themes/default/survey/results.html]` - [x] T1.2 Implement CSS File `[activity: frontend-styling]` - [x] T1.2.1 Create `public_html/css/survey-results.css` - [x] T1.2.2 Add CSS Variables section matching style-guide.md - [x] T1.2.3 Add `.survey-results-page` root scoping class - [x] T1.2.4 Add page header styles (icon, title, subtitle, actions) - [x] T1.2.5 Add stats-grid container with responsive grid - [x] T1.2.6 Add stat-card component with variants (primary, success, warning, danger) - [x] T1.2.7 Add chart-card container styles - [x] T1.2.8 Add AI analysis section styles (card, tabs, button) - [x] T1.2.9 Add survey-table-wrapper styles for DataTable - [x] T1.2.10 Add responsive breakpoints (mobile, tablet, desktop) - [x] T1.3 Validate - [x] T1.3.1 Validate CSS syntax (no errors) `[activity: lint-code]` - [x] T1.3.2 Verify color contrast meets WCAG AA `[activity: accessibility-check]` - [x] T1.3.3 Test CSS loads without console errors --- ### Phase 2: Template Restructuring - [x] T2 **Phase 2: Restructure HTML Template** [Modern layout matching backstock design] - [x] T2.1 Prime Context - [x] T2.1.1 Read SDD Component Structure Pattern `[ref: solution-design.md; lines: 519-561]` - [x] T2.1.2 Review existing template logic (date picker, chart init, DataTables) `[ref: userfrosting/templates/themes/default/survey/results.html]` - [x] T2.2 Implement Page Header `[activity: frontend-html]` - [x] T2.2.1 Add `.survey-results-page` class to body - [x] T2.2.2 Replace panel header with modern page-header component - [x] T2.2.3 Add icon (fa-poll or similar) and title "Post-Buy Survey Results" - [x] T2.2.4 Add subtitle "View customer feedback and satisfaction metrics" - [x] T2.2.5 Style date picker button to match backstock action buttons - [x] T2.2.6 Add quick search input in header (optional - "Should Have" feature) - [x] T2.3 Implement Stats Grid `[activity: frontend-html]` - [x] T2.3.1 Add stats-grid container div before charts - [x] T2.3.2 Add 4 stat-card placeholders with loading state - [x] T2.3.3 Cards: Total Responses, Avg Satisfaction, Greeted %, Top Source - [x] T2.3.4 Add data attributes for dynamic value population - [x] T2.4 Implement Charts Section `[activity: frontend-html]` - [x] T2.4.1 Replace Bootstrap wells with chart-card containers - [x] T2.4.2 Create 2-column grid for top row (Greeted + Process Explained) - [x] T2.4.3 Create 2-column grid for second row (Pass Explained + Satisfaction) - [x] T2.4.4 Create full-width row for Marketing Source chart - [x] T2.4.5 Ensure canvas IDs match existing JavaScript - [x] T2.5 Implement AI Analysis Section `[activity: frontend-html]` - [x] T2.5.1 Wrap AI section in modern card container - [x] T2.5.2 Style Generate button with primary gradient - [x] T2.5.3 Add loading spinner inside button - [x] T2.5.4 Style result tabs with modern tab component - [x] T2.5.5 Add collapsible sections for each analysis area - [x] T2.6 Implement Data Table Section `[activity: frontend-html]` - [x] T2.6.1 Wrap table in survey-table-wrapper container - [x] T2.6.2 Add modern header with "Survey Results" title - [x] T2.6.3 Style Show entries and Search inputs - [x] T2.6.4 Style export buttons (Excel, PDF, Print) with secondary button style - [x] T2.6.5 Ensure table structure compatible with DataTables init - [x] T2.7 Validate - [x] T2.7.1 Verify page renders without errors `[activity: manual-testing]` - [x] T2.7.2 Verify all existing functionality still works (date picker, charts, table) - [x] T2.7.3 Check responsive layout at 1440px, 768px, 375px widths --- ### Phase 3: JavaScript Enhancements - [x] T3 **Phase 3: JavaScript for Dynamic Features** [KPI calculations and UI updates] - [x] T3.1 Prime Context - [x] T3.1.1 Read SDD Implementation Examples for stats calculation `[ref: solution-design.md; lines: 344-404]` - [x] T3.1.2 Review existing drawResultsCallback and chart init functions - [x] T3.2 Implement Stats Calculation `[activity: frontend-javascript]` - [x] T3.2.1 Add calculateStats() function for KPI values - [x] T3.2.2 Add getStatCardVariant() function for color logic - [x] T3.2.3 Add updateStatCards() function to populate DOM - [x] T3.2.4 Call updateStatCards() in API success callback - [x] T3.3 Update Chart Styling `[activity: frontend-javascript]` - [x] T3.3.1 Update Chart.js color palette to match brand colors - [x] T3.3.2 Set `#7c3aed` (primary purple) for positive responses - [x] T3.3.3 Set `#f59e0b` (amber) for neutral responses - [x] T3.3.4 Set `#f43f5e` (rose) for negative responses - [x] T3.3.5 Update chart tooltips styling - [x] T3.3.6 Update chart legend styling - [x] T3.4 Implement Loading States `[activity: frontend-javascript]` - [x] T3.4.1 Add showLoadingState() function - [x] T3.4.2 Add hideLoadingState() function - [x] T3.4.3 Call loading states before/after API calls - [x] T3.4.4 Add skeleton loading for stat cards - [x] T3.5 Implement Error States `[activity: frontend-javascript]` - [x] T3.5.1 Add handleEmptyState() for no data scenarios - [x] T3.5.2 Add handleApiError() for network errors - [x] T3.5.3 Display user-friendly error messages - [x] T3.5.4 Add retry button for API errors - [x] T3.6 Validate - [x] T3.6.1 Verify KPI calculations are correct `[activity: manual-testing]` - [x] T3.6.2 Verify stat cards update when date range changes - [x] T3.6.3 Verify error handling works (test with network offline) --- ### Phase 4: DataTable Enhancements - [x] T4 **Phase 4: Modern DataTable Styling** [Enhanced table UX and mobile support] - [x] T4.1 Prime Context - [x] T4.1.1 Read PRD Feature 5 acceptance criteria `[ref: product-requirements.md; lines: 142-153]` - [x] T4.1.2 Review existing DataTables initialization - [x] T4.2 Implement Table Styling `[activity: frontend-styling]` - [x] T4.2.1 Style table header row (dark background, white text) - [x] T4.2.2 Style table body rows (alternating colors) - [x] T4.2.3 Style links in brand purple (#7c3aed) - [x] T4.2.4 Style pagination to match backstock - [x] T4.2.5 Style "Show entries" dropdown - [x] T4.2.6 Style search input - [x] T4.3 Implement Mobile Responsiveness `[activity: frontend-styling]` - [x] T4.3.1 Add horizontal scroll wrapper for mobile - [x] T4.3.2 Add sticky first column (Date) on mobile - [x] T4.3.3 Configure responsive column visibility - [x] T4.3.4 Hide secondary columns on mobile (Buyer, Sorter) - [x] T4.4 Implement Star Ratings Display `[activity: frontend-javascript]` - [x] T4.4.1 Ensure Raty initialization preserved in drawCallback - [x] T4.4.2 Update star colors to match brand (use purple) - [x] T4.4.3 Verify star display on page load and pagination - [x] T4.5 Validate - [x] T4.5.1 Verify table sorting works `[activity: manual-testing]` - [x] T4.5.2 Verify pagination works - [x] T4.5.3 Verify search/filter works - [x] T4.5.4 Verify star ratings display correctly - [x] T4.5.5 Verify mobile horizontal scroll works --- ### Phase 5: AI Analysis Section - [x] T5 **Phase 5: AI Analysis Enhancement** [Modern styling and better UX] - [x] T5.1 Prime Context - [x] T5.1.1 Read PRD Feature 4 acceptance criteria `[ref: product-requirements.md; lines: 132-140]` - [x] T5.1.2 Review existing AI analysis JavaScript - [x] T5.2 Implement Enhanced Styling `[activity: frontend-styling]` - [x] T5.2.1 Style Generate button with gradient and icon - [x] T5.2.2 Add loading spinner animation - [x] T5.2.3 Style result tabs with modern pill design - [x] T5.2.4 Style tab content areas - [x] T5.2.5 Add success/completion indicator after generation - [x] T5.3 Implement Loading Feedback `[activity: frontend-javascript]` - [x] T5.3.1 Show spinner on button click - [x] T5.3.2 Disable button during processing - [x] T5.3.3 Update button text to "Analyzing..." - [x] T5.3.4 Show progress feedback for long operations - [x] T5.3.5 Handle timeout gracefully - [x] T5.4 Validate - [x] T5.4.1 Verify AI generation works `[activity: manual-testing]` - [x] T5.4.2 Verify loading state displays correctly - [x] T5.4.3 Verify results display in tabs - [x] T5.4.4 Verify timeout handling --- ### Phase 6: Integration & Final Validation - [ ] T6 **Phase 6: Integration & End-to-End Validation** [Full system testing] - [ ] T6.1 Visual Testing `[activity: visual-testing]` - [ ] T6.1.1 Screenshot comparison at desktop (1440px) - [ ] T6.1.2 Screenshot comparison at tablet (768px) - [ ] T6.1.3 Screenshot comparison at mobile (375px) - [ ] T6.1.4 Verify visual consistency with backstock pages - [ ] T6.2 Functional Testing `[activity: manual-testing]` - [ ] T6.2.1 Test page load with survey data - [ ] T6.2.2 Test page load without survey data (empty state) - [ ] T6.2.3 Test all date range presets - [ ] T6.2.4 Test custom date range selection - [ ] T6.2.5 Test table sorting on all columns - [ ] T6.2.6 Test table pagination - [ ] T6.2.7 Test table search - [ ] T6.2.8 Test AI analysis generation - [ ] T6.2.9 Test export buttons (Excel, PDF, Print) - [ ] T6.3 Mobile Testing `[activity: mobile-testing]` - [ ] T6.3.1 Test on iOS Safari - [ ] T6.3.2 Test on Android Chrome - [ ] T6.3.3 Verify touch targets are 44px minimum - [ ] T6.3.4 Verify horizontal scroll on table - [ ] T6.3.5 Verify date picker works on mobile - [ ] T6.4 Accessibility Testing `[activity: accessibility-check]` - [ ] T6.4.1 Verify keyboard navigation - [ ] T6.4.2 Verify screen reader compatibility - [ ] T6.4.3 Verify color contrast - [ ] T6.4.4 Verify focus indicators - [ ] T6.5 Performance Testing `[activity: performance-testing]` - [ ] T6.5.1 Verify page load < 2s on 3G `[ref: solution-design.md; lines: 603-606]` - [ ] T6.5.2 Verify chart render < 500ms - [ ] T6.5.3 Verify table handles 1000+ rows - [ ] T6.6 Cross-Browser Testing `[activity: cross-browser-testing]` - [ ] T6.6.1 Test Chrome 90+ - [ ] T6.6.2 Test Safari 14+ - [ ] T6.6.3 Test Firefox 88+ - [ ] T6.6.4 Test Edge 90+ - [ ] T6.7 PRD Compliance Verification `[activity: business-acceptance]` - [ ] T6.7.1 Feature 1: Modern Page Header ✓ - [ ] T6.7.2 Feature 2: KPI Stats Grid ✓ - [ ] T6.7.3 Feature 3: Redesigned Charts ✓ - [ ] T6.7.4 Feature 4: AI Analysis Section ✓ - [ ] T6.7.5 Feature 5: Modern Data Table ✓ - [ ] T6.7.6 Feature 6: Mobile-First Layout ✓ - [ ] T6.8 Final Documentation - [ ] T6.8.1 Update any changed patterns in docs - [ ] T6.8.2 Document any deviations from spec - [ ] T6.8.3 Mark specification as implemented --- ## Summary | Phase | Description | Dependencies | Parallel | |-------|-------------|--------------|----------| | T1 | CSS Foundation | None | No | | T2 | Template Restructuring | T1 | No | | T3 | JavaScript Enhancements | T2 | No | | T4 | DataTable Enhancements | T2 | Yes (with T3) | | T5 | AI Analysis Section | T2 | Yes (with T3, T4) | | T6 | Integration & Validation | T3, T4, T5 | No | **Total Implementation Tasks**: 6 Phases, ~50 individual tasks **Estimated Files Changed**: - 1 file created: `public_html/css/survey-results.css` - 1 file modified: `userfrosting/templates/themes/default/survey/results.html`