vibecheck-ai 2.0.1 → 5.0.0

package/bin/runners/lib/polish/frontend.js

@@ -0,0 +1,817 @@
+/**
+ * Frontend Polish Engine
+ *
+ * Checks: Error boundaries, loading states, empty states, toasts,
+ * form validation, animations, hover states, haptics, ARIA,
+ * focus traps, skip links, data caching, memoization, logging,
+ * error tracking, lazy images, dark mode, confirm dialogs,
+ * optimistic updates, keyboard shortcuts, scroll-to-top, progress bars.
+ */
+
+const path = require("path");
+const {
+  pathExists,
+  findFile,
+  findAllFiles,
+  readFileSafe,
+} = require("./utils");
+const {
+  LIBRARY_ALTERNATIVES,
+  hasLibrary,
+  detectProjectType,
+  adjustSeverity,
+} = require("./libraries");
+
+module.exports = async function frontendEngine(projectPath) {
+  const issues = [];
+  const srcPath = path.join(projectPath, "src");
+  const appPath = path.join(projectPath, "app");
+  const pagesPath = path.join(projectPath, "pages");
+  const componentsPath = path.join(srcPath, "components");
+
+  const hasSrc = await pathExists(srcPath);
+  const hasApp = await pathExists(appPath);
+  const hasPages = await pathExists(pagesPath);
+
+  if (!hasSrc && !hasApp && !hasPages) return issues;
+
+  const searchPath = hasSrc ? srcPath : hasApp ? appPath : pagesPath;
+  const packageJson = await readFileSafe(path.join(projectPath, "package.json"));
+
+  const projectType = await detectProjectType(projectPath, packageJson);
+  if (projectType.skipFrontend) return issues;
+
+  // Detect installed libraries
+  const errorBoundaryLib = hasLibrary(packageJson, LIBRARY_ALTERNATIVES.errorBoundary);
+  const toastLib = hasLibrary(packageJson, LIBRARY_ALTERNATIVES.toast);
+  const spinnerLib = hasLibrary(packageJson, LIBRARY_ALTERNATIVES.spinner);
+  const skeletonLib = hasLibrary(packageJson, LIBRARY_ALTERNATIVES.skeleton);
+  const formLib = hasLibrary(packageJson, LIBRARY_ALTERNATIVES.formValidation);
+
+  // ── Error Handling & Boundaries ──────────────────────────────────────────
+
+  const hasErrorBoundary = await findFile(searchPath, /ErrorBoundary|error\.(tsx?|jsx?)$/i);
+  if (!hasErrorBoundary && !errorBoundaryLib && !projectType.uiLibrary) {
+    issues.push({
+      id: "missing-error-boundary",
+      category: "Frontend",
+      severity: adjustSeverity("critical", projectType, "missing-error-boundary"),
+      title: "Missing Error Boundary",
+      description: "No error boundary component found. React errors will crash the entire app.",
+      suggestion: "Add ErrorBoundary component to catch and handle React errors gracefully.",
+      autoFixable: true,
+      confidence: 0.9,
+      aiPrompt: `Create a reusable ErrorBoundary component for React/Next.js that:
+1. Catches JavaScript errors anywhere in the child component tree
+2. Logs errors to console and optionally to an error tracking service
+3. Displays a user-friendly fallback UI with:
+   - A friendly error message
+   - A "Try Again" button that resets the error state
+   - Option to report the error
+4. Supports custom fallback UI via props
+5. Uses TypeScript with proper typing
+6. Includes a useErrorBoundary hook for functional components
+7. Has smooth fade-in animation for the fallback UI
+
+Place it in src/components/ErrorBoundary.tsx`,
+    });
+  }
+
+  const has404 = await findFile(searchPath, /not-found|NotFound|404/i);
+  const hasNextAppRouter404 = hasApp && (await pathExists(path.join(appPath, "not-found.tsx")));
+  if (!has404 && !hasNextAppRouter404) {
+    issues.push({
+      id: "missing-404",
+      category: "Frontend",
+      severity: adjustSeverity("medium", projectType, "missing-404"),
+      title: "Missing 404 Page",
+      description: "No custom 404/NotFound page found. Users will see default browser error.",
+      suggestion: "Add a custom 404 page with navigation options.",
+      autoFixable: true,
+      confidence: 0.85,
+      aiPrompt: `Create a beautiful, user-friendly 404 Not Found page that:
+1. Has a visually appealing design with subtle animations
+2. Shows a clear "Page Not Found" message
+3. Includes helpful navigation options:
+   - Go back to previous page button
+   - Go to homepage button
+   - Search functionality (if applicable)
+   - Popular/suggested links
+4. Has a fun illustration or animation (CSS-based, no external images)
+5. Is fully responsive for mobile
+6. Maintains the site's design language
+7. Includes proper meta tags for SEO
+
+For Next.js App Router: Create app/not-found.tsx
+For Pages Router: Create pages/404.tsx`,
+    });
+  }
+
+  // ── Loading States & Skeletons ───────────────────────────────────────────
+
+  const hasLoadingSpinner = await findFile(searchPath, /Spinner|LoadingSpinner|Loading\.(tsx?|jsx?)$/i);
+  if (!hasLoadingSpinner && !spinnerLib && !projectType.uiLibrary) {
+    issues.push({
+      id: "missing-spinner",
+      category: "Frontend",
+      severity: adjustSeverity("high", projectType, "missing-spinner"),
+      title: "Missing Loading Spinner",
+      description: "No spinner component found. Users need visual feedback during loading.",
+      suggestion: spinnerLib
+        ? `Consider using the ${spinnerLib} library you have installed.`
+        : "Add a reusable Spinner component with multiple sizes and variants.",
+      autoFixable: true,
+      confidence: 0.7,
+      aiPrompt: `Create a modern, reusable Spinner/Loading component that:
+1. Has multiple size variants: sm, md, lg, xl
+2. Supports custom colors via props or CSS variables
+3. Has multiple styles: circular spinner, dots, pulse, bars
+4. Uses pure CSS animations (no external dependencies)
+5. Is accessible with proper ARIA attributes (role="status", aria-label)
+6. Supports dark/light mode automatically
+7. Can be used inline or as an overlay
+8. Has smooth entrance/exit animations
+9. TypeScript with proper prop types
+
+Create: src/components/ui/Spinner.tsx and src/components/ui/Spinner.css`,
+    });
+  }
+
+  const hasSkeleton = await findFile(searchPath, /Skeleton|Shimmer|ContentLoader/i);
+  if (!hasSkeleton && !skeletonLib && !projectType.uiLibrary) {
+    issues.push({
+      id: "missing-skeleton",
+      category: "Frontend",
+      severity: adjustSeverity("high", projectType, "missing-skeleton"),
+      title: "Missing Skeleton Loaders",
+      description: "No skeleton/shimmer components found. Skeleton loaders provide better perceived performance than spinners.",
+      suggestion: skeletonLib
+        ? `Consider using the ${skeletonLib} library you have installed.`
+        : "Add skeleton components for content placeholders.",
+      autoFixable: true,
+      confidence: 0.65,
+      aiPrompt: `Create a comprehensive Skeleton loading system with:
+
+1. Base Skeleton component with:
+   - Shimmer animation effect
+   - Multiple variants: text, circular, rectangular, rounded
+   - Customizable width, height, border-radius
+   - Animation that flows left-to-right with gradient
+
+2. Pre-built skeleton patterns:
+   - SkeletonText (paragraph lines with varying widths)
+   - SkeletonAvatar (circular profile picture placeholder)
+   - SkeletonCard (card layout placeholder)
+   - SkeletonTable (table rows placeholder)
+   - SkeletonList (list items placeholder)
+   - SkeletonImage (image placeholder with aspect ratio)
+
+3. Features:
+   - CSS-only animations (performant)
+   - Dark/light mode support
+   - Customizable animation speed
+   - Can disable animation for reduced motion preference
+   - TypeScript with proper types
+
+Create: src/components/ui/Skeleton.tsx with all variants`,
+    });
+  }
+
+  const hasLoadingPage = await findFile(searchPath, /loading\.(tsx?|jsx?)$/i);
+  if (!hasLoadingPage && hasApp) {
+    issues.push({
+      id: "missing-loading-page",
+      category: "Frontend",
+      severity: "medium",
+      title: "Missing Next.js Loading State",
+      description: "No loading.tsx found. Next.js App Router supports automatic loading states.",
+      suggestion: "Add loading.tsx files for route segments.",
+      autoFixable: true,
+      aiPrompt: `Create a loading.tsx file for Next.js App Router that:
+1. Shows a full-page skeleton loader matching your layout
+2. Uses your Skeleton components for consistency
+3. Includes a subtle progress indicator
+4. Maintains layout structure to prevent layout shift
+5. Has smooth fade-out when content loads
+
+Create: app/loading.tsx (root level) and consider adding to major route segments`,
+    });
+  }
+
+  // ── Empty States & Feedback ──────────────────────────────────────────────
+
+  const hasEmptyState = await findFile(searchPath, /EmptyState|Empty|NoData|NoResults/i);
+  if (!hasEmptyState) {
+    issues.push({
+      id: "missing-empty-states",
+      category: "Frontend",
+      severity: "medium",
+      title: "Missing Empty States",
+      description: "No empty state components found. Users need helpful messages when data is empty.",
+      suggestion: "Add EmptyState components for lists and data displays.",
+      autoFixable: true,
+      aiPrompt: `Create a versatile EmptyState component system with:
+
+1. Base EmptyState component with:
+   - Icon slot (customizable)
+   - Title and description
+   - Action button(s)
+   - Illustration option
+
+2. Pre-built variants:
+   - EmptySearch: "No results found" with search tips
+   - EmptyList: "No items yet" with add item CTA
+   - EmptyInbox: "All caught up!" positive empty state
+   - EmptyError: "Something went wrong" with retry
+   - EmptyPermission: "Access denied" with request access
+   - EmptyOffline: "You're offline" with retry when online
+
+3. Features:
+   - Subtle entrance animation
+   - Responsive design
+   - Supports custom illustrations
+   - Action buttons with loading states
+   - TypeScript with proper props
+
+Create: src/components/ui/EmptyState.tsx with all variants`,
+    });
+  }
+
+  const hasToast = await findFile(searchPath, /Toast|Notification|Snackbar|Toaster/i);
+  if (!hasToast && !toastLib && !projectType.uiLibrary) {
+    issues.push({
+      id: "missing-toast",
+      category: "Frontend",
+      severity: adjustSeverity("high", projectType, "missing-toast"),
+      title: "Missing Toast/Notification System",
+      description: "No toast or notification component found for user feedback.",
+      suggestion: toastLib
+        ? `Consider using the ${toastLib} library you have installed.`
+        : "Add a toast/notification system for user feedback on actions.",
+      autoFixable: true,
+      confidence: 0.75,
+      aiPrompt: `Create a complete Toast notification system with:
+
+1. Toast component with:
+   - Variants: success, error, warning, info, loading
+   - Auto-dismiss with configurable duration
+   - Manual dismiss button
+   - Progress bar showing time remaining
+   - Stack multiple toasts
+   - Position options: top-right, top-center, bottom-right, etc.
+
+2. Toast provider/context:
+   - useToast() hook for easy triggering
+   - toast.success(), toast.error(), etc. methods
+   - toast.promise() for async operations
+   - Global configuration
+
+3. Features:
+   - Smooth slide-in/out animations
+   - Swipe to dismiss on mobile
+   - Pause on hover
+   - Accessible with ARIA live regions
+   - Queue management
+   - TypeScript with proper types
+
+Create: src/components/ui/Toast.tsx and src/hooks/useToast.ts`,
+    });
+  }
+
+  // ── Forms & Input Feedback ───────────────────────────────────────────────
+
+  const hasFormValidation = await findFile(searchPath, /FormError|FieldError|ValidationMessage/i);
+  if (!hasFormValidation && !formLib && !projectType.uiLibrary) {
+    issues.push({
+      id: "missing-form-validation-ui",
+      category: "Frontend",
+      severity: adjustSeverity("high", projectType, "missing-form-validation-ui"),
+      title: "Missing Form Validation UI",
+      description: "No form validation components found. Users need clear feedback on form errors.",
+      suggestion: formLib
+        ? `The ${formLib} library you have installed provides form validation. Make sure to display errors.`
+        : "Add form validation components with clear error states.",
+      autoFixable: true,
+      confidence: 0.65,
+      aiPrompt: `Create a comprehensive form validation UI system with:
+
+1. FormField wrapper component with:
+   - Label with required indicator
+   - Help text / description
+   - Error message display
+   - Success state indicator
+   - Character counter for text inputs
+
+2. Input components with built-in validation states:
+   - TextInput with error/success borders
+   - SelectInput with validation
+   - Checkbox/Radio with error states
+   - TextArea with validation
+
+3. Validation feedback:
+   - Inline error messages with icons
+   - Shake animation on error
+   - Real-time validation feedback
+   - Form-level error summary
+   - Success checkmark animation
+
+4. Features:
+   - Works with react-hook-form or standalone
+   - Accessible error announcements
+   - Touch-friendly error targets
+   - TypeScript with proper types
+
+Create: src/components/ui/FormField.tsx and related input components`,
+    });
+  }
+
+  // ── Micro-Interactions & Animations ──────────────────────────────────────
+
+  const hasAnimationLib =
+    packageJson && /framer-motion|react-spring|@react-spring|gsap|animejs/i.test(packageJson);
+  const hasAnimations = await findFile(searchPath, /animate|motion|transition|useSpring/i);
+  if (!hasAnimationLib && !hasAnimations) {
+    issues.push({
+      id: "missing-animations",
+      category: "Frontend",
+      severity: "medium",
+      title: "Missing Animation System",
+      description: "No animation library or utilities found. Animations make UX feel polished.",
+      suggestion: "Add framer-motion or CSS animations for micro-interactions.",
+      autoFixable: true,
+      aiPrompt: `Create a lightweight animation system with:
+
+1. CSS animation utilities (no library needed):
+   - Fade in/out
+   - Slide in from directions
+   - Scale up/down
+   - Bounce, pulse, shake
+   - Stagger children animations
+
+2. Animation wrapper components:
+   - <FadeIn> - fade in on mount
+   - <SlideIn direction="up|down|left|right">
+   - <ScaleIn> - scale from 0 to 1
+   - <AnimatePresence> - animate on unmount
+   - <StaggerChildren> - stagger child animations
+
+3. CSS utilities:
+   - .animate-fade-in, .animate-slide-up, etc.
+   - Animation delay utilities
+   - Reduced motion media query support
+   - Duration and easing variables
+
+4. Hooks:
+   - useInView() - trigger animation when element is visible
+   - useAnimation() - programmatic control
+
+Create: src/styles/animations.css and src/components/ui/Animate.tsx
+
+Or install framer-motion: npm install framer-motion`,
+    });
+  }
+
+  const cssFiles = await findAllFiles(searchPath, /\.(css|scss|tsx?|jsx?)$/);
+  let foundHoverStates = false;
+  for (const file of cssFiles.slice(0, 20)) {
+    const content = await readFileSafe(file);
+    if (content && /:hover|onMouseEnter|hover:/i.test(content)) {
+      foundHoverStates = true;
+      break;
+    }
+  }
+  if (!foundHoverStates) {
+    issues.push({
+      id: "missing-hover-states",
+      category: "Frontend",
+      severity: "medium",
+      title: "Missing Hover States",
+      description: "No hover effects detected. Interactive elements need visual feedback on hover.",
+      suggestion: "Add hover states to buttons, links, and interactive elements.",
+      autoFixable: true,
+      aiPrompt: `Add comprehensive hover states to your components:
+
+1. Button hover effects:
+   - Subtle background color shift
+   - Slight scale transform (1.02)
+   - Shadow elevation change
+   - Underline animation for text buttons
+
+2. Card hover effects:
+   - Lift effect with shadow
+   - Border color change
+   - Subtle background shift
+   - Scale transform
+
+3. Link hover effects:
+   - Underline animation (slide in)
+   - Color transition
+   - Arrow/icon movement
+
+4. Interactive elements:
+   - Focus-visible states (keyboard users)
+   - Active/pressed states
+   - Disabled state styling
+
+5. CSS utilities to add:
+\`\`\`css
+.hover-lift:hover {
+  transform: translateY(-2px);
+  box-shadow: 0 4px 12px rgba(0,0,0,0.15);
+}
+
+.hover-scale:hover {
+  transform: scale(1.02);
+}
+
+.hover-glow:hover {
+  box-shadow: 0 0 20px rgba(var(--primary-rgb), 0.3);
+}
+\`\`\`
+
+Add to: src/styles/interactions.css or your global styles`,
+    });
+  }
+
+  // ── Haptic Feedback & Mobile UX ──────────────────────────────────────────
+
+  const hasHapticFeedback = await findFile(searchPath, /haptic|vibrate|navigator\.vibrate/i);
+  if (!hasHapticFeedback) {
+    issues.push({
+      id: "missing-haptic-feedback",
+      category: "Frontend",
+      severity: "low",
+      title: "Missing Haptic Feedback",
+      description: "No haptic feedback found. Mobile users benefit from tactile feedback on interactions.",
+      suggestion: "Add haptic feedback for key interactions on mobile.",
+      autoFixable: true,
+      aiPrompt: `Create a haptic feedback utility system:
+
+1. useHaptic() hook:
+\`\`\`typescript
+const useHaptic = () => {
+  const trigger = (type: 'light' | 'medium' | 'heavy' | 'success' | 'error') => {
+    if (!navigator.vibrate) return;
+    const patterns = {
+      light: [10],
+      medium: [20],
+      heavy: [30],
+      success: [10, 50, 10],
+      error: [50, 30, 50, 30, 50],
+    };
+    navigator.vibrate(patterns[type]);
+  };
+  return { trigger };
+};
+\`\`\`
+
+2. Integration points:
+   - Button clicks (light)
+   - Form submission success (success)
+   - Form validation error (error)
+   - Toggle switches (light)
+   - Pull-to-refresh complete (medium)
+   - Delete/destructive actions (heavy)
+
+Create: src/hooks/useHaptic.ts`,
+    });
+  }
+
+  const hasPullToRefresh = await findFile(searchPath, /PullToRefresh|pull-to-refresh|usePullRefresh/i);
+  if (!hasPullToRefresh && packageJson && /react-native|mobile|pwa/i.test(packageJson)) {
+    issues.push({
+      id: "missing-pull-refresh",
+      category: "Frontend",
+      severity: "low",
+      title: "Missing Pull-to-Refresh",
+      description: "No pull-to-refresh found. Mobile/PWA apps benefit from this gesture.",
+      suggestion: "Add pull-to-refresh for mobile list views.",
+      autoFixable: true,
+      aiPrompt: `Create a pull-to-refresh component for mobile:
+
+1. PullToRefresh wrapper component:
+   - Touch gesture detection
+   - Visual pull indicator
+   - Loading spinner during refresh
+   - Haptic feedback on trigger
+   - Smooth animations
+
+2. Features:
+   - Configurable pull threshold
+   - Custom pull indicator
+   - Callback on refresh
+   - Disable on desktop
+
+Create: src/components/ui/PullToRefresh.tsx`,
+    });
+  }
+
+  // ── Accessibility (ARIA & A11Y) ──────────────────────────────────────────
+
+  const hasAriaLive = await findFile(searchPath, /aria-live|role="alert"|role="status"/i);
+  if (!hasAriaLive) {
+    issues.push({
+      id: "missing-aria-live",
+      category: "Frontend",
+      severity: "high",
+      title: "Missing ARIA Live Regions",
+      description: "No ARIA live regions found. Screen readers won't announce dynamic content changes.",
+      suggestion: "Add aria-live regions for toasts, alerts, and dynamic updates.",
+      autoFixable: true,
+      aiPrompt: `Add ARIA live regions for accessibility:
+
+1. Create an Announcer component for screen readers:
+\`\`\`tsx
+const Announcer = () => {
+  const [message, setMessage] = useState('');
+  useEffect(() => {
+    window.announce = (msg: string) => setMessage(msg);
+    return () => delete window.announce;
+  }, []);
+  return (
+    <div role="status" aria-live="polite" aria-atomic="true" className="sr-only">
+      {message}
+    </div>
+  );
+};
+\`\`\`
+
+2. Places to add aria-live:
+   - Toast notifications: aria-live="polite"
+   - Error alerts: aria-live="assertive"
+   - Loading states: aria-live="polite" aria-busy="true"
+   - Search results count
+   - Form validation errors
+
+Create: src/components/ui/Announcer.tsx`,
+    });
+  }
+
+  const hasFocusTrap = await findFile(searchPath, /FocusTrap|focus-trap|useFocusTrap/i);
+  const hasModal = await findFile(searchPath, /Modal|Dialog|Drawer/i);
+  if (hasModal && !hasFocusTrap) {
+    issues.push({
+      id: "missing-focus-trap",
+      category: "Frontend",
+      severity: "high",
+      title: "Missing Focus Trap for Modals",
+      description: "Modal/Dialog found but no focus trap. Keyboard users can tab outside the modal.",
+      suggestion: "Add focus trap to modals and dialogs.",
+      autoFixable: true,
+      aiPrompt: `Add focus trapping to modals and dialogs:
+
+1. Create useFocusTrap hook that:
+   - Traps Tab/Shift+Tab within the modal
+   - Focuses first focusable element on open
+   - Returns focus to trigger element on close
+   - Handles Escape key to close
+   - Prevents body scroll when open
+   - Sets aria-modal="true" on modal
+
+Create: src/hooks/useFocusTrap.ts`,
+    });
+  }
+
+  const hasSkipLink = await findFile(searchPath, /SkipLink|skip-to-content|skip-nav/i);
+  if (!hasSkipLink) {
+    issues.push({
+      id: "missing-skip-link",
+      category: "Frontend",
+      severity: "medium",
+      title: "Missing Skip Link",
+      description: "No skip-to-content link found. Keyboard users can't skip navigation.",
+      suggestion: "Add a skip-to-main-content link at the top of pages.",
+      autoFixable: true,
+      aiPrompt: `Add a skip link for keyboard navigation:
+
+\`\`\`tsx
+export const SkipLink = () => (
+  <a href="#main-content" className="skip-link">
+    Skip to main content
+  </a>
+);
+\`\`\`
+
+Place at the very top of your layout, before the header.
+Add id="main-content" to your <main> element.`,
+    });
+  }
+
+  // ── Caching & Performance ────────────────────────────────────────────────
+
+  const hasSWR = packageJson && /swr|@tanstack\/react-query|react-query/i.test(packageJson);
+  if (!hasSWR) {
+    issues.push({
+      id: "missing-data-caching",
+      category: "Frontend",
+      severity: "high",
+      title: "Missing Data Caching Library",
+      description: "No SWR or React Query found. Data fetching lacks caching, revalidation, and deduplication.",
+      suggestion: "Add SWR or TanStack Query for data caching and synchronization.",
+      autoFixable: false,
+      aiPrompt: `Add a data fetching and caching solution:
+
+Option 1: SWR (lighter weight) - npm install swr
+Option 2: TanStack Query (more features) - npm install @tanstack/react-query
+
+Benefits: automatic caching, background revalidation, request deduplication, optimistic updates, offline support, retry logic.`,
+    });
+  }
+
+  const hasMemoization = await findFile(searchPath, /useMemo|useCallback|React\.memo/i);
+  if (!hasMemoization) {
+    issues.push({
+      id: "missing-memoization",
+      category: "Frontend",
+      severity: "low",
+      title: "No Memoization Detected",
+      description: "No useMemo/useCallback/React.memo usage found. May have unnecessary re-renders.",
+      suggestion: "Review components for memoization opportunities.",
+      autoFixable: false,
+      aiPrompt: `Review components for memoization opportunities:
+- useMemo for expensive calculations
+- useCallback for functions passed as props
+- React.memo for components receiving same props
+Focus on: list items, charts, components receiving objects/arrays as props.`,
+    });
+  }
+
+  // ── Logging & Debugging ──────────────────────────────────────────────────
+
+  const hasLogger = await findFile(searchPath, /logger|logging|winston|pino|loglevel/i);
+  if (!hasLogger) {
+    issues.push({
+      id: "missing-frontend-logger",
+      category: "Frontend",
+      severity: "medium",
+      title: "Missing Logging System",
+      description: "No structured logging found. console.log statements are not suitable for production.",
+      suggestion: "Add a logging utility that can be disabled in production.",
+      autoFixable: true,
+      aiPrompt: `Create a frontend logging utility (lib/logger.ts) with:
+- Log levels: debug, info, warn, error
+- Silent in production (except warn/error)
+- Error-level logs sent to error tracking service
+- Performance timing helpers (time/timeEnd)
+- Group logging support`,
+    });
+  }
+
+  const hasErrorTracking =
+    packageJson && /sentry|bugsnag|rollbar|logrocket|@sentry/i.test(packageJson);
+  if (!hasErrorTracking) {
+    issues.push({
+      id: "missing-error-tracking",
+      category: "Frontend",
+      severity: "high",
+      title: "Missing Error Tracking",
+      description: "No error tracking service found. Production errors will go unnoticed.",
+      suggestion: "Add Sentry, Bugsnag, or similar for production error monitoring.",
+      autoFixable: false,
+      aiPrompt: `Set up error tracking with Sentry:
+1. npm install @sentry/nextjs
+2. npx @sentry/wizard@latest -i nextjs
+3. Configure SENTRY_DSN and SENTRY_AUTH_TOKEN env vars
+4. Integrate with error boundary
+5. Set user context on auth`,
+    });
+  }
+
+  // ── Image & Media Optimization ───────────────────────────────────────────
+
+  const hasLazyImages = await findFile(searchPath, /loading="lazy"|LazyImage|Image.*priority/i);
+  if (!hasLazyImages) {
+    issues.push({
+      id: "missing-lazy-images",
+      category: "Frontend",
+      severity: "medium",
+      title: "Missing Lazy Loading for Images",
+      description: "No lazy loading for images detected. All images load immediately.",
+      suggestion: "Add lazy loading to below-the-fold images.",
+      autoFixable: true,
+      aiPrompt: `Implement lazy loading for images:
+- Next.js: Use next/image (lazy by default, add priority for above-fold)
+- Regular img: Add loading="lazy" decoding="async"
+- Create a LazyImage wrapper component`,
+    });
+  }
+
+  // ── Theme & Dark Mode ────────────────────────────────────────────────────
+
+  const hasDarkMode = await findFile(searchPath, /dark-mode|darkMode|theme-toggle|ThemeProvider|useTheme/i);
+  if (!hasDarkMode) {
+    issues.push({
+      id: "missing-dark-mode",
+      category: "Frontend",
+      severity: "low",
+      title: "Missing Dark Mode Support",
+      description: "No dark mode implementation found. Many users prefer dark mode.",
+      suggestion: "Add dark mode toggle with system preference detection.",
+      autoFixable: true,
+      aiPrompt: `Implement dark mode with system preference detection:
+1. ThemeProvider context + useTheme hook
+2. CSS variables for light/dark themes
+3. System preference detection via prefers-color-scheme
+4. Persist choice in localStorage
+5. Theme toggle component`,
+    });
+  }
+
+  // ── Confirmation & Destructive Actions ───────────────────────────────────
+
+  const hasConfirmDialog = await findFile(searchPath, /ConfirmDialog|Confirm|AlertDialog|useConfirm/i);
+  if (!hasConfirmDialog) {
+    issues.push({
+      id: "missing-confirm-dialog",
+      category: "Frontend",
+      severity: "high",
+      title: "Missing Confirmation Dialog",
+      description: "No confirmation dialog found. Destructive actions should require confirmation.",
+      suggestion: "Add a confirmation dialog for delete, logout, and irreversible actions.",
+      autoFixable: true,
+      aiPrompt: `Create a confirmation dialog system:
+1. ConfirmDialog component with danger/warning/info variants
+2. useConfirm() hook returning a promise-based API:
+   const shouldDelete = await confirm({ title: 'Delete?', message: '...' });
+3. Loading state support on confirm button
+4. Focus trap and keyboard handling`,
+    });
+  }
+
+  // ── Optimistic Updates ───────────────────────────────────────────────────
+
+  const hasOptimisticUpdates = await findFile(searchPath, /optimistic|mutate.*onMutate|useMutation/i);
+  if (!hasOptimisticUpdates && hasSWR) {
+    issues.push({
+      id: "missing-optimistic-updates",
+      category: "Frontend",
+      severity: "low",
+      title: "No Optimistic Updates",
+      description: "Data mutations may feel slow without optimistic updates.",
+      suggestion: "Add optimistic updates for better perceived performance.",
+      autoFixable: false,
+      aiPrompt: `Implement optimistic updates for mutations with SWR or TanStack Query.
+Pattern: update cache immediately, send request, revert on error.`,
+    });
+  }
+
+  // ── Keyboard Shortcuts ───────────────────────────────────────────────────
+
+  const hasKeyboardShortcuts = await findFile(searchPath, /useHotkeys|Keyboard|shortcut|Cmd\+|Ctrl\+/i);
+  if (!hasKeyboardShortcuts) {
+    issues.push({
+      id: "missing-keyboard-shortcuts",
+      category: "Frontend",
+      severity: "low",
+      title: "Missing Keyboard Shortcuts",
+      description: "No keyboard shortcuts detected. Power users benefit from keyboard navigation.",
+      suggestion: "Add keyboard shortcuts for common actions.",
+      autoFixable: true,
+      aiPrompt: `Implement keyboard shortcuts:
+1. useHotkey hook with cross-platform Cmd/Ctrl support
+2. Common shortcuts: Cmd+K (search), Cmd+S (save), Escape (close), ? (help)
+3. Display shortcut hints in UI via <kbd> elements`,
+    });
+  }
+
+  // ── Scroll Behavior ──────────────────────────────────────────────────────
+
+  const hasScrollToTop = await findFile(searchPath, /ScrollToTop|scroll-to-top|BackToTop/i);
+  if (!hasScrollToTop) {
+    issues.push({
+      id: "missing-scroll-to-top",
+      category: "Frontend",
+      severity: "low",
+      title: "Missing Scroll-to-Top Button",
+      description: "No scroll-to-top button found. Long pages need easy navigation back to top.",
+      suggestion: "Add a scroll-to-top button for long pages.",
+      autoFixable: true,
+      aiPrompt: `Create a scroll-to-top button:
+- Show after scrolling 500px
+- Smooth scroll animation
+- Fixed position bottom-right
+- Accessible with aria-label`,
+    });
+  }
+
+  // ── Progress Indicators ──────────────────────────────────────────────────
+
+  const hasProgressBar = await findFile(searchPath, /Progress|ProgressBar|NProgress|nprogress/i);
+  if (!hasProgressBar) {
+    issues.push({
+      id: "missing-progress-bar",
+      category: "Frontend",
+      severity: "medium",
+      title: "Missing Progress Indicators",
+      description: "No progress bar found. Users need visual feedback for page transitions and uploads.",
+      suggestion: "Add progress bar for navigation and long operations.",
+      autoFixable: true,
+      aiPrompt: `Add progress indicators:
+1. NProgress-style page transition bar (npm install nprogress)
+2. Custom ProgressBar component with role="progressbar"
+3. File upload progress indicator`,
+    });
+  }
+
+  return issues;
+};