# Check all HTML files for common issues
find public -name "*.html" -type f

# For each file, check:
- Broken links (404s)
- Missing images
- JavaScript errors in console
- CSS rendering issues
- Responsive design breakpoints
- Color contrast (accessibility)
- Typography consistency

Test every interactive element:
- [ ] Buttons: Click response, hover states, disabled states
- [ ] Forms: Validation, error messages, success states
- [ ] Navigation: All links work, breadcrumbs accurate
- [ ] Modals: Open/close, backdrop click, ESC key
- [ ] Dropdowns: Open/close, keyboard navigation
- [ ] Tables: Sorting, filtering, pagination
- [ ] Real-time updates: WebSocket connection, live data
- [ ] Loading states: Spinners, skeletons, placeholders

Map critical user journeys:
1. New user onboarding → Should be intuitive, max 3 steps
2. Core feature usage → Should be discoverable, max 2 clicks
3. Error recovery → Clear error messages, obvious next steps
4. Success confirmation → Visible feedback, celebratory if appropriate

Invoke Task tool with subagent_type="codex-deep-research"

Prompt:
"Research the best UX/UI practices for interactive demos and dashboards.

Context:
- Project Conductor is a workflow orchestration platform
- Demo showcases 7-module workflow (Onboarding → Implementation)
- Tech: HTML, CSS, JavaScript (vanilla), Socket.io
- Users: Product managers, engineers, stakeholders

Provide best practices for:
1. **Demo UX Patterns**
   - Interactive tutorials vs guided tours
   - Progress indicators
   - Contextual help
   - Error handling in demos

2. **Dashboard Design**
   - Card layouts
   - Data visualization
   - Real-time updates (WebSocket)
   - Empty states
   - Loading states

3. **Navigation**
   - Module-to-module flow
   - Breadcrumbs
   - Back button behavior
   - Deep linking

4. **Accessibility**
   - Keyboard navigation
   - Screen reader support
   - Focus management
   - ARIA labels

5. **Performance**
   - Perceived performance
   - Lazy loading
   - Animation frame rate
   - Memory leaks

6. **Error Handling**
   - User-friendly error messages
   - Recovery actions
   - Fallback UI
   - Offline behavior

Provide specific code examples and visual patterns."

Invoke Task tool with subagent_type="gemini-research-analyst"

Prompt:
"Research if Google's Gemini AI provides any UX design, usability testing, or UI generation tools.

Investigate:
1. Gemini-powered UX analysis tools
2. Automated accessibility testing
3. UI component generation
4. User flow optimization
5. A/B testing recommendations
6. Heatmap analysis tools

If available, explain how to integrate with HTML/JS demos."

// Check browser console for errors
// Common issues:
- Uncaught ReferenceError (missing variables)
- Uncaught TypeError (null/undefined access)
- Failed to fetch (broken API calls)
- WebSocket connection failed
- CORS errors
- 404 for assets (images, CSS, JS)

Check Network tab for:
- [ ] All resources load successfully (no 404s)
- [ ] API endpoints respond <200ms
- [ ] WebSocket connection established
- [ ] No unnecessary requests (optimize)
- [ ] Proper caching headers
- [ ] Compressed assets (gzip)

# Test breakpoints
- Mobile: 320px, 375px, 414px
- Tablet: 768px, 1024px
- Desktop: 1280px, 1440px, 1920px

# Check for:
- Horizontal scroll (should be none)
- Text overflow
- Image scaling
- Button touch targets (min 44x44px)
- Readable font sizes (min 16px)

Test in:
- [ ] Chrome (latest)
- [ ] Firefox (latest)
- [ ] Safari (latest)
- [ ] Edge (latest)

Check for:
- CSS compatibility (flexbox, grid)
- JavaScript APIs (fetch, WebSocket)
- Event handlers (click, keyboard)
- CSS animations

Checklist:
- [ ] Clear value proposition (what is this?)
- [ ] Obvious starting point (where do I begin?)
- [ ] Contextual help (tooltips, hints)
- [ ] Progress indicators (how far have I gone?)
- [ ] Success feedback (I completed something!)
- [ ] Error prevention (guard rails)
- [ ] Easy recovery (undo, reset)

/* Apply visual hierarchy principles */
- Primary actions: Bold, high contrast, larger
- Secondary actions: Less prominent
- Tertiary actions: Text links, subtle
- Destructive actions: Red, confirmation required
- Disabled states: Greyed out, not clickable

/* Example */
.btn-primary {
  background: #007bff;
  color: white;
  font-weight: 600;
  padding: 12px 24px;
  font-size: 16px;
}

.btn-secondary {
  background: transparent;
  border: 1px solid #6c757d;
  color: #6c757d;
  padding: 10px 20px;
  font-size: 14px;
}

// Every user action needs feedback
function handleAction(action) {
  // 1. Immediate feedback (button state)
  button.disabled = true;
  button.textContent = 'Processing...';

  // 2. Action execution
  await performAction(action);

  // 3. Success feedback
  showToast('✅ Action completed successfully!', 'success');
  button.disabled = false;
  button.textContent = 'Done';

  // 4. Update UI to reflect change
  refreshData();
}

// Toast notification system
function showToast(message, type = 'info', duration = 3000) {
  const toast = document.createElement('div');
  toast.className = `toast toast-${type}`;
  toast.textContent = message;
  document.body.appendChild(toast);

  setTimeout(() => {
    toast.classList.add('fade-out');
    setTimeout(() => toast.remove(), 300);
  }, duration);
}

// Bad: Generic error
catch (error) {
  alert('Error');
}

// Good: Helpful error with action
catch (error) {
  showError({
    title: 'Unable to Load Projects',
    message: 'We couldn\'t connect to the server. Please check your internet connection and try again.',
    actions: [
      { label: 'Retry', onClick: () => retryLoad() },
      { label: 'Go Back', onClick: () => history.back() }
    ],
    icon: '🔌'
  });

  // Log detailed error for debugging
  console.error('Project load failed:', error);
}

// Ensure all interactive elements are keyboard accessible
document.querySelectorAll('button, a, input, select, textarea').forEach(el => {
  // Add focus visible styles
  el.addEventListener('focus', (e) => {
    e.target.classList.add('focus-visible');
  });

  // Support Enter/Space on custom buttons
  if (el.getAttribute('role') === 'button') {
    el.addEventListener('keydown', (e) => {
      if (e.key === 'Enter' || e.key === ' ') {
        e.preventDefault();
        el.click();
      }
    });
  }
});

// Trap focus in modals
function trapFocus(modal) {
  const focusableElements = modal.querySelectorAll(
    'a[href], button, textarea, input, select, [tabindex]:not([tabindex="-1"])'
  );
  const firstElement = focusableElements[0];
  const lastElement = focusableElements[focusableElements.length - 1];

  modal.addEventListener('keydown', (e) => {
    if (e.key === 'Tab') {
      if (e.shiftKey && document.activeElement === firstElement) {
        e.preventDefault();
        lastElement.focus();
      } else if (!e.shiftKey && document.activeElement === lastElement) {
        e.preventDefault();
        firstElement.focus();
      }
    } else if (e.key === 'Escape') {
      closeModal();
    }
  });
}

<!-- Bad: No context for screen readers -->
<button onclick="save()">
  <svg>...</svg>
</button>

<!-- Good: Descriptive label -->
<button onclick="save()" aria-label="Save project changes">
  <svg aria-hidden="true">...</svg>
</button>

<!-- Dynamic content -->
<div role="status" aria-live="polite" aria-atomic="true">
  <span id="status-message">Loading projects...</span>
</div>

<!-- Form validation -->
<input
  type="email"
  id="email"
  aria-describedby="email-error"
  aria-invalid="true"
>
<span id="email-error" role="alert">
  Please enter a valid email address
</span>

// Ensure WCAG AA compliance (4.5:1 for normal text, 3:1 for large)
// Use tools: Chrome DevTools Lighthouse, axe DevTools

// Example: Check programmatically
function checkContrast(foreground, background) {
  const ratio = getContrastRatio(foreground, background);
  return {
    passAA: ratio >= 4.5,
    passAAA: ratio >= 7,
    ratio: ratio.toFixed(2)
  };
}

// Fix: Increase contrast
/* Before */
.text-muted { color: #999; } /* 2.8:1 - FAILS */

/* After */
.text-muted { color: #6c757d; } /* 4.5:1 - PASSES */

// Instant feedback, lazy load heavy content
async function loadDashboard() {
  // 1. Show skeleton immediately (0ms)
  showSkeleton();

  // 2. Load critical data first (100ms)
  const criticalData = await fetchCritical();
  renderCritical(criticalData);
  hideSkeleton();

  // 3. Load secondary data (background)
  fetchSecondary().then(renderSecondary);

  // 4. Prefetch likely next page
  prefetchNextPage();
}

// Skeleton UI
function showSkeleton() {
  const skeleton = `
    <div class="skeleton-card">
      <div class="skeleton-line skeleton-title"></div>
      <div class="skeleton-line"></div>
      <div class="skeleton-line"></div>
    </div>
  `;
  container.innerHTML = skeleton.repeat(6);
}

/* Bad: Causes layout thrashing */
.animate-bad {
  animation: slide-in 0.3s ease;
}
@keyframes slide-in {
  from { margin-left: -100px; }
  to { margin-left: 0; }
}

/* Good: GPU-accelerated */
.animate-good {
  animation: slide-in 0.3s ease;
}
@keyframes slide-in {
  from { transform: translateX(-100px); }
  to { transform: translateX(0); }
}

/* Use will-change for complex animations */
.will-animate {
  will-change: transform, opacity;
}

// Bad: Event listeners not cleaned up
socket.on('update', handleUpdate);

// Good: Clean up on unmount
const listeners = [];

function addListener(event, handler) {
  socket.on(event, handler);
  listeners.push({ event, handler });
}

function cleanup() {
  listeners.forEach(({ event, handler }) => {
    socket.off(event, handler);
  });
  listeners.length = 0;
}

// Call cleanup when leaving page
window.addEventListener('beforeunload', cleanup);

/* Smooth button interactions */
button {
  transition: all 0.2s ease;
  transform: scale(1);
}

button:hover {
  transform: scale(1.05);
  box-shadow: 0 4px 8px rgba(0,0,0,0.2);
}

button:active {
  transform: scale(0.98);
}

/* Loading spinner */
@keyframes spin {
  to { transform: rotate(360deg); }
}

.spinner {
  animation: spin 1s linear infinite;
}

<!-- Instead of blank screen -->
<div class="empty-state">
  <svg class="empty-icon"><!-- Icon --></svg>
  <h3>No projects yet</h3>
  <p>Create your first project to get started</p>
  <button class="btn-primary">Create Project</button>
</div>

Ensure consistency across:
- [ ] Button styles (primary, secondary, danger)
- [ ] Spacing (use 8px grid: 8, 16, 24, 32, 48, 64)
- [ ] Typography (max 3 font sizes, consistent weights)
- [ ] Colors (stick to design system palette)
- [ ] Icons (same style, size, stroke width)
- [ ] Shadows (consistent elevation levels)
- [ ] Border radius (consistent rounding)
- [ ] Animations (consistent timing, easing)

# Test all module transitions
Module 0 (Onboarding) → Module 1 (Dashboard)
Module 1 (Dashboard) → Module 2 (BRD)
Module 2 (BRD) → Module 3 (PRD)
Module 3 (PRD) → Module 4 (Engineering Design)
Module 4 (Engineering Design) → Module 5 (Conflicts)
Module 5 (Conflicts) → Module 6 (Implementation)
Module 6 (Implementation) → Module 1 (Dashboard)

# Check:
- [ ] All links work
- [ ] Navigation breadcrumbs update
- [ ] Back button works
- [ ] State persists (if applicable)

// Test WebSocket functionality
- [ ] Connection establishes on page load
- [ ] Live updates appear without refresh
- [ ] Multiple tabs stay in sync
- [ ] Reconnects after disconnect
- [ ] Shows offline indicator if disconnected
- [ ] No duplicate updates

- [ ] Projects list loads correctly
- [ ] Requirements display properly
- [ ] Status badges show correct colors
- [ ] Progress bars update in real-time
- [ ] Filters work correctly
- [ ] Sorting works correctly
- [ ] Pagination works correctly
- [ ] Search works correctly

## UX Audit Report

**Status**: [PERFECT ✅ / NEEDS FIXES ⚠️ / CRITICAL ISSUES ❌]

### Issues Found

#### Critical (Must Fix) 🔴
1. [Issue description]
   - Impact: [How this affects users]
   - Fix: [Specific code changes needed]
   - File: [path/to/file.html]
   - Line: [line number]

#### Important (Should Fix) 🟡
1. [Issue description]
   - Impact: [How this affects users]
   - Fix: [Specific code changes needed]

#### Nice to Have (Polish) 🟢
1. [Issue description]
   - Enhancement: [How this improves UX]
   - Suggestion: [Code example]

### UX Score

- Functionality: [X/10]
- Visual Design: [X/10]
- Usability: [X/10]
- Accessibility: [X/10]
- Performance: [X/10]

**Overall**: [X/50] - [Grade: A+ to F]

### Next Steps

1. Fix critical issues first
2. Implement important fixes
3. Add polish enhancements
4. Re-test all flows
5. Final validation

### Code Fixes

[Provide specific code changes with file paths and line numbers]