Wds 5 Agentic Development

Follow the instructions in ./workflow.md.

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

---

📊 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

Interactive Prototype Creation Guide

For: Freya WDS Designer Agent Purpose: Step-by-step guide to creating production-quality interactive prototypes Based on: Dog Week proven patterns

---

🎯 When to Create Interactive Prototypes

Create interactive prototypes when:

✅ Complex interactions - Multi-step forms, drag-and-drop, animations ✅ User testing needed - Need real usability feedback ✅ Developer handoff - Developers need working reference ✅ Stakeholder demo - Need to show actual functionality ✅ Custom components - Non-standard UI patterns (Swedish calendar, etc.)

Skip prototypes when: ❌ Simple static pages ❌ Standard CRUD forms (specs are enough) ❌ Time-constrained projects (use Figma/Excalidraw instead)

---

📁 Step 1: Set Up File Structure

Create Folder Structure

docs/C-UX-Scenarios/[Scenario-Name]/[Page-Number]-[Page-Name]/
├── [Page-Number]-[Page-Name].md          ← Specification
├── Sketches/
│   └── [sketch-files].jpg
└── Frontend/                              ← PROTOTYPE FOLDER
    ├── [Page-Number]-[Page-Name]-Preview.html
    ├── [Page-Number]-[Page-Name]-Preview.css
    ├── [Page-Number]-[Page-Name]-Preview.js
    └── prototype-api.js                   ← Copy from existing

Example (Add Dog page):

docs/C-UX-Scenarios/01-Customer-Onboarding/1.6-Add-Dog/
├── 1.6-Add-Dog.md
├── Sketches/
│   └── add-dog-sketch.jpg
└── Frontend/
    ├── 1.6-Add-Dog-Preview.html
    ├── 1.6-Add-Dog-Preview.css
    ├── 1.6-Add-Dog-Preview.js
    └── prototype-api.js

---

🌍 Multi-Language Support

Hardcoded Translations (Recommended for Prototypes)

Best practice: Use hardcoded translations directly in HTML/JS for readability.

Why?

• ✅ Code is immediately readable
• ✅ No separate translation files to manage
• ✅ Easy to see what user sees
• ✅ Simple language switcher if needed
• ✅ Faster prototyping
• ✅ No secrets in translations anyway

Simple Language Switcher

// Define translations inline
const strings = {
  sv: { 
    bookWalk: 'Boka promenad', 
    cancel: 'Avbryt',
    save: 'Spara',
    delete: 'Ta bort'
  },
  en: { 
    bookWalk: 'Book walk', 
    cancel: 'Cancel',
    save: 'Save',
    delete: 'Delete'
  }
};

let currentLang = 'sv'; // or get from localStorage

// Update UI text
function updateLanguage(lang) {
  currentLang = lang;
  document.querySelectorAll('[data-i18n]').forEach(el => {
    const key = el.dataset.i18n;
    el.textContent = strings[lang][key];
  });
  localStorage.setItem('language', lang);
}

// Language toggle
document.getElementById('lang-toggle').addEventListener('click', () => {
  const newLang = currentLang === 'sv' ? 'en' : 'sv';
  updateLanguage(newLang);
});

// Initialize on load
document.addEventListener('DOMContentLoaded', () => {
  const savedLang = localStorage.getItem('language') || 'sv';
  updateLanguage(savedLang);
});

HTML with Language Support

<!-- Option 1: data-i18n attribute (dynamic) -->
<button data-i18n="bookWalk" data-object-id="calendar-book-btn">
  Boka promenad
</button>

<!-- Option 2: Hardcoded with comment (simple) -->
<button data-object-id="calendar-book-btn">
  Boka promenad <!-- Book walk -->
</button>

<!-- Language toggle -->
<button id="lang-toggle" class="language-toggle">
  🇸🇪 / 🇬🇧
</button>

When to Include Language Switching

Include if:

• Project defines multiple languages in project brief
• Stakeholders need to see different languages
• User testing requires language options

Skip if:

• Single language project
• Prototype for internal team only
• Time-constrained

---

📝 Step 2: Create HTML Structure

HTML Template

<!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>

    <!-- Google Fonts (if using Inter) -->
    <link rel="preconnect" href="https://fonts.googleapis.com" />
    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet" />

    <!-- Page Styles -->
    <link rel="stylesheet" href="[Page-Number]-[Page-Name]-Preview.css" />
  </head>
  <body>
    <!-- Header -->
    <header class="page-header">
      <button id="[page]-header-back" data-object-id="[page]-header-back" onclick="handleBack()">← Back</button>

      <h1 id="[page]-header-title" data-object-id="[page]-header-title">[Page Title]</h1>

      <!-- Optional: Language selector, actions, etc. -->
    </header>

    <!-- Main Content -->
    <main class="page-content">
      <form id="mainForm" class="form" onsubmit="handleSubmit(event)">
        <!-- Form fields here -->

        <!-- Example Input Field -->
        <div class="input-container">
          <input
            type="text"
            id="[page]-input-[field]"
            data-object-id="[page]-input-[field]"
            name="[fieldName]"
            placeholder="[Placeholder text]"
            class="internal-input"
            required
          />
          <p class="text-sm text-red-600 hidden" id="[field]Error"></p>
        </div>

        <!-- Submit Button -->
        <button type="submit" id="[page]-button-submit" data-object-id="[page]-button-submit" class="submit-button">
          <span id="submitButtonText">[Button Text]</span>
          <svg id="submitButtonSpinner" class="hidden spinner">
            <!-- Spinner SVG -->
          </svg>
        </button>
      </form>
    </main>

    <!-- Optional: Modals -->
    <div id="modal" class="modal-overlay hidden">
      <!-- Modal content -->
    </div>

    <!-- Optional: Toast Notification -->
    <div id="toast" class="toast hidden">
      <span id="toastMessage"></span>
    </div>

    <!-- Scripts -->
    <script src="prototype-api.js"></script>
    <script src="[Page-Number]-[Page-Name]-Preview.js"></script>
  </body>
</html>

Critical HTML Rules

1. Always include Object IDs on interactive elements 2. Use semantic HTML (header, main, nav, section) 3. Include aria labels for accessibility 4. Mobile viewport meta tag is mandatory 5. Load prototype-api.js first, then page-specific JS

---

🎨 Step 3: Write CSS Styles

CSS Template

/* ============================================================================
   [Page Number] [Page Name] - Prototype Styles
   Project: [Project Name]
   ============================================================================ */

/* Reset & Base Styles */
* {
  margin: 0;
  padding: 0;
  box-sizing: border-box;
}

body {
  font-family:
    'Inter',
    -apple-system,
    BlinkMacSystemFont,
    sans-serif;
  font-size: 16px;
  line-height: 1.5;
  color: var(--gray-900);
  background: var(--gray-50);
  -webkit-font-smoothing: antialiased;
}

/* CSS Variables (Design Tokens) */
:root {
  /* Colors */
  --primary: #2563eb;
  --primary-hover: #1d4ed8;
  --success: #10b981;
  --error: #ef4444;

  --gray-50: #f9fafb;
  --gray-100: #f3f4f6;
  --gray-200: #e5e7eb;
  --gray-300: #d1d5db;
  --gray-600: #4b5563;
  --gray-700: #374151;
  --gray-900: #111827;

  /* Spacing */
  --spacing-sm: 0.5rem;
  --spacing-md: 1rem;
  --spacing-lg: 1.5rem;
  --spacing-xl: 2rem;

  /* Border Radius */
  --radius-sm: 0.375rem;
  --radius-md: 0.5rem;
  --radius-lg: 0.75rem;

  /* Shadows */
  --shadow-sm: 0 1px 2px 0 rgba(0, 0, 0, 0.05);
  --shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
}

/* ============================================================================
   Layout
   ============================================================================ */

.page-header {
  background: white;
  border-bottom: 1px solid var(--gray-200);
  padding: 1rem;
  display: flex;
  align-items: center;
  justify-content: space-between;
}

.page-content {
  max-width: 640px;
  margin: 0 auto;
  padding: var(--spacing-lg);
}

/* ============================================================================
   Form Components
   ============================================================================ */

.form {
  display: flex;
  flex-direction: column;
  gap: var(--spacing-md);
}

.input-container {
  display: flex;
  flex-direction: column;
  gap: var(--spacing-sm);
}

.internal-input {
  width: 100%;
  padding: 0.75rem;
  border: 1px solid var(--gray-300);
  border-radius: var(--radius-md);
  font-size: 1rem;
  transition: all 0.2s;
}

.internal-input:focus {
  outline: none;
  border-color: var(--primary);
  box-shadow: 0 0 0 3px rgba(37, 99, 235, 0.1);
}

.internal-input.error {
  border-color: var(--error);
}

/* ============================================================================
   Buttons
   ============================================================================ */

.submit-button {
  width: 100%;
  padding: 0.75rem 1.5rem;
  background: var(--primary);
  color: white;
  border: none;
  border-radius: var(--radius-md);
  font-size: 1rem;
  font-weight: 600;
  cursor: pointer;
  transition: background 0.2s;
  display: flex;
  align-items: center;
  justify-content: center;
  gap: 0.5rem;
  min-height: 44px; /* Mobile touch target */
}

.submit-button:hover {
  background: var(--primary-hover);
}

.submit-button:disabled {
  opacity: 0.5;
  cursor: not-allowed;
}

/* ============================================================================
   Utility Classes
   ============================================================================ */

.hidden {
  display: none !important;
}

.text-red-600 {
  color: var(--error);
}

.text-sm {
  font-size: 0.875rem;
}

/* Spinner Animation */
.spinner {
  animation: spin 1s linear infinite;
}

@keyframes spin {
  from {
    transform: rotate(0deg);
  }
  to {
    transform: rotate(360deg);
  }
}

/* ============================================================================
   Modal
   ============================================================================ */

.modal-overlay {
  position: fixed;
  inset: 0;
  background: rgba(0, 0, 0, 0.5);
  display: flex;
  align-items: center;
  justify-content: center;
  z-index: 1000;
}

.modal-content {
  background: white;
  border-radius: var(--radius-lg);
  padding: var(--spacing-xl);
  max-width: 90%;
  max-height: 90vh;
  overflow-y: auto;
}

/* ============================================================================
   Toast Notification
   ============================================================================ */

.toast {
  position: fixed;
  bottom: 2rem;
  left: 50%;
  transform: translateX(-50%);
  background: var(--gray-900);
  color: white;
  padding: 1rem 1.5rem;
  border-radius: var(--radius-lg);
  box-shadow: var(--shadow-md);
  z-index: 1001;
  animation: slideUp 0.3s ease-out;
}

@keyframes slideUp {
  from {
    transform: translateX(-50%) translateY(100%);
    opacity: 0;
  }
  to {
    transform: translateX(-50%) translateY(0);
    opacity: 1;
  }
}

/* ============================================================================
   Responsive Design
   ============================================================================ */

@media (min-width: 768px) {
  .page-content {
    padding: var(--spacing-xl);
  }
}

CSS Best Practices

1. Use CSS Variables for colors, spacing, etc. 2. Mobile-first approach (base styles for mobile, media queries for larger) 3. Organize by sections with clear comments 4. Follow naming conventions (BEM or utility-based) 5. Include animations (subtle, performance-conscious)

---

⚙️ Step 4: Write JavaScript Logic

JavaScript Template

/**
 * [Page Number] [Page Name] - Interactive Prototype
 * Project: [Project Name]
 *
 * This prototype demonstrates [key functionality].
 */

// ============================================================================
// STATE MANAGEMENT
// ============================================================================

let formData = {
  // Initialize form state
};

// ============================================================================
// INITIALIZATION
// ============================================================================

document.addEventListener('DOMContentLoaded', async () => {
  console.log('📄 [Page Name] prototype loaded');

  // Load saved data (if any)
  await loadSavedData();

  // Initialize form listeners
  initializeFormListeners();

  // Load language preference
  applyLanguage(DogWeekAPI.getLanguagePreference());
});

// ============================================================================
// DATA LOADING
// ============================================================================

async function loadSavedData() {
  try {
    const user = await DogWeekAPI.getUser();
    if (user) {
      console.log('👤 User loaded:', user.firstName);
      // Pre-fill form if needed
    }
  } catch (error) {
    console.error('❌ Error loading data:', error);
  }
}

// ============================================================================
// FORM HANDLING
// ============================================================================

function initializeFormListeners() {
  const form = document.getElementById('mainForm');

  // Real-time validation
  form.querySelectorAll('input').forEach(input => {
    input.addEventListener('blur', () => validateField(input));
    input.addEventListener('input', () => clearError(input));
  });
}

async function handleSubmit(event) {
  event.preventDefault();

  // Validate all fields
  if (!validateForm()) {
    return;
  }

  // Show loading state
  setLoadingState(true);

  try {
    // Collect form data
    const formData = new FormData(event.target);
    const data = Object.fromEntries(formData.entries());

    // Call API (prototype or production)
    const result = await DogWeekAPI.[relevantMethod](data);

    console.log('✅ Success:', result);

    // Show success feedback
    showSuccessToast('[Success message]');

    // Navigate to next page (after delay)
    setTimeout(() => {
      navigateToNextPage();
    }, 1500);

  } catch (error) {
    console.error('❌ Error:', error);
    showErrorBanner(error.message);
  } finally {
    setLoadingState(false);
  }
}

// ============================================================================
// VALIDATION
// ============================================================================

function validateForm() {
  let isValid = true;

  const fields = [
    { id: 'fieldName', validator: validateRequired, message: 'Field is required' },
    // Add more fields
  ];

  fields.forEach(field => {
    const input = document.getElementById(field.id);
    if (!field.validator(input.value)) {
      showFieldError(field.id, field.message);
      isValid = false;
    }
  });

  return isValid;
}

function validateField(input) {
  const value = input.value.trim();
  const fieldName = input.name;

  // Example validations
  if (input.required && !value) {
    showFieldError(fieldName, 'This field is required');
    return false;
  }

  if (input.type === 'email' && !isValidEmail(value)) {
    showFieldError(fieldName, 'Please enter a valid email');
    return false;
  }

  clearError(input);
  return true;
}

function validateRequired(value) {
  return value && value.trim().length > 0;
}

function isValidEmail(email) {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
}

// ============================================================================
// UI FEEDBACK
// ============================================================================

function showFieldError(fieldName, message) {
  const errorElement = document.getElementById(`${fieldName}Error`);
  const inputElement = document.getElementById(fieldName);

  if (errorElement) {
    errorElement.textContent = message;
    errorElement.classList.remove('hidden');
  }

  if (inputElement) {
    inputElement.classList.add('error');
  }
}

function clearError(input) {
  const fieldName = input.name || input.id;
  const errorElement = document.getElementById(`${fieldName}Error`);

  if (errorElement) {
    errorElement.classList.add('hidden');
  }

  input.classList.remove('error');
}

function setLoadingState(isLoading) {
  const submitBtn = document.getElementById('[page]-button-submit');
  const submitText = document.getElementById('submitButtonText');
  const submitSpinner = document.getElementById('submitButtonSpinner');

  submitBtn.disabled = isLoading;

  if (isLoading) {
    submitText.classList.add('hidden');
    submitSpinner.classList.remove('hidden');
  } else {
    submitText.classList.remove('hidden');
    submitSpinner.classList.add('hidden');
  }
}

function showSuccessToast(message) {
  const toast = document.getElementById('toast');
  const toastMessage = document.getElementById('toastMessage');

  toastMessage.textContent = message;
  toast.classList.remove('hidden');

  setTimeout(() => {
    toast.classList.add('hidden');
  }, 3000);
}

function showErrorBanner(message) {
  const errorBanner = document.getElementById('networkError');
  const errorMessage = document.getElementById('networkErrorMessage');

  errorMessage.textContent = message;
  errorBanner.classList.remove('hidden');

  setTimeout(() => {
    errorBanner.classList.add('hidden');
  }, 5000);
}

// ============================================================================
// NAVIGATION
// ============================================================================

function handleBack() {
  console.log('🔙 Navigating back');
  window.history.back();
  // OR: window.location.href = '../[previous-page]/Frontend/[previous-page]-Preview.html';
}

function navigateToNextPage() {
  console.log('➡️ Navigating to next page');
  window.location.href = '../[next-page]/Frontend/[next-page]-Preview.html';
}

// ============================================================================
// MULTI-LANGUAGE SUPPORT (Optional)
// ============================================================================

const translations = {
  se: {
    pageTitle: '[Swedish Title]',
    submitButton: '[Swedish Submit]',
    // ... all UI text
  },
  en: {
    pageTitle: '[English Title]',
    submitButton: '[English Submit]',
    // ...
  }
};

function applyLanguage(lang) {
  const t = translations[lang];

  // Update all text elements
  Object.keys(t).forEach(key => {
    const element = document.getElementById(key);
    if (element) {
      element.textContent = t[key];
    }
  });

  // Save preference
  DogWeekAPI.setLanguagePreference(lang);
}

JavaScript Best Practices

1. Use async/await for API calls 2. Console.log key actions (with emojis for visibility) 3. Handle errors gracefully (try/catch) 4. Validate before submit 5. Show loading states 6. Always reset UI state (finally blocks)

---

🔌 Step 5: Integrate with Prototype API

Common API Patterns

1. Get Current User

const user = await DogWeekAPI.getUser();
if (user) {
  console.log('Logged in as:', user.firstName);
}

2. Create/Update User Profile

const userData = {
  firstName: 'Patrick',
  lastName: 'Parent',
  email: 'patrick@example.com',
  phoneNumber: '+46701234567',
};

const user = await DogWeekAPI.createUserProfile(userData);

3. Create Family

const familyData = {
  name: 'The Johnsons',
  description: 'Our lovely dog family',
  location: 'Stockholm, Sweden',
};

const family = await DogWeekAPI.createFamily(familyData);

4. Add Dog

const dogData = {
  name: 'Rufus',
  breed: 'Golden Retriever',
  gender: 'male',
  birthDate: '2020-05-15',
  color: 'Golden',
  picture: '[base64-image-data]',
};

const dog = await DogWeekAPI.addDog(dogData);

5. Get Family Data

const family = await DogWeekAPI.getActiveFamily();
const dogs = await DogWeekAPI.getFamilyDogs();
const members = await DogWeekAPI.getFamilyMembers();

---

✅ Step 6: Testing Checklist

Before Considering Prototype "Done"

Functionality Testing

• [ ] All form fields work
• [ ] Validation shows errors correctly
• [ ] Submit button works
• [ ] Loading states display
• [ ] Success feedback shows
• [ ] Error handling works
• [ ] Navigation works (back, next)
• [ ] Data persists (reload page)

Mobile Testing

• [ ] Viewport is 375px wide (iPhone SE)
• [ ] All tap targets min 44x44px
• [ ] Text is readable (min 16px)
• [ ] No horizontal scroll
• [ ] Inputs don't cause zoom (iOS)
• [ ] Touch gestures work (if applicable)

Code Quality

• [ ] All Object IDs present
• [ ] Console logs helpful (not excessive)
• [ ] No console errors
• [ ] CSS organized with comments
• [ ] JS functions documented
• [ ] No hardcoded values (use variables)

Accessibility

• [ ] Keyboard navigation works
• [ ] Form labels present
• [ ] Error messages clear
• [ ] Focus states visible
• [ ] Color contrast sufficient

Documentation

• [ ] Comments explain complex logic
• [ ] TODOs noted for Supabase migration
• [ ] Known limitations documented
• [ ] README included (if needed)

---

📚 Common Patterns Library

Pattern 1: Image Upload with Crop

Use When: User profile pictures, dog photos, etc.

Files Needed:

• image-crop.js (copy from existing prototype)
• Modal HTML in main file
• CSS for crop interface

Implementation:

function handlePictureUpload() {
  document.getElementById('pictureInput').click();
}

document.getElementById('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);
  }
});

---

Pattern 2: Searchable Dropdown (Combobox)

Use When: Large lists (breeds, countries, etc.)

HTML:

<button type="button" onclick="toggleDropdown()">
  <span id="selectedValue">Select...</span>
</button>

<div id="dropdown" class="dropdown hidden">
  <input type="text" id="searchInput" oninput="filterOptions()" placeholder="Search..." />
  <div id="optionsList"></div>
</div>

JavaScript:

function filterOptions() {
  const query = document.getElementById('searchInput').value.toLowerCase();
  const filtered = allOptions.filter((opt) => opt.toLowerCase().includes(query));
  renderOptions(filtered);
}

---

Pattern 3: Multi-Language Toggle

Use When: International products

HTML:

<select id="languageSelector" onchange="switchLanguage(this.value)">
  <option value="se">SE</option>
  <option value="en">EN</option>
</select>

JavaScript:

function switchLanguage(lang) {
  applyLanguage(lang);
  DogWeekAPI.setLanguagePreference(lang);
}

---

Pattern 4: Loading State

Use During: API calls, navigation, heavy processing

Implementation:

function setLoadingState(isLoading) {
  const btn = document.getElementById('submitButton');
  const text = btn.querySelector('.text');
  const spinner = btn.querySelector('.spinner');

  btn.disabled = isLoading;
  text.classList.toggle('hidden', isLoading);
  spinner.classList.toggle('hidden', !isLoading);
}

// Usage
try {
  setLoadingState(true);
  await DogWeekAPI.someOperation();
} finally {
  setLoadingState(false);
}

---

Pattern 5: Toast Notification

Use For: Success messages, simple errors

Implementation:

function showToast(message, duration = 3000) {
  const toast = document.getElementById('toast');
  toast.textContent = message;
  toast.classList.remove('hidden');

  setTimeout(() => {
    toast.classList.add('hidden');
  }, duration);
}

// Usage
showToast('Dog added successfully! ✓');

---

🚨 Common Pitfalls to Avoid

1. Forgetting Object IDs

❌ Wrong: <button id="submitBtn">Submit</button> ✅ Right: <button id="page-button-submit" data-object-id="page-button-submit">Submit</button>

2. Not Handling Loading States

❌ Wrong: Submit button stays active during API call ✅ Right: Disable button, show spinner, prevent double-submit

3. Hardcoded Values

❌ Wrong: background-color: #2563eb; ✅ Right: background-color: var(--primary);

4. No Error Handling

❌ Wrong: const result = await API.call(); ✅ Right: try { const result = await API.call(); } catch (error) { showError(error); }

5. Desktop-Only Design

❌ Wrong: Hover states, small tap targets ✅ Right: Touch-friendly, min 44px targets

6. Missing Validation Feedback

❌ Wrong: Form just doesn't submit ✅ Right: Show specific error messages per field

7. No Console Logging

❌ Wrong: Silent operations ✅ Right: console.log('✅ Dog added:', dog.name);

---

🎓 Learning Path

For New Prototype Creators

Week 1: Study existing prototypes

• Read PROTOTYPE-ANALYSIS.md
• Open 1.2 Sign In, examine code
• Test in mobile viewport
• Check console logs

Week 2: Modify existing prototype

• Copy 1.3 Profile Setup
• Change field names
• Update validation rules
• Test thoroughly

Week 3: Create simple prototype from scratch

• Pick simple page (static content + form)
• Follow this guide step-by-step
• Get code review

Week 4: Create complex prototype

• Multi-step flow
• Custom components
• Advanced interactions

---

📖 Quick Reference

Object ID Naming Convention

[page]-[section]-[action]

Examples:
- add-dog-input-name
- profile-avatar-upload
- calendar-week-next
- signin-button-google

File Naming Convention

[Page-Number]-[Page-Name]-Preview.[ext]

Examples:
- 1.2-Sign-In-Preview.html
- 3.1-Dog-Calendar-Booking-Preview.css
- 1.6-Add-Dog-Preview.js

Required Meta Tag

<meta name="viewport" content="width=device-width, initial-scale=1.0" />

Minimum Touch Target Size

44px × 44px (Apple Human Interface Guidelines)
48px × 48px (Material Design)

---

✨ Final Tips

1. Start simple - Get basic version working first 2. Test early - Open in mobile viewport immediately 3. Console log everything - Makes debugging easier 4. Copy working patterns - Don't reinvent the wheel 5. Ask for help - Reference existing prototypes 6. Document as you go - Comments save time later 7. Test on real devices - Emulator != real thing

---

Remember: A good interactive prototype is:

• ✅ Functional - Actually works
• ✅ Mobile-optimized - Touch-friendly
• ✅ Well-documented - Code is clear
• ✅ Developer-ready - Easy to extract
• ✅ User-testable - Can get real feedback

Now go create amazing prototypes! 🚀

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:

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:

| # | 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.

User Feedback Protocol

CRITICAL: Never implement feedback without first classifying it and stating when it should be addressed.

Feedback Types

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.

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.

Agentic Development - File Index

Location: src/workflows/wds-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

---

All templates and micro-step instructions are ready!

Next step: Activate Freya and follow workflow.md → steps-p/1-prototype-setup.md

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

The agent never asks the user to verify something it can measure itself.

---

When to Test

---

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:

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

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.

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

---

🏗️ 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

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

config: {
  mode: 'prototype', // or 'production'
  supabaseUrl: null,
  supabaseKey: null
}

Benefit: Same calling code works in prototype and production

2. Async/Await Pattern

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

_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

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:

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:

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:

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:

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:

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:

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

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

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

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:

<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

<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

:root {
  --dog-week-primary: #2563eb;
  --dog-week-primary-hover: #1d4ed8;
  --dog-week-success: #10b981;
  --gray-50: #f9fafb;
  --gray-900: #111827;
}

Usage:

.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

/* 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:

const user = await DogWeekAPI.createUserProfile({
  firstName: 'Patrick',
  lastName: 'Parent',
  email: 'patrick@example.com',
});

Production Code (minimal changes):

// 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

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

<!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:

<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

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:

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! 🎯

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

---

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

// 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:

### 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:

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)

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: ../../wds-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.

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

Issue Templates

Templates for creating issue tickets and test reports.

---

Issue File Template

File: issues/ISS-XXX-description.md

# Issue: [Short Description]

**ID:** ISS-XXX
**Severity:** [Critical | High | Medium | Low]
**Status:** Open
**Delivery:** DD-XXX
**Test:** TS-XXX, Check: [Test ID]
**Created:** [Date]
**Assigned:** BMad Developer

## Description

[Clear description of the problem]

## Expected

[What should happen according to design]

## Actual

[What actually happens]

## Impact

[Why this matters - user impact, business impact]

## Design Reference

- Design Spec: [Path to specification]
- Design Token: [Path to token if applicable]
- Component Spec: [Path to component spec if applicable]

## Steps to Reproduce

1. [Step 1]
2. [Step 2]
3. [Step 3]

## Screenshot/Video

![Issue screenshot](../testing/DD-XXX/screenshots/ISS-XXX.png)

## Recommendation

[How to fix this - be specific]

## Related Issues

- [Link to related issues if any]

---

**Priority for fix:** [Next release | This release | Future]

---

Severity Levels

---

Test Report Template

File: testing/DD-XXX/TR-XXX-[flow-name].md

# Test Report: DD-XXX [Flow Name]

**Report ID:** TR-XXX
**Date:** [Date]
**Tester:** [Your name]
**Build:** [Version]
**Device:** [Device/Browser]
**Status:** PASS / FAIL

## Summary

**Overall Result:** [PASS/FAIL]
**Total Issues:** [X]
**High Severity:** [X]
**Blocking:** [Yes/No]

## Test Coverage

| Category | Passed | Failed | Total |
|----------|--------|--------|-------|
| Happy Path | X | X | X |
| Error States | X | X | X |
| Edge Cases | X | X | X |
| Design System | X | X | X |
| Accessibility | X | X | X |
| **Total** | X | X | X |

## Issues Found

| ID | Severity | Description | Status |
|----|----------|-------------|--------|
| ISS-001 | High | [Description] | Open |
| ISS-002 | Medium | [Description] | Open |

## Sign-Off Recommendation

- [ ] Ready for production
- [x] Needs fixes before production

## Next Steps

1. [Next step 1]
2. [Next step 2]

## Attachments

- Screen recordings: [List]
- Screenshots: [List]
- Issue files: [List]

---

Retest Report Template

# Retest Report: DD-XXX

**Date:** [Date]
**Build:** [New version]
**Previous Build:** [Previous version]

## Fixed Issues Verification

| ID | Description | Fixed? |
|----|-------------|--------|
| ISS-001 | [Description] | ✓ Yes |
| ISS-002 | [Description] | ✓ Yes |

## Regression Check

- [ ] Happy path still works
- [ ] Error handling still works
- [ ] No new issues introduced

## Result

**Retest Status:** PASS / FAIL

## Recommendation

[Approve for production / Need more fixes]

---

Sign-Off Document Template

# Sign-Off: DD-XXX [Flow Name]

**Date:** [Date]
**Approved By:** [Your name], WDS UX Expert

## Approval Summary

I certify that Design Delivery DD-XXX has been:

- ✅ Tested against all test scenarios
- ✅ Verified against design specifications
- ✅ Validated for accessibility requirements
- ✅ Confirmed ready for production

## Test Summary

- **Total Tests:** X
- **Passed:** X/X (XX%)
- **Issues Found:** X
- **Issues Fixed:** X
- **Test Iterations:** X

## Quality Gate

- [x] All Critical issues fixed
- [x] All High severity issues fixed
- [x] Medium/Low issues accepted or deferred
- [x] Design system compliance > 95%
- [x] No accessibility blockers

## Approved

**Signature:** [Your name]
**Date:** [Date]
**Role:** WDS UX Expert

---

_This feature is approved for production deployment._

Test Result Templates

Templates for documenting test execution results.

---

Test Step Documentation Template

## [Test-ID]: [Test Name]

### Step X: [Step Name]

- Action: [What was done]
- Expected: [What should happen]
- Actual: [What actually happened]
- Result: PASS/FAIL
- Issue: [If FAIL, describe the issue]
- Screenshot: [filename if FAIL]

---

Happy Path Results Template

# Happy Path Test Results

## HP-001: [Test Name]

- Status: PASS/FAIL
- Steps: X total
- Passed: X/X (XX%)
- Failed: X/X (XX%)
- Issues: X ([brief description])
- Duration: X minutes X seconds
- Recording: happy-path-HP-001.mov

## Summary

- Total Tests: X
- Passed: X/X (XX%)
- Failed: X/X (XX%)
- Total Issues: X

---

Error State Results Template

# Error State Test Results

## ES-001: [Error Scenario Name]

- Status: PASS/FAIL
- Issue: [Brief description if FAIL]
- Severity: Critical/High/Medium/Low

## Summary

- Total Tests: X
- Passed: X/X (XX%)
- Failed: X/X (XX%)
- Total Issues: X

---

Edge Case Results Template

# Edge Case Test Results

## EC-001: [Edge Case Name]

- Status: PASS/FAIL
- Issue: [Brief description if FAIL]
- Severity: Critical/High/Medium/Low

## Summary

- Total Tests: X
- Passed: X/X (XX%)
- Failed: X/X (XX%)
- Total Issues: X

---

Design System Validation Template

# Design System Validation Results

## DS-001: [Component Type]

### [Component Instance]: "[Label]"

- Height: Xpx ✓/✗
- Background: #XXXXXX ✓/✗ (Expected: #XXXXXX)
- Text: #XXXXXX ✓/✗
- Typography: Xpx, weight ✓/✗
- Border radius: Xpx ✓/✗
- Padding: Xpx Xpx ✓/✗
- Result: PASS/FAIL ([issue if FAIL])

## Summary

- Total Components: X types
- Compliant: X/X (XX%)
- Non-compliant: X/X (XX%)
- Target: >95% compliance
- Result: PASS/FAIL

---

Accessibility Results Template

# Accessibility Test Results

## A11Y-001: Screen Reader Navigation

- Status: PASS/PARTIAL PASS/FAIL
- Issues: X ([brief description])
- Severity: Critical/High/Medium/Low

## A11Y-002: Color Contrast

- Body text: X:1 ✓/✗ (min 4.5:1)
- Button text: X:1 ✓/✗ (min 4.5:1)
- Error text: X:1 ✓/✗ (min 4.5:1)
- Link text: X:1 ✓/✗ (min 4.5:1)
- Result: PASS/FAIL

## A11Y-003: Touch Targets

- Buttons: Xpx height ✓/✗ (min 44px)
- Input fields: Xpx height ✓/✗ (min 44px)
- Text links: Xpx height ✓/✗ (min 44px)
- Spacing: Xpx ✓/✗ (min 8px)
- Result: PASS/FAIL

## Summary

- Total Tests: X
- Passed: X/X (XX%)
- Partial: X/X (XX%)
- Failed: X/X (XX%)
- Total Issues: X

---

Overall Test Summary Template

# Test Summary: DD-XXX [Flow Name]

**Date:** [Date]
**Tester:** [Your name]
**Build:** [Version]
**Device:** [Device/Browser]

## Overall Result

**Status:** PASS/FAIL ([X] issues found, [X] high severity)

## Test Coverage

- Happy Path: X/X passed (XX%)
- Error States: X/X passed (XX%)
- Edge Cases: X/X passed (XX%)
- Design System: X/X compliant (XX%)
- Accessibility: X/X passed (XX%)

## Issues Summary

**Total Issues:** X

**By Severity:**
- Critical: X
- High: X
- Medium: X
- Low: X

**By Category:**
- Functionality: X
- Design System: X
- Accessibility: X

## Next Steps

1. Create issue tickets for all issues
2. Create detailed test report
3. Send to BMad for fixes
4. Schedule retest after fixes

---

Screenshot Naming Convention

• Happy Path: HP-XXX-step-X-FAIL.png
• Error State: ES-XXX-[description]-FAIL.png
• Edge Case: EC-XXX-[description]-FAIL.png
• Design System: DS-XXX-[component]-FAIL.png
• Accessibility: A11Y-XXX-[issue]-FAIL.png

Phase 5 [T] Acceptance Testing (Designer Validation)

Validate implementation matches design vision and quality standards

---

Purpose

Acceptance Testing is where you:

1. Wait for BMad to notify you that a feature is complete 2. Run test scenarios to validate implementation 3. Create issues if problems are found 4. Iterate with BMad until quality meets standards 5. Sign off when approved

This is Touch Point 3: BMad → WDS (BMad integrates with WDS testing)

---

When to Enter Acceptance Testing

After BMad notifies you:

BMad Developer: "Feature complete: DD-001 Login & Onboarding

                 Implemented:
                 ✓ All 4 scenarios
                 ✓ All error states
                 ✓ All edge cases
                 ✓ Design system components

                 Build: v0.1.0-beta.1
                 Device: Staging environment

                 Ready for designer validation.
                 Test scenario: test-scenarios/TS-001.yaml"

You respond:

WDS Analyst: "Received! Starting validation testing..."

---

Acceptance Testing Steps

Step 1: Prepare for Testing

Gather materials:

• [ ] Test scenario file (TS-XXX.yaml)
• [ ] Design Delivery file (DD-XXX.yaml)
• [ ] Scenario specifications (C-UX-Scenarios/)
• [ ] Design system specs (D-Design-System/)

Set up environment:

• [ ] Access to staging build
• [ ] Test devices ready (iOS, Android, etc.)
• [ ] Test data prepared
• [ ] Screen recording tools ready
• [ ] Note-taking tools ready

---

Step 2: Run Happy Path Tests

Follow test scenario:

happy_path:
  - id: 'HP-001'
    name: 'New User Complete Onboarding'
    steps:
      - action: 'Open app'
        expected: 'Welcome screen appears'
        design_ref: 'C-UX-Scenarios/01-welcome/Frontend/specifications.md'

For each step:

1. Perform the action 2. Observe the result 3. Compare to expected result 4. Check design reference 5. Mark as Pass or Fail 6. Take screenshots if issues found 7. Note any deviations

Record results:

HP-001: New User Complete Onboarding
✓ Step 1: Open app → Welcome screen appears (PASS)
✓ Step 2: Tap "Get Started" → Login/Signup choice (PASS)
✗ Step 3: Tap "Create Account" → Signup form (FAIL)
  Issue: Transition too fast, feels jarring
  Expected: 300ms smooth transition
  Actual: Instant transition
  Screenshot: screenshots/HP-001-step-3.png

---

Step 3: Run Error State Tests

Test error handling:

error_states:
  - id: 'ES-001'
    name: 'Email Already Exists'
    steps:
      - action: 'Enter existing email'
      - action: "Tap 'Create Account'"
      - expected: "Error message: 'This email is already registered...'"

Verify:

• Error messages are clear and helpful
• Error states are visually distinct
• Recovery options are provided
• User can retry without losing data

---

Step 4: Run Edge Case Tests

Test unusual scenarios:

edge_cases:
  - id: 'EC-001'
    name: 'User Closes App Mid-Onboarding'
    steps:
      - action: 'Start onboarding, complete signup'
      - action: 'Close app (force quit)'
      - action: 'Reopen app'
      - expected: 'Resume at Family Setup'

Verify:

• Edge cases are handled gracefully
• No crashes or blank screens
• User experience is smooth

---

Step 5: Validate Design System Compliance

Check component usage:

design_system_checks:
  - id: 'DS-001'
    name: 'Button Components'
    checks:
      - component: 'Primary Button'
        instances: ['Get Started', 'Create Account']
        verify:
          - 'Correct size (48px height)'
          - 'Correct color (primary brand color)'
          - 'Correct typography (16px, semibold)'

Verify:

• Components match design system specs
• Colors are correct
• Typography is correct
• Spacing is correct
• States work correctly (hover, active, disabled)

---

Step 6: Validate SEO (Public Pages)

Run SEO validation for all public pages:

Reference: ../wds-5-agentic-development/guides/SEO-VALIDATION-GUIDE.md

seo_checks:
  - id: 'SEO-001'
    name: 'Title tag correct'
    verify:
      - 'Title matches specification (≤ 60 chars)'
      - 'Contains primary keyword'
      - 'Contains brand name'

  - 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'
      - 'H1 contains primary keyword'
      - 'No skipped heading levels'

  - id: 'SEO-004'
    name: 'Image alt text complete'
    verify:
      - 'All content images have alt text'
      - 'Alt text in correct language'
      - 'No images > 200KB (hero < 400KB)'

  - id: 'SEO-005'
    name: 'Social sharing tags'
    verify:
      - 'og:title, og:description, og:image present'
      - 'twitter:card present'

  - id: 'SEO-006'
    name: 'Structured data valid'
    verify:
      - 'JSON-LD present and parseable'
      - 'Schema type matches plan'

  - id: 'SEO-007'
    name: 'Technical SEO'
    verify:
      - 'Canonical URL present'
      - 'hreflang tags present (if multilingual)'
      - 'robots.txt exists and references sitemap'
      - 'Security headers present'

Verify:

• All public pages have title, meta description, H1
• All images have alt text in all languages
• Social sharing tags present
• Structured data valid
• No oversized images
• Security headers configured

---

Step 7: Test Accessibility

Run accessibility tests:

accessibility:
  - id: 'A11Y-001'
    name: 'Screen Reader Navigation'
    setup: 'Enable VoiceOver (iOS) or TalkBack (Android)'
    verify:
      - 'All buttons have descriptive labels'
      - 'Form fields announce their purpose'
      - 'Error messages are announced'

Verify:

• Screen reader can navigate
• All interactive elements are accessible
• Color contrast meets WCAG 2.1 AA
• Touch targets are 44×44px minimum

---

Step 8: Create Issues

If problems found, create issue tickets:

File: issues/ISS-XXX-description.md

Template:

````markdown

Issue: Button Color Incorrect

ID: ISS-001 Severity: High Status: Open Delivery: DD-001 Test: TS-001, Check: DS-001

Description

Primary button color doesn't match design system specification.

Expected

Primary button background: #2563EB (brand primary)

Actual

Primary button background: #3B82F6 (lighter blue)

Impact

Brand inconsistency, doesn't match design system

Design Reference

• Design System: D-Design-System/03-Atomic-Components/Buttons/Button-Primary.md
• Design Token: tokens/colors.json → "button.primary.background"

Steps to Reproduce

1. Open Login screen 2. Observe "Sign In" button color

Screenshot

!Button color issue

Recommendation

Update button background color to use design token:

backgroundColor: tokens.button.primary.background; // #2563EB

````

````

Severity levels:

• Critical: Blocks usage, must fix immediately
• High: Major issue, fix before release
• Medium: Noticeable issue, fix soon
• Low: Minor issue, fix when possible

---

Step 9: Create Test Report

File: test-reports/TR-XXX-YYYY-MM-DD.md

Template:

# Test Report: TS-001 Login & Onboarding

**Date:** 2024-12-09
**Tester:** Sarah (Designer)
**Device:** iPhone 14 Pro (iOS 17)
**Build:** v0.1.0-beta.1

## Summary

**Overall Result:** FAIL (2 issues found, 1 high severity)

**Test Coverage:**
- Happy Path: 12/13 passed (92%)
- Error States: 3/3 passed (100%)
- Edge Cases: 2/2 passed (100%)
- Design System: 8/10 passed (80%)
- Accessibility: 2/2 passed (100%)

## Issues Found

### ISS-001: Button Color Incorrect (HIGH)
[Details...]

### ISS-002: Transition Too Fast (MEDIUM)
[Details...]

## Recommendations

### What Worked Well
- Error handling is clear and helpful
- Accessibility is excellent
- User flow is intuitive

### What Needs Improvement
- Design system compliance (80% → target 95%)
- Transition animations need polish

### Next Steps
1. Fix ISS-001 (button color) - CRITICAL
2. Fix ISS-002 (transition speed)
3. Retest with updated build

## Sign-off

**Status:** NOT APPROVED
**Reason:** High severity issue + design system compliance below threshold
**Retest Required:** Yes

---

Step 10: Send to BMad

Notify BMad of results:

WDS Analyst: "Testing complete for DD-001.

              Results: 2 issues found
              - ISS-001: Button color incorrect (HIGH)
              - ISS-002: Transition too fast (MEDIUM)

              Test report: test-reports/TR-001-2024-12-09.md
              Issues: issues/ISS-001.md, issues/ISS-002.md

              Please fix and notify when ready for retest."

BMad responds:

BMad Developer: "Issues received. Fixing:
                 - ISS-001: Button color
                 - ISS-002: Transition speed

                 Will notify when ready for retest."

---

Step 11: Iterate Until Approved

BMad fixes issues:

BMad Developer: "Issues fixed.
                 Build: v0.1.0-beta.2
                 Ready for retest."

You retest:

• Run test scenarios again
• Verify issues are fixed
• Check for new issues
• Update test report

If approved:

WDS Analyst: "Retest complete!

              All issues resolved.
              Design system compliance: 98%

              ✅ APPROVED - Ready to ship!

              Test report: test-reports/TR-001-2024-12-15.md"

If not approved:

• Create new issues
• Send to BMad
• Repeat until approved

---

Sign-Off Criteria

Required for approval:

• [ ] All critical tests pass
• [ ] No critical or high severity issues
• [ ] Design system compliance > 95%
• [ ] Accessibility tests pass
• [ ] SEO validation passes (all public pages)
• [ ] Usability metrics meet targets
• [ ] All acceptance criteria met

Designer approval:

I confirm that the implemented feature matches the design
specifications and meets the quality standards defined in
the test scenario.

Designer: ________________
Date: ________________

---

Deliverables

Test Report

Location: test-reports/TR-XXX-YYYY-MM-DD.md

Contents:

• Test summary (date, tester, device, build)
• Overall result (pass/fail/partial)
• Test coverage (happy path, errors, edge cases, etc.)
• Issues found (with severity and details)
• Recommendations (what worked, what needs improvement)
• Sign-off status

---

Issue Tickets

Location: issues/ISS-XXX-description.md

Contents:

• Issue metadata (id, severity, status, delivery, test)
• Description
• Expected vs Actual
• Impact
• Design reference
• Steps to reproduce
• Screenshot/video
• Recommendation

---

Common Issues

Design System Violations

Button color incorrect:

• Expected: Design token color
• Actual: Hardcoded color
• Fix: Use design token

Typography wrong:

• Expected: 16px, Semibold
• Actual: 14px, Regular
• Fix: Use design system styles

Spacing inconsistent:

• Expected: 20px between elements
• Actual: 15px, 18px, 23px
• Fix: Use spacing tokens

---

Interaction Issues

Transition too fast:

• Expected: 300ms smooth transition
• Actual: Instant transition
• Fix: Add transition animation

Touch target too small:

• Expected: 44×44px minimum
• Actual: 32×32px
• Fix: Increase button size

No loading state:

• Expected: Spinner during load
• Actual: Blank screen
• Fix: Add loading indicator

---

Accessibility Issues

Missing labels:

• Expected: Descriptive button labels
• Actual: Generic "Button" label
• Fix: Add aria-label

Low contrast:

• Expected: 4.5:1 contrast ratio
• Actual: 3:1 contrast ratio
• Fix: Increase text color contrast

Not keyboard accessible:

• Expected: Can navigate with keyboard
• Actual: Keyboard navigation doesn't work
• Fix: Add keyboard support

---

Tips for Success

DO ✅

Be thorough:

• Test every step in test scenario
• Check all design references
• Verify all acceptance criteria
• Don't skip edge cases

Be specific:

• Clear issue descriptions
• Include screenshots/videos
• Reference design specs
• Provide recommendations

Be collaborative:

• Communicate clearly with BMad
• Answer questions promptly
• Appreciate good work
• Focus on quality, not blame

Be iterative:

• Expect multiple rounds
• Test quickly and provide feedback
• Don't wait for perfection
• Sign off when quality is good enough

DON'T ❌

Don't be vague:

• "It doesn't look right" ❌
• "Button color is #3B82F6, should be #2563EB" ✅

Don't be nitpicky:

• Focus on critical issues first
• Don't block on minor details
• Remember: good enough to ship

Don't disappear:

• Respond to BMad questions
• Retest promptly
• Stay engaged until sign-off

Don't skip documentation:

• Always create test reports
• Always document issues
• Always provide clear feedback

---

Next Steps

After Acceptance Testing (Sign-off):

1. Feature ships to production 2. Monitor user feedback and metrics 3. Iterate based on real-world usage 4. Continue with next delivery (return to Phase 4-5)

If more flows in progress:

• Test next completed flow
• Continue parallel work
• Maintain quality standards

---

Resources

Templates:

• templates/test-scenario.template.yaml
• templates/test-report.template.md (to be created)
• templates/issue.template.md (to be created)

Specifications:

• src/core/resources/wds/integration-guide.md
• Test scenario files in test-scenarios/

---

Acceptance Testing is where you ensure quality! Test thoroughly, communicate clearly, and sign off with confidence! ✅✨

Step 3: Fix

STEP GOAL:

Implement the minimal fix targeting the root cause.

MANDATORY EXECUTION RULES (READ FIRST):

Universal Rules:

• 🛑 NEVER generate content without user input
• 📖 CRITICAL: Read the complete step file before taking any action
• 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
• 📋 YOU ARE A FACILITATOR, not a content generator
• ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config {communication_language}

Role Reinforcement:

• ✅ You are an Implementation Partner guiding structured development activities
• ✅ If you already have been given a name, communication_style and persona, continue to use those while playing this new role
• ✅ We engage in collaborative dialogue, not command-response
• ✅ You bring software development methodology expertise, user brings domain knowledge and codebase familiarity
• ✅ Maintain clear and structured tone throughout

Step-Specific Rules:

• 🎯 Focus only on writing a failing test, implementing the minimal fix, and verifying the reproduction case passes
• 🚫 FORBIDDEN to refactor surrounding code, add unrelated improvements, or fix other issues noticed nearby
• 💬 Approach: Write test first, then minimal fix, then verify — test-driven bugfixing
• 📋 The fix must be the smallest change that resolves the root cause

EXECUTION PROTOCOLS:

• 🎯 Bug fixed with minimal change, regression test written, reproduction case passes
• 💾 Update dialog file with fix details
• 📖 Reference root cause from Step 2 and reproduction steps from Step 1
• 🚫 Do not include unrelated changes in the fix

CONTEXT BOUNDARIES:

• Available context: Reproduction details from Step 1; root cause and proposed fix from Step 2
• Focus: Minimal fix targeting root cause with regression test
• Limits: No refactoring, no unrelated improvements
• Dependencies: Step 2 must be complete (root cause identified)

Sequence of Instructions (Do not deviate, skip, or optimize)

1. Create Fix Branch

• Create a branch from the current working branch
• Use a descriptive name: fix/<short-description> or bugfix/<issue-id>
• Commit the branch before making changes

2. Write a Test That Catches the Bug

• Before writing the fix, write a test that reproduces the bug
• The test should fail in the current state (proving the bug exists)
• This ensures the fix is verifiable and the bug cannot silently return
• If automated testing is not set up, document the manual test steps clearly

3. Implement the Minimal Fix

• Target the root cause identified in Step 02
• Make the smallest change that resolves the issue
• Do NOT:
• Refactor surrounding code
• Add unrelated improvements
• Change formatting or style in unrelated lines
• "Fix" other issues you noticed nearby
• If the fix requires more than a few lines, pause and verify scope

4. Verify the Fix Resolves the Reproduction Case

• Run the reproduction steps from Step 01
• Confirm the bug no longer occurs
• Run the test from sub-step 2 — it should now pass
• If the fix does not resolve the bug, revisit Step 02

5. Verify Checklist

• [ ] Fix branch created
• [ ] Test written that catches the bug (fails before fix, passes after)
• [ ] Minimal fix implemented targeting root cause
• [ ] No unrelated changes included
• [ ] Reproduction case passes with the fix
• [ ] Dialog file updated with fix details

6. Present MENU OPTIONS

Display: "Select an Option: [C] Continue to Step 4: Verify"

Menu Handling Logic:

• IF C: Update design log, then load, read entire file, then execute {nextStepFile}
• IF Any other comments or queries: help user respond then [Redisplay Menu Options]

EXECUTION RULES:

• ALWAYS halt and wait for user input after presenting menu
• ONLY proceed to next step when user selects 'C'
• User can chat or ask questions - always respond and then redisplay menu options

CRITICAL STEP COMPLETION NOTE

ONLY WHEN the fix is implemented, test passes, and reproduction case is resolved will you then load and read fully {nextStepFile} to execute.

---

🚨 SYSTEM SUCCESS/FAILURE METRICS

✅ SUCCESS:

• Fix branch created
• Test written that catches the bug (fails before fix, passes after)
• Minimal fix implemented targeting root cause
• No unrelated changes included
• Reproduction case passes with the fix

❌ SYSTEM FAILURE:

• Implementing fix without writing a regression test first
• Including refactoring or unrelated improvements
• Fix does not target root cause (treats symptom only)
• Proceeding without verifying reproduction case

Master Rule: Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.