# Interactive Prototypes - Getting Started Guide

**Version**: 1.0  
**Last Updated**: December 10, 2025  
**For**: WDS Agents (Freya, Saga)

---

## 🎯 Overview

This system creates **production-ready, self-contained interactive prototypes** using:

✅ **Tailwind CSS** - No separate CSS files  
✅ **Vanilla JavaScript** - Components in shared folders  
✅ **Section-by-section** - Approval gates prevent errors  
✅ **Just-in-time stories** - Created as needed, not all upfront  
✅ **Demo data auto-loading** - Works immediately  
✅ **Self-contained** - Zip & share, works anywhere

---

## 📁 Folder Structure (Per Scenario)

```
[Scenario]/Prototype/
│
├── [Page-1].html                    ← HTML in ROOT (double-click to open)
├── [Page-2].html                    ← HTML in ROOT
├── [Page-3].html                    ← HTML in ROOT
│
├── shared/                          ← Shared code (ONE COPY)
│   ├── prototype-api.js
│   ├── init.js
│   └── utils.js
│
├── components/                      ← Reusable components (ONE COPY)
│   ├── image-crop.js
│   ├── toast.js
│   ├── modal.js
│   └── form-validation.js
│
├── pages/                           ← Page-specific scripts (only if >150 lines)
│   ├── [complex-page].js
│   └── [another-complex-page].js
│
├── data/                            ← Demo data (auto-loads)
│   ├── demo-data.json
│   └── [additional-data].json
│
├── assets/                          ← Images, icons (optional)
│   ├── images/
│   └── icons/
│
├── stories/                         ← Section dev files (created just-in-time)
│   ├── [Page].1-[section].md
│   ├── [Page].2-[section].md
│   └── ...
│
├── work/                            ← Planning files (created at start)
│   ├── [Page]-Work.yaml
│   └── ...
│
└── PROTOTYPE-ROADMAP.md             ← ONE document with everything
```

---

## 🔄 Complete Workflow

### Phase 1: INITIATION & PLANNING

1. **User requests** prototype for [Page]
2. **Agent asks** about device compatibility
3. **Agent creates** `work/[Page]-Work.yaml` (complete plan)
4. **User reviews** and approves plan
5. **Ready to implement** section-by-section

### Phase 2: SECTION-BY-SECTION IMPLEMENTATION

**For each section (1-N)**:

1. **Agent announces** section
2. **Agent creates** story file (just-in-time)
3. **Agent implements** in HTML (root location from start)
4. **Agent presents** for testing
5. **User tests** and gives feedback
6. **Agent fixes** any issues (loop until approved)
7. **User approves** → Move to next section

### Phase 3: FINALIZATION

1. **All sections complete**
2. **Final integration test**
3. **User approves**
4. **Prototype complete** (already in final location)

---

## 📄 Templates Available

### In `templates/` folder:

1. **`work-file-template.yaml`**
   - Complete planning document
   - Created ONCE at start
   - High-level section breakdown

2. **`story-file-template.md`**
   - Detailed section implementation guide
   - Created JUST-IN-TIME before each section
   - Documents what was actually built

3. **`page-template.html`**
   - Complete HTML page with Tailwind
   - Inline JavaScript examples
   - All common patterns included

4. **`PROTOTYPE-ROADMAP-template.md`**
   - Scenario overview document
   - One per scenario Prototype folder

5. **`demo-data-template.json`**
   - Demo data structure
   - Auto-loads on first page open

---

## 🎨 Key Principles

### 1. Tailwind First
- Use Tailwind CDN
- Inline config for project colors
- Custom CSS only for what Tailwind can't do
- No separate CSS files

### 2. Pages in Root
- All HTML files in Prototype root
- Easy to find and open
- Simple relative paths
- No nested page folders

### 3. ONE COPY of Shared Code
- `shared/` contains ONE copy of each utility
- `components/` contains ONE copy of each component
- Update once → affects all pages
- Zero duplication

### 4. Self-Contained
- Zip entire Prototype folder
- Works on any computer
- No server needed
- No setup needed

### 5. Section-by-Section
- Break page into 4-8 sections
- Build one section at a time
- Test after each section
- Approval gate before next section
- Prevents errors from compounding

### 6. Just-in-Time Stories
- Create story file RIGHT BEFORE implementing each section
- Not all at once upfront
- Allows flexibility to adjust based on feedback
- Documents exactly what was built (including changes)

### 7. Build in Final Location
- No temp folder
- Create file in root from start
- Add sections incrementally
- Use "🚧" placeholders for upcoming sections
- File grows organically

---

## 🛠️ Tools & Technologies

**Required**:
- Tailwind CSS (via CDN)
- Vanilla JavaScript (no frameworks)
- SessionStorage (for demo data)

**Optional**:
- Google Fonts (Inter recommended)
- Custom fonts in `assets/fonts/`

**Not Needed**:
- Node.js / npm
- Build process
- CSS preprocessors
- Bundlers

---

## 📚 For Agents

### Freya (UX/UI Designer)
**Primary role**: Create interactive prototypes

**Read**:
1. `FREYA-WORKFLOW-INSTRUCTIONS.md` (complete step-by-step)
2. `templates/` (use these for all work)
3. Dog Week examples (reference implementations)

**Create**:
1. Work files (planning)
2. Story files (just-in-time)
3. HTML pages (section-by-section)
4. Demo data (if new data entities)

---

### Saga (Analyst)
**Role in prototypes**: Provide specifications, validate requirements

**Read**:
1. Work files (understand planned sections)
2. Story files (review implementation details)
3. Completed prototypes (validate against requirements)

**Create**:
1. Page specifications (source for work files)
2. User flow documentation
3. Success criteria definitions

---

---

## 🎓 Learning Path

### Week 1: Understand the System
- Read this guide
- Read `FREYA-WORKFLOW-INSTRUCTIONS.md`
- Open Dog Week prototypes
- Test in browser
- Check console logs

### Week 2: Study Examples
- Read 1.2-Sign-In.html (simple)
- Read 1.6-Add-Dog.html (medium)
- Read 3.1-Calendar.html (complex)
- Compare to their work files
- Review story files

### Week 3: Modify Example
- Copy existing prototype
- Change fields, text, colors
- Test modifications
- Understand file relationships

### Week 4: Create New Prototype
- Start with simple page
- Follow workflow exactly
- Build section-by-section
- Get feedback, iterate

---

## ✅ Quality Standards

Every prototype must have:

**Functionality**:
- [ ] All interactions work
- [ ] Form validation correct
- [ ] Loading states display
- [ ] Success/error feedback shows
- [ ] Navigation works
- [ ] Data persists

**Code Quality**:
- [ ] All Object IDs present
- [ ] Tailwind classes used properly
- [ ] Console logs helpful
- [ ] No console errors
- [ ] Inline JS < 150 lines (or external file)
- [ ] Functions documented

**Mobile**:
- [ ] Tested at target width
- [ ] Touch targets min 44px
- [ ] No horizontal scroll
- [ ] Text readable

**Documentation**:
- [ ] Work file complete
- [ ] Story files for all sections
- [ ] Changes documented
- [ ] Status updated

---

## 🚀 Benefits

| Aspect | Benefit |
|--------|---------|
| **For Designers** | No coding complexity, visual results fast |
| **For Users** | Real interactions, usable for testing |
| **For Developers** | Clear implementation reference |
| **For Stakeholders** | Works immediately, no setup |
| **For Project** | Self-contained, easy to share |

---

## 📊 Success Metrics

**Speed**: 30-45 min per page (section-by-section)  
**Quality**: Production-ready code  
**Error Rate**: Low (approval gates prevent issues)  
**Flexibility**: High (adjust as you go)  
**Reusability**: High (shared components)  
**Maintainability**: High (ONE copy of shared code)

---

## 🆘 Need Help?

**Question**: "How do I start?"  
**Answer**: Read `FREYA-WORKFLOW-INSTRUCTIONS.md` and follow step-by-step

**Question**: "Which template do I use?"  
**Answer**: 
- Planning → `work-file-template.yaml`
- Implementing → `story-file-template.md` (just-in-time)
- Coding → `page-template.html`

**Question**: "How do I create demo data?"  
**Answer**: Copy `demo-data-template.json`, fill in values, save to `data/` folder

**Question**: "What if section needs changes?"  
**Answer**: Make changes directly in HTML, document in story file, re-test, get approval

**Question**: "How do I share prototype?"  
**Answer**: Zip entire Prototype folder, send to stakeholder

---

## 📝 Quick Reference

**Start new prototype**: Create work file → Get approval → Build section 1  
**Add section**: Create story → Implement → Test → Get approval → Next section  
**Fix issue**: Update HTML → Re-test → Get approval  
**Complete prototype**: Final integration test → Update status → Done  
**Share prototype**: Zip Prototype folder → Send  

---

## 🎯 Remember

1. **Tailwind first** - Use classes, not custom CSS
2. **Pages in root** - Easy to find and open
3. **ONE COPY** - No duplication of shared code
4. **Section-by-section** - Approval gates prevent errors
5. **Just-in-time stories** - Create when needed, not all upfront
6. **Build in final location** - No temp folder needed
7. **Test after each section** - Don't wait until the end
8. **Object IDs always** - Every interactive element
9. **Demo data ready** - Auto-loads on first use
10. **Self-contained** - Zip & works anywhere

---

**You are ready to create production-ready interactive prototypes!** 🚀

For detailed step-by-step instructions, see: `FREYA-WORKFLOW-INSTRUCTIONS.md`