@elsahafy/ux-mcp-server 2.0.0

package/knowledge/react-patterns.json

@@ -0,0 +1,353 @@
+{
+  "name": "React Component Patterns",
+  "description": "Advanced React patterns for component composition, state management, and performance",
+  "composition_patterns": {
+    "compound_components": {
+      "description": "Components that work together to form a cohesive UI",
+      "use_when": "Building flexible, customizable components (tabs, select, accordion)",
+      "example": "<Tabs>\n  <TabList>\n    <Tab>Tab 1</Tab>\n    <Tab>Tab 2</Tab>\n  </TabList>\n  <TabPanels>\n    <TabPanel>Panel 1</TabPanel>\n    <TabPanel>Panel 2</TabPanel>\n  </TabPanels>\n</Tabs>",
+      "implementation": "Use React.Children or Context to share state",
+      "benefits": [
+        "Flexible API",
+        "Clear component relationships",
+        "Easier to customize"
+      ],
+      "libraries": ["Radix UI", "Reach UI", "Headless UI"]
+    },
+    "render_props": {
+      "description": "Pass function as children/prop to share logic",
+      "use_when": "Need to share behavior with different rendering",
+      "example": "<Mouse>\n  {({ x, y }) => (\n    <div>Mouse position: {x}, {y}</div>\n  )}\n</Mouse>",
+      "modern_alternative": "Custom hooks (usually preferred now)",
+      "still_useful": "When component needs to own the DOM structure"
+    },
+    "higher_order_components": {
+      "description": "Function that takes component, returns enhanced component",
+      "use_when": "Legacy codebases, some library patterns",
+      "example": "const EnhancedComponent = withAuth(MyComponent);",
+      "modern_alternative": "Hooks (strongly preferred)",
+      "drawbacks": [
+        "Wrapper hell",
+        "Props collision",
+        "Hard to follow in DevTools"
+      ],
+      "legacy": "Mostly replaced by hooks, but still used in some libraries"
+    },
+    "custom_hooks": {
+      "description": "Extract and reuse stateful logic",
+      "use_when": "Share logic between components",
+      "naming": "Always start with 'use' prefix",
+      "examples": {
+        "data_fetching": "function useFetch(url) {\n  const [data, setData] = useState(null);\n  const [loading, setLoading] = useState(true);\n  \n  useEffect(() => {\n    fetch(url)\n      .then(res => res.json())\n      .then(setData)\n      .finally(() => setLoading(false));\n  }, [url]);\n  \n  return { data, loading };\n}",
+        "local_storage": "function useLocalStorage(key, initial) {\n  const [value, setValue] = useState(() => {\n    const stored = localStorage.getItem(key);\n    return stored ? JSON.parse(stored) : initial;\n  });\n  \n  useEffect(() => {\n    localStorage.setItem(key, JSON.stringify(value));\n  }, [key, value]);\n  \n  return [value, setValue];\n}"
+      },
+      "best_practices": [
+        "Return values consistently (tuple or object)",
+        "Handle cleanup in useEffect",
+        "Memoize expensive computations",
+        "Follow hooks rules (top level, React functions only)"
+      ]
+    },
+    "slots_pattern": {
+      "description": "Named placeholders for content injection",
+      "implementation": "Props for different content areas",
+      "example": "<Card\n  header={<CardHeader title='Title' />}\n  footer={<CardFooter>Actions</CardFooter>}\n>\n  Card content\n</Card>",
+      "benefits": [
+        "Clear API",
+        "Type-safe with TypeScript",
+        "Better than many boolean props"
+      ]
+    },
+    "provider_pattern": {
+      "description": "Context API for sharing state down tree",
+      "use_when": "Data needed by many nested components (theme, auth, etc.)",
+      "example": "const ThemeContext = createContext();\n\nfunction ThemeProvider({ children }) {\n  const [theme, setTheme] = useState('light');\n  return (\n    <ThemeContext.Provider value={{ theme, setTheme }}>\n      {children}\n    </ThemeContext.Provider>\n  );\n}\n\nfunction useTheme() {\n  const context = useContext(ThemeContext);\n  if (!context) throw new Error('useTheme must be used within ThemeProvider');\n  return context;\n}",
+      "best_practices": [
+        "Split contexts by update frequency",
+        "Provide custom hook for consuming",
+        "Validate context exists",
+        "Memoize context value if expensive"
+      ],
+      "optimization": "Use useMemo for context value to prevent re-renders"
+    }
+  },
+  "state_management": {
+    "local_state": {
+      "use_when": "State only needed in component/small tree",
+      "tools": ["useState", "useReducer"],
+      "example": "const [count, setCount] = useState(0);",
+      "prefer": "Keep state as local as possible"
+    },
+    "lifted_state": {
+      "description": "State shared between siblings via common parent",
+      "use_when": "Multiple components need same state",
+      "pattern": "Lift state to nearest common ancestor"
+    },
+    "url_state": {
+      "description": "State stored in URL (query params, hash)",
+      "use_when": "Need shareable/bookmarkable state (filters, search, pagination)",
+      "benefits": [
+        "Shareable links",
+        "Back button works",
+        "No re-fetch on refresh"
+      ],
+      "libraries": ["React Router", "Next.js router", "TanStack Router"]
+    },
+    "global_state": {
+      "context": {
+        "use_when": "Shared state, low update frequency",
+        "pros": ["Built-in", "No extra library"],
+        "cons": ["Can cause unnecessary re-renders"]
+      },
+      "zustand": {
+        "use_when": "Simple global state",
+        "pros": ["Minimal API", "No providers", "Good DevTools"],
+        "cons": ["Less ecosystem than Redux"]
+      },
+      "redux": {
+        "use_when": "Complex state, time-travel debugging needed",
+        "pros": ["Mature ecosystem", "Excellent DevTools", "Predictable"],
+        "cons": ["Boilerplate", "Learning curve"]
+      },
+      "jotai": {
+        "use_when": "Atomic state management",
+        "pros": ["Minimal boilerplate", "TypeScript-first"],
+        "cons": ["Smaller ecosystem"]
+      },
+      "recommendation": "Start with Context/useState, add library when needed"
+    },
+    "server_state": {
+      "description": "Data from server (different from client state)",
+      "tools": {
+        "react_query": {
+          "use": "Data fetching, caching, synchronization",
+          "features": ["Auto refetch", "Caching", "Optimistic updates", "Infinite scroll"],
+          "recommended": "Yes - industry standard"
+        },
+        "swr": {
+          "use": "Similar to React Query, lighter weight",
+          "features": ["Stale-while-revalidate", "Focus refetch", "Offline support"]
+        },
+        "rtk_query": {
+          "use": "Redux Toolkit's data fetching (if already using Redux)",
+          "integration": "Tight Redux integration"
+        }
+      },
+      "best_practice": "Separate server state from client state"
+    }
+  },
+  "performance_patterns": {
+    "memoization": {
+      "react_memo": {
+        "use": "Prevent re-render if props haven't changed",
+        "example": "const MemoizedComponent = React.memo(MyComponent);",
+        "when": "Expensive render or frequent parent re-renders",
+        "note": "Shallow comparison by default, can provide custom compare"
+      },
+      "use_memo": {
+        "use": "Memoize expensive computations",
+        "example": "const sortedList = useMemo(() => list.sort(compareFn), [list]);",
+        "when": "Expensive calculations, derived data",
+        "avoid": "Don't memoize everything (overhead exists)"
+      },
+      "use_callback": {
+        "use": "Memoize function reference",
+        "example": "const handleClick = useCallback(() => doSomething(), []);",
+        "when": "Passing callback to memoized child or useEffect dependency",
+        "note": "Only needed if child is memoized or in dependency array"
+      }
+    },
+    "code_splitting": {
+      "lazy_loading": {
+        "use": "Load components on demand",
+        "example": "const HeavyComponent = React.lazy(() => import('./HeavyComponent'));\n\nfunction App() {\n  return (\n    <Suspense fallback={<Loading />}>\n      <HeavyComponent />\n    </Suspense>\n  );\n}",
+        "benefits": [
+          "Smaller initial bundle",
+          "Faster first load",
+          "Better Core Web Vitals"
+        ],
+        "use_for": [
+          "Route-based splitting",
+          "Modal/dialog content",
+          "Tabs not initially visible",
+          "Below-fold features"
+        ]
+      },
+      "dynamic_import": {
+        "use": "Load code only when needed",
+        "example": "const handleExport = async () => {\n  const { exportToPDF } = await import('./export');\n  exportToPDF(data);\n};"
+      }
+    },
+    "virtualization": {
+      "description": "Render only visible items in long lists",
+      "use_when": "Lists with 100+ items",
+      "libraries": [
+        "react-window (recommended, lightweight)",
+        "react-virtualized (feature-rich, larger)",
+        "TanStack Virtual (framework agnostic)"
+      ],
+      "benefit": "Massive performance improvement for long lists",
+      "example": "<FixedSizeList\n  height={600}\n  itemCount={1000}\n  itemSize={35}\n>\n  {({ index, style }) => <div style={style}>Row {index}</div>}\n</FixedSizeList>"
+    },
+    "debounce_throttle": {
+      "debounce": {
+        "use": "Wait for user to stop typing before action",
+        "example": "Search input - wait 300ms after last keystroke",
+        "implementation": "useDeferredValue or custom hook with setTimeout"
+      },
+      "throttle": {
+        "use": "Limit frequency of function calls",
+        "example": "Scroll/resize handlers - max once per 100ms",
+        "implementation": "Custom hook or library (lodash)"
+      }
+    },
+    "suspense": {
+      "description": "Declarative loading states",
+      "use": "With React.lazy and data fetching (future)",
+      "example": "<Suspense fallback={<Skeleton />}>\n  <AsyncComponent />\n</Suspense>",
+      "benefits": [
+        "Declarative loading",
+        "Better UX with skeletons",
+        "Coordinates multiple async components"
+      ]
+    },
+    "transitions": {
+      "use_transition": {
+        "use": "Mark updates as non-urgent",
+        "example": "const [isPending, startTransition] = useTransition();\n\nstartTransition(() => {\n  setSearchResults(heavyFilter(query));\n});",
+        "benefit": "Keep UI responsive during heavy updates"
+      },
+      "use_deferred_value": {
+        "use": "Defer updating a value",
+        "example": "const deferredQuery = useDeferredValue(query);",
+        "benefit": "Similar to useTransition, for values instead of updates"
+      }
+    }
+  },
+  "data_fetching_patterns": {
+    "fetch_on_render": {
+      "description": "Fetch data in useEffect",
+      "example": "useEffect(() => {\n  fetch('/api/data').then(r => r.json()).then(setData);\n}, []);",
+      "issues": [
+        "Waterfall requests",
+        "No caching",
+        "Manual loading/error states"
+      ],
+      "better": "Use React Query or SWR"
+    },
+    "fetch_then_render": {
+      "description": "Fetch before rendering component",
+      "use": "Server-side rendering, route loaders",
+      "example": "Next.js getServerSideProps, Remix loaders"
+    },
+    "render_as_fetch": {
+      "description": "Start fetching when component renders (Suspense)",
+      "future": "React Server Components",
+      "benefit": "Parallel data fetching"
+    },
+    "prefetching": {
+      "description": "Load data before it's needed",
+      "use_when": "Predictable user paths (hover link, pagination)",
+      "example": "const queryClient = useQueryClient();\nqueryClient.prefetchQuery({ queryKey: ['post', id] });"
+    },
+    "optimistic_updates": {
+      "description": "Update UI before server confirms",
+      "use_when": "Good network, recoverable actions (like, vote)",
+      "example": "mutation.mutate(newData, {\n  onMutate: async (newData) => {\n    await queryClient.cancelQueries(['posts']);\n    const prev = queryClient.getQueryData(['posts']);\n    queryClient.setQueryData(['posts'], old => [...old, newData]);\n    return { prev };\n  },\n  onError: (err, newData, context) => {\n    queryClient.setQueryData(['posts'], context.prev);\n  }\n});",
+      "benefit": "Instant feedback, better UX"
+    }
+  },
+  "error_handling": {
+    "error_boundary": {
+      "description": "Catch React errors in component tree",
+      "example": "class ErrorBoundary extends React.Component {\n  state = { hasError: false };\n  \n  static getDerivedStateFromError(error) {\n    return { hasError: true };\n  }\n  \n  componentDidCatch(error, info) {\n    console.error('Error:', error, info);\n  }\n  \n  render() {\n    if (this.state.hasError) {\n      return <ErrorFallback />;\n    }\n    return this.props.children;\n  }\n}",
+      "use": "Wrap app sections to prevent full app crash",
+      "note": "Only catches render errors, not async or event handlers",
+      "libraries": ["react-error-boundary (recommended)"]
+    },
+    "async_error_handling": {
+      "try_catch": "Wrap async calls in try-catch",
+      "react_query": "Built-in error handling",
+      "example": "const { data, error, isError } = useQuery({\n  queryKey: ['posts'],\n  queryFn: fetchPosts,\n  retry: 3\n});\n\nif (isError) return <ErrorMessage error={error} />;"
+    }
+  },
+  "accessibility_patterns": {
+    "focus_management": {
+      "use_ref": "Get reference to DOM elements",
+      "focus_trap": "Keep focus inside modal",
+      "restore_focus": "Return focus after closing modal",
+      "example": "const previousFocus = useRef();\n\nuseEffect(() => {\n  if (isOpen) {\n    previousFocus.current = document.activeElement;\n    modalRef.current?.focus();\n    return () => previousFocus.current?.focus();\n  }\n}, [isOpen]);"
+    },
+    "keyboard_navigation": {
+      "arrow_keys": "Handle in onKeyDown",
+      "escape": "Close modals, clear search",
+      "enter_space": "Activate buttons/links",
+      "example": "const handleKeyDown = (e) => {\n  if (e.key === 'Escape') close();\n  if (e.key === 'ArrowDown') focusNext();\n};"
+    },
+    "aria_attributes": {
+      "live_regions": "Announce dynamic content",
+      "example": "<div role='status' aria-live='polite'>{message}</div>",
+      "labels": "aria-label, aria-labelledby for context",
+      "states": "aria-expanded, aria-selected, aria-checked"
+    }
+  },
+  "testing_patterns": {
+    "component_testing": {
+      "library": "React Testing Library (recommended)",
+      "principle": "Test behavior, not implementation",
+      "example": "import { render, screen } from '@testing-library/react';\n\ntest('shows error message on failed login', async () => {\n  render(<LoginForm />);\n  await userEvent.click(screen.getByRole('button', { name: 'Login' }));\n  expect(screen.getByText(/invalid credentials/i)).toBeInTheDocument();\n});",
+      "query_priority": [
+        "getByRole (most accessible)",
+        "getByLabelText (forms)",
+        "getByPlaceholderText",
+        "getByText",
+        "getByTestId (last resort)"
+      ]
+    },
+    "mocking": {
+      "api_calls": "Mock fetch with MSW (Mock Service Worker)",
+      "example": "import { rest } from 'msw';\n\nconst handlers = [\n  rest.get('/api/user', (req, res, ctx) => {\n    return res(ctx.json({ name: 'John' }));\n  })\n];"
+    }
+  },
+  "file_organization": {
+    "by_feature": {
+      "structure": "features/auth/\n  components/\n  hooks/\n  utils/\n  index.ts",
+      "recommended": "Yes - scales well"
+    },
+    "by_type": {
+      "structure": "components/\nhooks/\nutils/",
+      "use": "Small apps only"
+    },
+    "colocation": {
+      "principle": "Keep related files together",
+      "example": "Button/\n  Button.tsx\n  Button.test.tsx\n  Button.module.css\n  index.ts",
+      "benefit": "Easy to find everything for a component"
+    }
+  },
+  "best_practices": [
+    "Keep components small and focused (Single Responsibility)",
+    "Prefer composition over prop drilling",
+    "Use TypeScript for type safety",
+    "Memoize only when profiling shows benefit",
+    "Use proper semantic HTML and ARIA",
+    "Handle loading and error states",
+    "Test user behavior, not implementation details",
+    "Use keys properly in lists (stable, unique, not index)",
+    "Avoid prop drilling with Context for deeply nested state",
+    "Split large components into smaller ones",
+    "Use custom hooks to extract logic",
+    "Follow consistent naming conventions"
+  ],
+  "anti_patterns": [
+    "Huge components (> 300 lines)",
+    "Prop drilling 5+ levels deep",
+    "Overusing Context (causes re-renders)",
+    "Premature optimization (memoize everything)",
+    "Using index as key in dynamic lists",
+    "Mutating state directly",
+    "Side effects in render",
+    "Not handling errors",
+    "Missing loading states",
+    "Ignoring accessibility"
+  ]
+}

package/knowledge/responsive-design.json

@@ -0,0 +1,258 @@
+{
+  "name": "Responsive Design Best Practices",
+  "description": "Mobile-first design principles, breakpoints, and responsive patterns",
+  "principles": {
+    "mobile_first": {
+      "description": "Design for mobile devices first, then progressively enhance for larger screens",
+      "rationale": [
+        "Forces focus on core content and features",
+        "Easier to scale up than down",
+        "Better performance on mobile devices",
+        "Mobile traffic often exceeds desktop"
+      ],
+      "implementation": {
+        "css_approach": "Base styles for mobile, media queries for desktop",
+        "example": "/* Mobile first (no media query) */\n.container { padding: 1rem; }\n\n/* Tablet and up */\n@media (min-width: 768px) {\n  .container { padding: 2rem; }\n}\n\n/* Desktop and up */\n@media (min-width: 1024px) {\n  .container { padding: 3rem; }\n}"
+      }
+    },
+    "breakpoints": {
+      "description": "Common device breakpoints for responsive layouts",
+      "standard_breakpoints": {
+        "mobile": "0px - 639px",
+        "tablet": "640px - 1023px",
+        "desktop": "1024px - 1279px",
+        "wide": "1280px+"
+      },
+      "tailwind_breakpoints": {
+        "sm": "640px",
+        "md": "768px",
+        "lg": "1024px",
+        "xl": "1280px",
+        "2xl": "1536px"
+      },
+      "bootstrap_breakpoints": {
+        "xs": "< 576px",
+        "sm": "576px",
+        "md": "768px",
+        "lg": "992px",
+        "xl": "1200px",
+        "xxl": "1400px"
+      },
+      "best_practices": [
+        "Design for content, not specific devices",
+        "Use 3-4 breakpoints maximum",
+        "Test actual devices, not just browser resize",
+        "Consider landscape orientations",
+        "Use relative units (rem, em) over px"
+      ]
+    },
+    "viewport_meta": {
+      "description": "Essential viewport configuration for mobile",
+      "required": "<meta name='viewport' content='width=device-width, initial-scale=1'>",
+      "explanation": {
+        "width=device-width": "Match screen width (prevents zoom out)",
+        "initial-scale=1": "No zoom on page load"
+      },
+      "avoid": {
+        "user-scalable=no": "Prevents pinch zoom (accessibility issue)",
+        "maximum-scale=1": "Prevents zoom (accessibility issue)"
+      }
+    },
+    "touch_targets": {
+      "description": "Minimum sizes for touch interactions",
+      "requirements": {
+        "minimum": "44x44px (Apple) or 48x48px (Android)",
+        "recommended": "48x48px minimum for all platforms",
+        "spacing": "8px minimum between targets"
+      },
+      "implementation": [
+        "Add padding to increase touch area",
+        "Use ::before/::after for larger hitbox",
+        "Avoid placing small targets near edges",
+        "Consider thumb zones on mobile"
+      ]
+    }
+  },
+  "responsive_patterns": {
+    "navigation": {
+      "mobile": {
+        "hamburger_menu": {
+          "when_to_use": "5+ navigation items",
+          "structure": "Hamburger icon → Full-screen or slide-in menu",
+          "best_practices": [
+            "Icon should be 44x44px minimum",
+            "Clearly labeled (aria-label='Menu')",
+            "Show/hide with smooth transition",
+            "Close button or overlay dismiss",
+            "Prevent body scroll when open"
+          ]
+        },
+        "bottom_navigation": {
+          "when_to_use": "Mobile apps, 3-5 primary destinations",
+          "structure": "Fixed bottom bar with icons + labels",
+          "best_practices": [
+            "Icons with text labels",
+            "Current page highlighted",
+            "56-72px height recommended",
+            "3-5 items only"
+          ]
+        }
+      },
+      "tablet_desktop": {
+        "horizontal_nav": "Traditional header navigation",
+        "sidebar": "Persistent side navigation for apps"
+      }
+    },
+    "layout": {
+      "single_column": {
+        "mobile": "All content stacks vertically",
+        "implementation": "Default layout, no grid needed"
+      },
+      "multi_column": {
+        "tablet": "2-column layouts",
+        "desktop": "3-4 column layouts",
+        "implementation": "CSS Grid or Flexbox with media queries"
+      },
+      "grid_examples": {
+        "responsive_grid": "/* Mobile: 1 column */\n.grid {\n  display: grid;\n  gap: 1rem;\n}\n\n/* Tablet: 2 columns */\n@media (min-width: 768px) {\n  .grid {\n    grid-template-columns: repeat(2, 1fr);\n  }\n}\n\n/* Desktop: 3+ columns */\n@media (min-width: 1024px) {\n  .grid {\n    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));\n  }\n}"
+      }
+    },
+    "typography": {
+      "fluid_typography": {
+        "description": "Font sizes that scale with viewport",
+        "implementation": "clamp(min, preferred, max)",
+        "example": "font-size: clamp(1rem, 2.5vw, 2rem);",
+        "benefits": [
+          "Smooth scaling between breakpoints",
+          "No need for multiple media queries",
+          "Better readability across devices"
+        ]
+      },
+      "responsive_scale": {
+        "mobile": "Base size 16px, scale 1.2",
+        "desktop": "Base size 18px, scale 1.25",
+        "implementation": "Adjust root font-size at breakpoints"
+      }
+    },
+    "images": {
+      "responsive_images": {
+        "srcset": {
+          "description": "Provide multiple image sizes",
+          "example": "<img\n  src='image-800.jpg'\n  srcset='image-400.jpg 400w,\n          image-800.jpg 800w,\n          image-1200.jpg 1200w'\n  sizes='(max-width: 768px) 100vw,\n         (max-width: 1024px) 50vw,\n         800px'\n  alt='Description'\n/>"
+        },
+        "picture": {
+          "description": "Art direction or format switching",
+          "example": "<picture>\n  <source media='(max-width: 768px)' srcset='mobile.jpg'>\n  <source media='(max-width: 1024px)' srcset='tablet.jpg'>\n  <img src='desktop.jpg' alt='Description'>\n</picture>"
+        },
+        "css_background": {
+          "example": ".hero {\n  background-image: url('mobile.jpg');\n}\n\n@media (min-width: 768px) {\n  .hero {\n    background-image: url('desktop.jpg');\n  }\n}"
+        }
+      },
+      "lazy_loading": {
+        "native": "<img src='image.jpg' loading='lazy' alt='Description'>",
+        "best_for": "Below-the-fold images",
+        "avoid": "Above-the-fold or LCP images"
+      }
+    },
+    "forms": {
+      "mobile_optimization": [
+        "Large input fields (min 44px height)",
+        "Appropriate input types (tel, email, number)",
+        "Reduce form fields to minimum",
+        "Use autocomplete attributes",
+        "Large, tappable submit buttons",
+        "Inline validation",
+        "Auto-advance for OTP/PIN inputs"
+      ],
+      "input_types": {
+        "tel": "Numeric keyboard with tel symbols",
+        "email": "Keyboard with @ and .",
+        "number": "Numeric keypad",
+        "url": "Keyboard with / and .com",
+        "search": "Shows search action in keyboard",
+        "date": "Native date picker"
+      }
+    },
+    "tables": {
+      "responsive_strategies": [
+        {
+          "name": "Horizontal Scroll",
+          "when": "Few columns with important data",
+          "implementation": "overflow-x: auto on container"
+        },
+        {
+          "name": "Stack Columns",
+          "when": "2-3 columns",
+          "implementation": "Convert to vertical layout on mobile"
+        },
+        {
+          "name": "Card View",
+          "when": "Many columns",
+          "implementation": "Display each row as a card"
+        },
+        {
+          "name": "Hide Columns",
+          "when": "Non-critical columns",
+          "implementation": "Show only essential columns on mobile"
+        }
+      ],
+      "card_transform_example": "/* Desktop table */\ntable { display: table; }\n\n/* Mobile cards */\n@media (max-width: 768px) {\n  table, thead, tbody, tr, th, td {\n    display: block;\n  }\n  \n  tr {\n    margin-bottom: 1rem;\n    border: 1px solid #e5e7eb;\n    border-radius: 0.5rem;\n  }\n  \n  td::before {\n    content: attr(data-label);\n    font-weight: bold;\n  }\n}"
+    }
+  },
+  "testing_checklist": [
+    "Test on real devices (iOS, Android)",
+    "Check all breakpoints",
+    "Test portrait and landscape",
+    "Verify touch targets (44x44px min)",
+    "Test forms with mobile keyboard",
+    "Check image loading and sizes",
+    "Verify navigation works on mobile",
+    "Test with slow 3G network",
+    "Check accessibility on mobile screen readers",
+    "Verify no horizontal scroll",
+    "Test with large font sizes (accessibility)",
+    "Check dark mode if supported"
+  ],
+  "common_mistakes": [
+    {
+      "mistake": "Desktop-first CSS",
+      "problem": "Requires overriding styles for mobile",
+      "solution": "Start with mobile base styles"
+    },
+    {
+      "mistake": "Disabling zoom (user-scalable=no)",
+      "problem": "Accessibility violation (WCAG)",
+      "solution": "Never disable zoom"
+    },
+    {
+      "mistake": "Small touch targets",
+      "problem": "Hard to tap accurately",
+      "solution": "Minimum 44x44px"
+    },
+    {
+      "mistake": "Horizontal scroll",
+      "problem": "Poor mobile UX",
+      "solution": "Use overflow-x: hidden on body, design within viewport"
+    },
+    {
+      "mistake": "Tiny text on mobile",
+      "problem": "Unreadable",
+      "solution": "Minimum 16px font size"
+    },
+    {
+      "mistake": "Loading full desktop images on mobile",
+      "problem": "Slow, wastes data",
+      "solution": "Use srcset or picture element"
+    }
+  ],
+  "performance_tips": [
+    "Lazy load below-the-fold images",
+    "Use modern image formats (WebP, AVIF)",
+    "Minimize CSS and JavaScript",
+    "Avoid render-blocking resources",
+    "Use system fonts when possible",
+    "Implement critical CSS",
+    "Reduce network requests",
+    "Use CSS instead of JavaScript animations"
+  ]
+}