whiteport-design-studio 0.1.0

package/src/workflows/4-ux-design/agentic-development/templates/PROTOTYPE-ROADMAP-template.md

@@ -0,0 +1,382 @@
+# Scenario [Number]: [Scenario Name] - Prototype Roadmap
+
+**Scenario**: [Scenario Name]  
+**Pages**: [First] through [Last]  
+**Device Compatibility**: [Type] ([Width range])  
+**Last Updated**: [Date]
+
+---
+
+## 🎯 Scenario Overview
+
+**User Journey**: [Brief description of complete user flow]
+
+**Pages in this Scenario**:
+1. [Page 1] - [Description]
+2. [Page 2] - [Description]
+3. [Page 3] - [Description]
+...
+
+---
+
+## 📱 Device Compatibility
+
+**Type**: [Mobile-Only | Mobile + Tablet | Fully Responsive | Desktop-Only]
+
+**Reasoning**: 
+[Why this device compatibility was chosen for this scenario]
+
+**Test Viewports**:
+- [Device 1] ([width]px × [height]px) - [Purpose]
+- [Device 2] ([width]px × [height]px) - [Purpose]
+- [Device 3] ([width]px × [height]px) - [Purpose]
+
+**Optimization Strategy**:
+- ✅ [Optimization 1]
+- ✅ [Optimization 2]
+- ✅ [Optimization 3]
+- ❌ [Not included 1]
+- ❌ [Not included 2]
+
+**Tailwind Approach**:
+```html
+<!-- [Brief description of Tailwind strategy] -->
+```
+
+---
+
+## 📁 Folder Structure
+
+**HTML Files** (root level - double-click to open):
+```
+[Page-1].html
+[Page-2].html
+[Page-3].html
+...
+```
+
+**Supporting Folders**:
+- `shared/` - Shared code (ONE COPY for all pages)
+- `components/` - Reusable UI components (ONE COPY)
+- `pages/` - Page-specific scripts (only for complex pages)
+- `data/` - Demo data (auto-loads on first use)
+- `stories/` - Section development documentation
+- `work/` - Planning files (work.yaml for each page)
+
+---
+
+## 🚀 Quick Start
+
+### For Testing
+1. **Open** `[First-Page].html` (double-click)
+2. **Demo data prompt** → Click YES
+3. **Navigate** through the flow
+4. **Data persists** across pages (sessionStorage)
+
+### For Stakeholders
+1. **Unzip** the Prototype folder
+2. **Open** `[First-Page].html`
+3. **Test** complete user journey
+4. **Share feedback**
+
+### For Developers
+1. **Review** `work/` folder for specifications
+2. **Check** `stories/` folder for implementation details
+3. **Examine** `shared/prototype-api.js` for data operations
+4. **Extract** HTML/Tailwind structure
+5. **Migrate** to production (see TODOs in code)
+
+---
+
+## 🎨 Shared Resources (No Duplication!)
+
+### `shared/prototype-api.js`
+**Used by**: ALL prototypes  
+**Purpose**: API abstraction layer (simulates backend with sessionStorage)
+
+**Key methods**:
+```javascript
+PrototypeAPI.getUser()
+PrototypeAPI.createUserProfile(userData)
+PrototypeAPI.createFamily(familyData)
+PrototypeAPI.addDog(dogData)
+// ... see file for complete API
+```
+
+**Console commands** (for debugging):
+```javascript
+PrototypeAPI.getDebugInfo()  // See current state
+PrototypeAPI.clearAllData()  // Reset everything
+```
+
+---
+
+### `shared/init.js`
+**Used by**: ALL prototypes  
+**Purpose**: Auto-initialization (loads demo data, sets up page)
+
+**What it does**:
+- Checks if demo data exists
+- Loads from `data/demo-data.json` if empty
+- Calls `window.initPage()` if defined
+- Logs current state to console
+
+---
+
+### `shared/utils.js`
+**Used by**: ALL prototypes  
+**Purpose**: Helper functions (date formatting, validation, etc.)
+
+---
+
+## 🧩 Components (Reusable - ONE COPY)
+
+### `components/image-crop.js`
+**Used by**: [Pages that use image upload]  
+**Purpose**: Image upload with circular crop
+
+**Usage**:
+```javascript
+ImageCrop.cropImage(file, { aspectRatio: 1 });
+```
+
+---
+
+### `components/toast.js`
+**Used by**: [Pages with notifications]  
+**Purpose**: Success/error toast notifications
+
+**Usage**:
+```javascript
+showToast('Success message!', 'success');
+showToast('Error message', 'error');
+```
+
+---
+
+### `components/modal.js`
+**Used by**: [Pages with modals]  
+**Purpose**: Generic modal overlay
+
+---
+
+### `components/form-validation.js`
+**Used by**: [Pages with forms]  
+**Purpose**: Real-time form validation
+
+---
+
+## 📊 Demo Data
+
+### `data/demo-data.json`
+**Purpose**: Complete demo dataset for scenario
+
+**Contents**:
+- User profile
+- Family data
+- [Other data entities]
+
+**Edit this file** to change demo data (JSON format, designer-friendly)
+
+---
+
+### `data/[additional-data].json`
+**Purpose**: [Description]
+
+---
+
+## 📋 Prototype Status
+
+| Page | Status | Sections | Last Updated | Notes |
+|------|--------|----------|--------------|-------|
+| [Page 1] | ✅ Complete | 3/3 | [Date] | - |
+| [Page 2] | ✅ Complete | 4/4 | [Date] | - |
+| [Page 3] | 🚧 In Progress | 2/5 | [Date] | Building form fields |
+| [Page 4] | ⏸️ Not Started | 0/6 | - | Planned |
+
+**Status Legend**:
+- ✅ Complete - All sections done, tested, approved
+- 🚧 In Progress - Currently building section-by-section
+- ⏸️ Not Started - Planned, not yet started
+- 🔴 Blocked - Waiting on dependency
+
+---
+
+## 🔄 Development Workflow
+
+### 1. Planning Phase
+- Create work file: `work/[Page]-Work.yaml`
+- Define sections (4-8 per page)
+- Identify Object IDs
+- List demo data needs
+- Get approval
+
+### 2. Implementation Phase
+- Build section-by-section
+- Create story files just-in-time
+- Test after each section
+- Get approval before next section
+- File lives in root from start (no temp folder)
+
+### 3. Finalization Phase
+- Complete integration test
+- Update status to Complete
+- Document any changes
+- Update this roadmap
+
+---
+
+## 🧪 Testing Requirements
+
+### Functional Testing (All Pages)
+- [ ] All form fields work
+- [ ] Validation shows errors correctly
+- [ ] Submit buttons work with loading states
+- [ ] Success/error feedback displays
+- [ ] Navigation works (back, next, cancel)
+- [ ] Data persists across pages
+
+### Device Testing
+- [ ] [Primary viewport] ([width]px)
+- [ ] [Secondary viewport] ([width]px)
+- [ ] [Tertiary viewport] ([width]px)
+- [ ] Portrait orientation
+- [ ] Touch interactions work
+- [ ] No horizontal scroll
+
+### Browser Testing
+- [ ] Chrome (primary)
+- [ ] Safari (iOS/Mac)
+- [ ] Firefox
+- [ ] Edge
+
+---
+
+## 🎓 Tailwind Reference
+
+### Project Colors
+```javascript
+// Tailwind config (in each HTML file)
+'[project-name]': {
+  50: '#eff6ff',
+  500: '#2563eb',
+  600: '#1d4ed8',
+  700: '#1e40af',
+}
+```
+
+**Usage**: `bg-[project-name]-600`, `text-[project-name]-500`, etc.
+
+### Common Patterns
+
+**Form Input**:
+```html
+<input class="w-full px-3 py-2 border border-gray-300 rounded-lg focus:outline-none focus:ring-2 focus:ring-[project]-500">
+```
+
+**Primary Button**:
+```html
+<button class="w-full py-3 bg-[project]-600 text-white rounded-lg font-semibold hover:bg-[project]-700 transition-colors">
+```
+
+**Toast Notification**:
+```html
+<div class="fixed bottom-6 left-1/2 -translate-x-1/2 bg-gray-900 text-white px-6 py-3 rounded-lg shadow-lg">
+```
+
+---
+
+## 🐛 Troubleshooting
+
+### Issue: Demo data not loading
+**Solution**: Check `data/demo-data.json` exists, check console for errors
+
+### Issue: Tailwind not working
+**Solution**: Check `<script src="https://cdn.tailwindcss.com"></script>` in `<head>`
+
+### Issue: Navigation not working
+**Solution**: Check relative paths (should be `[Page].html` from root)
+
+### Issue: Shared code not loading
+**Solution**: Check paths are `shared/[file].js`, `components/[file].js`
+
+### Issue: Form not submitting
+**Solution**: Check `event.preventDefault()` in `handleSubmit(event)`
+
+---
+
+## 📚 Documentation
+
+**Work Files** (`work/` folder):
+- High-level plans for each page
+- Section breakdowns
+- Object ID maps
+- Acceptance criteria
+
+**Story Files** (`stories/` folder):
+- Detailed section implementation guides
+- Created just-in-time during development
+- Document what was actually built
+- Include changes from original plan
+
+---
+
+## 🚀 Production Migration
+
+### Steps to Production
+1. **Replace** `PrototypeAPI` calls with real backend
+2. **Migrate** sessionStorage to database
+3. **Add** authentication layer
+4. **Implement** proper error handling
+5. **Add** loading states for real network delays
+6. **Setup** Tailwind build process (vs CDN)
+7. **Optimize** images and assets
+8. **Test** with real data
+
+### Migration Helpers
+- Search for `TODO:` comments in code
+- Check `PrototypeAPI` methods for Supabase equivalents
+- Review work files for production requirements
+
+---
+
+## 📧 Support & Questions
+
+**For design questions**: Review story files in `stories/` folder  
+**For functionality questions**: Review work files in `work/` folder  
+**For implementation details**: Check inline comments in HTML files  
+**For API questions**: Review `shared/prototype-api.js` documentation
+
+---
+
+## 📊 Scenario Statistics
+
+**Total Pages**: [N]  
+**Completed**: [N]  
+**In Progress**: [N]  
+**Total Sections**: [N]  
+**Object IDs**: [N]  
+**Shared Components**: [N]  
+**Demo Data Files**: [N]
+
+**Estimated Test Time**: [X] minutes (complete flow)  
+**Estimated Build Time**: [X] hours (all pages)
+
+---
+
+## 📝 Change Log
+
+### [Date]
+- [Change description]
+- [Page affected]
+
+### [Date]
+- [Change description]
+- [Page affected]
+
+---
+
+**Last Updated**: [Date]  
+**Version**: 1.0  
+**Status**: [In Development | Testing | Complete]
+

package/src/workflows/4-ux-design/agentic-development/templates/components/DEV-MODE-GUIDE.md

@@ -0,0 +1,189 @@
+# Dev Mode - Usage Guide
+
+**Purpose**: Easy feedback on prototypes by copying Object IDs to clipboard
+
+---
+
+## 🎯 What is Dev Mode?
+
+Dev Mode is a built-in feature in all WDS prototypes that allows testers, stakeholders, and designers to easily reference specific UI elements when providing feedback.
+
+Instead of saying *"The button in the top right"*, you can say *"Fix `customer-sign-bankid`"* - precise and unambiguous!
+
+---
+
+## 🚀 How to Use
+
+### Step 1: Activate Dev Mode
+
+**Two ways**:
+1. Click the **Dev Mode button** (top-right corner)
+2. Press **Ctrl+E** on your keyboard
+
+The button will turn blue and say **"Dev Mode: ON"**
+
+---
+
+### Step 2: Find the Element
+
+- **Hover** over any element you want to reference
+- You'll see a **gray outline** appear
+- A **tooltip** shows the Object ID
+
+**Prototype still works normally!** You can click buttons, fill forms, etc.
+
+---
+
+### Step 3: Copy the Object ID
+
+- **Hold the Shift key** (outline turns **green**)
+- **Click the element** while holding Shift
+- **Object ID is copied!** ✓
+
+You'll see a green success message: **"✓ Copied: [object-id]"**
+
+**Important**: Shift key is **disabled when typing in form fields** (input, textarea, etc.) so you can type capital letters and special characters normally!
+
+---
+
+### Step 4: Paste in Feedback
+
+Now paste the Object ID in your feedback:
+
+**Good feedback**:
+```
+❌ Issue with `customer-sign-bankid`:
+The button is disabled even after I check the consent checkbox.
+
+💡 Suggestion for `sidebar-video`:
+Make the video auto-play on mobile.
+```
+
+**Developer knows EXACTLY** which element you're talking about!
+
+---
+
+## 🎨 Visual Guide
+
+| State | Appearance | Action |
+|-------|------------|--------|
+| **Dev Mode OFF** | Normal prototype | Click button or press Ctrl+E |
+| **Dev Mode ON (hovering)** | Gray outline | Shows Object ID in tooltip |
+| **Shift held (hovering)** | Green outline | Click to copy |
+| **After copying** | Green flash | Object ID in clipboard |
+
+---
+
+## ⌨️ Keyboard Shortcuts
+
+- **Ctrl+E**: Toggle Dev Mode on/off
+- **Shift + Click**: Copy Object ID (when dev mode is on)
+
+---
+
+## 💡 Tips
+
+1. **Activate once**, then navigate through prototype normally
+2. **Hold Shift only when copying** - prototype works without it
+3. **Type in fields normally** - Shift is disabled when focused on input/textarea
+4. **Deactivate when done** testing (Ctrl+E again)
+5. **Object IDs are permanent** - always refer to the same element
+
+---
+
+## 📋 Example Workflow
+
+### Tester's Perspective:
+
+1. Open prototype
+2. Press **Ctrl+E** (Dev Mode on)
+3. Test the prototype normally
+4. Find a bug - hover over problem element
+5. Hold **Shift**, click element
+6. Paste Object ID into bug report: "`customer-facility-startdate-group` shows wrong default date"
+7. Continue testing
+
+### Designer's Perspective:
+
+Receives feedback:
+```
+Bug: `customer-facility-startdate-group` shows wrong default date
+```
+
+- Open prototype
+- Press **Ctrl+F** in browser, search for `customer-facility-startdate-group`
+- Find exact element in code
+- Fix the date calculation
+- Done! ✅
+
+---
+
+## 🔧 For Developers
+
+When you receive Object IDs in feedback:
+
+1. Open the HTML file
+2. Search for the Object ID (Ctrl+F)
+3. Element is either:
+   - `id="object-id"` attribute
+   - `data-object-id="object-id"` attribute
+4. Fix the issue in that specific element
+
+---
+
+## ❓ FAQs
+
+**Q: Does Dev Mode affect the prototype?**  
+A: No! The prototype works normally. You need to hold Shift to copy IDs.
+
+**Q: Can I use this on mobile?**  
+A: Yes! The button appears on mobile too. Use a Bluetooth keyboard or on-screen Shift key.
+
+**Q: Can I type in form fields while Dev Mode is on?**  
+A: Yes! Shift key is automatically disabled when you're typing in input fields or textareas, so you can type capital letters and special characters normally.
+
+**Q: What if an element doesn't have an ID?**  
+A: Dev Mode walks up the tree to find the nearest parent with an ID.
+
+**Q: Can I copy multiple IDs?**  
+A: Yes! Hold Shift, click first element, release Shift, hold again, click second element, etc.
+
+**Q: Is this only for bugs?**  
+A: No! Use it for any feedback - bugs, suggestions, questions, clarifications.
+
+---
+
+## 🎓 Best Practices
+
+### For Testers:
+- ✅ **DO**: Include Object ID in every piece of feedback
+- ✅ **DO**: Test prototype normally, copy IDs when needed
+- ✅ **DO**: Combine Object ID with description
+- ❌ **DON'T**: Leave Dev Mode on during normal use
+
+### For Designers:
+- ✅ **DO**: Ensure all interactive elements have Object IDs
+- ✅ **DO**: Use descriptive, consistent naming
+- ✅ **DO**: Include Dev Mode in all prototypes
+- ❌ **DON'T**: Change Object IDs after sharing prototype
+
+---
+
+## 🚨 Troubleshooting
+
+**Problem**: Dev Mode button not showing  
+**Solution**: Check that `dev-mode.js` and `dev-mode.css` are loaded
+
+**Problem**: Clicking doesn't copy  
+**Solution**: Make sure you're holding **Shift** while clicking
+
+**Problem**: Tooltip not showing  
+**Solution**: Element might not have an ID - check console logs
+
+**Problem**: Can't turn off Dev Mode  
+**Solution**: Press Ctrl+E or refresh the page
+
+---
+
+**Dev Mode makes feedback precise, fast, and frustration-free!** 🎯
+