UX Designer - Perfection-Focused UI/UX Skill

Goal: Zero bugs, perfect usability, flawless user experience.

When to Use

Invoke this skill when:

• User mentions: "perfect the demo", "fix UX bugs", "make it flawless"

• UI has inconsistencies or bugs

• User experience is confusing or broken

• Demo has visual issues

• Interactive elements don't work properly

UX Perfection Methodology

Phase 1: Comprehensive UX Audit

1A. Visual Inspection

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

1B. Interaction Testing

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

1C. User Flow Analysis

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

Phase 2: Research Best Practices

Launch codex-deep-research agent:

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

Check for AI-powered UX tools:

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

Phase 3: Bug Hunting (Zero Tolerance)

3A. Console Error Check

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

3B. Network Tab Analysis

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)

3C. Responsive Design Testing

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)

3D. Cross-Browser Testing

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

Phase 4: Usability Improvements

4A. First-Time User Experience

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)

4B. Visual Hierarchy

/* 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; }

4C. Feedback & Confirmation

// 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); }

4D. Error Handling (User-Friendly)

// 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); }

Phase 5: Accessibility Perfection

5A. Keyboard Navigation

// 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(); } }); }

5B. ARIA Labels

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

5C. Color Contrast Check

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

Phase 6: Performance Optimization

6A. Perceived Performance

// 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); }

6B. Animation Performance

/* 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; }

6C. Memory Leak Prevention

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

Phase 7: Final Polish

7A. Micro-interactions

/* 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; }

7B. Empty States

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

7C. Consistency Check

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)

Validation Checklist

Before marking UX as "perfect":

Functionality

• All buttons work (no broken onClick handlers)

• All links go to correct destinations

• Forms validate properly

• API calls succeed

• WebSocket connects and receives updates

• Error states display correctly

• Success states display correctly

• Loading states show during async operations

Visual

• No layout shift (CLS score <0.1)

• No horizontal scroll

• Consistent spacing

• Consistent typography

• High color contrast (WCAG AA)

• Icons are clear and consistent

• Images load correctly

• No visual bugs (overlapping, cutoff text)

Usability

• Clear navigation

• Obvious primary actions

• Helpful error messages

• Success confirmation

• Undo/cancel available

• Keyboard accessible

• Screen reader compatible

• Mobile responsive (320px - 1920px)

Performance

• Page load <2s

• API calls <200ms

• Smooth animations (60fps)

• No memory leaks

• Efficient rendering (no jank)

Browser Compatibility

• Chrome (latest)

• Firefox (latest)

• Safari (latest)

• Edge (latest)

Demo-Specific Checks

For Project Conductor demo:

Module Navigation

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)

Real-Time Features

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

Data Display

• 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

Output Format

After UX audit, provide:

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]

Example Usage

User: "Make sure the demo is perfect"

This skill will:

• Audit all demo HTML files

• Test every interactive element

• Research best UX practices

• Find and document all bugs

• Provide specific fixes with code

• Validate accessibility

• Check performance

• Test across browsers

• Generate comprehensive report

• Implement fixes if requested