Initial commit

.agents/skills/storefront-best-practices/reference/components/search.md

@@ -0,0 +1,101 @@
+# Search Component
+
+## Contents
+
+- [Overview](#overview)
+- [Search Placement](#search-placement)
+- [Autocomplete and Product Suggestions](#autocomplete-and-product-suggestions)
+- [Search Results Page](#search-results-page)
+- [Empty States](#empty-states)
+- [Recent and Popular Searches](#recent-and-popular-searches)
+- [Mobile Search](#mobile-search)
+
+## Overview
+
+Search is critical for ecommerce - users with search intent convert at higher rates. Provide fast, relevant product discovery with autocomplete.
+
+**Assumed knowledge**: AI agents know how to build search inputs with icons and clear buttons. This guide focuses on ecommerce search patterns.
+
+### Key Requirements
+
+- Prominent search input (always accessible)
+- Instant autocomplete after 2-3 characters
+- Product suggestions with images
+- Fast, relevant search results
+- Filters to refine results
+- Empty state guidance
+- Mobile full-screen search modal
+
+## Search Placement
+
+**Desktop**: Navbar center (between logo and cart) or right side. Always visible, 300-500px width. Part of sticky navbar. Never hide in hamburger menu.
+
+**Mobile**: Magnifying glass icon in top-right (44x44px minimum). Opens full-screen modal - eliminates distractions, maximizes suggestion space, better typing experience.
+
+## Autocomplete and Product Suggestions
+
+**Show suggestions** after 2-3 characters (not 1). Debounce 300ms to prevent excessive API calls.
+
+**Display 5-10 product suggestions:**
+- Small image (40-60px), title, price
+- Clickable to product page
+- Optional: Category/brand suggestions, popular terms
+- Divide sections with headers
+- "View all results for [query]" footer link
+
+**Backend integration**: Fetch from search API. Check with ecommerce platform's documentation for API reference.
+
+## Search Results Page
+
+**Header**: "Search Results for '[query]'" + result count ("24 products found"). Search bar visible and pre-filled for refining.
+
+**Grid layout**: Same as product listings (see product-listing.md). 1-4 columns based on device.
+
+**Sorting**: Relevance (default, unique to search), Price Low/High, Newest.
+
+**Filters**: Sidebar (desktop) or drawer (mobile). Category, Price, Brand, Availability with result counts.
+
+## Empty States
+
+**No results**: "No results for '[query]'" with helpful suggestions (check spelling, try broader keywords, browse categories). "Browse All Products" button + links to popular categories.
+
+**Loading state**: Product card skeletons (6-8 cards), minimum 300ms display to avoid flashing.
+
+## Recent and Popular Searches
+
+**Recent searches** (user-specific, localStorage): Show 3-5 recent searches when input focused (before typing). Helps re-search without retyping.
+
+**Popular searches** (site-wide, from backend): Show 5-10 trending terms when focused. Pill/tag styling.
+
+Display both on: Empty input focus (desktop dropdown), mobile modal open.
+
+## Mobile Search
+
+**Full-screen modal pattern:**
+- Header: Back button (44x44px) + search input (48px height, auto-focus, `type="search"`)
+- Content: Recent/popular searches (empty), autocomplete (typing), scrollable
+- Close: Back button, device back gesture, Escape key
+
+## Ecommerce Search Checklist
+
+**Essential features:**
+
+- [ ] Prominent search input in navbar (desktop)
+- [ ] Search icon clearly visible (mobile)
+- [ ] Full-screen modal on mobile tap
+- [ ] Autocomplete after 2-3 characters
+- [ ] Debounced API calls (300ms)
+- [ ] Product suggestions with images, prices
+- [ ] "View all results" link in dropdown
+- [ ] Search results page shows query
+- [ ] Result count displayed
+- [ ] Sort by Relevance (default for search)
+- [ ] Filters for refining results (category, price, brand)
+- [ ] Empty state with helpful guidance
+- [ ] Loading state indicator (skeleton)
+- [ ] Recent searches (localStorage)
+- [ ] Popular searches (from backend)
+- [ ] Mobile: Auto-focus, large input (48px)
+- [ ] Keyboard navigation (arrow keys, Enter, Escape)
+- [ ] ARIA labels (`role="search"`, `aria-label`)
+- [ ] Accessible to screen readers