Build search experiences that help users find what they need quickly, even when they are uncertain about what they are looking for. The goal is not perfect relevance on the first try; it is guiding users from intent to outcome through forgiving search and clear results.
Consult the search and filtering UX reference for autocomplete patterns, filter architecture, result presentation, and zero-results recovery.
Consult the search and findability reference for site search, autosuggest, command palettes, and intent-aware findability.
Consult the collection browsing and filtering reference for long result lists, faceted browsing, and filter overlays.
Consult the predictive and intent-driven UI reference for recommendations, smart defaults, and resume flows.
MANDATORY PREPARATION
Users start this workflow with /search. Once this skill is active, load $frontend-design — it contains design principles, anti-patterns, and the Context Gathering Protocol. Follow that protocol before proceeding — if no design context exists yet, you MUST load $setup first. Additionally gather: what users typically search for, what common queries fail, and how large the searchable dataset is.
Assess Search Needs
Understand the search context before designing the interface:
- Search intent: Are users looking for a specific item (known-item search), exploring a category (exploratory), or trying to complete a task (transactional)?
- Dataset size: Small datasets (< 100 items) may not need search; filtering or categorization may suffice. Large datasets need faceted search and ranking.
- Query patterns: What do users actually type? Common misspellings, synonyms, and abbreviations should be handled.
- Failure modes: What happens when search returns nothing? When it returns too much?
Search Interface Design
Query input
- Use concrete placeholder text ("Search for "project alpha"") instead of generic filler
- Show a clear button once the user has typed
- Support Enter to submit; do not rely solely on live results
- Include a visible search button, not just a decorative icon
- If scope is selectable ("All", "Products", "Help"), make it obvious and changeable
Autocomplete and suggestions
- Show suggestions after 2-3 characters
- Group by type: recent searches, popular queries, products, help articles
- Bold the matching substring
- Support arrow-key navigation, Enter to select, Escape to close
- On mobile, ensure suggestions are scrollable and do not overflow
- Show a helpful message when nothing matches instead of an empty list
Filter integration
- Sidebar filters for many filters on wide layouts
- Top bar for a few key filters
- Drawer/overlay on narrow layouts
- Inline chips for active filters that can be removed directly
- Synchronize filter state with the URL for shareability
- Show active filter count when collapsed
Result Presentation
Result list
- Clear hierarchy: title, metadata, snippet, thumbnail
- Highlight matching query terms in titles and snippets
- Consistent formatting across all results
- Each result should be a clear link or have a primary action
Empty states
- Acknowledge the query ("No results for 'xyz'")
- Suggest alternatives: corrected spelling, related terms, broader categories
- Offer to clear filters if any are active
- Provide a fallback action ("Browse all", "Contact support")
Ranking controls
- Allow users to change sort order (relevance, price, date, rating)
- Label the default sort and explain why it is the default
- If results are promoted, label them transparently ("Featured")
Pagination and Loading
| Pattern |
Best for |
| Pagination |
Large result sets, SEO-critical pages, users who reference specific pages |
| Infinite scroll |
Discovery browsing, image galleries, social feeds |
| Load more |
Balanced approach; user controls when to load |
- Show skeleton screens that match result layout during loading
- Preserve previous results while loading new ones when possible
Accessibility
- Announce result count changes for screen readers
- Associate filter controls with result regions using
aria-controls
- Ensure active filters are announced when changed
- Provide skip links from filters to results
- Support keyboard navigation through suggestions and filters
Anti-Patterns
- Case-sensitive search: Users should not guess capitalization
- No visual feedback during search: Silent search feels broken
- Filters that produce zero results: Disable or hide invalid combinations
- Overwhelming filter panels: Too many filters create decision paralysis
- Hidden active filters: Users forget what they filtered
- Losing filter state on refresh: Filters should persist in the URL
- Infinite scroll without footer access: Users cannot reach footer links
- Search requiring exact matches: Fuzzy matching and stemming are essential
- No zero-results recovery: An empty screen with no guidance is a dead end
- Autocomplete that hijacks the cursor: Suggestions should not auto-submit
Verify Search Quality
Before shipping:
1---
2name: search
3description: Design or improve search experiences, result presentation, and filtering interfaces. Use when the user asks to add search, redesign search results, improve findability, build autocomplete, add filters, or fix zero-results dead ends.
4metadata:
5 argument-hint: "[search surface or result set]"
6---
7
8Build search experiences that help users find what they need quickly, even when they are uncertain about what they are looking for. The goal is not perfect relevance on the first try; it is guiding users from intent to outcome through forgiving search and clear results.
9
10Consult the [search and filtering UX](../frontend-design/reference/search-and-filtering-ux.md) reference for autocomplete patterns, filter architecture, result presentation, and zero-results recovery.
11Consult the [search and findability](../frontend-design/reference/search-and-findability.md) reference for site search, autosuggest, command palettes, and intent-aware findability.
12Consult the [collection browsing and filtering](../frontend-design/reference/collection-browsing-and-filtering.md) reference for long result lists, faceted browsing, and filter overlays.
13Consult the [predictive and intent-driven UI](../frontend-design/reference/predictive-and-intent-ui.md) reference for recommendations, smart defaults, and resume flows.
14
15## MANDATORY PREPARATION
16
17Users start this workflow with `/search`. Once this skill is active, load $frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow that protocol before proceeding — if no design context exists yet, you MUST load $setup first. Additionally gather: what users typically search for, what common queries fail, and how large the searchable dataset is.
18
19## Assess Search Needs
20
21Understand the search context before designing the interface:
22
231. **Search intent**: Are users looking for a specific item (known-item search), exploring a category (exploratory), or trying to complete a task (transactional)?
242. **Dataset size**: Small datasets (< 100 items) may not need search; filtering or categorization may suffice. Large datasets need faceted search and ranking.
253. **Query patterns**: What do users actually type? Common misspellings, synonyms, and abbreviations should be handled.
264. **Failure modes**: What happens when search returns nothing? When it returns too much?
27
28## Search Interface Design
29
30### Query input
31
32- Use concrete placeholder text ("Search for "project alpha"") instead of generic filler
33- Show a clear button once the user has typed
34- Support Enter to submit; do not rely solely on live results
35- Include a visible search button, not just a decorative icon
36- If scope is selectable ("All", "Products", "Help"), make it obvious and changeable
37
38### Autocomplete and suggestions
39
40- Show suggestions after 2-3 characters
41- Group by type: recent searches, popular queries, products, help articles
42- Bold the matching substring
43- Support arrow-key navigation, Enter to select, Escape to close
44- On mobile, ensure suggestions are scrollable and do not overflow
45- Show a helpful message when nothing matches instead of an empty list
46
47### Filter integration
48
49- Sidebar filters for many filters on wide layouts
50- Top bar for a few key filters
51- Drawer/overlay on narrow layouts
52- Inline chips for active filters that can be removed directly
53- Synchronize filter state with the URL for shareability
54- Show active filter count when collapsed
55
56## Result Presentation
57
58### Result list
59
60- Clear hierarchy: title, metadata, snippet, thumbnail
61- Highlight matching query terms in titles and snippets
62- Consistent formatting across all results
63- Each result should be a clear link or have a primary action
64
65### Empty states
66
67- Acknowledge the query ("No results for 'xyz'")
68- Suggest alternatives: corrected spelling, related terms, broader categories
69- Offer to clear filters if any are active
70- Provide a fallback action ("Browse all", "Contact support")
71
72### Ranking controls
73
74- Allow users to change sort order (relevance, price, date, rating)
75- Label the default sort and explain why it is the default
76- If results are promoted, label them transparently ("Featured")
77
78## Pagination and Loading
79
80| Pattern | Best for |
81|---------|----------|
82| Pagination | Large result sets, SEO-critical pages, users who reference specific pages |
83| Infinite scroll | Discovery browsing, image galleries, social feeds |
84| Load more | Balanced approach; user controls when to load |
85
86- Show skeleton screens that match result layout during loading
87- Preserve previous results while loading new ones when possible
88
89## Accessibility
90
91- Announce result count changes for screen readers
92- Associate filter controls with result regions using `aria-controls`
93- Ensure active filters are announced when changed
94- Provide skip links from filters to results
95- Support keyboard navigation through suggestions and filters
96
97## Anti-Patterns
98
99- **Case-sensitive search**: Users should not guess capitalization
100- **No visual feedback during search**: Silent search feels broken
101- **Filters that produce zero results**: Disable or hide invalid combinations
102- **Overwhelming filter panels**: Too many filters create decision paralysis
103- **Hidden active filters**: Users forget what they filtered
104- **Losing filter state on refresh**: Filters should persist in the URL
105- **Infinite scroll without footer access**: Users cannot reach footer links
106- **Search requiring exact matches**: Fuzzy matching and stemming are essential
107- **No zero-results recovery**: An empty screen with no guidance is a dead end
108- **Autocomplete that hijacks the cursor**: Suggestions should not auto-submit
109
110## Verify Search Quality
111
112Before shipping:
113
114- [ ] Search handles typos, partial matches, and common synonyms
115- [ ] Autocomplete is keyboard-navigable and mobile-friendly
116- [ ] Active filters are visible and individually removable
117- [ ] Filter state is reflected in the URL
118- [ ] Zero-results pages offer alternatives and recovery paths
119- [ ] Result rankings can be changed by the user
120- [ ] Loading states match the result layout
121- [ ] Screen readers announce result count and filter changes
122- [ ] Focus management follows a logical path
123- [ ] Search is tested with realistic queries and misspellings
aladicf