raven-mcp 1.0.0

package/src/data/patterns/forms.json

@@ -0,0 +1,53 @@
+{
+  "id": "forms",
+  "name": "Form Design",
+  "category": "usability",
+  "summary": "Form patterns that minimize friction, prevent errors, and maximize completion rates.",
+  "principles_referenced": ["fitts-law", "hicks-law", "millers-law", "postels-law", "error-prevention", "teslers-law"],
+  "patterns": [
+    {
+      "name": "Single-column layout",
+      "description": "All form fields in a single vertical column. Users process forms top-to-bottom. Multi-column layouts break the scanning pattern and cause field-skipping errors.",
+      "do": ["Stack all fields vertically in a single column", "Left-align labels above inputs", "Group related fields with section headers", "Use full-width inputs (or consistent widths)"],
+      "dont": ["Use multi-column form layouts (except very short paired fields like city/state)", "Place labels to the left of inputs on forms with 5+ fields", "Mix label positions (some above, some inline, some left)"],
+      "evidence": "Single-column forms are completed 15.4 seconds faster than multi-column equivalents (CXL research). Eye-tracking shows multi-column causes 50% more field-skipping errors."
+    },
+    {
+      "name": "Inline validation",
+      "description": "Validate fields as the user fills them out, showing success or error states in real time. Validates on blur (leaving the field) not on every keystroke.",
+      "do": ["Validate on blur (when the user leaves the field)", "Show error messages directly below the field", "Use color + icon + text for error states (not color alone)", "Show success state for validated fields (green checkmark)", "Keep error messages specific and actionable"],
+      "dont": ["Validate on every keystroke (shows errors while user is still typing)", "Show errors only on form submission", "Use generic errors ('Invalid input') — be specific", "Remove the user's input on error — let them correct it"],
+      "evidence": "Inline validation reduces form errors by 22% and completion time by 42% compared to submit-only validation (Luke Wroblewski)."
+    },
+    {
+      "name": "Smart defaults and auto-detection",
+      "description": "Pre-fill fields with smart defaults whenever possible. Auto-detect country, timezone, currency. Use browser autocomplete. Reduce the number of fields the user must actively fill.",
+      "do": ["Set autocomplete attributes on all relevant fields", "Auto-detect country from IP or browser locale", "Pre-fill with previously entered data when editing", "Default to the most common option for radio/select fields", "Auto-format inputs (phone numbers, credit cards)"],
+      "dont": ["Pre-fill fields with placeholder text that must be cleared", "Auto-detect and hide the field — show it pre-filled so users can verify", "Default to an option that could cause data issues if not changed", "Pre-fill marketing opt-in checkboxes (dark pattern, often illegal)"],
+      "evidence": "Auto-filling reduces form completion time by 30% and errors by 25%. Google found that users complete forms 30% faster with autofill."
+    },
+    {
+      "name": "Progressive form disclosure",
+      "description": "Show only the fields relevant to the user's previous selections. Conditional fields appear/disappear based on prior answers. Reduces visible complexity.",
+      "do": ["Show conditional fields only when triggered by a prior selection", "Animate the appearance of new fields (slide down, fade in)", "Group optional fields under an 'Advanced' or 'More options' toggle", "Pre-fill conditional fields with smart defaults"],
+      "dont": ["Show all fields including conditional ones with disable states", "Remove previously answered fields when new ones appear", "Use confusing conditional logic — the user should understand why fields appeared", "Hide required fields behind toggles"],
+      "evidence": "Progressive disclosure reduces perceived form complexity by 40% and increases completion rates by 20-30%."
+    }
+  ],
+  "checklist": [
+    "Is the form single-column layout?",
+    "Are labels positioned above inputs?",
+    "Does every field have a visible label (not just placeholder text)?",
+    "Is inline validation implemented (on blur)?",
+    "Are error messages specific, actionable, and positioned below the field?",
+    "Are appropriate input types used (email, tel, url, number)?",
+    "Are autocomplete attributes set on all relevant fields?",
+    "Is the submit button clearly visible and action-oriented?",
+    "Are optional fields marked (or better: removed)?",
+    "Is there a clear way to cancel/abandon the form?",
+    "Does the form work with keyboard only (tab, enter)?",
+    "Is the form mobile-friendly (touch targets, keyboard types)?",
+    "Are smart defaults applied where possible?",
+    "Is sensitive data (password) masked with a show/hide toggle?"
+  ]
+}

package/src/data/patterns/landing-page.json

@@ -0,0 +1,51 @@
+{
+  "id": "landing-page",
+  "name": "Landing Page",
+  "category": "conversion",
+  "summary": "Landing page patterns that communicate value, build trust, and drive conversions.",
+  "principles_referenced": ["aesthetic-usability-effect", "serial-position-effect", "von-restorff-effect", "hicks-law", "peak-end-rule"],
+  "patterns": [
+    {
+      "name": "Hero section",
+      "description": "The first screen a visitor sees. Must communicate what the product does, who it's for, and why they should care — in under 5 seconds. One primary CTA.",
+      "do": ["Clear headline that states the benefit (not the feature)", "Subheadline that adds specificity (who it's for, how it works)", "One primary CTA with high-contrast styling", "Product screenshot, video, or illustration that shows value", "Keep it above the fold — no scrolling required to understand"],
+      "dont": ["Multiple CTAs competing for attention", "Jargon-heavy headline that requires industry knowledge", "Autoplay video with sound", "Headline about the company instead of the user's benefit", "Generic stock photos that don't relate to the product"],
+      "evidence": "Users form an opinion about a page in 50ms. Hero sections with product screenshots convert 80% better than stock photos. Single-CTA heroes outperform multi-CTA by 20%."
+    },
+    {
+      "name": "Social proof section",
+      "description": "Customer logos, testimonials, case studies, ratings, and usage metrics that build trust. Should appear early — ideally as the second section after the hero.",
+      "do": ["Show recognizable customer logos (6-8 is optimal)", "Include testimonials with real names, photos, and titles", "Display specific metrics ('Saved 10 hours/week', not 'Saved time')", "Show aggregate stats ('50,000+ teams trust us')", "Place social proof near CTAs to reduce purchase anxiety"],
+      "dont": ["Use fake or anonymous testimonials", "Show logos without permission", "Use vague testimonials ('Great product!')", "Place all social proof at the bottom of the page", "Show ratings without the number of reviews"],
+      "evidence": "92% of consumers trust peer recommendations over advertising. Testimonials with photos increase trust by 35%. Customer logos increase B2B conversion by 15%."
+    },
+    {
+      "name": "Feature/benefit blocks",
+      "description": "Sections that explain key features through the lens of user benefits. Typically 3-4 features with alternating left/right image+text layout or icon-based grid.",
+      "do": ["Lead with the benefit, follow with the feature", "Use screenshots or illustrations showing the feature in action", "Keep to 3-4 key features — don't list everything", "Use alternating layouts to maintain visual interest", "Each feature gets its own clear section with breathing room"],
+      "dont": ["List 20 features as bullet points", "Use generic icons that don't relate to the feature", "Write feature-first copy ('We have X' vs 'You can do X')", "Cram all features into one section"],
+      "evidence": "Benefit-oriented copy outperforms feature-oriented copy by 20-30%. Limiting to 3-4 features increases recall by 40%."
+    },
+    {
+      "name": "Final CTA section",
+      "description": "A closing section that restates the value proposition and presents the final call to action. This is the 'end' in Peak-End Rule — make it compelling.",
+      "do": ["Restate the core value proposition (different wording from hero)", "Use a high-contrast CTA button", "Address the primary objection ('No credit card required', 'Free for teams under 10')", "Create urgency without manipulation (limited beta, growing community)", "Make it visually distinct from the rest of the page"],
+      "dont": ["Just repeat the hero section verbatim", "Add a lengthy form — keep it to one button", "Introduce new information that should have been earlier", "End with a generic 'Contact us' instead of a clear action"],
+      "evidence": "Pages with a final CTA section have 15% higher conversion than those ending with footer content. Peak-End Rule: the last impression disproportionately affects memory."
+    }
+  ],
+  "checklist": [
+    "Does the hero clearly communicate what the product does in 5 seconds?",
+    "Is there one clear primary CTA above the fold?",
+    "Is there social proof (logos, testimonials) early on the page?",
+    "Are features presented as benefits to the user?",
+    "Is there a product screenshot or demo showing real value?",
+    "Does the page follow a clear narrative arc (problem → solution → proof → action)?",
+    "Is the page responsive and fast-loading on mobile?",
+    "Is there a final CTA section before the footer?",
+    "Are objections addressed near the CTA ('Free trial', 'No credit card')?",
+    "Is the page focused on one goal (not a homepage trying to do everything)?",
+    "Does the page load in under 3 seconds?",
+    "Is there a clear visual hierarchy guiding the user's eye?"
+  ]
+}

package/src/data/patterns/loading-states.json

@@ -0,0 +1,51 @@
+{
+  "id": "loading-states",
+  "name": "Loading States",
+  "category": "usability",
+  "summary": "Patterns for skeleton screens, optimistic UI, and perceived performance that keep users engaged during data loading.",
+  "principles_referenced": ["doherty-threshold", "visibility-of-system-status", "aesthetic-usability-effect"],
+  "patterns": [
+    {
+      "name": "Skeleton screens",
+      "description": "Placeholder UI that mirrors the layout of the content being loaded, using gray shapes. Shows the user what's coming and reduces perceived wait time.",
+      "do": ["Match the skeleton to the actual content layout (cards, text lines, avatars)", "Use subtle animation (shimmer/pulse) to indicate loading", "Show immediately — no spinner before the skeleton", "Transition smoothly from skeleton to real content", "Size skeleton elements to match real content dimensions"],
+      "dont": ["Use generic skeletons that don't match the actual content", "Show a skeleton for more than 3-5 seconds (fall back to a spinner with message)", "Animate too aggressively — a gentle shimmer, not rapid flashing", "Show skeleton screens for instant data (under 200ms)", "Mix skeletons and spinners on the same page"],
+      "evidence": "Skeleton screens reduce perceived loading time by 10-20% compared to spinners. Users rate pages with skeletons as loading faster even when actual load times are identical."
+    },
+    {
+      "name": "Optimistic UI",
+      "description": "Immediately show the result of a user action (like, save, delete) before the server confirms it. Roll back only if the server returns an error.",
+      "do": ["Show the action result immediately", "Send the server request in the background", "Roll back with a clear error message if the server fails", "Use for low-risk, reversible actions (likes, toggles, edits)", "Queue offline actions and sync when connection returns"],
+      "dont": ["Use for irreversible or high-stakes actions (payments, deletes)", "Roll back silently — always inform the user of failures", "Delay the UI update waiting for server confirmation", "Show a loading spinner for actions that can be optimistic"],
+      "evidence": "Optimistic UI makes interfaces feel 2-3x faster. Instagram, Twitter, and Slack all use optimistic updates for likes, sends, and edits."
+    },
+    {
+      "name": "Progressive loading",
+      "description": "Load and display content incrementally as it arrives, rather than waiting for everything before showing anything.",
+      "do": ["Load above-the-fold content first", "Stream in content as it loads (text before images, structure before data)", "Use lazy loading for images and below-fold content", "Show placeholders for content still loading", "Prioritize interactive elements over decorative ones"],
+      "dont": ["Wait for all data before rendering anything", "Load below-fold content eagerly (especially images)", "Lazy-load above-fold content (causes layout shifts)", "Show a blank page while assembling all the data"],
+      "evidence": "Progressive loading improves First Contentful Paint by 30-50%. Users perceive progressively loaded pages as 40% faster than pages that wait for all content."
+    },
+    {
+      "name": "Loading indicators by duration",
+      "description": "Different loading patterns for different expected durations. The right indicator sets correct expectations.",
+      "do": ["Under 200ms: no indicator needed", "200ms-1s: subtle inline indicator (spinner, pulse)", "1-5s: skeleton screen or progress bar", "5-30s: progress bar with percentage or step description", "30s+: background task with notification on completion"],
+      "dont": ["Show a spinner for operations under 200ms (feels glitchy)", "Use a spinner for operations over 5 seconds (no progress information)", "Show indeterminate progress for long operations (users need to estimate time)", "Block the entire UI for operations that could run in the background"],
+      "evidence": "Matching loading indicator to duration reduces perceived wait time by up to 40%. Users abandon tasks after 10 seconds without progress feedback."
+    }
+  ],
+  "checklist": [
+    "Do all data-loading views have a loading state?",
+    "Are skeleton screens used for content-heavy views?",
+    "Is optimistic UI used for low-risk, reversible actions?",
+    "Is above-the-fold content prioritized in loading order?",
+    "Are images lazy-loaded below the fold?",
+    "Is the loading indicator appropriate for the expected duration?",
+    "Do long operations (5s+) show progress percentage or steps?",
+    "Is there a timeout and error state for failed loads?",
+    "Do loading states prevent layout shift when content arrives?",
+    "Are background tasks used for very long operations (30s+)?",
+    "Is content streamed progressively rather than shown all at once?",
+    "Does the app remain interactive during loading when possible?"
+  ]
+}

package/src/data/patterns/mobile-conversion.json

@@ -0,0 +1,51 @@
+{
+  "id": "mobile-conversion",
+  "name": "Mobile Conversion",
+  "category": "conversion",
+  "summary": "Mobile-specific conversion patterns that account for thumb zones, small screens, and on-the-go usage contexts.",
+  "principles_referenced": ["fitts-law", "thumb-zone", "touch-targets", "hicks-law", "doherty-threshold"],
+  "patterns": [
+    {
+      "name": "Sticky mobile CTA",
+      "description": "A persistent CTA button fixed to the bottom of the screen on mobile. Always visible, always in the thumb zone. Essential for landing pages and product pages.",
+      "do": ["Fix to the bottom of the viewport", "Use full-width or near-full-width button", "High-contrast, brand-accent color", "Show/hide intelligently (appear after scroll past hero CTA)", "Include supporting text inline ('Free 14-day trial')"],
+      "dont": ["Cover important content (add bottom padding to compensate)", "Show immediately on page load (wait for initial scroll)", "Use alongside other fixed bottom elements (competing for space)", "Animate distractingly on scroll", "Block the ability to scroll to the footer"],
+      "evidence": "Sticky mobile CTAs increase conversion by 10-15% on long scrolling pages. Most effective when they appear after the user has scrolled past the first CTA."
+    },
+    {
+      "name": "Thumb-friendly checkout",
+      "description": "Mobile checkout flows designed for one-handed use. Large inputs, smart keyboard types, and minimal steps.",
+      "do": ["Use Apple Pay, Google Pay, and Shop Pay as primary options", "Single-column layout with large touch targets", "Appropriate keyboard types (numeric for card, email for email)", "Auto-advance between fields where possible", "Show order summary in a collapsible section"],
+      "dont": ["Require typing credit card numbers when wallet payments are available", "Use multi-column layouts for address forms", "Show a progress indicator with more than 3 steps", "Force account creation before checkout", "Open new tabs/windows during checkout"],
+      "evidence": "Mobile wallet payments convert 2-3x higher than manual card entry. Removing account creation from checkout reduces abandonment by 35%."
+    },
+    {
+      "name": "Simplified mobile forms",
+      "description": "Mobile form optimization: fewer fields, larger inputs, native pickers, and graceful keyboard management.",
+      "do": ["Reduce fields to the absolute minimum", "Use native pickers (date, select) instead of custom ones", "Set inputmode and autocomplete attributes", "Make the submit button visible above the keyboard", "Use a single-field-per-screen pattern for critical flows"],
+      "dont": ["Use custom dropdowns that fight with mobile scrolling", "Show more than 4-5 fields at once on mobile", "Place the submit button where the keyboard hides it", "Use placeholder-only labels (they disappear on focus)", "Require precise input formatting (let the system format)"],
+      "evidence": "Every additional form field on mobile reduces conversion by 3-5%. Native pickers are 40% faster than custom dropdowns on mobile."
+    },
+    {
+      "name": "Bottom sheet actions",
+      "description": "Replace desktop dropdowns and popovers with bottom sheets on mobile. Native to the platform, in the thumb zone, dismissible by swipe.",
+      "do": ["Use for action menus, filters, and selection lists", "Include a drag handle at the top", "Support swipe-down to dismiss", "Limit actions to 5-7 per sheet", "Use icons + labels for quick scanning"],
+      "dont": ["Use desktop-style dropdowns on mobile", "Show more than 7-8 actions without scrolling", "Nest bottom sheets inside bottom sheets", "Use bottom sheets for critical confirmations (use a centered dialog)", "Remove the backdrop tap-to-dismiss behavior"],
+      "evidence": "Bottom sheets have 25% higher task completion than dropdown menus on mobile. They align with native platform patterns (iOS Action Sheet, Material Bottom Sheet)."
+    }
+  ],
+  "checklist": [
+    "Is there a sticky CTA on long scrolling mobile pages?",
+    "Are wallet payments (Apple Pay, Google Pay) offered prominently?",
+    "Are all touch targets at least 44x44px?",
+    "Do forms use appropriate input modes and autocomplete?",
+    "Are dropdown menus replaced with bottom sheets on mobile?",
+    "Is the submit button visible above the virtual keyboard?",
+    "Is the checkout flow 3 steps or fewer?",
+    "Are forms single-column on mobile?",
+    "Can core tasks be completed one-handed?",
+    "Does the page load in under 3 seconds on mobile?",
+    "Are images optimized/lazy-loaded for mobile bandwidth?",
+    "Is font size at least 16px to prevent iOS auto-zoom?"
+  ]
+}

package/src/data/patterns/modals-dialogs.json

@@ -0,0 +1,51 @@
+{
+  "id": "modals-dialogs",
+  "name": "Modals and Dialogs",
+  "category": "usability",
+  "summary": "Patterns for modals, dialogs, and overlay interfaces that focus attention without losing context.",
+  "principles_referenced": ["user-control-freedom", "visibility-of-system-status", "error-prevention", "fitts-law", "gestalt-figure-ground"],
+  "patterns": [
+    {
+      "name": "Confirmation dialog",
+      "description": "A focused dialog that asks the user to confirm a significant or destructive action. Should clearly state what will happen and offer clear accept/cancel options.",
+      "do": ["State the consequence clearly ('This will permanently delete 23 files')", "Use descriptive button labels ('Delete files' not just 'OK')", "Make the destructive action the secondary button style (not primary/colored)", "Use red/destructive styling on the dangerous action button", "Keep the dialog focused — one question, two options"],
+      "dont": ["Use 'Are you sure?' as the only content", "Use 'OK' and 'Cancel' for destructive actions — be specific", "Make the destructive button the primary/default style", "Show confirmation for every minor action (only for destructive/irreversible ones)", "Stack two modals (modal on modal)"],
+      "evidence": "Specific confirmation messages reduce accidental destructive actions by 85%. Generic 'Are you sure?' dialogs are dismissed without reading 60% of the time."
+    },
+    {
+      "name": "Form modal",
+      "description": "A modal that contains a form for creating or editing an entity. Should have clear title, focused form fields, and primary/cancel actions at the bottom.",
+      "do": ["Clear title stating the action ('Create project', 'Edit profile')", "Keep forms short — modal forms should have 3-7 fields max", "Primary action button on the right, cancel on the left", "Close on Escape key and backdrop click (unless there are unsaved changes)", "Focus the first field automatically on open"],
+      "dont": ["Put long multi-step forms in modals — use a page instead", "Nest modals inside modals", "Remove the close button or Escape key dismiss", "Use a modal for content that needs to reference the page behind it", "Auto-close on save without feedback (show success first)"],
+      "evidence": "Modals work best for quick, focused tasks (under 30 seconds). Forms exceeding 7 fields should use a dedicated page instead."
+    },
+    {
+      "name": "Non-modal dialog (toast/snackbar)",
+      "description": "Temporary, non-blocking notifications that confirm an action without interrupting workflow. Appear briefly and auto-dismiss.",
+      "do": ["Auto-dismiss after 3-5 seconds", "Show at a consistent position (bottom-center or top-right)", "Include an undo action for reversible changes", "Keep text concise (under 10 words)", "Stack multiple toasts in order"],
+      "dont": ["Use for critical errors that require action — those need persistent alerts", "Show more than 3 stacked toasts at once", "Place over important interactive elements", "Auto-dismiss error messages — only auto-dismiss success/info"],
+      "evidence": "Toasts with undo actions reduce 'support requests for accidental actions' by 70%. Auto-dismiss after 4 seconds is the optimal duration."
+    },
+    {
+      "name": "Modal overlay management",
+      "description": "The scrim, positioning, and animation patterns that make modals feel polished and contextual.",
+      "do": ["Use a semi-transparent scrim/overlay behind the modal (rgba(0,0,0,0.5))", "Center the modal vertically and horizontally on desktop", "Bottom-anchor modals on mobile (bottom sheet pattern)", "Animate open (fade + scale up) and close (fade out)", "Trap focus within the modal for keyboard accessibility"],
+      "dont": ["Open without a scrim — ambiguous figure-ground", "Allow scroll on the page behind the modal", "Use full-screen modals for simple tasks", "Animate too slowly (keep it under 300ms)", "Allow tab focus to escape to elements behind the modal"],
+      "evidence": "Bottom-anchored modals on mobile increase completion rate by 15% vs centered modals. The 300ms animation threshold maintains perceived responsiveness."
+    }
+  ],
+  "checklist": [
+    "Can the modal be dismissed with Escape key?",
+    "Can the modal be dismissed by clicking the backdrop?",
+    "Is there a visible close button (X)?",
+    "Does the modal trap keyboard focus?",
+    "Is there a semi-transparent scrim behind the modal?",
+    "Are action buttons clearly labeled (not just 'OK'/'Cancel')?",
+    "Is the destructive action styled differently from the safe action?",
+    "Does the modal return focus to the trigger element when closed?",
+    "Are modals kept to one level (no nested modals)?",
+    "Do success messages auto-dismiss? Do errors persist?",
+    "Is scroll prevented on the content behind the modal?",
+    "Does the modal work correctly on mobile devices?"
+  ]
+}

package/src/data/patterns/navigation.json

@@ -0,0 +1,50 @@
+{
+  "id": "navigation",
+  "name": "Navigation Patterns",
+  "category": "usability",
+  "summary": "Navigation patterns that help users find content quickly and understand where they are in the product.",
+  "principles_referenced": ["hicks-law", "millers-law", "jakobs-law", "recognition-over-recall", "serial-position-effect"],
+  "patterns": [
+    {
+      "name": "Top navigation bar",
+      "description": "Horizontal navigation across the top of the page. Standard for desktop web. Contains logo (left), primary nav items (center or left), and utility items (right — search, profile, CTA).",
+      "do": ["Logo in top-left linking to homepage", "5-7 primary nav items maximum", "Active state on current page/section", "CTA button (Sign up, Get started) on the far right", "Sticky on scroll for long pages"],
+      "dont": ["More than 7 primary items — use grouping or mega-menu", "Hide primary nav in a hamburger on desktop", "Equally styled nav items and CTA — the CTA should stand out", "Auto-hide on scroll down without showing on scroll up"],
+      "evidence": "Top navigation is the most expected pattern on desktop web. Users find content 50% faster with visible navigation vs. hidden hamburger menus."
+    },
+    {
+      "name": "Sidebar navigation",
+      "description": "Vertical navigation on the left side. Standard for SaaS dashboards and admin panels. Can be collapsed/expanded. Supports hierarchy with nested sections.",
+      "do": ["Icon + label for each item (not icon-only when expanded)", "Collapsible to icon-only mode for more content space", "Group items by section with dividers or headers", "Show active state and expand active section", "Keep it fixed/sticky while content scrolls"],
+      "dont": ["More than 3 levels of nesting — flatten or redesign", "Auto-collapse on every page navigation", "Use right-side navigation (unexpected in LTR languages)", "Put primary actions in the sidebar — they belong in the content area"],
+      "evidence": "Sidebar navigation is the dominant pattern for SaaS products (Slack, Linear, Notion, Figma). Users expect it for tool-type applications."
+    },
+    {
+      "name": "Breadcrumbs",
+      "description": "Horizontal trail showing the user's location in the site hierarchy. Helpful for deep content structures (e-commerce categories, documentation, file systems).",
+      "do": ["Show the full path from root to current page", "Make each breadcrumb item a clickable link (except the current page)", "Use a chevron (>) or slash (/) as separator", "Place below the top nav, above the page title"],
+      "dont": ["Use as the only navigation — it's supplementary", "Show breadcrumbs on flat sites with no hierarchy", "Truncate breadcrumbs without showing the first and last items", "Use breadcrumbs for multi-step wizards (use a step indicator instead)"],
+      "evidence": "Breadcrumbs reduce the number of actions needed to navigate to a higher page by 50%. Most effective for sites with 3+ levels of hierarchy."
+    },
+    {
+      "name": "Command palette",
+      "description": "Keyboard-triggered search overlay (Cmd+K / Ctrl+K) that lets users jump to any page, run commands, or search content. Power user essential for complex products.",
+      "do": ["Trigger with Cmd+K / Ctrl+K (de facto standard)", "Search across pages, actions, settings, and content", "Show recent items and suggested actions", "Support keyboard navigation within results", "Show keyboard shortcuts next to actions"],
+      "dont": ["Replace standard search with command palette — it's an accelerator, not the default", "Require the command palette for basic navigation", "Show too many result categories — keep it focused", "Delay results — show them as the user types (instant)"],
+      "evidence": "Power users cite command palettes as the #1 productivity feature in tools like Linear, Figma, VS Code, and Slack."
+    }
+  ],
+  "checklist": [
+    "Can a user reach any key page in 3 clicks or fewer?",
+    "Is there a visible active state on the current navigation item?",
+    "Does the logo link to the homepage?",
+    "Is there a search feature for products with 20+ pages?",
+    "Is the navigation consistent across all pages?",
+    "Does the mobile navigation follow thumb-zone principles?",
+    "Are breadcrumbs shown for deep hierarchical content?",
+    "Is there a keyboard shortcut for search/command palette?",
+    "Does navigation persist during scrolling (sticky or scroll-up reveal)?",
+    "Is the navigation responsive — does it adapt to mobile breakpoints?",
+    "Are primary navigation items limited to 7 or fewer?"
+  ]
+}

package/src/data/patterns/pricing-page.json

@@ -0,0 +1,59 @@
+{
+  "id": "pricing-page",
+  "name": "Pricing Page",
+  "category": "conversion",
+  "summary": "Patterns for pricing pages that convert browsers into buyers through clear value communication and smart psychology.",
+  "principles_referenced": ["hicks-law", "von-restorff-effect", "jakobs-law", "aesthetic-usability-effect", "serial-position-effect"],
+  "patterns": [
+    {
+      "name": "Recommended plan highlight",
+      "description": "Visually distinguish one plan as recommended. This leverages the Von Restorff Effect and anchoring to guide choice. The recommended plan should be the one that delivers the best value for most users.",
+      "do": ["Use a 'Most Popular' or 'Recommended' badge", "Make the recommended plan visually elevated (larger card, colored border, different background)", "Position the recommended plan in the center (3 plans) or second from left (4 plans)", "Show the recommended plan's CTA as the primary button style"],
+      "dont": ["Highlight the most expensive plan (feels pushy)", "Highlight two or more plans (defeats the purpose)", "Use subtle differentiation — it needs to be obvious", "Make the recommended plan look like an ad users might ignore"],
+      "evidence": "Highlighting a recommended plan increases selection of that plan by 20-30%. The center position effect (serial position) adds another 5-10%."
+    },
+    {
+      "name": "Three-plan structure",
+      "description": "Offer exactly 3 plans: a free/low tier for consideration, a mid tier as the target, and a high tier for anchoring. This is the most effective pricing structure for most SaaS products.",
+      "do": ["Name plans for the user segment, not the feature set (Starter, Pro, Team)", "Keep the free tier useful enough to demonstrate value", "Make the mid tier the obvious best value", "Use the top tier for price anchoring and enterprise needs"],
+      "dont": ["Offer more than 4 plans on the main pricing page", "Name plans Good/Better/Best (it's patronizing)", "Make the free tier so limited it's frustrating", "Price the tiers too close together — create clear value gaps"],
+      "evidence": "The 'decoy effect' (asymmetric dominance) is most effective with 3 options. Adding a premium tier can increase mid-tier conversion by 40%."
+    },
+    {
+      "name": "Feature comparison table",
+      "description": "A detailed comparison of what's included in each plan, using checkmarks and clear categories. Placed below the plan cards for users who need details before deciding.",
+      "do": ["Group features by category", "Use checkmarks (not just text) for at-a-glance scanning", "Highlight the differences between plans, not the similarities", "Make the table responsive — stack on mobile or allow horizontal scroll"],
+      "dont": ["Show the comparison as the primary pricing view (overwhelming)", "List 50+ features without categorization", "Use vague feature names only internal teams understand", "Hide limits in footnotes — be transparent"],
+      "evidence": "Feature comparison tables increase time-on-page by 60% and conversion by 15% for considered purchases."
+    },
+    {
+      "name": "Annual vs monthly toggle",
+      "description": "Offer both billing cycles with the annual savings prominently displayed. Default to annual (higher LTV) but make monthly easy to switch to.",
+      "do": ["Show the savings percentage or dollar amount for annual billing", "Default to annual pricing view", "Use a simple toggle switch between monthly/annual", "Show monthly price even for annual (e.g., '$8/mo billed annually')"],
+      "dont": ["Hide the monthly option", "Make the savings math hard to calculate", "Show only the annual price without explaining the billing", "Use confusing 'per seat per month billed annually' without a total"],
+      "evidence": "Showing annual savings increases annual plan selection by 15-25%. Displaying the monthly-equivalent price for annual plans reduces sticker shock."
+    },
+    {
+      "name": "Social proof on pricing",
+      "description": "Place trust signals on the pricing page to reduce purchase anxiety: customer logos, testimonials, ratings, and security badges.",
+      "do": ["Show customer logos relevant to the plan tier", "Include a testimonial about value/ROI near the CTA", "Display security badges near payment forms", "Show customer count ('Join 10,000+ teams')"],
+      "dont": ["Use fake testimonials or logos without permission", "Place social proof where it distracts from pricing clarity", "Show generic testimonials unrelated to the product's value", "Overload with too many logos — 6-8 is optimal"],
+      "evidence": "Social proof near pricing CTAs increases conversion by 10-15%. Customer logos increase trust for B2B buyers."
+    }
+  ],
+  "checklist": [
+    "Are there 2-4 clearly differentiated plans?",
+    "Is one plan visually highlighted as recommended?",
+    "Is the recommended plan positioned in the center or one-from-left?",
+    "Are plan names based on user segments, not features?",
+    "Is there an annual/monthly toggle with savings displayed?",
+    "Can users start a free trial or freemium tier without payment?",
+    "Is there a feature comparison table for detail-oriented buyers?",
+    "Are CTAs action-oriented ('Start free trial', not 'Buy now')?",
+    "Is social proof visible on the pricing page?",
+    "Is the pricing page responsive and readable on mobile?",
+    "Are enterprise/custom plans handled with 'Contact sales'?",
+    "Is there a FAQ section addressing common pricing objections?",
+    "Is the currency localized or selectable?"
+  ]
+}

package/src/data/patterns/signup-flow.json

@@ -0,0 +1,52 @@
+{
+  "id": "signup-flow",
+  "name": "Signup Flow",
+  "category": "conversion",
+  "summary": "Patterns for high-converting signup experiences that minimize friction and maximize activation.",
+  "principles_referenced": ["fitts-law", "hicks-law", "millers-law", "goal-gradient-effect", "teslers-law", "postels-law"],
+  "patterns": [
+    {
+      "name": "Progressive disclosure",
+      "description": "Don't show all fields at once. Break signup into logical steps, revealing fields progressively as the user commits to the process.",
+      "do": ["Split into 2-3 logical steps (identity → details → preferences)", "Show a progress indicator", "Allow going back to previous steps", "Save progress so users can return later"],
+      "dont": ["Show all 15 fields on one page", "Ask for optional fields during initial signup", "Require credit card on free trial signup", "Ask for information you can auto-detect (timezone, country)"],
+      "evidence": "Reducing form fields from 11 to 4 increased conversions by 120% (Imagescape). HubSpot saw a 5% conversion increase per field removed."
+    },
+    {
+      "name": "Social login as primary",
+      "description": "Offer social/SSO login as the primary path, with email signup as secondary. Reduces friction to near-zero for users with Google/Apple/GitHub accounts.",
+      "do": ["Place social login buttons prominently above email form", "Support Google, Apple, and GitHub for developer tools", "Auto-fill profile data from social account", "Show 'Continue with...' language (not 'Sign in with')"],
+      "dont": ["Offer more than 4 social login options (paradox of choice)", "Hide the email signup option", "Require additional profile completion after social signup", "Use social login buttons that look like regular buttons"],
+      "evidence": "Social login can increase signup rates by 20-40%. Google Sign-In alone accounts for over 50% of social logins on most platforms."
+    },
+    {
+      "name": "Single-field step-through",
+      "description": "Show one field at a time with large input areas and auto-advance. Creates a focused, low-cognitive-load experience. Works especially well on mobile.",
+      "do": ["Auto-focus the input field on each step", "Auto-advance after valid selection (no submit button needed)", "Use keyboard-appropriate input types", "Show inline validation immediately"],
+      "dont": ["Use for more than 5-6 steps — it becomes tedious", "Remove the ability to see/edit previous answers", "Auto-advance on text fields — only on selection fields", "Skip the progress indicator"],
+      "evidence": "Typeform-style single-field forms see 3-4x higher completion rates than traditional multi-field forms for surveys and lead capture."
+    },
+    {
+      "name": "Value-first onboarding",
+      "description": "Let users experience value before requiring signup. Show the product working, then gate further usage behind account creation.",
+      "do": ["Let users try the core feature without signing up", "Gate saves, exports, or collaboration behind signup", "Show what they'll get by signing up in context", "Preserve any work done before signup"],
+      "dont": ["Require signup before showing any product value", "Lose the user's pre-signup work after account creation", "Show a generic landing page instead of the product", "Force signup for read-only access"],
+      "evidence": "Products that allow value-first usage see 2-3x higher signup rates. Canva, Figma, and Notion all use this pattern."
+    }
+  ],
+  "checklist": [
+    "Is the value proposition clear before the user starts signing up?",
+    "Can a user complete signup in under 60 seconds?",
+    "Are only essential fields required at signup?",
+    "Is there a social/SSO login option?",
+    "Does the form use appropriate input types and autocomplete?",
+    "Is there a progress indicator for multi-step flows?",
+    "Can the user go back and edit previous steps?",
+    "Is inline validation provided (not just on submit)?",
+    "Is the form single-column layout?",
+    "Does the CTA button have clear, action-oriented text ('Create account', not 'Submit')?",
+    "Is there a clear path if the user already has an account?",
+    "Does the form work well on mobile?",
+    "Is progress saved if the user leaves and returns?"
+  ]
+}

package/src/data/patterns/social-proof.json

@@ -0,0 +1,49 @@
+{
+  "id": "social-proof",
+  "name": "Social Proof",
+  "category": "conversion",
+  "summary": "Patterns for testimonials, logos, reviews, and trust signals that build credibility and reduce purchase anxiety.",
+  "principles_referenced": ["aesthetic-usability-effect", "jakobs-law", "serial-position-effect"],
+  "patterns": [
+    {
+      "name": "Customer logos",
+      "description": "A row of recognizable customer logos that instantly communicates credibility. Most effective for B2B products where brand association signals trust.",
+      "do": ["Show 6-8 logos — enough for credibility, not so many they're overwhelming", "Use grayscale/monochrome versions for visual consistency", "Include logos the target audience will recognize (industry-relevant)", "Place near the hero section — early on the page", "Update regularly to show current, relevant customers"],
+      "dont": ["Use more than 12 logos (dilutes impact)", "Include logos without permission", "Show tiny, unrecognizable logo sizes", "Mix colored logos with different styles (visual chaos)", "Show logos of companies that aren't actually customers"],
+      "evidence": "Customer logos increase trust for B2B buyers by 15-25%. Recognition of even one logo significantly increases credibility perception."
+    },
+    {
+      "name": "Testimonials with attribution",
+      "description": "Quotes from real customers with full attribution (name, title, company, photo). The more specific and verifiable, the more trustworthy.",
+      "do": ["Include real name, title, company, and headshot photo", "Feature specific outcomes ('Reduced support tickets by 40%')", "Rotate testimonials relevant to the page context", "Place near decision points (pricing, signup, checkout)", "Video testimonials for high-stakes purchases"],
+      "dont": ["Use anonymous testimonials ('A satisfied customer')", "Use vague praise ('Great product!', 'Love it!')", "Show only 5-star reviews (suspicious)", "Use stock photos for headshots", "Write testimonials that sound like marketing copy"],
+      "evidence": "Testimonials with photos increase trust by 35%. Specific testimonials with metrics are 2x more persuasive than general praise."
+    },
+    {
+      "name": "Aggregate metrics",
+      "description": "Large numbers that communicate scale and momentum: user counts, transactions processed, countries served, uptime percentages.",
+      "do": ["Show 2-3 impressive metrics prominently", "Use real, verifiable numbers", "Round to readable numbers ('50,000+' not '49,847')", "Update regularly to show growth", "Choose metrics that resonate with the target audience's concerns"],
+      "dont": ["Show vanity metrics that don't indicate trust or value", "Use numbers so large they're unrelatable", "Show metrics that could be embarrassingly small", "Lie or exaggerate — it destroys trust when discovered"],
+      "evidence": "Aggregate metrics create 'bandwagon effect' — people trust what others trust. '50,000+ teams' is more persuasive than any individual testimonial."
+    },
+    {
+      "name": "Star ratings and reviews",
+      "description": "Numerical ratings and user-generated reviews. Most effective for consumer products and marketplaces where peer experience matters.",
+      "do": ["Show average rating + total number of reviews", "Display a distribution chart (5-star breakdown)", "Allow filtering by rating", "Show recent reviews prominently", "Respond to negative reviews publicly (shows accountability)"],
+      "dont": ["Show only 5-star reviews (suspicious — 4.2-4.7 is the trust sweet spot)", "Hide negative reviews", "Show ratings without the review count", "Use ratings without a sufficient sample size", "Fake reviews (illegal in many jurisdictions)"],
+      "evidence": "Products with 4.2-4.5 star ratings convert better than 5.0 (imperfect feels more authentic). Showing the review count increases trust by 20%."
+    }
+  ],
+  "checklist": [
+    "Is there social proof above the fold or early on the page?",
+    "Are customer logos real and permission-granted?",
+    "Do testimonials include full attribution (name, title, company, photo)?",
+    "Are testimonials specific (metrics, outcomes) not vague?",
+    "Are aggregate metrics real and regularly updated?",
+    "Is social proof placed near decision points (pricing, signup)?",
+    "Are star ratings shown with review counts?",
+    "Is there a mix of social proof types (logos + testimonials + metrics)?",
+    "Are testimonials relevant to the page context?",
+    "Is there social proof that resonates with each target audience segment?"
+  ]
+}