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