ericrisco/rsc-harness / skills/ux
ux
VerifiedUse when an app or SaaS must be easy to use: designing complete user flows, screens and every state, navigation, forms, onboarding, tables, dashboards, search or AI features, or auditing usability and accessibility. Anyone finishes the job without a manual; experts go fast. NOT the visual direction (design), NOT the words (landing-copy).
upstream/ux-designer/references/19-search-ux.md
View on GitHub# Search UX
Search is a critical navigation pattern that goes beyond basic text matching. This reference covers search input design, autocomplete, faceted filtering, results display, and emerging AI-powered search patterns.
---
## Contents
- Search Box Design
- Autocomplete
- Faceted Search & Filters
- Search Results
- Zero Results
- Advanced Search
- Voice Search
- AI-Powered Search
- Key Metrics
- Anti-Patterns
- Sources
---
## Search Box Design
### Placement & Sizing
```
Top navigation (most common):
┌─────────────────────────────────────────────────────┐
│ Logo [🔍 Search... ] [User]│
└─────────────────────────────────────────────────────┘
Centered hero (landing pages / search-first apps):
┌─────────────────────────────────────────────────────┐
│ │
│ What are you looking for? │
│ [🔍 Search products, brands, categories... ] │
│ │
└─────────────────────────────────────────────────────┘
```
**Guidelines:**
- Minimum width: 300px (desktop), full-width on mobile
- Visible by default (not hidden behind an icon on desktop)
- Magnifying glass icon on the left (universal affordance)
- Clear/reset button (✕) appears when text is entered
- Search on Enter or with a submit button
- Consistent location across all pages
### Input Behavior
```html
<div class="search-container" role="search">
<label for="search" class="sr-only">Search</label>
<span class="search-icon" aria-hidden="true">🔍</span>
<input
id="search"
type="search"
placeholder="Search..."
autocomplete="off"
aria-expanded="false"
aria-controls="search-results"
aria-autocomplete="list"
/>
<button class="clear-btn" aria-label="Clear search" hidden>✕</button>
</div>
```
- `type="search"` for native clear button on some browsers
- `role="search"` on the container for screen readers
- Focus on keyboard shortcut (/ or Ctrl+K is common)
- Show shortcut hint in the placeholder: "Search... (⌘K)"
- Debounce input: 200-300ms before triggering search
- Preserve query on back navigation
### Placeholder Text
```
❌ "Search..." (too vague)
❌ "Type here to search for products, articles, help topics, and more..." (too long)
✅ "Search products and articles..." (specific, concise)
✅ "Search by name, email, or ID..." (tells user what's searchable)
```
- Indicate what types of content are searchable
- Keep under 40 characters
- Don't rely on placeholder alone for labeling (accessibility)
---
## Autocomplete
### Suggestion Types
```
┌─────────────────────────────────────────┐
│ 🔍 "react hook" [✕] │
├─────────────────────────────────────────┤
│ Recent searches │
│ 🕐 react hooks tutorial │
│ 🕐 react context api │
├─────────────────────────────────────────┤
│ Suggestions │
│ 🔍 react hooks best practices │
│ 🔍 react hook form │
│ 🔍 react hooks vs classes │
├─────────────────────────────────────────┤
│ Products │
│ 📦 React Hook Form (library) 4.9★ │
│ 📦 useHooks (collection) 4.7★ │
└─────────────────────────────────────────┘
```
**Suggestion categories:**
- **Recent searches**: User's own history (with clear history option)
- **Popular/trending**: Common searches from all users
- **Predictive**: Completions based on typing so far
- **Entity matches**: Direct links to specific results (products, people, pages)
- **Category suggestions**: "Search in Documentation" or "Search in Products"
### Keyboard Navigation
```
Tab / ↓ Move to suggestions dropdown
↑ / ↓ Navigate between suggestions
Enter Select highlighted suggestion / submit search
Esc Close dropdown, keep query text
→ Complete highlighted suggestion in input (Google-style)
```
- Highlight active suggestion visually
- Arrow keys should not move cursor in input while dropdown is open
- First suggestion can be auto-highlighted (or not — be consistent)
- Screen reader announcement of current suggestion
### Highlighting Matches
```
Searching for "des"
┌──────────────────────────┐
│ 🔍 **des**ign system │ ← Bold matching portion
│ 🔍 **des**ktop app │
│ 🔍 ui **des**ign patterns │
└──────────────────────────┘
```
- Bold or highlight the matching text portion
- Works with mid-word and multi-word matches
- Match highlighting in both suggestion text and description
### Performance
- Show suggestions after 1-2 characters minimum
- Debounce: 150-300ms after last keystroke
- Show loading indicator if search takes >300ms
- Cache recent suggestion results
- Maximum 7-10 suggestions visible (scroll for more)
---
## Faceted Search & Filters
### Filter Panel Layout
```
Desktop — Side panel: Mobile — Bottom sheet:
┌──────────┬──────────────────┐ ┌──────────────────────┐
│ Filters │ Results │ │ Results (23) │
│ │ │ │ [🔽 Filter & Sort] │
│ Category │ │ └──────────────────────┘
│ ☑ Books │ 23 results │ ↓ (tap)
│ ☐ Video │ │ ┌──────────────────────┐
│ ☐ Audio │ ┌──────────────┐ │ │ ── Filters ── │
│ │ │ Result 1 │ │ │ Category ▾ │
│ Price │ │ Result 2 │ │ │ Price Range ▾ │
│ $0-$25 │ │ Result 3 │ │ │ Rating ▾ │
│ $25-$50 │ └──────────────┘ │ │ │
│ │ │ │ [Reset] [Apply (23)] │
└──────────┴──────────────────┘ └──────────────────────┘
```
### Active Filter Chips
```
┌─────────────────────────────────────────────────────┐
│ Active: [Category: Books ✕] [Price: $0-$25 ✕] │
│ [Rating: 4+ stars ✕] [Clear all filters] │
├─────────────────────────────────────────────────────┤
│ 23 results for "design patterns" │
```
- Show all active filters as removable chips above results
- Individual remove (✕) on each chip
- "Clear all filters" link when multiple are active
- Update result count in real-time as filters change
- Persist filter selections on back navigation
### Filter UX Patterns
| Filter Type | UI Pattern | Best For |
|-------------|-----------|----------|
| **Single select** | Radio buttons / dropdown | Category, sort order |
| **Multi select** | Checkboxes | Tags, sizes, colors |
| **Range** | Slider or min/max inputs | Price, date range |
| **Boolean** | Toggle switch | "In stock", "Free shipping" |
| **Text** | Search within filter | Long category lists |
| **Color** | Color swatches | Product colors |
| **Rating** | Star row (clickable) | Minimum rating |
### Filter Counts
```
Category
☐ Books (156)
☐ Video (43)
☐ Audio (12)
☐ Courses (0) ← Gray out or hide zero-count options
```
- Show result count per filter option
- Update counts as other filters are applied
- Gray out (don't hide) zero-count options to prevent layout shift
- Option: hide zero-count in secondary/collapsed filters
---
## Search Results
### Result Layout
```
┌─────────────────────────────────────────────────────┐
│ About 23 results for "design patterns" (0.12s) │
│ Showing results from: [All ▾] │
├─────────────────────────────────────────────────────┤
│ │
│ 📄 Design Patterns: Elements of Reusable Software │
│ www.example.com/books/design-patterns │
│ The definitive guide to **design** **patterns** │
│ in object-oriented programming. Covers 23 │
│ fundamental **patterns**... │
│ ⭐⭐⭐⭐⭐ (2,341 reviews) • Books • $45.99 │
│ │
│ 📄 UI Design Patterns — Best Practices │
│ www.example.com/articles/ui-patterns │
│ A collection of common UI **design** **patterns** │
│ for web and mobile applications... │
│ Articles • Free • Updated 2 days ago │
│ │
└─────────────────────────────────────────────────────┘
```
**Result item components:**
- Title (linked, keyword-highlighted)
- URL/breadcrumb path
- Snippet with highlighted matching terms
- Metadata (rating, category, date, price)
- Thumbnail image (when available)
### Result Sorting
```
Sort by: [Relevance ▾]
• Relevance (default)
• Newest first
• Oldest first
• Price: Low to High
• Price: High to Low
• Rating: High to Low
• Most Popular
```
- Default to relevance for text searches
- Default to newest for browsing/feed contexts
- Show current sort prominently
- Changing sort should not clear filters
### Result Grouping
```
All (23) | Articles (12) | Products (8) | People (3)
─── Articles ───────────────────
📄 UI Design Patterns...
📄 Design Thinking...
─── Products ──────────────────
📦 Design Patterns Book...
📦 Pattern Library Tool...
```
- Group by content type when searching across multiple types
- Tab navigation between groups
- Show count per group
- "All" tab shows mixed results with type indicators
---
## Zero Results
### Helpful Messaging
```
┌─────────────────────────────────────────┐
│ No results for "dezign paterns" │
│ │
│ Did you mean: design patterns? │
│ │
│ Suggestions: │
│ • Check your spelling │
│ • Try more general keywords │
│ • Try fewer keywords │
│ │
│ Popular searches: │
│ [UX design] [Typography] [Color theory]│
│ │
│ Or browse categories: │
│ [Books] [Articles] [Courses] │
└─────────────────────────────────────────┘
```
**Zero results checklist:**
- [ ] Spelling suggestion ("Did you mean...?")
- [ ] Actionable tips (fewer keywords, check spelling)
- [ ] Alternative queries or popular searches
- [ ] Category browsing links
- [ ] Contact support or request option
- [ ] Never show a completely blank page
---
## Advanced Search
### Query Syntax
```
Common query operators (if supported, document them):
"exact phrase" — Match exact phrase
term1 AND term2 — Both terms required
term1 OR term2 — Either term
-excluded — Exclude term
field:value — Search specific field
type:article — Filter by content type
```
- Don't require advanced syntax — it should enhance, not replace basic search
- Show syntax guide as a help tooltip or link
- Parse common natural language queries intelligently
### Saved Searches
```
┌─ Saved Searches ────────────────────────┐
│ 🔖 "react hooks" in:docs │
│ 🔖 "bugs" type:issue status:open │
│ 🔖 author:me modified:last-week │
│ │
│ [+ Save current search] │
└──────────────────────────────────────────┘
```
- Allow saving complex filter + query combinations
- Accessible from search interface
- Named searches with optional notifications (alert on new results)
- Shareable search links
---
## Voice Search
### Microphone Button
```
┌─────────────────────────────────────────┐
│ 🔍 Search... [🎤] │
└─────────────────────────────────────────┘
↓ (tap microphone)
┌─────────────────────────────────────────┐
│ 🎤 Listening... │
│ 🔴 ∿∿∿∿∿∿∿∿∿∿ │
│ [Cancel] │
└─────────────────────────────────────────┘
↓ (speech detected)
┌─────────────────────────────────────────┐
│ 🔍 "best design patterns for" [✕] │
│ Transcribing... │
└─────────────────────────────────────────┘
```
- Show waveform or animation during listening
- Display transcription in real-time
- Allow editing before submitting
- "Cancel" to stop without searching
- Handle no-speech-detected timeout gracefully
---
## AI-Powered Search
### Natural Language Queries
```
Traditional search: "return policy days limit"
AI-powered search: "How many days do I have to return an item?"
↓
┌─────────────────────────────────────────┐
│ 📍 Quick Answer │
│ You have 30 days from purchase to │
│ return most items for a full refund. │
│ Exceptions apply for electronics (15 │
│ days) and final sale items. │
│ │
│ Source: Return Policy FAQ │
│ [View full policy] │
├─────────────────────────────────────────┤
│ Related results: │
│ 📄 Return Policy... │
│ 📄 How to Start a Return... │
│ 📄 Refund Processing Times... │
└─────────────────────────────────────────┘
```
### AI Search Patterns
- **Direct answer**: Synthesized answer at top, traditional results below
- **Source attribution**: Every AI answer links to source documents
- **Confidence**: Only show direct answer when confidence is high
- **Follow-up**: "Ask a follow-up question" for conversational refinement
- **Fallback**: If AI can't answer, show traditional search results gracefully
- **Transparency**: "AI-generated answer" label clearly visible
### Semantic Search UX
- Understand synonyms and related concepts automatically
- "Showing results for X" when query is reinterpreted
- Allow explicit override: "Search instead for [exact query]"
- Explain why results are relevant when not keyword-obvious
---
## Key Metrics
| Metric | Target | Context |
|--------|--------|---------|
| Search success rate | > 70% | Users who find what they need |
| Zero results rate | < 10% | Queries returning nothing |
| Click-through rate | > 40% | Clicks on search results |
| Time to first click | < 10s | Speed of finding relevant result |
| Search exit rate | < 30% | Users who leave after searching |
| Refinement rate | < 30% | Users who modify their query |
| Autocomplete usage | > 30% | Suggestions selected |
| Queries per session | < 2 | Finding it on first try |
---
## Anti-Patterns
1. **Hidden search** — Search behind an icon on content-heavy sites
2. **No autocomplete** — Missing the most basic search enhancement
3. **Search that ignores typos** — No fuzzy matching or spell correction
4. **Results with no snippets** — Just titles with no context
5. **No empty state guidance** — "No results" with no help
6. **Filter clearing on new search** — Losing filter context on new query
7. **Slow autocomplete** — Suggestions that appear after the user finishes typing
8. **Non-persistent queries** — Search term cleared on back navigation
9. **Search that only matches titles** — Missing full-text search
10. **No result count** — Users can't gauge if their query is too broad or narrow
---
## Sources
- [Nielsen Norman Group: Search UX](https://www.nngroup.com/topic/search/) — Usability research
- [Baymard Institute: Search UX](https://baymard.com/blog/categories/search) — E-commerce search patterns
- [Algolia: Search UX Best Practices](https://www.algolia.com/blog/) — Search implementation
- [Google Search Central: Search Guidelines](https://developers.google.com/search) — Search quality
- [WAI-ARIA: Combobox Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/) — Accessible autocomplete
- [Elasticsearch: Search UI](https://www.elastic.co/search-labs) — Search technology patterns
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |