julian
17c08e6392
- Nx 22.7 monorepo (pnpm 11.1, TypeScript 5.9, Node 24) - apps/api: NestJS 11 (CJS conforme CODING-RULES.md PGD-DB-004) - apps/web: React 19 + Vite 8 (ESM) - libs/shared/api-interface: Zod contract base - Docker Compose dev: Postgres 18, Valkey 8, MinIO, Mailpit - WDS artifacts: - design-artifacts/A-Product-Brief/ (5 docs canônicos + 16 dialogs) - design-artifacts/B-Trigger-Map/ (hub + 4 personas + feature impact) - Stack canon: STACK.md v2.2 + CODING-RULES.md v2.0 + brand.md - AGENTS.md + README.md como entrada para devs/agentes Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
368 lines
9.5 KiB
Markdown
368 lines
9.5 KiB
Markdown
# 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`
|
|
|