initial commit
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`
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,75 @@
|
||||
# Execution Principles
|
||||
|
||||
## Document Before Acting
|
||||
|
||||
**Every decision, action, and problem must be documented in the dialog file BEFORE acting on it.**
|
||||
|
||||
This ensures full traceability, clean handoff, and the dialog document is always the source of truth.
|
||||
|
||||
## Sketch Fidelity
|
||||
|
||||
**Implement code as close to the provided sketches as possible.**
|
||||
|
||||
Sketches are intentional design decisions, not loose suggestions:
|
||||
|
||||
| Element | Approach |
|
||||
|---------|----------|
|
||||
| **Text sizes** | Match relative sizes (headings vs body vs labels) |
|
||||
| **Proportions** | Preserve ratios between elements |
|
||||
| **Spacing** | Maintain visual rhythm and whitespace |
|
||||
| **Layout** | Follow the arrangement precisely |
|
||||
| **Component style** | Match the visual pattern (pills, cards, buttons) |
|
||||
|
||||
When in doubt: ask the designer. If constraints make exact matching impossible, document the deviation and explain why.
|
||||
|
||||
## Sub-Steps During Execution
|
||||
|
||||
While working on a step, add discovered tasks as sub-steps:
|
||||
|
||||
```markdown
|
||||
| # | Section | Status | Notes |
|
||||
|---|---------|--------|-------|
|
||||
| 14 | Book It Button | Done | Complete |
|
||||
| 14a | Fix button alignment | Done | Added during 14 |
|
||||
| 14b | Add loading state | Done | Added during 14 |
|
||||
| 15 | Cancel Button | In Progress | |
|
||||
```
|
||||
|
||||
Sub-steps use letter suffixes (14a, 14b) to maintain parent position.
|
||||
|
||||
## Dynamic Planning After Step Completion
|
||||
|
||||
After completing each step, review and adjust the plan:
|
||||
|
||||
1. Review remaining steps — still accurate?
|
||||
2. Shuffle if needed — reorder based on learnings
|
||||
3. Add new steps — if implementation revealed new requirements
|
||||
4. Remove steps — if no longer needed
|
||||
5. Update the dialog file
|
||||
|
||||
**Numbering rules:** Completed steps = fixed numbering. Future steps = dynamic numbering.
|
||||
|
||||
## Plan-then-Execute Pattern
|
||||
|
||||
**Separate planning from execution into distinct sessions.**
|
||||
|
||||
Context windows are finite. Long sessions accumulate noise. The solution:
|
||||
|
||||
**Planning Session:**
|
||||
1. Explore codebase and requirements
|
||||
2. Discuss approach with designer
|
||||
3. Write plan to dialog file
|
||||
4. End with clear handoff
|
||||
|
||||
**Execution Session:**
|
||||
1. Start fresh (new conversation)
|
||||
2. Read product brief for context
|
||||
3. Read page specification for requirements
|
||||
4. Read dialog document for plan and progress
|
||||
5. Execute steps one by one
|
||||
|
||||
**When to split:** After complex exploration, when plan is complete, when session is getting long, before major implementation.
|
||||
|
||||
## Handoff Always References Dialog
|
||||
|
||||
Any handoff — to a new session, agent, or human — **MUST** reference the dialog document. Never hand off verbally. Always point to the dialog.
|
||||
@@ -0,0 +1,86 @@
|
||||
# User Feedback Protocol
|
||||
|
||||
**CRITICAL: Never implement feedback without first classifying it and stating when it should be addressed.**
|
||||
|
||||
## Feedback Types
|
||||
|
||||
| Type | What It Is | When to Address |
|
||||
|------|------------|-----------------|
|
||||
| **Bug/Issue** | Something broken, error, not working | Now — fix immediately, iterate until resolved |
|
||||
| **Quick Adjustment** | Small tweak, change X to Y | Now — implement immediately |
|
||||
| **Addition** | New requirement that fits current dialog | Later step — add to plan |
|
||||
| **Change Request** | Outside current dialog scope | Future session — document in Change Requests |
|
||||
|
||||
## The 2-Minute Rule (GTD)
|
||||
|
||||
**If a fix takes less than 2 minutes, do it immediately.**
|
||||
|
||||
From David Allen's "Getting Things Done": planning overhead should not exceed task complexity.
|
||||
|
||||
| Situation | Action |
|
||||
|-----------|--------|
|
||||
| Missing condition check | Fix now, log as sub-step |
|
||||
| Wrong variable name | Fix now, log as sub-step |
|
||||
| Needs new component | Add to plan |
|
||||
| Architectural change | Add to plan |
|
||||
|
||||
**Pattern:** Do the fix → Log as sub-step (e.g., 20a-1) → Continue main task
|
||||
|
||||
## Response Flow
|
||||
|
||||
When user reports something:
|
||||
|
||||
1. **CLASSIFY** — What type of feedback is this?
|
||||
2. **TIMING** — When should it be addressed?
|
||||
3. **DOCUMENT** — For bugs, add to plan BEFORE fixing
|
||||
4. **CONFIRM** — For additions and change requests, confirm before proceeding
|
||||
5. **EXECUTE** — Implement or document as appropriate
|
||||
|
||||
### Bug/Issue (Document First, Then Fix)
|
||||
|
||||
**User says:** "This is broken" / "Error occurred" / "Not working"
|
||||
|
||||
**Agent response:**
|
||||
```
|
||||
This is a bug — [brief description].
|
||||
Let's call it 10A and let me add it to the plan, then fix it.
|
||||
```
|
||||
|
||||
Required sequence:
|
||||
1. Identify — Understand and describe the bug
|
||||
2. Document — Add to dialog plan as sub-step (e.g., 21a, 21b)
|
||||
3. Execute — Fix and iterate until resolved
|
||||
4. Log — Record resolution in progress log
|
||||
|
||||
If user reports multiple issues: list each separately, add ALL to plan first, then fix one by one.
|
||||
|
||||
### Quick Adjustment (Fix Now)
|
||||
|
||||
**User says:** "Change X to Y" / "Make this button go here"
|
||||
|
||||
**Agent response:** "Quick adjustment — I'll implement this now." Then implement.
|
||||
|
||||
### Addition (Add to Plan)
|
||||
|
||||
**User says:** "We should also add X"
|
||||
|
||||
**Agent response:** "This is an addition that fits the current dialog. I'll add it to Step {N}. Confirm?"
|
||||
|
||||
### Change Request (Document for Later)
|
||||
|
||||
**User says:** "We need a settings page"
|
||||
|
||||
**Agent response:**
|
||||
```
|
||||
This is outside the current dialog scope.
|
||||
It doesn't block {feature name}.
|
||||
I'll add it to Change Requests for a future session. Confirm?
|
||||
```
|
||||
|
||||
**WAIT for user confirmation.** If user says "do it now" → treat as quick adjustment.
|
||||
|
||||
### Anti-Pattern
|
||||
|
||||
**NEVER** immediately implement without classifying. **ALWAYS** classify, state timing, then confirm or act.
|
||||
|
||||
The extra seconds to classify and confirm build trust and ensure alignment.
|
||||
@@ -0,0 +1,212 @@
|
||||
# Agentic Development - File Index
|
||||
|
||||
**Location**: `src/workflows/5-agentic-development/`
|
||||
|
||||
---
|
||||
|
||||
## 📁 Complete File Structure
|
||||
|
||||
```
|
||||
agentic-development/
|
||||
│
|
||||
├── AGENTIC-DEVELOPMENT-GUIDE.md ← START HERE (overview & quick reference)
|
||||
├── workflow.md ← Workflow overview with phase links
|
||||
├── PROTOTYPE-INITIATION-DIALOG.md ← Conversation scripts for initiation
|
||||
├── CREATION-GUIDE.md ← Original detailed guide (reference)
|
||||
├── PROTOTYPE-ANALYSIS.md ← Dog Week analysis (examples)
|
||||
│
|
||||
├── steps-p/ ← Micro-step workflow files
|
||||
│ ├── 1-prototype-setup.md ← Phase 1: Environment setup
|
||||
│ ├── 2-scenario-analysis.md ← Phase 2: Analyze spec & create views
|
||||
│ ├── 3-logical-view-breakdown.md ← Phase 3: Break view into sections
|
||||
│ ├── 4a-announce-and-gather.md ← Phase 4a: Announce section
|
||||
│ ├── 4b-create-story-file.md ← Phase 4b: Create story file
|
||||
│ ├── 4c-implement-section.md ← Phase 4c: Implement code
|
||||
│ ├── 4d-present-for-testing.md ← Phase 4d: Present for testing
|
||||
│ ├── 4e-handle-issue.md ← Phase 4e: Fix issues (loop)
|
||||
│ ├── 4f-handle-improvement.md ← Phase 4f: Handle improvements (loop)
|
||||
│ ├── 4g-section-approved.md ← Phase 4g: Section approved
|
||||
│ └── 5-finalization.md ← Phase 5: Integration test & approval
|
||||
│
|
||||
├── templates/
|
||||
│ ├── work-file-template.yaml ← Planning document template
|
||||
│ ├── story-file-template.md ← Section implementation template
|
||||
│ ├── page-template.html ← Complete HTML page template
|
||||
│ ├── PROTOTYPE-ROADMAP-template.md ← Scenario roadmap template
|
||||
│ ├── demo-data-template.json ← Demo data structure template
|
||||
│ └── components/
|
||||
│ ├── dev-mode.html ← Dev mode toggle button
|
||||
│ ├── dev-mode.js ← Dev mode logic (Shift+Click to copy IDs)
|
||||
│ ├── dev-mode.css ← Dev mode styles
|
||||
│ └── DEV-MODE-GUIDE.md ← Dev mode usage guide
|
||||
│
|
||||
└── examples/
|
||||
└── (Dog Week prototypes as reference)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📚 What Each File Does
|
||||
|
||||
### Core Documentation
|
||||
|
||||
#### `AGENTIC-DEVELOPMENT-GUIDE.md`
|
||||
**Purpose**: Complete system overview
|
||||
**For**: All agents (Freya, Saga)
|
||||
**Contains**:
|
||||
- System overview
|
||||
- Folder structure
|
||||
- Complete workflow summary
|
||||
- Key principles
|
||||
- Quick reference
|
||||
- Success metrics
|
||||
|
||||
**Read this**: To understand the complete system
|
||||
|
||||
---
|
||||
|
||||
#### `workflow.md`
|
||||
**Purpose**: Workflow overview with phase navigation
|
||||
**For**: Freya (primary), other agents (reference)
|
||||
**Contains**:
|
||||
- Overview of all phases
|
||||
- Clear links to step files
|
||||
- When to use each phase
|
||||
- What each phase creates
|
||||
|
||||
**Read this**: To understand the workflow structure
|
||||
|
||||
---
|
||||
|
||||
### Step Files
|
||||
|
||||
#### `steps-p/1-prototype-setup.md`
|
||||
**Purpose**: Environment setup instructions
|
||||
**Contains**: Device compatibility, design fidelity, languages, demo data creation
|
||||
**Next**: Phase 2
|
||||
|
||||
---
|
||||
|
||||
#### `steps-p/2-scenario-analysis.md`
|
||||
**Purpose**: Scenario analysis and view identification
|
||||
**Contains**: Spec analysis, logical view mapping
|
||||
**Next**: Phase 3
|
||||
|
||||
---
|
||||
|
||||
#### `steps-p/3-logical-view-breakdown.md`
|
||||
**Purpose**: Break view into implementable sections
|
||||
**Contains**: Section breakdown, work file creation
|
||||
**Next**: Phase 4
|
||||
|
||||
---
|
||||
|
||||
#### `steps-p/4a-4g-*.md` (Phase 4 Loop)
|
||||
**Purpose**: Section-by-section implementation
|
||||
**Contains**: Announce, create story, implement, test, handle feedback, approve
|
||||
**Flow**: 4a → 4b → 4c → 4d → [4e/4f loop] → 4g → [next section]
|
||||
|
||||
---
|
||||
|
||||
#### `steps-p/5-finalization.md`
|
||||
**Purpose**: Integration test and completion
|
||||
**Contains**: Final test, quality checklist, next steps
|
||||
**Next**: New page (Phase 3) or new scenario (Phase 1)
|
||||
|
||||
---
|
||||
|
||||
### Templates
|
||||
|
||||
#### `templates/work-file-template.yaml`
|
||||
**Purpose**: Planning document
|
||||
**When to use**: Start of EVERY implementation
|
||||
**Created**: Once per page at beginning
|
||||
**Contains**:
|
||||
- Metadata (page info, device compatibility)
|
||||
- Design tokens (Tailwind config)
|
||||
- Page requirements (from spec)
|
||||
- Demo data needs
|
||||
- Object ID map
|
||||
- Section breakdown (4-8 sections)
|
||||
- Testing checklist
|
||||
|
||||
**Use this**: To create work file (plan BEFORE coding)
|
||||
|
||||
---
|
||||
|
||||
#### `templates/story-file-template.md`
|
||||
**Purpose**: Section implementation guide
|
||||
**When to use**: Just-in-time (right before implementing each section)
|
||||
**Created**: Once per section (4-8 per page)
|
||||
**Contains**:
|
||||
- Section goal
|
||||
- What to build (HTML/JS)
|
||||
- Tailwind classes to use
|
||||
- Dependencies
|
||||
- Acceptance criteria
|
||||
- Test instructions
|
||||
- Common issues
|
||||
|
||||
**Use this**: To create story file before each section
|
||||
|
||||
---
|
||||
|
||||
#### `templates/page-template.html`
|
||||
**Purpose**: Complete HTML page structure
|
||||
**When to use**: Creating new HTML page
|
||||
**Created**: Once per page (at start of Section 1)
|
||||
**Contains**:
|
||||
- Complete HTML structure
|
||||
- Tailwind CDN setup
|
||||
- Tailwind config inline
|
||||
- Component examples
|
||||
- Shared script includes
|
||||
|
||||
**Use this**: As starting point for new page HTML
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Which File When?
|
||||
|
||||
### Starting New Scenario
|
||||
1. Read: `workflow.md` (understand phases)
|
||||
2. Follow: `steps-p/1-prototype-setup.md` (setup)
|
||||
3. Use: `PROTOTYPE-ROADMAP-template.md` → Create roadmap
|
||||
4. Use: `demo-data-template.json` → Create demo data
|
||||
|
||||
### Starting New Page
|
||||
1. Follow: `steps-p/2-scenario-analysis.md` (analyze)
|
||||
2. Follow: `steps-p/3-logical-view-breakdown.md` (break down)
|
||||
3. Use: `work-file-template.yaml` → Create work file
|
||||
4. Get approval
|
||||
|
||||
### Implementing Each Section
|
||||
1. Follow: `steps-p/4a-4g-*.md` (loop)
|
||||
2. Use: `story-file-template.md` → Create story file (just-in-time)
|
||||
3. Implement in HTML (incrementally)
|
||||
4. Test
|
||||
5. Get approval
|
||||
6. Repeat for next section
|
||||
|
||||
### Finishing Page
|
||||
1. Follow: `steps-p/5-finalization.md` (integration test)
|
||||
2. Get final approval
|
||||
3. Choose: New page, new scenario, or done
|
||||
|
||||
---
|
||||
|
||||
## 📝 Template Usage Summary
|
||||
|
||||
| Template | When Created | How Many | Purpose |
|
||||
|----------|--------------|----------|---------|
|
||||
| work-file | Start of page | 1 per page | Complete plan |
|
||||
| story-file | Before each section | 4-8 per page | Section implementation |
|
||||
| page | Start of Section 1 | 1 per page | HTML structure |
|
||||
| roadmap | Start of scenario | 1 per scenario | Scenario overview |
|
||||
| demo-data | Setup scenario | 1 per scenario | Auto-loading data |
|
||||
|
||||
---
|
||||
|
||||
**All templates and micro-step instructions are ready!**
|
||||
|
||||
Next step: Activate Freya and follow `workflow.md` → `steps-p/1-prototype-setup.md`
|
||||
@@ -0,0 +1,190 @@
|
||||
# Inline Testing Guide
|
||||
|
||||
**For**: WDS Agents performing Agentic Development
|
||||
**Purpose**: Self-verify implementation using Puppeteer before presenting to user
|
||||
**Scope**: During-development testing (NOT Phase 7 post-development validation)
|
||||
|
||||
---
|
||||
|
||||
## Core Principle
|
||||
|
||||
**The agent tests its own work before presenting it to the user.**
|
||||
|
||||
After implementing a section, the agent uses Puppeteer to open the browser, navigate to the page, and verify all measurable acceptance criteria. Only after all measurable criteria pass does the agent present the result to the user for qualitative feedback.
|
||||
|
||||
---
|
||||
|
||||
## Responsibility Split
|
||||
|
||||
| Responsibility | Owner | Examples |
|
||||
|---------------|-------|----------|
|
||||
| **Measurable criteria** | Agent (Puppeteer) | Text content matches spec, colors match hex values, touch targets >= 44px, error states display correctly, element visibility, layout positioning |
|
||||
| **Qualitative judgment** | Human | Flow feels natural, visual hierarchy works, user understands next steps, pacing feels right, overall consistency |
|
||||
|
||||
**The agent never asks the user to verify something it can measure itself.**
|
||||
|
||||
---
|
||||
|
||||
## When to Test
|
||||
|
||||
| Trigger | Action |
|
||||
|---------|--------|
|
||||
| Section implementation complete (4c done) | Run Puppeteer verification before presenting (4d) |
|
||||
| Public page implementation complete | Run SEO validation → [SEO-VALIDATION-GUIDE.md](SEO-VALIDATION-GUIDE.md) |
|
||||
| Issue fixed (4e done) | Re-verify the fix + check for regressions before re-presenting |
|
||||
| Modifying existing feature | Capture baseline BEFORE making changes |
|
||||
| Integration test (Phase 5) | Verify all states across all sections |
|
||||
|
||||
---
|
||||
|
||||
## Baseline Capture
|
||||
|
||||
When modifying an existing feature, capture current state BEFORE making changes:
|
||||
|
||||
1. Open browser with Puppeteer
|
||||
2. Navigate to the page/component
|
||||
3. Document current state:
|
||||
- Screenshot the current rendering
|
||||
- Key measurable values (text, colors, dimensions)
|
||||
- Current behavior for each relevant interaction
|
||||
4. Record as baseline in the story file under "Baseline State"
|
||||
5. After implementation, compare against baseline to confirm only intended changes occurred
|
||||
|
||||
**Why:** Without a baseline, you can't distinguish intended changes from regressions. The agent needs to know what "before" looked like to verify "after" is correct.
|
||||
|
||||
---
|
||||
|
||||
## Puppeteer Verification Process
|
||||
|
||||
### Step 1: Open and Navigate
|
||||
|
||||
```
|
||||
1. Open browser with Puppeteer
|
||||
2. Navigate to [View].html or the relevant page URL
|
||||
3. Wait for page to fully load
|
||||
4. Set viewport to target device width if relevant (e.g., 375px for mobile)
|
||||
```
|
||||
|
||||
### Step 2: Verify Each Criterion
|
||||
|
||||
For each acceptance criterion in the test plan:
|
||||
|
||||
```
|
||||
1. Locate the element (by data-object-id, selector, or content)
|
||||
2. Read the actual value (text, computed style, dimensions, visibility)
|
||||
3. Compare against the spec value
|
||||
4. Record result with narration
|
||||
```
|
||||
|
||||
### Step 3: Narrate Findings
|
||||
|
||||
Use this narration pattern — group by category, state both actual and expected:
|
||||
|
||||
```
|
||||
Verifying Section [N]: [Section Name]
|
||||
|
||||
Text Content:
|
||||
Headline text is "Boka promenad" — matches spec. ✓
|
||||
Subtext is "Välj tid och dag" — matches spec. ✓
|
||||
|
||||
Styling:
|
||||
Primary button background is #2563EB — matches spec. ✓
|
||||
Error text color is #EF4444 — spec says #DC2626. ✗ Mismatch.
|
||||
|
||||
Layout:
|
||||
Touch target is 48x48px — meets minimum 44px. ✓
|
||||
Input field width is 100% of container — matches spec. ✓
|
||||
|
||||
States:
|
||||
Empty state shows placeholder text — correct. ✓
|
||||
Error state displays validation message — correct. ✓
|
||||
Loading state disables button and shows spinner — correct. ✓
|
||||
|
||||
Result: 8/9 criteria pass. 1 mismatch found.
|
||||
```
|
||||
|
||||
**Rules:**
|
||||
- Always state both actual and expected values
|
||||
- Always group by category for readability
|
||||
- Always end with a summary line (X/Y criteria pass)
|
||||
|
||||
### Step 4: Fix or Present
|
||||
|
||||
- **All criteria pass** — Proceed to Phase 4d (present to user for qualitative feedback)
|
||||
- **Any criteria fail** — Fix the issue, then re-run verification. Do NOT present to user with known measurable failures.
|
||||
|
||||
---
|
||||
|
||||
## Test Plan Structure
|
||||
|
||||
Story files split acceptance criteria into two categories. This is the format:
|
||||
|
||||
### Agent-Verifiable (Puppeteer)
|
||||
|
||||
Measurable criteria the agent checks itself:
|
||||
|
||||
| # | Criterion | Element | Expected | How to Verify |
|
||||
|---|-----------|---------|----------|---------------|
|
||||
| 1 | Headline text | `[data-object-id="section-title"]` | "Boka promenad" | Read textContent |
|
||||
| 2 | Button color | `[data-object-id="submit-btn"]` | bg: #2563EB | Read computed backgroundColor |
|
||||
| 3 | Touch target | `[data-object-id="submit-btn"]` | >= 44x44px | Read offsetWidth, offsetHeight |
|
||||
| 4 | Error display | `#emailError` | Visible when email invalid | Trigger error, check visibility |
|
||||
| 5 | Loading state | `[data-object-id="submit-btn"]` | Disabled + spinner | Click submit, check disabled attr |
|
||||
|
||||
### User-Evaluable (Qualitative)
|
||||
|
||||
Criteria only the human can judge:
|
||||
|
||||
- [ ] Flow feels natural and intuitive
|
||||
- [ ] Visual hierarchy guides the eye correctly
|
||||
- [ ] Error messages are understandable (not just present)
|
||||
- [ ] Section feels consistent with the rest of the prototype
|
||||
|
||||
---
|
||||
|
||||
## Integration with Phase 4 Flow
|
||||
|
||||
```
|
||||
4a: Announce & Gather
|
||||
4b: Create Story File (includes split test plan)
|
||||
4c: Implement Section
|
||||
↓
|
||||
Agent runs Puppeteer verification
|
||||
Agent runs SEO validation (if public page) → SEO-VALIDATION-GUIDE.md
|
||||
↓
|
||||
All pass? ── No ──→ Agent fixes, re-verifies (loop)
|
||||
│
|
||||
Yes
|
||||
↓
|
||||
4d: Present for Testing (user evaluates qualitative criteria only)
|
||||
4e/4f: Handle Issue/Improvement (if needed)
|
||||
4g: Section Approved
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Distinction from Phase 7 Testing
|
||||
|
||||
| Aspect | Inline Testing (This Guide) | Phase 7 Testing |
|
||||
|--------|----------------------------|-----------------|
|
||||
| **When** | During development, per section | After development complete |
|
||||
| **Who tests** | Agent (automated via Puppeteer) | Designer (manual validation) |
|
||||
| **What** | Measurable spec conformity | Full design vision validation |
|
||||
| **Scope** | Single section at a time | Entire feature/delivery |
|
||||
| **Outcome** | Agent fixes before showing user | Issues documented for developer |
|
||||
|
||||
These are complementary, not competing. Inline testing catches measurable issues early. Phase 7 testing validates the complete feature against the full design vision.
|
||||
|
||||
---
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
- **Never present to user with known measurable failures** — Fix them first
|
||||
- **Never ask user to check something Puppeteer can verify** — Colors, text, sizes are the agent's job
|
||||
- **Never skip baseline capture when modifying existing features** — Prevents unintended regressions
|
||||
- **Never narrate without comparison values** — Always state both actual and expected
|
||||
- **Never batch all testing to the end** — Test each section as you build it
|
||||
|
||||
---
|
||||
|
||||
*Test as you build. Fix before you present. Let the human focus on what only humans can judge.*
|
||||
@@ -0,0 +1,832 @@
|
||||
# Interactive Prototype Analysis - Dog Week Project
|
||||
|
||||
**Date**: December 10, 2025
|
||||
**Project**: Dog Week Mobile Web App
|
||||
**Analyzed By**: WDS System
|
||||
**Purpose**: Document proven interactive prototype patterns for WDS agents
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Executive Summary
|
||||
|
||||
The Dog Week project demonstrates **production-ready interactive prototypes** that bridge the gap between design specifications and developer handoff. These prototypes are:
|
||||
|
||||
✅ **Fully functional** - Real interactions, state management, data persistence
|
||||
✅ **Mobile-optimized** - Responsive design with touch interactions
|
||||
✅ **Developer-ready** - Clean code, documented patterns, easy to extract
|
||||
✅ **User-testable** - Can be used for real usability testing
|
||||
✅ **Backend-agnostic** - Uses abstraction layer for easy Supabase integration
|
||||
|
||||
---
|
||||
|
||||
## 📋 Prototype Inventory
|
||||
|
||||
### Analyzed Prototypes
|
||||
|
||||
| Page | Location | Features Demonstrated |
|
||||
| ------------------------ | --------------------------------------------------------------------- | -------------------------------------------------------------------------- |
|
||||
| **1.2 Sign In** | `C-UX-Scenarios/01-Customer-Onboarding/1.2-Sign-In/Frontend/` | Google SSO, Magic Link, Multi-language, State transitions |
|
||||
| **1.3 Profile Setup** | `C-UX-Scenarios/01-Customer-Onboarding/1.3-Profile-Setup/Frontend/` | Image upload/crop, Form validation, Multi-language, Terms acceptance |
|
||||
| **1.6 Add Dog** | `C-UX-Scenarios/01-Customer-Onboarding/1.6-Add-Dog/Frontend/` | Image cropping, Breed search/filter, Split buttons, Character counters |
|
||||
| **3.1 Calendar Booking** | `C-UX-Scenarios/03-Booking-Dog-Walks/3.1-Dog-Calendar-Booking/Frontend/` | Swedish week calendar, Leaderboard, Dev tools menu, Multi-member switching |
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ Architecture Patterns
|
||||
|
||||
### File Structure (Per Page)
|
||||
|
||||
```
|
||||
1.2-Sign-In/
|
||||
├── Frontend/
|
||||
│ ├── 1.2-Sign-In-Preview.html ← Main HTML with structure
|
||||
│ ├── 1.2-Sign-In-Preview.css ← Page-specific styles
|
||||
│ ├── 1.2-Sign-In-Preview.js ← Page logic & interactions
|
||||
│ └── prototype-api.js ← Shared API abstraction layer
|
||||
```
|
||||
|
||||
**Why this works:**
|
||||
|
||||
- **Separation of concerns** - HTML, CSS, JS clearly divided
|
||||
- **Reusable API layer** - `prototype-api.js` shared across all pages
|
||||
- **Easy extraction** - Developers can grab entire folder
|
||||
- **Version control friendly** - Each page isolated, easy to track changes
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Core Innovation: Prototype API Layer
|
||||
|
||||
### The `prototype-api.js` Abstraction
|
||||
|
||||
**Location**: `prototype-api.js` (shared across all prototypes)
|
||||
|
||||
**Purpose**: Simulate backend API calls using sessionStorage, with clear path to Supabase migration
|
||||
|
||||
### Architecture Overview
|
||||
|
||||
```javascript
|
||||
const DogWeekAPI = {
|
||||
config: {
|
||||
mode: 'prototype', // Switch to 'production' later
|
||||
storagePrefix: 'dogweek_'
|
||||
},
|
||||
|
||||
// User operations
|
||||
async getUser() { ... },
|
||||
async createUserProfile(userData) { ... },
|
||||
async signInWithEmail(email) { ... },
|
||||
|
||||
// Family operations
|
||||
async createFamily(familyData) { ... },
|
||||
async getActiveFamily() { ... },
|
||||
|
||||
// Dog operations
|
||||
async addDog(dogData) { ... },
|
||||
async getFamilyDogs() { ... },
|
||||
|
||||
// Utility
|
||||
clearAllData() { ... },
|
||||
getDebugInfo() { ... }
|
||||
};
|
||||
```
|
||||
|
||||
### Key Features
|
||||
|
||||
#### 1. Mode Switching
|
||||
|
||||
```javascript
|
||||
config: {
|
||||
mode: 'prototype', // or 'production'
|
||||
supabaseUrl: null,
|
||||
supabaseKey: null
|
||||
}
|
||||
```
|
||||
|
||||
**Benefit**: Same calling code works in prototype and production
|
||||
|
||||
#### 2. Async/Await Pattern
|
||||
|
||||
```javascript
|
||||
async getUser() {
|
||||
await this._delay(); // Simulate network latency
|
||||
|
||||
if (this.config.mode === 'prototype') {
|
||||
return this._storage.get('currentUser');
|
||||
} else {
|
||||
// TODO: Replace with Supabase auth.getUser()
|
||||
return null;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Benefit**: Realistic timing, clear migration path with TODO comments
|
||||
|
||||
#### 3. SessionStorage Abstraction
|
||||
|
||||
```javascript
|
||||
_storage: {
|
||||
get(key) {
|
||||
const prefixedKey = DogWeekAPI.config.storagePrefix + key;
|
||||
return JSON.parse(sessionStorage.getItem(prefixedKey));
|
||||
},
|
||||
set(key, value) { ... },
|
||||
remove(key) { ... }
|
||||
}
|
||||
```
|
||||
|
||||
**Benefit**: Easy to swap storage backend without changing calling code
|
||||
|
||||
#### 4. Console Logging
|
||||
|
||||
```javascript
|
||||
console.log('🐕 Adding dog to family:', dog.name);
|
||||
console.log('👤 Creating user profile:', user);
|
||||
console.log('🔐 Signing in with email:', email);
|
||||
```
|
||||
|
||||
**Benefit**: Developers can track data flow, test without backend
|
||||
|
||||
---
|
||||
|
||||
## 🎨 UI/UX Patterns
|
||||
|
||||
### 1. Multi-Language Support (1.2 Sign In)
|
||||
|
||||
**Implementation**:
|
||||
|
||||
```javascript
|
||||
const translations = {
|
||||
se: {
|
||||
welcomeTitle: 'Välkommen tillbaka',
|
||||
welcomeSubtitle: 'Logga in på ditt konto',
|
||||
// ... all UI text
|
||||
},
|
||||
en: {
|
||||
welcomeTitle: 'Welcome back',
|
||||
welcomeSubtitle: 'Sign in to your account',
|
||||
// ...
|
||||
},
|
||||
};
|
||||
|
||||
function applyLanguage(lang) {
|
||||
document.getElementById('welcomeTitle').textContent = translations[lang].welcomeTitle;
|
||||
// ... update all elements
|
||||
}
|
||||
```
|
||||
|
||||
**Why it's excellent**:
|
||||
|
||||
- ✅ All text centralized in one place
|
||||
- ✅ Easy to add new languages
|
||||
- ✅ Preserves language preference in storage
|
||||
- ✅ Instant switching without reload
|
||||
|
||||
**Extracted Pattern**: Language selector in header + translation dictionary
|
||||
|
||||
---
|
||||
|
||||
### 2. Image Upload with Cropping (1.3 Profile Setup, 1.6 Add Dog)
|
||||
|
||||
**Flow**:
|
||||
|
||||
1. User clicks upload button → file picker
|
||||
2. Image loaded → **crop modal appears**
|
||||
3. User adjusts zoom/position → circle mask overlay
|
||||
4. Confirm → cropped image displayed in avatar
|
||||
5. Image stored as base64 in sessionStorage
|
||||
|
||||
**Technical Implementation**:
|
||||
|
||||
```javascript
|
||||
function handlePictureUpload() {
|
||||
document.getElementById('pictureInput').click();
|
||||
}
|
||||
|
||||
pictureInput.addEventListener('change', (e) => {
|
||||
const file = e.target.files[0];
|
||||
if (file) {
|
||||
const reader = new FileReader();
|
||||
reader.onload = (e) => {
|
||||
showCropModal(e.target.result);
|
||||
};
|
||||
reader.readAsDataURL(file);
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
**Crop Modal Features**:
|
||||
|
||||
- Circle mask overlay (CSS clip-path)
|
||||
- Zoom slider (10-200%)
|
||||
- Drag-to-reposition
|
||||
- "Replace Image" and "Cancel" options
|
||||
- Final confirm button
|
||||
|
||||
**Why it's production-ready**:
|
||||
|
||||
- ✅ Real image manipulation (not just display)
|
||||
- ✅ Mobile-touch friendly
|
||||
- ✅ Stores base64 for easy API upload later
|
||||
- ✅ Handles aspect ratios and constraints
|
||||
|
||||
---
|
||||
|
||||
### 3. Breed Combobox with Search (1.6 Add Dog)
|
||||
|
||||
**Pattern**: Custom combobox (not native select) with:
|
||||
|
||||
- Button trigger showing selected breed
|
||||
- Popover with search input
|
||||
- Filtered list of options
|
||||
- "No results" state with custom option hint
|
||||
|
||||
**Implementation**:
|
||||
|
||||
```javascript
|
||||
function handleBreedSearch(query) {
|
||||
const filtered = dogBreeds.filter((breed) => breed.toLowerCase().includes(query.toLowerCase()));
|
||||
|
||||
if (filtered.length === 0) {
|
||||
showNoResults();
|
||||
} else {
|
||||
renderBreedSuggestions(filtered);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Why this pattern is superior to native `<select>`**:
|
||||
|
||||
- ✅ Searchable (critical for 300+ dog breeds)
|
||||
- ✅ Mobile-friendly large tap targets
|
||||
- ✅ Custom styling matches design system
|
||||
- ✅ Keyboard navigation support
|
||||
|
||||
---
|
||||
|
||||
### 4. Split Button (Gender Selection)
|
||||
|
||||
**Visual**: `[ Hane | Hona ]`
|
||||
|
||||
**Implementation**:
|
||||
|
||||
```javascript
|
||||
function selectGender(gender) {
|
||||
// Remove active from both
|
||||
document.getElementById('genderMale').classList.remove('selected');
|
||||
document.getElementById('genderFemale').classList.remove('selected');
|
||||
|
||||
// Add to selected
|
||||
if (gender === 'male') {
|
||||
document.getElementById('genderMale').classList.add('selected');
|
||||
} else {
|
||||
document.getElementById('genderFemale').classList.add('selected');
|
||||
}
|
||||
|
||||
selectedGender = gender;
|
||||
}
|
||||
```
|
||||
|
||||
**Why it works**:
|
||||
|
||||
- ✅ Clear binary choice
|
||||
- ✅ Large tap targets (mobile-friendly)
|
||||
- ✅ Visual feedback (selected state)
|
||||
- ✅ Better than radio buttons for mobile
|
||||
|
||||
---
|
||||
|
||||
### 5. Swedish Week Calendar (3.1 Calendar Booking)
|
||||
|
||||
**Unique Feature**: Week-based calendar (not month) with:
|
||||
|
||||
- Week number display (V48, V49, etc.)
|
||||
- 7-day horizontal scroll
|
||||
- Today indicator
|
||||
- Multi-dog leaderboard
|
||||
- Per-member booking rows
|
||||
|
||||
**Technical Complexity**:
|
||||
|
||||
- ISO 8601 week calculation
|
||||
- Swedish week numbering (starts Monday)
|
||||
- Dynamic day generation
|
||||
- Horizontal scroll with snap points
|
||||
- Touch gestures for booking slots
|
||||
|
||||
**Implementation Highlights**:
|
||||
|
||||
```javascript
|
||||
function getWeekNumber(date) {
|
||||
const target = new Date(date.valueOf());
|
||||
const dayNr = (date.getDay() + 6) % 7; // Monday = 0
|
||||
target.setDate(target.getDate() - dayNr + 3);
|
||||
const jan4 = new Date(target.getFullYear(), 0, 4);
|
||||
const dayDiff = (target - jan4) / 86400000;
|
||||
return 1 + Math.ceil(dayDiff / 7);
|
||||
}
|
||||
```
|
||||
|
||||
**Why it's impressive**:
|
||||
|
||||
- ✅ Culturally accurate (Swedish weeks)
|
||||
- ✅ Complex date math handled correctly
|
||||
- ✅ Smooth scrolling and interactions
|
||||
- ✅ Multi-user state management
|
||||
|
||||
---
|
||||
|
||||
### 6. Developer Tools Menu (3.1 Calendar)
|
||||
|
||||
**Purpose**: Built-in testing and debugging tools
|
||||
|
||||
**Features**:
|
||||
|
||||
- **Edit Mode**: Click any element to copy its Object ID
|
||||
- **Member Switcher**: View calendar as different family members
|
||||
- **Load Demo Family**: Instantly populate with test data
|
||||
- **Clear All Data**: Reset sessionStorage
|
||||
- **Keyboard Shortcuts**: `Ctrl+E` for edit mode
|
||||
|
||||
**Implementation**:
|
||||
|
||||
```javascript
|
||||
document.addEventListener('keydown', (e) => {
|
||||
if (e.ctrlKey && e.key === 'e') {
|
||||
e.preventDefault();
|
||||
toggleEditMode();
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
**Why this is genius**:
|
||||
|
||||
- ✅ **UX testing** - Switch user perspectives instantly
|
||||
- ✅ **Design validation** - Copy Object IDs for specs
|
||||
- ✅ **Developer handoff** - Demo data ready to explore
|
||||
- ✅ **QA workflow** - Reset and test from scratch
|
||||
|
||||
---
|
||||
|
||||
## 🔄 State Management Patterns
|
||||
|
||||
### 1. Form Validation States
|
||||
|
||||
**Pattern**: Real-time validation with visual feedback
|
||||
|
||||
```javascript
|
||||
function validateField(fieldId, value, validator) {
|
||||
const errorElement = document.getElementById(`${fieldId}Error`);
|
||||
|
||||
if (!validator(value)) {
|
||||
errorElement.textContent = 'Invalid value';
|
||||
errorElement.classList.remove('hidden');
|
||||
return false;
|
||||
} else {
|
||||
errorElement.classList.add('hidden');
|
||||
return true;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Visual States**:
|
||||
|
||||
- ⚪ **Default**: Normal border, no message
|
||||
- 🔴 **Error**: Red border, error message shown
|
||||
- ✅ **Valid**: Subtle green indicator (optional)
|
||||
|
||||
---
|
||||
|
||||
### 2. Loading States
|
||||
|
||||
**Pattern**: Disable form, show spinner, prevent double-submit
|
||||
|
||||
```javascript
|
||||
async function handleSubmit(event) {
|
||||
event.preventDefault();
|
||||
|
||||
// Show loading state
|
||||
const submitBtn = document.getElementById('submitButton');
|
||||
submitBtn.disabled = true;
|
||||
submitBtn.querySelector('#submitButtonText').classList.add('hidden');
|
||||
submitBtn.querySelector('#submitButtonSpinner').classList.remove('hidden');
|
||||
|
||||
try {
|
||||
await DogWeekAPI.addDog(formData);
|
||||
showSuccessToast();
|
||||
navigateToNextPage();
|
||||
} catch (error) {
|
||||
showErrorBanner(error.message);
|
||||
} finally {
|
||||
// Reset loading state
|
||||
submitBtn.disabled = false;
|
||||
submitBtn.querySelector('#submitButtonText').classList.remove('hidden');
|
||||
submitBtn.querySelector('#submitButtonSpinner').classList.add('hidden');
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Why it's production-quality**:
|
||||
|
||||
- ✅ Prevents double-submission
|
||||
- ✅ Clear visual feedback
|
||||
- ✅ Handles errors gracefully
|
||||
- ✅ Always resets state (finally block)
|
||||
|
||||
---
|
||||
|
||||
### 3. Toast Notifications
|
||||
|
||||
**Pattern**: Non-blocking success/error messages
|
||||
|
||||
```javascript
|
||||
function showSuccessToast(message) {
|
||||
const toast = document.getElementById('successToast');
|
||||
toast.querySelector('#successToastMessage').textContent = message;
|
||||
toast.classList.remove('hidden');
|
||||
|
||||
setTimeout(() => {
|
||||
toast.classList.add('hidden');
|
||||
}, 3000);
|
||||
}
|
||||
```
|
||||
|
||||
**Design**: Slides in from bottom, auto-dismisses after 3s
|
||||
|
||||
---
|
||||
|
||||
## 🎓 Best Practices Demonstrated
|
||||
|
||||
### 1. Object ID System
|
||||
|
||||
**Every interactive element** has a `data-object-id` attribute:
|
||||
|
||||
```html
|
||||
<button id="add-dog-button-submit" data-object-id="add-dog-button-submit" class="submit-button">Lägg till hund</button>
|
||||
```
|
||||
|
||||
**Purpose**:
|
||||
|
||||
- Links prototype to specification document
|
||||
- Enables automatic testing (Playwright, Cypress)
|
||||
- Makes developer handoff crystal clear
|
||||
- Supports design validation workflow
|
||||
|
||||
---
|
||||
|
||||
### 2. Semantic HTML Structure
|
||||
|
||||
**Pattern**: Proper landmarks and hierarchy
|
||||
|
||||
```html
|
||||
<header class="calendar-header">...</header>
|
||||
<main class="px-4 py-6">
|
||||
<section class="week-overview">...</section>
|
||||
<section class="leaderboard-section">...</section>
|
||||
<section class="booking-calendar-section">...</section>
|
||||
</main>
|
||||
<nav class="bottom-nav">...</nav>
|
||||
```
|
||||
|
||||
**Benefits**:
|
||||
|
||||
- ✅ Accessibility (screen readers)
|
||||
- ✅ SEO-ready structure
|
||||
- ✅ Easy to navigate in dev tools
|
||||
- ✅ Reflects actual implementation needs
|
||||
|
||||
---
|
||||
|
||||
### 3. CSS Custom Properties
|
||||
|
||||
**Pattern**: Design tokens as CSS variables
|
||||
|
||||
```css
|
||||
:root {
|
||||
--dog-week-primary: #2563eb;
|
||||
--dog-week-primary-hover: #1d4ed8;
|
||||
--dog-week-success: #10b981;
|
||||
--gray-50: #f9fafb;
|
||||
--gray-900: #111827;
|
||||
}
|
||||
```
|
||||
|
||||
**Usage**:
|
||||
|
||||
```css
|
||||
.submit-button {
|
||||
background: var(--dog-week-primary);
|
||||
}
|
||||
|
||||
.submit-button:hover {
|
||||
background: var(--dog-week-primary-hover);
|
||||
}
|
||||
```
|
||||
|
||||
**Why it matters**:
|
||||
|
||||
- ✅ Single source of truth for colors
|
||||
- ✅ Easy theme switching
|
||||
- ✅ Consistent with design system
|
||||
- ✅ Matches Tailwind CSS conventions
|
||||
|
||||
---
|
||||
|
||||
### 4. Mobile-First Responsive Design
|
||||
|
||||
**Pattern**: All prototypes start mobile, scale up
|
||||
|
||||
```css
|
||||
/* Mobile-first (default) */
|
||||
.calendar-page {
|
||||
max-width: 100%;
|
||||
padding: 1rem;
|
||||
}
|
||||
|
||||
/* Tablet and up */
|
||||
@media (min-width: 768px) {
|
||||
.calendar-page {
|
||||
max-width: 640px;
|
||||
margin: 0 auto;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Why mobile-first**:
|
||||
|
||||
- ✅ Dog Week is mobile-focused
|
||||
- ✅ Forces constraint-based thinking
|
||||
- ✅ Easier to scale up than down
|
||||
- ✅ Matches user behavior (80%+ mobile usage expected)
|
||||
|
||||
---
|
||||
|
||||
## 📦 Reusable Components
|
||||
|
||||
### Components That Could Be Extracted
|
||||
|
||||
1. **Image Cropper** (`image-crop.js`)
|
||||
- Circular mask overlay
|
||||
- Zoom slider
|
||||
- Drag-to-reposition
|
||||
- Base64 output
|
||||
|
||||
2. **Language Selector** (Header component)
|
||||
- Dropdown with flags
|
||||
- Persistence
|
||||
- Instant UI updates
|
||||
|
||||
3. **Breed Combobox** (Custom select with search)
|
||||
- Popover trigger
|
||||
- Search input
|
||||
- Filtered list
|
||||
- No results state
|
||||
|
||||
4. **Split Button** (Binary choice)
|
||||
- Two-option selector
|
||||
- Active state
|
||||
- Mobile-optimized
|
||||
|
||||
5. **Toast Notification** (Success/error)
|
||||
- Slide-in animation
|
||||
- Auto-dismiss
|
||||
- Icon + message
|
||||
|
||||
6. **Dev Tools Menu** (Debug panel)
|
||||
- Edit mode
|
||||
- Data management
|
||||
- Test utilities
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Migration Path to Production
|
||||
|
||||
### From Prototype to Supabase (Example)
|
||||
|
||||
**Prototype Code**:
|
||||
|
||||
```javascript
|
||||
const user = await DogWeekAPI.createUserProfile({
|
||||
firstName: 'Patrick',
|
||||
lastName: 'Parent',
|
||||
email: 'patrick@example.com',
|
||||
});
|
||||
```
|
||||
|
||||
**Production Code** (minimal changes):
|
||||
|
||||
```javascript
|
||||
// In prototype-api.js, update createUserProfile:
|
||||
async createUserProfile(userData) {
|
||||
if (this.config.mode === 'production') {
|
||||
const { data, error } = await supabase
|
||||
.from('profiles')
|
||||
.insert([userData])
|
||||
.select()
|
||||
.single();
|
||||
|
||||
if (error) throw error;
|
||||
return data;
|
||||
} else {
|
||||
// ... existing prototype code
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Calling code stays identical!**
|
||||
|
||||
---
|
||||
|
||||
## 📊 Prototype Quality Metrics
|
||||
|
||||
| Metric | Dog Week Score | Notes |
|
||||
| ----------------------- | -------------- | ------------------------------------------ |
|
||||
| **Functionality** | 95% | All interactions work, minor polish needed |
|
||||
| **Mobile UX** | 100% | Touch-optimized, smooth gestures |
|
||||
| **Code Quality** | 90% | Clean, documented, follows patterns |
|
||||
| **Developer Readiness** | 95% | Clear structure, easy to extract |
|
||||
| **Design Fidelity** | 90% | Matches specs, minor visual refinements |
|
||||
| **Testing Utility** | 100% | Can be used for real user testing |
|
||||
| **Migration Path** | 95% | Clear TODOs, abstraction in place |
|
||||
|
||||
**Overall Assessment**: 🌟 **Production-Ready Interactive Prototypes**
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Recommendations for WDS Agents
|
||||
|
||||
### For Freya (UX/UI Designer Agent)
|
||||
|
||||
When creating interactive prototypes, follow this proven structure:
|
||||
|
||||
#### 1. File Organization
|
||||
|
||||
```
|
||||
Page-Name/
|
||||
├── Frontend/
|
||||
│ ├── Page-Name-Preview.html
|
||||
│ ├── Page-Name-Preview.css
|
||||
│ ├── Page-Name-Preview.js
|
||||
│ ├── prototype-api.js (shared)
|
||||
│ └── [specialized libs: image-crop.js, etc.]
|
||||
```
|
||||
|
||||
#### 2. HTML Template Structure
|
||||
|
||||
```html
|
||||
<!DOCTYPE html>
|
||||
<html lang="se">
|
||||
<head>
|
||||
<meta charset="UTF-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
||||
<title>[Page Number] [Page Name] - [Project Name]</title>
|
||||
|
||||
<!-- Fonts -->
|
||||
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet" />
|
||||
|
||||
<!-- Page-specific styles -->
|
||||
<link rel="stylesheet" href="[Page-Name]-Preview.css" />
|
||||
</head>
|
||||
<body>
|
||||
<!-- Header -->
|
||||
<header>...</header>
|
||||
|
||||
<!-- Main Content -->
|
||||
<main>
|
||||
<form id="mainForm" onsubmit="handleSubmit(event)">
|
||||
<!-- Form fields with Object IDs -->
|
||||
</form>
|
||||
</main>
|
||||
|
||||
<!-- Modals (if needed) -->
|
||||
<div id="modal" class="modal-overlay hidden">...</div>
|
||||
|
||||
<!-- Toast (if needed) -->
|
||||
<div id="toast" class="toast hidden">...</div>
|
||||
|
||||
<!-- Scripts -->
|
||||
<script src="prototype-api.js"></script>
|
||||
<script src="[Page-Name]-Preview.js"></script>
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
#### 3. Required Object IDs
|
||||
|
||||
**Every interactive element** must have:
|
||||
|
||||
```html
|
||||
<button id="page-section-action" data-object-id="page-section-action" onclick="handleAction()"></button>
|
||||
```
|
||||
|
||||
**Naming Convention**: `[page]-[section]-[action]`
|
||||
|
||||
Examples:
|
||||
|
||||
- `add-dog-input-name`
|
||||
- `profile-avatar-upload`
|
||||
- `calendar-week-next`
|
||||
|
||||
#### 4. State Management Checklist
|
||||
|
||||
✅ Loading states (spinner, disabled)
|
||||
✅ Error states (red border, error message)
|
||||
✅ Success feedback (toast notification)
|
||||
✅ Form validation (real-time)
|
||||
✅ Data persistence (sessionStorage via API)
|
||||
|
||||
#### 5. Mobile Optimization Checklist
|
||||
|
||||
✅ Touch targets min 44x44px
|
||||
✅ Viewport meta tag present
|
||||
✅ Mobile-first CSS
|
||||
✅ Touch gestures (swipe, pinch-zoom where needed)
|
||||
✅ No hover-dependent interactions
|
||||
|
||||
#### 6. Developer Handoff Assets
|
||||
|
||||
Include with each prototype:
|
||||
|
||||
1. **README.md** - How to run, features, known issues
|
||||
2. **Object ID map** - Links to specification
|
||||
3. **API usage examples** - How page uses prototype-api.js
|
||||
4. **Migration notes** - What needs Supabase integration
|
||||
|
||||
---
|
||||
|
||||
## 🔮 Future Enhancements
|
||||
|
||||
### Potential Improvements Identified
|
||||
|
||||
1. **Component Library**
|
||||
- Extract reusable components (image cropper, breed selector, etc.)
|
||||
- Create shared component library
|
||||
- Reduce code duplication across pages
|
||||
|
||||
2. **Prototype Navigation**
|
||||
- Add global navigation between prototypes
|
||||
- Show current flow position
|
||||
- Quick jump to any page in scenario
|
||||
|
||||
3. **Animation Library**
|
||||
- Standardize transitions (slide-in, fade, etc.)
|
||||
- Page transition animations
|
||||
- Micro-interactions library
|
||||
|
||||
4. **Accessibility Audit**
|
||||
- Keyboard navigation testing
|
||||
- Screen reader testing
|
||||
- ARIA labels audit
|
||||
|
||||
5. **Performance Optimization**
|
||||
- Image compression
|
||||
- Lazy loading for modals
|
||||
- CSS/JS minification for production
|
||||
|
||||
---
|
||||
|
||||
## 📚 Learning Resources
|
||||
|
||||
### For Team Members Learning From This
|
||||
|
||||
**To understand the patterns**:
|
||||
|
||||
1. Start with simplest prototype (1.2 Sign In)
|
||||
2. Study `prototype-api.js` architecture
|
||||
3. Compare two similar prototypes (1.3 Profile vs 1.6 Add Dog)
|
||||
4. Explore most complex (3.1 Calendar)
|
||||
|
||||
**To create new prototypes**:
|
||||
|
||||
1. Copy an existing prototype folder as template
|
||||
2. Update HTML structure and content
|
||||
3. Modify CSS for new design
|
||||
4. Update JS for new interactions
|
||||
5. Ensure all Object IDs match spec
|
||||
|
||||
**To test prototypes**:
|
||||
|
||||
1. Open in mobile viewport (375px width)
|
||||
2. Complete full user flow
|
||||
3. Check dev tools console for errors
|
||||
4. Test data persistence (reload page)
|
||||
5. Try edge cases (empty states, errors)
|
||||
|
||||
---
|
||||
|
||||
## ✅ Conclusion
|
||||
|
||||
The Dog Week interactive prototypes represent **the gold standard** for UX design deliverables in 2025:
|
||||
|
||||
🎯 **For Designers**: These are _real interfaces_, not mockups
|
||||
🎯 **For Developers**: These provide _working reference implementations_
|
||||
🎯 **For Users**: These enable _real usability testing_
|
||||
🎯 **For Stakeholders**: These demonstrate _actual functionality_
|
||||
|
||||
**These prototypes prove that AI-assisted design can produce production-quality interactive prototypes that serve as both design validation tools AND developer handoff artifacts.**
|
||||
|
||||
---
|
||||
|
||||
**Document Status**: Complete
|
||||
**Last Updated**: December 10, 2025
|
||||
**Maintained By**: WDS System
|
||||
**Next Review**: After next major prototype addition
|
||||
@@ -0,0 +1,409 @@
|
||||
# Prototype Initiation Dialog
|
||||
|
||||
**Agent**: Freya WDS Designer Agent
|
||||
**Purpose**: Interactive conversation to gather all requirements before creating a prototype
|
||||
**Output**: Complete Work File (YAML) ready for section-by-section implementation
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Conversation Flow
|
||||
|
||||
### **Opening**
|
||||
|
||||
> "I'll create an interactive prototype for this page. Before we start coding, let's plan it out together through a few quick questions. This ensures we build exactly what you need!"
|
||||
>
|
||||
> **Let's start!** 🚀
|
||||
|
||||
---
|
||||
|
||||
## 📝 **Question 1: Page Context**
|
||||
|
||||
> "**Which page are we building?**
|
||||
>
|
||||
> Please provide:
|
||||
> - Page number and name (e.g., "3.1 Dog Calendar Booking")
|
||||
> - Link to the specification (if available)
|
||||
> - Scenario name"
|
||||
|
||||
**Wait for response**
|
||||
|
||||
**Record**:
|
||||
- `metadata.page_number`
|
||||
- `metadata.page_name`
|
||||
- `metadata.scenario`
|
||||
|
||||
---
|
||||
|
||||
## 📱 **Question 2: Device Compatibility**
|
||||
|
||||
> "**Which devices will users primarily use this page on?**
|
||||
>
|
||||
> Choose one:
|
||||
>
|
||||
> 1. 📱 **Mobile-Only** (375px-428px)
|
||||
> - For: Personal apps, on-the-go tools
|
||||
> - Testing: iPhone SE, iPhone 14 Pro, iPhone 14 Pro Max
|
||||
> - No breakpoints, touch-optimized only
|
||||
> - Hover: None
|
||||
>
|
||||
> 2. 📱💻 **Mobile + Tablet** (375px-1024px)
|
||||
> - For: Content apps, casual use
|
||||
> - Testing: Mobile + iPad
|
||||
> - Breakpoint at 768px
|
||||
> - Hover: Tablet only
|
||||
>
|
||||
> 3. 🌐 **Fully Responsive** (375px-1920px+)
|
||||
> - For: Business apps, multi-device use
|
||||
> - Testing: Mobile + Tablet + Desktop
|
||||
> - Multiple breakpoints (768px, 1024px, 1280px)
|
||||
> - Hover: Tablet & Desktop
|
||||
>
|
||||
> 4. 🖥️ **Desktop-Only** (1280px+)
|
||||
> - For: Complex data entry, professional tools
|
||||
> - Testing: Desktop only
|
||||
> - Breakpoint: None (fixed large)
|
||||
> - Hover: Always
|
||||
>
|
||||
> **Which option?** (1-4)"
|
||||
|
||||
**Wait for response**
|
||||
|
||||
**Record**:
|
||||
- `metadata.device_compatibility.type`
|
||||
- `metadata.device_compatibility.test_viewports`
|
||||
- `metadata.device_compatibility.touch_optimized`
|
||||
- `metadata.device_compatibility.hover_interactions`
|
||||
|
||||
**If Mobile-Only**, ask:
|
||||
> "Perfect! **Which mobile devices should we test on?**
|
||||
>
|
||||
> Default is:
|
||||
> - iPhone SE (375px × 667px) - Smallest common size
|
||||
> - iPhone 14 Pro (393px × 852px) - Standard size
|
||||
> - iPhone 14 Pro Max (428px × 926px) - Largest common size
|
||||
>
|
||||
> Use these defaults? (Y/N)"
|
||||
|
||||
---
|
||||
|
||||
## 🎨 **Question 3: Design Fidelity**
|
||||
|
||||
> "**What level of design fidelity should we use?**
|
||||
>
|
||||
> Choose one:
|
||||
>
|
||||
> 1. **Generic Gray Model** (Wireframe)
|
||||
> - Grayscale placeholder design
|
||||
> - Generic Tailwind defaults (grays, blues)
|
||||
> - Focus on functionality first, style later
|
||||
> - Fastest to build
|
||||
>
|
||||
> 2. **Design System Components**
|
||||
> - Uses your documented Design System
|
||||
> - Branded colors, typography, spacing
|
||||
> - Consistent with your design tokens
|
||||
> - Production-ready look and feel
|
||||
>
|
||||
> 3. **Full Design / Figma MCP Integration**
|
||||
> - Import directly from Figma designs
|
||||
> - Pixel-perfect implementation
|
||||
> - All visual details, shadows, gradients
|
||||
> - Highest fidelity
|
||||
>
|
||||
> **Which option?** (1, 2, or 3)"
|
||||
|
||||
**Wait for response**
|
||||
|
||||
**If option 2 or 3**, ask:
|
||||
> "Great! Where is your Design System located? (I'll look for it in `docs/D-Design-System/` or you can specify)"
|
||||
|
||||
**Record**:
|
||||
- `metadata.design_fidelity`
|
||||
- `design_tokens` (colors, typography, spacing from Design System)
|
||||
|
||||
---
|
||||
|
||||
## 🌍 **Question 4: Languages**
|
||||
|
||||
**Check project brief/outline first**:
|
||||
- If project defines multiple languages → Ask this question
|
||||
- If project is single language → Skip this question
|
||||
|
||||
> "**I see your project supports [Languages from project brief].**
|
||||
>
|
||||
> **Should this prototype include language switching?** (Y/N)
|
||||
>
|
||||
> If **YES**:
|
||||
> - Which languages? (e.g., Swedish, English)
|
||||
> - How to switch? (Toggle button, dropdown, flag icons)
|
||||
>
|
||||
> If **NO**:
|
||||
> - Which language to use? (Default to primary language from project)"
|
||||
|
||||
**Wait for response**
|
||||
|
||||
**Record**:
|
||||
- `languages` (array: ["sv", "en"] or single: ["en"])
|
||||
- `language_switcher` (boolean)
|
||||
- `primary_language` (default language)
|
||||
|
||||
**Implementation Note**:
|
||||
- Prototypes use **hardcoded translations** directly in HTML/JS
|
||||
- No separate translation files (easier to read, no secrets)
|
||||
- Simple language switcher if multi-language
|
||||
|
||||
**Example**:
|
||||
```javascript
|
||||
const strings = {
|
||||
sv: { bookWalk: 'Boka promenad', cancel: 'Avbryt' },
|
||||
en: { bookWalk: 'Book walk', cancel: 'Cancel' }
|
||||
};
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📦 **Question 5: Required Components**
|
||||
|
||||
> "**Let me identify the components needed based on your specification...**
|
||||
>
|
||||
> [Agent reads specification and extracts Component Dependencies section]
|
||||
>
|
||||
> **This page requires:**
|
||||
>
|
||||
> **Organism Components**:
|
||||
> - [List with Object IDs from spec]
|
||||
>
|
||||
> **Molecular Components**:
|
||||
> - [List with Object IDs from spec]
|
||||
>
|
||||
> **Atomic Components**:
|
||||
> - [List from Design System]
|
||||
>
|
||||
> **Special Features**:
|
||||
> - [Real-time features, persistence, etc.]
|
||||
>
|
||||
> **All components and Object IDs from the specification will be included.**
|
||||
>
|
||||
> **Does this match your expectations?** (Y/N)"
|
||||
|
||||
**Wait for response**
|
||||
|
||||
**If N**, ask:
|
||||
> "What would you like to add or change?"
|
||||
|
||||
**Record**:
|
||||
- `metadata.dependencies`
|
||||
- `object_ids` (all Object IDs from spec)
|
||||
- `design_tokens.components_available`
|
||||
|
||||
---
|
||||
|
||||
## 🗂️ **Question 6: Demo Data**
|
||||
|
||||
> "**What demo data do we need for realistic testing?**
|
||||
>
|
||||
> Based on your user context, I'll suggest:
|
||||
> - Current user (first name, last name, email)
|
||||
> - [Other entities based on page type]
|
||||
>
|
||||
> **Any specific demo data requirements?** (or 'use defaults')"
|
||||
|
||||
**Wait for response**
|
||||
|
||||
**Record**:
|
||||
- `demo_data_needed`
|
||||
|
||||
---
|
||||
|
||||
## 📄 **Initiation Complete - Summary**
|
||||
|
||||
> "Perfect! Here's what we have:
|
||||
>
|
||||
> **📱 Scenario**: [Scenario Name]
|
||||
> **📄 Pages**: [List pages in this scenario]
|
||||
> **📱 Devices**: [Device type] ([Viewport range])
|
||||
> **🎨 Design**: [Gray Model / Design System / Figma]
|
||||
> **👥 Demo Family**: [Family members + dogs]
|
||||
>
|
||||
> **Files Created**:
|
||||
> - ✅ `data/demo-data.json` (demo family data)
|
||||
> - ✅ `PROTOTYPE-ROADMAP.md` (scenario overview)
|
||||
>
|
||||
> **Next: Build prototypes page by page!**
|
||||
>
|
||||
> **Which page should we start with?** ([Page number] or list to see all)"
|
||||
|
||||
**Wait for user to select first page**
|
||||
|
||||
---
|
||||
|
||||
## 🚀 **Per-Page Building Process**
|
||||
|
||||
**When user selects a page** (e.g., "3.1"):
|
||||
|
||||
> "**Building: 3.1 Dog Calendar Booking**
|
||||
>
|
||||
> Let me analyze the specification and break it into sections...
|
||||
>
|
||||
> [Agent reads spec, identifies all components and Object IDs]
|
||||
>
|
||||
> **Proposed sections**:
|
||||
> 1. [Section name] (~X min)
|
||||
> 2. [Section name] (~X min)
|
||||
> 3. [Section name] (~X min)
|
||||
> ...
|
||||
>
|
||||
> **Total**: [N] sections, ~[X] hours
|
||||
>
|
||||
> **Approve this breakdown?** (Y/N)"
|
||||
|
||||
**If Y**:
|
||||
> "✅ Creating Work File: `work/3.1-Dog-Calendar-Work.yaml`
|
||||
>
|
||||
> [Creates complete work file with all sections]
|
||||
>
|
||||
> ✅ Work File created!
|
||||
>
|
||||
> **Ready to start Section 1?** (Y)"
|
||||
|
||||
**Then proceed to section-by-section building** (follow FREYA-WORKFLOW-INSTRUCTIONS.md Phase 2)
|
||||
|
||||
---
|
||||
|
||||
## 📝 **Notes for Freya**
|
||||
|
||||
**Scenario Initiation** creates:
|
||||
- ✅ `[Scenario]-Prototype/` folder with complete structure:
|
||||
- `data/` folder with `demo-data.json`
|
||||
- `work/` folder (empty, for work files)
|
||||
- `stories/` folder (empty, for just-in-time stories)
|
||||
- `shared/` folder (empty, for shared JS)
|
||||
- `components/` folder (empty, for reusable components)
|
||||
- `pages/` folder (empty, for page-specific scripts)
|
||||
- `assets/` folder (empty, for images/icons)
|
||||
- ✅ `PROTOTYPE-ROADMAP.md` (scenario overview)
|
||||
|
||||
**Per-Page Building** creates:
|
||||
- ✅ `work/[Page]-Work.yaml` (page-specific work file)
|
||||
- ✅ `stories/[Page]-[Section].md` (just-in-time story files)
|
||||
- ✅ `[Page].html` (actual prototype, built section-by-section)
|
||||
|
||||
**Key Principles**:
|
||||
1. **Scenario init** = High-level setup (device type, demo data)
|
||||
2. **Per-page** = Detailed section breakdown and building
|
||||
3. **One page at a time** = Prevents overwhelming scope
|
||||
4. **Just-in-time stories** = Create story right before building that section
|
||||
|
||||
---
|
||||
|
||||
## 🎓 **Tips During Conversation**
|
||||
|
||||
**For Freya (implementation notes)**:
|
||||
|
||||
1. **Be conversational** - Not a survey, a dialogue
|
||||
2. **Explain options** - Help user understand choices
|
||||
3. **Suggest defaults** - Based on common patterns
|
||||
4. **Adapt questions** - Skip irrelevant based on answers
|
||||
5. **Show examples** - Make abstract concepts concrete
|
||||
6. **Confirm understanding** - Reflect back what you heard
|
||||
7. **Stay encouraging** - This is collaborative, not interrogation
|
||||
|
||||
---
|
||||
|
||||
## 🔄 **After Work File Creation**
|
||||
|
||||
**Agent automatically**:
|
||||
1. Creates `work/[Page]-Work.yaml` with all gathered info
|
||||
2. Creates `data/demo-data.json` (if doesn't exist)
|
||||
3. Updates `PROTOTYPE-ROADMAP.md` with this page
|
||||
4. Presents Section 1 story and asks to proceed
|
||||
|
||||
**Then enters**: Section-by-section build mode (separate workflow)
|
||||
|
||||
---
|
||||
|
||||
## 📋 **Example Complete Exchange**
|
||||
|
||||
### **Part 1: Scenario Initiation** (one-time setup)
|
||||
|
||||
**Freya**: "Let's set up prototypes for Scenario 3: Booking Dog Walks! Which devices?"
|
||||
- 1. Mobile-Only
|
||||
- 2. Mobile + Tablet
|
||||
- 3. Fully Responsive
|
||||
- 4. Desktop-Only
|
||||
|
||||
**User**: "1"
|
||||
|
||||
**Freya**: "Mobile-only! Use default test devices? (320-428px) (Y/N)"
|
||||
|
||||
**User**: "Y"
|
||||
|
||||
**Freya**: "Design fidelity?"
|
||||
- 1. Generic Gray Model
|
||||
- 2. Design System Components
|
||||
- 3. Full Design / Figma MCP Integration
|
||||
|
||||
**User**: "2"
|
||||
|
||||
**Freya**: "Perfect! I'll use your Design System. I see your project supports Swedish and English. Should this prototype include language switching? (Y/N)"
|
||||
|
||||
**User**: "Y - Swedish primary, English secondary, toggle button"
|
||||
|
||||
**Freya**: "Got it! Demo data?"
|
||||
- Need realistic test family? (Y/N)
|
||||
|
||||
**User**: "Y - Familjen Svensson with 4 members and Golden Retriever Rufus, no pre-booked walks"
|
||||
|
||||
**Freya**: "✅ Created complete prototype environment!
|
||||
- ✅ `03-Booking-Dog-Walks-Prototype/` folder
|
||||
- ✅ `data/demo-data.json` with demo family
|
||||
- ✅ `PROTOTYPE-ROADMAP.md` with scenario overview
|
||||
- ✅ All working folders ready
|
||||
|
||||
**Which page should we start with?**"
|
||||
|
||||
---
|
||||
|
||||
### **Part 2: Page Selection**
|
||||
|
||||
**Freya**: "Which page should we start with?"
|
||||
|
||||
**User**: "3.1 Dog Calendar Booking"
|
||||
|
||||
---
|
||||
|
||||
### **Part 3: Per-Page Section Breakdown**
|
||||
|
||||
**Freya**: "Building: 3.1 Dog Calendar Booking. Let me analyze the spec...
|
||||
|
||||
**Proposed sections**:
|
||||
1. Page Structure & Header (~10 min)
|
||||
2. Week Overview Component (~20 min)
|
||||
3. Leaderboard Section (~15 min)
|
||||
4. Booking Calendar - Day Columns (~15 min)
|
||||
5. Walk Slot Cards - States & Booking (~30 min)
|
||||
6. Real-Time Updates (~20 min)
|
||||
7. Bottom Tab Navigation (~10 min)
|
||||
8. Dev Mode Integration (~5 min)
|
||||
|
||||
**Total**: 8 sections, ~2 hours
|
||||
|
||||
**Approve this breakdown?** (Y/N)"
|
||||
|
||||
**User**: "Y"
|
||||
|
||||
**Freya**: "✅ Creating Work File: `work/3.1-Dog-Calendar-Work.yaml`
|
||||
|
||||
✅ Work File created!
|
||||
|
||||
**Ready to start Section 1?** (Y)"
|
||||
|
||||
**User**: "Y"
|
||||
|
||||
**Freya**: "🚀 Starting Section 1: Page Structure & Header..."
|
||||
|
||||
---
|
||||
|
||||
**Scenario initiation: 3-4 questions, 2-3 minutes**
|
||||
**Per-page building: Section approval, then build!** 🎯
|
||||
|
||||
@@ -0,0 +1,551 @@
|
||||
# SEO Validation Guide
|
||||
|
||||
**For:** WDS Agents performing Agentic Development
|
||||
**Purpose:** Verify SEO implementation against specification before presenting to user
|
||||
**When:** After a public page is built and previewable (browser or deployed)
|
||||
|
||||
---
|
||||
|
||||
## Core Principle
|
||||
|
||||
**Every public page must pass SEO validation before approval.**
|
||||
|
||||
The agent verifies all measurable SEO criteria using browser tools (Puppeteer, MCP browser-tools, or manual inspection). SEO failures caught during development cost minutes to fix. SEO failures caught after deployment cost rankings and traffic.
|
||||
|
||||
---
|
||||
|
||||
## When to Run SEO Validation
|
||||
|
||||
| Trigger | Action |
|
||||
|---------|--------|
|
||||
| Public page section complete (4c/4d) | Run SEO checks before presenting |
|
||||
| Full page implementation complete | Run complete SEO audit |
|
||||
| Pre-deployment review | Full validation against spec + project brief |
|
||||
| Post-deployment verification | Validate live URL matches specification |
|
||||
|
||||
---
|
||||
|
||||
## Reference Documents
|
||||
|
||||
Before running validation, gather:
|
||||
|
||||
1. **Page specification** — SEO & Search section (keywords, URL, headings, meta)
|
||||
2. **Project brief** — SEO Strategy section (page-keyword map, structured data plan)
|
||||
3. **SEO Strategy Guide** — `../../data/agent-guides/saga/seo-strategy-guide.md`
|
||||
|
||||
---
|
||||
|
||||
## SEO Validation Checklist
|
||||
|
||||
### Level 1: Critical (Must Pass)
|
||||
|
||||
These are the top errors found in real-world SEO audits. Failing any of these blocks approval.
|
||||
|
||||
#### 1.1 Page Title Tag
|
||||
|
||||
```
|
||||
Verify:
|
||||
- Title tag exists and is not empty
|
||||
- Length ≤ 60 characters (check each language)
|
||||
- Contains primary keyword
|
||||
- Contains brand name
|
||||
- Is unique (different from other pages)
|
||||
- Matches specification
|
||||
|
||||
Report:
|
||||
"Page title is 'Bilservice på Öland | Källa Fordonservice' (51 chars)
|
||||
— contains keyword 'bilservice', includes brand. ✓ Passes"
|
||||
|
||||
"Page title is 'Home' (4 chars)
|
||||
— too short, no keyword, no brand. ✗ Fails"
|
||||
```
|
||||
|
||||
#### 1.2 Meta Description
|
||||
|
||||
```
|
||||
Verify:
|
||||
- Meta description tag exists and is not empty
|
||||
- Length 150-160 characters
|
||||
- Contains primary keyword
|
||||
- Contains call-to-action
|
||||
- Matches specification
|
||||
|
||||
Report:
|
||||
"Meta description is 156 chars, contains 'bilservice Öland', ends with
|
||||
'Ring oss idag!' ✓ Passes"
|
||||
|
||||
"Meta description is missing. ✗ Fails — 80% of audited sites miss this"
|
||||
```
|
||||
|
||||
#### 1.3 H1 Heading
|
||||
|
||||
```
|
||||
Verify:
|
||||
- Exactly ONE <h1> tag on the page
|
||||
- Contains primary keyword (natural, not stuffed)
|
||||
- Is visible (not hidden)
|
||||
- Matches specification
|
||||
|
||||
Report:
|
||||
"Found 1 <h1>: 'Bilservice och reparationer på Öland'
|
||||
— contains keyword 'bilservice'. ✓ Passes"
|
||||
|
||||
"Found 0 <h1> tags. ✗ Fails — 75% of audited sites have H1 issues"
|
||||
|
||||
"Found 3 <h1> tags. ✗ Fails — only one H1 allowed per page"
|
||||
```
|
||||
|
||||
#### 1.4 Heading Hierarchy
|
||||
|
||||
```
|
||||
Verify:
|
||||
- Headings follow logical order (H1 → H2 → H3)
|
||||
- No skipped levels (H1 → H3 without H2)
|
||||
- No duplicate H1
|
||||
|
||||
Report:
|
||||
"Heading hierarchy: H1 → H2 → H3 → H2 → H3 ✓ Logical flow"
|
||||
|
||||
"Heading hierarchy: H1 → H3 (skipped H2) ✗ Fix: Change H3 to H2"
|
||||
```
|
||||
|
||||
#### 1.5 Image Alt Text
|
||||
|
||||
```
|
||||
Verify:
|
||||
- ALL images have alt attributes
|
||||
- Alt text is descriptive (not empty, not "image")
|
||||
- Alt text exists in all required languages
|
||||
- Decorative images have alt="" (empty, not missing)
|
||||
|
||||
Report:
|
||||
"Found 8 images:
|
||||
hero-image: alt='Källa Fordonservice verkstad...' ✓
|
||||
service-ac: alt='AC-service på personbil' ✓
|
||||
icon-phone: alt='' (decorative) ✓
|
||||
team-photo: alt attribute MISSING ✗
|
||||
|
||||
Result: 7/8 images pass. 1 missing alt text."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Level 2: Important (Should Pass)
|
||||
|
||||
#### 2.1 Open Graph / Social Sharing
|
||||
|
||||
```
|
||||
Verify:
|
||||
- og:title tag present
|
||||
- og:description tag present
|
||||
- og:image tag present (valid URL, image exists)
|
||||
- og:type tag present
|
||||
- twitter:card tag present
|
||||
|
||||
Report:
|
||||
"Social sharing tags:
|
||||
og:title: 'Bilservice Öland — Källa Fordonservice' ✓
|
||||
og:description: present (148 chars) ✓
|
||||
og:image: '/images/social/hem-social.jpg' ✓ (file exists)
|
||||
og:type: 'website' ✓
|
||||
twitter:card: 'summary_large_image' ✓
|
||||
All social tags present."
|
||||
|
||||
"Missing: og:image ✗ — 70% of audited sites miss social tags"
|
||||
```
|
||||
|
||||
#### 2.2 Structured Data (Schema.org)
|
||||
|
||||
```
|
||||
Verify:
|
||||
- JSON-LD script tag exists
|
||||
- Schema type matches project brief plan
|
||||
- Required properties present (name, address, phone for LocalBusiness)
|
||||
- JSON is valid (parseable)
|
||||
|
||||
Report:
|
||||
"Structured data found:
|
||||
@type: 'AutoRepair' ✓
|
||||
name: 'Källa Fordonservice' ✓
|
||||
address: complete ✓
|
||||
telephone: '+46485-27070' ✓
|
||||
openingHours: present ✓
|
||||
JSON-LD validates. ✓ Passes"
|
||||
|
||||
"No structured data found. ✗ Fails — spec requires LocalBusiness schema"
|
||||
```
|
||||
|
||||
#### 2.3 Internal Links
|
||||
|
||||
```
|
||||
Verify:
|
||||
- Page has at least 2 internal links to other pages
|
||||
- Links have descriptive anchor text (not "click here", "read more")
|
||||
- No broken internal links (404s)
|
||||
- No redirect chains (link → 301 → 301 → page)
|
||||
|
||||
Report:
|
||||
"Internal links found: 5
|
||||
'Läs mer om AC-service' → /ac-service ✓ Descriptive
|
||||
'Ring oss' → tel:+46485-27070 ✓ CTA
|
||||
'Klicka här' → /kontakt ✗ Non-descriptive anchor text
|
||||
|
||||
Result: 4/5 links pass."
|
||||
```
|
||||
|
||||
#### 2.4 URL / Slug
|
||||
|
||||
```
|
||||
Verify:
|
||||
- URL slug matches specification
|
||||
- Slug is lowercase
|
||||
- Uses hyphens (not underscores or spaces)
|
||||
- No special characters (ä, ö, å)
|
||||
- Keyword present in slug
|
||||
|
||||
Report:
|
||||
"URL slug: /ac-service ✓ Matches spec, lowercase, keyword present"
|
||||
|
||||
"URL slug: /Sida?id=42 ✗ Not descriptive, no keyword"
|
||||
```
|
||||
|
||||
#### 2.5 Canonical URL
|
||||
|
||||
```
|
||||
Verify:
|
||||
- <link rel="canonical"> tag present
|
||||
- Points to the correct URL (self-referencing)
|
||||
- One canonical per page
|
||||
|
||||
Report:
|
||||
"Canonical: <link rel='canonical' href='https://kallafordon.se/ac-service'> ✓"
|
||||
|
||||
"Canonical tag missing. ✗ Fails"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Level 3: Technical (Verify on Deployment)
|
||||
|
||||
These checks apply to the deployed/preview site, not the prototype.
|
||||
|
||||
#### 3.1 Performance
|
||||
|
||||
```
|
||||
Verify:
|
||||
- Total page weight < 3MB
|
||||
- Largest image < 400KB (hero) / < 200KB (other)
|
||||
- Time to First Byte (TTFB) < 1.5s
|
||||
- No uncompressed images (should be WebP or compressed JPEG)
|
||||
|
||||
Report:
|
||||
"Page weight: 1.8MB ✓ (target < 3MB)
|
||||
hero.jpg: 380KB ✓ (target < 400KB)
|
||||
team.jpg: 1.2MB ✗ (target < 200KB — compress!)
|
||||
icon.svg: 3KB ✓
|
||||
TTFB: 0.8s ✓ (target < 1.5s)"
|
||||
```
|
||||
|
||||
#### 3.2 robots.txt
|
||||
|
||||
```
|
||||
Verify:
|
||||
- robots.txt exists (not 404)
|
||||
- Allows crawling of public pages
|
||||
- References sitemap
|
||||
- Blocks admin/private pages
|
||||
|
||||
Report:
|
||||
"robots.txt: exists ✓
|
||||
Sitemap reference: present ✓
|
||||
Public pages: allowed ✓
|
||||
/wp-admin/: blocked ✓"
|
||||
```
|
||||
|
||||
#### 3.3 XML Sitemap
|
||||
|
||||
```
|
||||
Verify:
|
||||
- Sitemap exists at /sitemap.xml (or referenced location)
|
||||
- Contains all public pages
|
||||
- All URLs return 200 (no broken links)
|
||||
- Includes all language versions (if multilingual)
|
||||
|
||||
Report:
|
||||
"Sitemap: 32 URLs, all return 200 ✓
|
||||
Includes /en/ versions ✓
|
||||
Includes /de/ versions ✓"
|
||||
```
|
||||
|
||||
#### 3.4 hreflang Tags (Multilingual)
|
||||
|
||||
```
|
||||
Verify:
|
||||
- Each page declares all language alternates
|
||||
- x-default points to primary language
|
||||
- Tags are reciprocal (EN page links to SE, SE page links to EN)
|
||||
|
||||
Report:
|
||||
"hreflang tags on /ac-service:
|
||||
sv: /ac-service ✓
|
||||
en: /en/ac-service ✓
|
||||
de: /de/ac-service ✓
|
||||
x-default: /ac-service ✓
|
||||
All reciprocal. ✓ Passes"
|
||||
```
|
||||
|
||||
#### 3.5 Security Headers
|
||||
|
||||
```
|
||||
Verify:
|
||||
- HSTS present
|
||||
- X-Content-Type-Options present
|
||||
- X-Frame-Options present
|
||||
- Referrer-Policy present
|
||||
|
||||
Report:
|
||||
"Security headers: 2/6 present ✗
|
||||
HSTS: missing
|
||||
CSP: missing
|
||||
X-Content-Type-Options: 'nosniff' ✓
|
||||
X-Frame-Options: 'DENY' ✓
|
||||
Referrer-Policy: missing
|
||||
Permissions-Policy: missing
|
||||
|
||||
Note: 95% of audited sites fail security headers."
|
||||
```
|
||||
|
||||
#### 3.6 Favicon
|
||||
|
||||
```
|
||||
Verify:
|
||||
- Favicon exists (check <link rel="icon">)
|
||||
- Multiple sizes available (16x16, 32x32, 180x180)
|
||||
|
||||
Report:
|
||||
"Favicon: present ✓
|
||||
16x16: ✓
|
||||
32x32: ✓
|
||||
apple-touch-icon (180x180): ✓"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Verification with Puppeteer
|
||||
|
||||
### Automated SEO Check Script Pattern
|
||||
|
||||
```javascript
|
||||
// Navigate to page
|
||||
await page.goto(pageUrl, { waitUntil: 'networkidle0' });
|
||||
|
||||
// 1. Title tag
|
||||
const title = await page.title();
|
||||
console.log(`Title: "${title}" (${title.length} chars)`);
|
||||
|
||||
// 2. Meta description
|
||||
const metaDesc = await page.$eval(
|
||||
'meta[name="description"]',
|
||||
el => el.content
|
||||
).catch(() => null);
|
||||
console.log(`Meta desc: "${metaDesc}" (${metaDesc?.length || 0} chars)`);
|
||||
|
||||
// 3. H1 count and content
|
||||
const h1s = await page.$$eval('h1', els => els.map(el => el.textContent.trim()));
|
||||
console.log(`H1 tags: ${h1s.length} — "${h1s.join('", "')}"`);
|
||||
|
||||
// 4. Heading hierarchy
|
||||
const headings = await page.$$eval('h1,h2,h3,h4,h5,h6', els =>
|
||||
els.map(el => ({ tag: el.tagName, text: el.textContent.trim().substring(0, 50) }))
|
||||
);
|
||||
console.log('Heading hierarchy:', headings.map(h => h.tag).join(' → '));
|
||||
|
||||
// 5. Images without alt
|
||||
const imagesNoAlt = await page.$$eval('img', els =>
|
||||
els.filter(el => !el.hasAttribute('alt')).map(el => el.src)
|
||||
);
|
||||
console.log(`Images without alt: ${imagesNoAlt.length}`);
|
||||
|
||||
// 6. Open Graph tags
|
||||
const ogTags = await page.$$eval('meta[property^="og:"]', els =>
|
||||
els.map(el => ({ property: el.getAttribute('property'), content: el.content }))
|
||||
);
|
||||
console.log(`OG tags: ${ogTags.length}`, ogTags);
|
||||
|
||||
// 7. Structured data
|
||||
const jsonLd = await page.$$eval('script[type="application/ld+json"]', els =>
|
||||
els.map(el => JSON.parse(el.textContent))
|
||||
).catch(() => []);
|
||||
console.log(`Structured data: ${jsonLd.length} blocks`, jsonLd.map(j => j['@type']));
|
||||
|
||||
// 8. Canonical
|
||||
const canonical = await page.$eval('link[rel="canonical"]', el => el.href).catch(() => null);
|
||||
console.log(`Canonical: ${canonical || 'MISSING'}`);
|
||||
|
||||
// 9. Internal links
|
||||
const links = await page.$$eval('a[href]', els =>
|
||||
els.filter(el => el.href.startsWith(window.location.origin))
|
||||
.map(el => ({ text: el.textContent.trim().substring(0, 40), href: el.href }))
|
||||
);
|
||||
console.log(`Internal links: ${links.length}`);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Narration Pattern
|
||||
|
||||
Group results by severity and narrate clearly:
|
||||
|
||||
```
|
||||
## SEO Validation Report: {Page Name}
|
||||
|
||||
### Critical ✓/✗
|
||||
Title tag: "Bilservice Öland | Källa Fordonservice" (51 chars) ✓
|
||||
Meta description: "Komplett bilverkstad..." (156 chars) ✓
|
||||
H1: 1 found — "Bilservice och reparationer på Öland" ✓
|
||||
Heading hierarchy: H1 → H2 → H3 → H2 → H3 ✓
|
||||
Image alt text: 7/8 images have alt ✗ (team-photo missing)
|
||||
|
||||
### Important ✓/✗
|
||||
Open Graph: 5/5 tags present ✓
|
||||
Structured data: AutoRepair schema valid ✓
|
||||
Internal links: 5 found, 4/5 descriptive ✗ (1 "Klicka här")
|
||||
URL slug: /ac-service ✓
|
||||
Canonical: present, self-referencing ✓
|
||||
|
||||
### Technical (deployment only)
|
||||
Page weight: 1.8MB ✓
|
||||
Image sizes: 1 oversized (team.jpg 1.2MB) ✗
|
||||
Security headers: 2/6 ✗
|
||||
|
||||
### Summary
|
||||
Critical: 4/5 pass
|
||||
Important: 4/5 pass
|
||||
Technical: 1/3 pass
|
||||
|
||||
Action needed: Fix 1 missing alt text, 1 non-descriptive link,
|
||||
1 oversized image, 4 security headers.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Integration with Phase 5 Flow
|
||||
|
||||
```
|
||||
4a: Announce & Gather
|
||||
4b: Create Story File
|
||||
4c: Implement Section
|
||||
↓
|
||||
Agent runs Puppeteer verification (INLINE-TESTING-GUIDE)
|
||||
Agent runs SEO validation (THIS GUIDE) — for public pages only
|
||||
↓
|
||||
All pass? ── No ──→ Agent fixes, re-verifies (loop)
|
||||
│
|
||||
Yes
|
||||
↓
|
||||
4d: Present for Testing
|
||||
```
|
||||
|
||||
### Story File Addition
|
||||
|
||||
Add SEO criteria to the story file's Agent-Verifiable section:
|
||||
|
||||
```markdown
|
||||
### SEO Criteria (Public Pages)
|
||||
|
||||
| # | Criterion | Expected | How to Verify |
|
||||
|---|-----------|----------|---------------|
|
||||
| S1 | Title tag | "Bilservice Öland \| Källa" ≤60 chars | Read document.title |
|
||||
| S2 | Meta description | 150-160 chars, keyword present | Read meta[name=description] |
|
||||
| S3 | H1 count | Exactly 1 | Count h1 elements |
|
||||
| S4 | H1 keyword | Contains "bilservice" | Read h1 textContent |
|
||||
| S5 | Heading hierarchy | H1→H2→H3, no skips | Scan all headings |
|
||||
| S6 | Image alt coverage | 100% images have alt | Check img elements |
|
||||
| S7 | OG tags | og:title, og:description, og:image | Check meta[property^=og:] |
|
||||
| S8 | Internal links | ≥ 2, descriptive text | Count and check a[href] |
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Integration with Acceptance Testing
|
||||
|
||||
When creating test scenarios (Phase 4 [H] Handover / Phase 5 [T] Acceptance Testing), include SEO as a test category:
|
||||
|
||||
```yaml
|
||||
seo_checks:
|
||||
- id: 'SEO-001'
|
||||
name: 'Page title correct'
|
||||
verify:
|
||||
- 'Title tag matches specification'
|
||||
- 'Title ≤ 60 characters'
|
||||
- 'Contains primary keyword'
|
||||
|
||||
- id: 'SEO-002'
|
||||
name: 'Meta description correct'
|
||||
verify:
|
||||
- 'Meta description matches specification'
|
||||
- 'Length 150-160 characters'
|
||||
- 'Contains CTA'
|
||||
|
||||
- id: 'SEO-003'
|
||||
name: 'Heading structure valid'
|
||||
verify:
|
||||
- 'Exactly one H1'
|
||||
- 'No skipped heading levels'
|
||||
|
||||
- id: 'SEO-004'
|
||||
name: 'Image alt text complete'
|
||||
verify:
|
||||
- 'All content images have alt text'
|
||||
- 'Alt text in correct language'
|
||||
|
||||
- id: 'SEO-005'
|
||||
name: 'Structured data valid'
|
||||
verify:
|
||||
- 'JSON-LD present and parseable'
|
||||
- 'Schema type matches plan'
|
||||
- 'Required properties present'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
- **Never skip SEO validation on public pages** — It's not optional
|
||||
- **Never approve a page with missing alt text** — 85% of real sites fail this
|
||||
- **Never use "click here" or "read more" as link text** — Describe the destination
|
||||
- **Never have more than one H1** — One per page, always
|
||||
- **Never deploy without meta description** — 80% of sites miss this
|
||||
- **Never assume SEO "can be added later"** — It's specification, not decoration
|
||||
|
||||
---
|
||||
|
||||
## Common Fixes (From 44 Real-World Audits)
|
||||
|
||||
| Issue | Frequency | Fix Time | Fix |
|
||||
|-------|-----------|----------|-----|
|
||||
| Missing alt text | 85% | 1 min/image | Add descriptive alt attribute |
|
||||
| Missing meta description | 80% | 2 min/page | Add meta tag from spec |
|
||||
| H1 missing or wrong | 75% | 1 min | Add/fix h1 tag |
|
||||
| Missing OG tags | 70% | 3 min/page | Add og: meta tags from spec |
|
||||
| Missing structured data | 65% | 5 min/page | Add JSON-LD script |
|
||||
| Oversized images | 65% | 2 min/image | Compress + convert to WebP |
|
||||
| Non-descriptive links | 30% | 1 min/link | Rewrite anchor text |
|
||||
| Missing canonical | 40% | 1 min | Add link rel=canonical |
|
||||
|
||||
**Total estimated fix time for a typical page: 15-20 minutes**
|
||||
These are all preventable by validating during development.
|
||||
|
||||
---
|
||||
|
||||
## Related Resources
|
||||
|
||||
- **Inline Testing Guide:** `INLINE-TESTING-GUIDE.md` — General Puppeteer verification
|
||||
- **SEO Strategy Guide:** `../../data/agent-guides/saga/seo-strategy-guide.md` — SEO reference
|
||||
- **SEO Content Instructions:** `../../4-ux-design/templates/instructions/seo-content.instructions.md` — Spec-level SEO
|
||||
- **Specification Quality:** `../../data/agent-guides/freya/specification-quality.md` — Quality checklist
|
||||
- **Meta Content Guide:** `../../data/agent-guides/freya/meta-content-guide.md` — Meta tag details
|
||||
|
||||
---
|
||||
|
||||
*SEO validation during development = zero SEO issues at launch. Validate as you build.*
|
||||
@@ -0,0 +1,46 @@
|
||||
# Session Start Protocol
|
||||
|
||||
When starting or resuming a session, **always follow this sequence before implementing anything:**
|
||||
|
||||
## 1. Read the Dialog Document
|
||||
|
||||
Read the dialog file completely to understand:
|
||||
- What steps are done
|
||||
- What steps remain
|
||||
- Any blockers or change requests
|
||||
- Current context and decisions
|
||||
|
||||
## 2. Verify Plan Against Reality
|
||||
|
||||
**The plan may be outdated.** Check if:
|
||||
- Steps marked "To Do" have actually been implemented
|
||||
- Steps marked "Done" are truly complete
|
||||
- Numbering is sequential and accurate
|
||||
|
||||
If the plan is outdated → Update it before proceeding.
|
||||
|
||||
## 3. Present Current Status
|
||||
|
||||
Summarize for the designer:
|
||||
- What's done (with step numbers)
|
||||
- What's remaining (with step numbers)
|
||||
- Any change requests pending
|
||||
|
||||
## 4. Before Implementing a Step
|
||||
|
||||
**Always check the specification/sketches first:**
|
||||
|
||||
```
|
||||
Agent: "Before implementing step 20, let me check the sketches..."
|
||||
Agent: "I see this requires a nested drawer pattern, not inline buttons.
|
||||
Should I break this into sub-steps?"
|
||||
```
|
||||
|
||||
This prevents building the wrong thing and wasting effort.
|
||||
|
||||
## Why This Matters
|
||||
|
||||
Sessions can be interrupted. Context can be lost. The dialog document survives — but only if it's kept accurate. This protocol ensures:
|
||||
- No duplicate work (re-implementing what exists)
|
||||
- No missed work (skipping what's actually needed)
|
||||
- Correct understanding of requirements before implementation
|
||||
Reference in New Issue
Block a user