docs: update all documentation and add AI tooling configs
- Rewrite README.md with current architecture, features and stack - Update docs/API.md with all current endpoints (corporate, BI, client 360) - Update docs/ARCHITECTURE.md with cache, modular queries, services, ETL - Update docs/GUIA-USUARIO.md for all roles (admin, corporate, agente) - Add docs/INDEX.md documentation index - Add PROJETO.md comprehensive project reference - Add BI-CCC-Implementation-Guide.md - Include AI agent configs (.claude, .agents, .gemini, _bmad) - Add netbird VPN configuration - Add status report Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,367 @@
|
||||
# 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`
|
||||
|
||||
Reference in New Issue
Block a user