MCP UI/UX Prompt Refiner

import type { InterfaceType, UXFlowStep } from '../utils/types.js'; import { UX_PATTERNS, ACCESSIBILITY_PATTERNS, ERROR_HANDLING_UX } from '../resources/ux-patterns.js'; import { INTERFACE_TEMPLATES } from '../resources/templates.js'; interface UXFlowInput { interfaceType: InterfaceType; primaryGoal: string; secondaryGoals?: string[]; userPersonas?: string[]; customFlows?: string[]; } function generateUserJourney(interfaceType: InterfaceType, primaryGoal: string): UXFlowStep[] { const journeyTemplates: Record<InterfaceType, UXFlowStep[]> = { 'website-landing': [ { step: 1, screen: 'Hero Section', userAction: 'Lands on page', systemResponse: 'Display value proposition with animated entrance', microInteractions: ['Logo fade in', 'Headline type effect', 'CTA button pulse'] }, { step: 2, screen: 'Hero Section', userAction: 'Scrolls down or clicks CTA', systemResponse: 'Smooth scroll to features or open signup modal', microInteractions: ['Scroll indicator bounce', 'Button press feedback', 'Modal slide up'] }, { step: 3, screen: 'Features Section', userAction: 'Explores features', systemResponse: 'Reveal features with scroll-triggered animations', microInteractions: ['Card hover lift', 'Icon animations', 'Staggered reveals'] }, { step: 4, screen: 'Social Proof', userAction: 'Views testimonials', systemResponse: 'Show rotating testimonials or grid', microInteractions: ['Carousel auto-advance', 'Quote fade transitions'] }, { step: 5, screen: 'Pricing/CTA', userAction: 'Reviews offering', systemResponse: 'Display pricing or final value prop', microInteractions: ['Price toggle animation', 'Feature list reveals'] }, { step: 6, screen: 'Signup Form', userAction: 'Submits email/info', systemResponse: 'Validate and confirm signup', microInteractions: ['Input focus glow', 'Validation checkmarks', 'Success animation'], errorHandling: 'Inline validation with helpful messages' } ], 'website-saas': [ { step: 1, screen: 'Homepage', userAction: 'Arrives from marketing', systemResponse: 'Show product overview and primary CTA', microInteractions: ['Hero animation', 'Navigation highlight'] }, { step: 2, screen: 'Features Page', userAction: 'Explores features', systemResponse: 'Detail each feature with demos', microInteractions: ['Interactive previews', 'Comparison toggles'] }, { step: 3, screen: 'Pricing Page', userAction: 'Compares plans', systemResponse: 'Show tier comparison with toggle', microInteractions: ['Annual/monthly toggle', 'Feature tooltips', 'Recommended badge pulse'] }, { step: 4, screen: 'Signup Flow', userAction: 'Starts trial', systemResponse: 'Streamlined signup process', microInteractions: ['Progress indicator', 'Form validation', 'Loading states'], errorHandling: 'Clear error messages with recovery options' }, { step: 5, screen: 'Onboarding', userAction: 'Sets up account', systemResponse: 'Guided setup wizard', microInteractions: ['Step transitions', 'Completion celebrations', 'Skip options'] }, { step: 6, screen: 'Dashboard', userAction: 'Starts using product', systemResponse: 'Show key actions and help', microInteractions: ['Feature tooltips', 'Empty state guidance'] } ], 'website-portfolio': [ { step: 1, screen: 'Landing', userAction: 'Views portfolio', systemResponse: 'Impactful first impression', microInteractions: ['Name/logo animation', 'Custom cursor activation'] }, { step: 2, screen: 'Work Grid', userAction: 'Browses projects', systemResponse: 'Display project thumbnails', microInteractions: ['Hover reveals', 'Image zoom', 'Project title slides'] }, { step: 3, screen: 'Project Detail', userAction: 'Opens project', systemResponse: 'Smooth transition to detail', microInteractions: ['Page transition', 'Gallery navigation', 'Related projects'] }, { step: 4, screen: 'About Section', userAction: 'Learns about creator', systemResponse: 'Personal story and skills', microInteractions: ['Skill bar animations', 'Timeline reveals'] }, { step: 5, screen: 'Contact', userAction: 'Reaches out', systemResponse: 'Contact form or info', microInteractions: ['Form interactions', 'Social link hovers', 'Success confirmation'] } ], 'website-ecommerce': [ { step: 1, screen: 'Homepage', userAction: 'Browses store', systemResponse: 'Featured products and categories', microInteractions: ['Product card hovers', 'Quick view triggers'] }, { step: 2, screen: 'Category Page', userAction: 'Filters products', systemResponse: 'Dynamic filtering with results', microInteractions: ['Filter animations', 'Sort transitions', 'Load more reveals'] }, { step: 3, screen: 'Product Detail', userAction: 'Views product', systemResponse: 'Full product information', microInteractions: ['Image zoom', 'Variant selection', 'Add to cart feedback'] }, { step: 4, screen: 'Cart', userAction: 'Reviews cart', systemResponse: 'Cart summary and options', microInteractions: ['Quantity adjusters', 'Remove animations', 'Price updates'] }, { step: 5, screen: 'Checkout', userAction: 'Completes purchase', systemResponse: 'Multi-step checkout flow', microInteractions: ['Step progress', 'Address autocomplete', 'Payment processing'], errorHandling: 'Payment error recovery, saved cart' }, { step: 6, screen: 'Confirmation', userAction: 'Order placed', systemResponse: 'Success and next steps', microInteractions: ['Celebration animation', 'Order summary', 'Continue shopping CTA'] } ], 'dashboard': [ { step: 1, screen: 'Login', userAction: 'Authenticates', systemResponse: 'Secure login flow', microInteractions: ['Input validation', 'Loading state', 'Success transition'] }, { step: 2, screen: 'Overview', userAction: 'Views dashboard', systemResponse: 'Key metrics at a glance', microInteractions: ['Number counting', 'Chart animations', 'Refresh indicators'] }, { step: 3, screen: 'Data View', userAction: 'Explores data', systemResponse: 'Interactive charts/tables', microInteractions: ['Chart hover tooltips', 'Table sorting', 'Filter animations'] }, { step: 4, screen: 'Detail View', userAction: 'Drills down', systemResponse: 'Detailed data view', microInteractions: ['Breadcrumb updates', 'Data transitions', 'Export options'] }, { step: 5, screen: 'Actions', userAction: 'Takes action', systemResponse: 'Action confirmation', microInteractions: ['Button feedback', 'Toast notifications', 'Status updates'] } ], 'mobile-app': [ { step: 1, screen: 'Splash', userAction: 'Opens app', systemResponse: 'Brand moment and load', microInteractions: ['Logo animation', 'Progress indicator'] }, { step: 2, screen: 'Onboarding', userAction: 'First launch', systemResponse: 'Feature introduction', microInteractions: ['Swipe navigation', 'Skip option', 'Progress dots'] }, { step: 3, screen: 'Home', userAction: 'Main screen', systemResponse: 'Primary content/actions', microInteractions: ['Pull to refresh', 'Tab switches', 'FAB interactions'] }, { step: 4, screen: 'Feature Screen', userAction: 'Uses feature', systemResponse: 'Feature functionality', microInteractions: ['Gesture feedback', 'Loading states', 'Success animations'] }, { step: 5, screen: 'Settings', userAction: 'Configures app', systemResponse: 'Preferences and options', microInteractions: ['Toggle switches', 'List interactions', 'Save confirmations'] } ], 'desktop-app': [ { step: 1, screen: 'Launch', userAction: 'Opens application', systemResponse: 'Load workspace', microInteractions: ['Splash screen', 'Workspace restore'] }, { step: 2, screen: 'Main Workspace', userAction: 'Primary tasks', systemResponse: 'Working environment', microInteractions: ['Panel resizing', 'Tool selection', 'Context menus'] }, { step: 3, screen: 'File Operations', userAction: 'Opens/saves files', systemResponse: 'File dialogs', microInteractions: ['File browser', 'Progress indicators', 'Recent files'] }, { step: 4, screen: 'Preferences', userAction: 'Customizes app', systemResponse: 'Settings panels', microInteractions: ['Tab navigation', 'Apply/cancel', 'Reset options'] } ], 'cli-terminal': [ { step: 1, screen: 'Init', userAction: 'Runs command', systemResponse: 'Parse and validate', microInteractions: ['Typing echo', 'Validation feedback'] }, { step: 2, screen: 'Processing', userAction: 'Waits for result', systemResponse: 'Progress indication', microInteractions: ['Spinner', 'Progress bar', 'Status updates'] }, { step: 3, screen: 'Output', userAction: 'Views result', systemResponse: 'Formatted output', microInteractions: ['Syntax highlighting', 'Pagination'] }, { step: 4, screen: 'Interactive', userAction: 'Makes choices', systemResponse: 'Prompts for input', microInteractions: ['Arrow selection', 'Confirmation prompts'], errorHandling: 'Clear error messages with suggestions' } ], 'presentation': [ { step: 1, screen: 'Title Slide', userAction: 'Starts presentation', systemResponse: 'Display opening', microInteractions: ['Title animation', 'Author reveal'] }, { step: 2, screen: 'Content Slides', userAction: 'Advances slides', systemResponse: 'Show content', microInteractions: ['Slide transitions', 'Build animations', 'Chart reveals'] }, { step: 3, screen: 'Interactive', userAction: 'Engages audience', systemResponse: 'Interactive elements', microInteractions: ['Poll results', 'Q&A interface'] }, { step: 4, screen: 'Closing', userAction: 'Concludes', systemResponse: 'Final CTA', microInteractions: ['Contact info reveal', 'Thank you animation'] } ], 'admin-panel': [ { step: 1, screen: 'Login', userAction: 'Authenticates', systemResponse: 'Secure access', microInteractions: ['2FA if needed', 'Loading state'], errorHandling: 'Lockout protection, password reset' }, { step: 2, screen: 'Dashboard', userAction: 'Views overview', systemResponse: 'System status', microInteractions: ['Alert indicators', 'Quick actions'] }, { step: 3, screen: 'Content List', userAction: 'Manages content', systemResponse: 'Data table view', microInteractions: ['Sort/filter', 'Bulk selection', 'Quick edit'] }, { step: 4, screen: 'Edit Form', userAction: 'Modifies item', systemResponse: 'Edit interface', microInteractions: ['Auto-save', 'Validation', 'Preview'], errorHandling: 'Unsaved changes warning, version history' }, { step: 5, screen: 'Publish', userAction: 'Publishes changes', systemResponse: 'Confirm and deploy', microInteractions: ['Publish animation', 'Status update', 'Undo option'] } ], 'social-platform': [ { step: 1, screen: 'Feed', userAction: 'Views content', systemResponse: 'Infinite scroll feed', microInteractions: ['Pull to refresh', 'New posts indicator', 'Skeleton loading'] }, { step: 2, screen: 'Interact', userAction: 'Likes/comments', systemResponse: 'Update engagement', microInteractions: ['Like animation', 'Comment expansion', 'Share modal'] }, { step: 3, screen: 'Create', userAction: 'Posts content', systemResponse: 'Post creation flow', microInteractions: ['Media upload', 'Typing indicator', 'Post animation'] }, { step: 4, screen: 'Profile', userAction: 'Views profile', systemResponse: 'User profile page', microInteractions: ['Follow button', 'Tab navigation', 'Grid/list toggle'] }, { step: 5, screen: 'Messages', userAction: 'Direct messages', systemResponse: 'Chat interface', microInteractions: ['Message bubbles', 'Typing indicator', 'Read receipts'] } ], 'custom': [ { step: 1, screen: 'Entry Point', userAction: 'Initial interaction', systemResponse: 'Welcome/overview', microInteractions: ['Entry animation'] }, { step: 2, screen: 'Core Flow', userAction: 'Primary action', systemResponse: 'Main functionality', microInteractions: ['Contextual feedback'] }, { step: 3, screen: 'Completion', userAction: 'Completes goal', systemResponse: 'Success state', microInteractions: ['Completion animation'] } ] }; return journeyTemplates[interfaceType] || journeyTemplates.custom; } function generateUXPatternRecommendations(interfaceType: InterfaceType): string { const recommendations: string[] = []; recommendations.push('### Navigation Patterns'); if (['mobile-app', 'social-platform'].includes(interfaceType)) { recommendations.push('- Use bottom tab navigation for primary actions'); recommendations.push('- Implement gesture-based navigation (swipe)'); } else if (['dashboard', 'admin-panel'].includes(interfaceType)) { recommendations.push('- Use collapsible sidebar navigation'); recommendations.push('- Implement command palette (Cmd+K) for power users'); } else { recommendations.push('- Use sticky header with transparent-to-solid transition'); recommendations.push('- Implement breadcrumbs for deep navigation'); } recommendations.push('\n### Feedback Patterns'); recommendations.push('- Show optimistic UI updates for common actions'); recommendations.push('- Use skeleton loaders for content, spinners for actions'); recommendations.push('- Provide toast notifications for background operations'); recommendations.push('\n### Form Patterns'); recommendations.push('- Inline validation with real-time feedback'); recommendations.push('- Smart defaults based on context'); recommendations.push('- Auto-save for long forms'); return recommendations.join('\n'); } export function generateUXFlow(input: UXFlowInput): string { const { interfaceType, primaryGoal, secondaryGoals, userPersonas, customFlows } = input; const template = INTERFACE_TEMPLATES[interfaceType]; const userJourney = generateUserJourney(interfaceType, primaryGoal); const patternRecommendations = generateUXPatternRecommendations(interfaceType); return `# UX Flow Specification ## Overview **Interface Type**: ${interfaceType.replace(/-/g, ' ').replace(/\b\w/g, c => c.toUpperCase())} **Primary Goal**: ${primaryGoal} ${secondaryGoals ? `**Secondary Goals**: ${secondaryGoals.join(', ')}` : ''} ${userPersonas ? `**Target Users**: ${userPersonas.join(', ')}` : `**Target Users**: ${template.uxPriorities.join(', ')}`} --- ## User Journey Map ${userJourney.map(step => ` ### Step ${step.step}: ${step.screen} **User Action**: ${step.userAction} **System Response**: ${step.systemResponse} **Micro-Interactions**: ${step.microInteractions.map(m => `- ${m}`).join('\n')} ${step.errorHandling ? `**Error Handling**: ${step.errorHandling}` : ''} `).join('\n---\n')} --- ## UX Pattern Recommendations ${patternRecommendations} --- ## Interaction Design Principles ### Response Time Guidelines | Action Type | Expected Response | User Feedback | |-------------|-------------------|---------------| | Button click | Immediate (<100ms) | Visual press state | | Form submit | <1 second | Loading indicator | | Page load | <2 seconds | Skeleton loader | | Background task | Variable | Progress indicator | ### Feedback Loop Requirements 1. **Immediate**: Visual change on interaction (hover, press) 2. **Short-term**: Confirmation of action (toast, animation) 3. **Long-term**: Status of outcome (success page, notification) --- ## State Management ### Screen States to Design For each screen, design these states: 1. **Empty State** - First-time user guidance - Clear CTA to populate - Friendly illustration 2. **Loading State** - Skeleton that matches content structure - Meaningful progress indication - Avoid layout shift when content loads 3. **Error State** - Clear problem explanation - Actionable recovery steps - Maintain user's context/data 4. **Success State** - Celebration appropriate to action importance - Clear next steps - Easy navigation to continue 5. **Partial State** - Graceful degradation - Clear indication of limitations - Offline-capable where possible --- ## Error Handling UX ### Prevention ${Object.entries(ERROR_HANDLING_UX.preventive).map(([key, value]) => `- **${key}**: ${value}`).join('\n')} ### Communication ${Object.entries(ERROR_HANDLING_UX.informative).map(([key, value]) => `- **${key}**: ${value}`).join('\n')} ### Recovery ${Object.entries(ERROR_HANDLING_UX.recovery).map(([key, value]) => `- **${key}**: ${value}`).join('\n')} --- ## Accessibility Requirements ### Focus Management ${Object.entries(ACCESSIBILITY_PATTERNS.focusManagement).map(([key, value]) => `- **${key}**: ${value}`).join('\n')} ### Screen Reader Support ${Object.entries(ACCESSIBILITY_PATTERNS.screenReaders).map(([key, value]) => `- **${key}**: ${value}`).join('\n')} ### Color & Contrast ${Object.entries(ACCESSIBILITY_PATTERNS.colorAndContrast).map(([key, value]) => `- **${key}**: ${value}`).join('\n')} ### Motion Sensitivity ${Object.entries(ACCESSIBILITY_PATTERNS.motion).map(([key, value]) => `- **${key}**: ${value}`).join('\n')} --- ## Mobile UX Considerations ### Touch Targets - Minimum touch target: 44x44px (iOS) / 48x48dp (Android) - Spacing between targets: minimum 8px - Place primary actions in thumb-friendly zones ### Gestures - Swipe: Navigation, dismissal, actions - Long press: Context menus, selection - Pinch: Zoom (images, maps) - Pull down: Refresh content ### Mobile-Specific Patterns - Bottom sheets for additional options - Full-screen modals for focused tasks - Floating action button for primary create action - Snackbars for brief feedback --- ## Performance UX ### Perceived Performance Optimizations 1. **Instant feedback**: Respond to input immediately 2. **Optimistic updates**: Show expected result before confirmation 3. **Progressive loading**: Prioritize above-fold content 4. **Skeleton screens**: Show structure while loading 5. **Preloading**: Anticipate next action, preload resources ### Loading Strategy by Content Type | Content | Strategy | Placeholder | |---------|----------|-------------| | Text | Skeleton lines | Gray bars matching text | | Images | Blur-up/LQIP | Blurred thumbnail | | Lists | Skeleton cards | Repeated card shapes | | Data | Skeleton + spinner | Structure + activity | --- ${customFlows ? `## Custom Flow Requirements ${customFlows.map(flow => `- ${flow}`).join('\n')} ---` : ''} ## UX Quality Metrics ### Key Metrics to Track - **Task completion rate**: % of users completing primary goal - **Time to first action**: How quickly users engage - **Error rate**: Frequency of user errors - **Recovery rate**: % who recover from errors - **Satisfaction**: User-reported satisfaction scores ### Success Criteria - [ ] Users can complete primary goal without help - [ ] Error states provide clear recovery paths - [ ] Loading states prevent user confusion - [ ] Accessibility requirements met (WCAG AA) - [ ] Mobile experience is fully functional --- *This UX flow is designed to create intuitive, delightful user experiences that feel thoughtfully crafted rather than generic.* `; }