Search Skill
How this skill behaves (read first)
This is a generative skill. The default failure modes: a box and nothing more (an input that returns a bare list — no suggestions, no query persistence, no recovery), dead ends ("No results found." period), and feature stacking (rich suggestions + trending + recent + filters + chips everywhere, even where search is a minor utility). Search is a journey — formulate → suggest → results → refine — and which stages need investment depends on how users seek. This skill gates:
- Establish how users seek and how central search is — that decides which stages to invest in.
- Apply the always-true core — discoverable placement, working input conventions, suggestion basics, a scannable results page, no dead ends.
- Surface the context-dependent decisions (rich auto-suggest, filter layout, chips, view options) with trade-offs.
Then it hands off to ux-heuristics-audit, ux-accessibility-audit, ux-aesthetics-audit, and ux-microcopy-audit for validation.
Step 0 — Establish context before designing
Ask if not known; state the assumption if proceeding without an answer:
- How do users seek here? Known-item (they can name what they want — invest in the input, auto-suggest, re-finding) vs. exploratory/semi-directed (vague needs that evolve — invest in suggestions, related searches, filters, browsing). Re-finding is chronically underserved: recent searches and history pay off everywhere.
- How central is search? Search-first product (e-commerce, docs, booking) → persistent, prominent search and a rich results page. Search-as-emergency-exit → simpler treatment, but still discoverable.
- Platform — mobile: persistent search (search-focused apps) vs. expandable icon (search-secondary apps); filters concealed behind a Filter button; comfortable one-handed targets.
- Result type — products with images vs. documents vs. data rows: drives list-vs-grid and what a result row shows.
Remember information needs evolve mid-search and people browse rapidly (most page visits <10s) — design for iteration and scanning, not one perfect query.
The always-apply core (correct for almost every case)
The input
- Put search where users look for it: top center or top right, on every page. Never behind a hamburger; on desktop, show the field itself, not just an icon.
- Magnifying-glass icon inside the bar, and it's a working button that submits the query.
- ~27-character input width — cramped inputs cause cramped, worse queries.
- Placeholder = example queries ("Search flights, hotels, destinations"), muted so it can't read as filled-in text — never a label replacement.
Suggestions (the formulate stage)
- Auto-suggest as users type — fewer typos, less cognitive load, faster queries. Cap at ~10 suggestions, no scrolling in the dropdown.
- Visually split typed vs. suggested characters (bold/color) so users can scan why each suggestion appears.
- Recent searches when the field is focused — recognition over recall for re-finding.
The results page
- Keep the query visible and editable — first attempts usually need tweaking; never make users retype.
- Show the match count — it tells users whether to refine, broaden, or start reviewing.
- Highlight matching keywords in results — users scan, they don't read.
- Loading is part of the experience: skeleton screens for result areas; progress/spinner with a short explanation for longer waits.
- Pagination type fits the content (see
ux-navigationfor the pagination vs. infinite scroll decision and control specs).
No dead ends — ever
A bare "No results found" is the single worst search failure. The No-Results page always offers a way forward: alternative query suggestions, category links, similar/related items, or recommendations from past behavior.
The context-dependent decisions (surface, don't auto-apply)
| Decision | Apply when | Avoid / adapt when | Default recommendation |
|---|---|---|---|
| Rich auto-suggest (thumbnails, category links, product previews) | Known-item seeking with visual goods (e-commerce) | Simple utility search — clutter slows the dropdown | Plain query suggestions first; enrich only when recognition genuinely speeds choice |
| Trending/related searches before typing | Exploratory products where inspiration helps (stores, media) | Task tools where it's noise | Show for discovery-driven products only |
| Persistent vs. expandable search (mobile) | Persistent for search-focused apps; expandable icon to save space elsewhere | Hiding search in a search-first app | Match prominence to search centrality |
| Filters | Results sets large enough to need narrowing | A dozen results (filters are overhead) | 5–7 visible filters, rest behind "More filters"; most-used first (from data); checkboxes for multi-select; familiar words ("Fabric," not "Textile") |
| Filter layout | Vertical sidebar: many filter groups, desktop. Horizontal panel: few, attention-grabbing. Mobile: behind a Filter button above results | Horizontal with many groups (eats the screen); sidebars users overlook | Vertical for filter-heavy desktop; horizontal for ≤ a handful; concealed on mobile |
| Auto-update vs. Apply button | Auto-update results as filters change (low interaction cost) | Slow connections / heavy queries — batch with an Apply button showing the match count | Auto-update when fast; Apply+count when not |
| Filter chips | Compact, tappable refinement ("Open now," "Price: $$") updating results in place; applied-filter overview tags with × to remove | Mixing single- and multi-select chip sets on one page; chips below 48px touch targets | Chips for quick filters + applied-filter overview; full panel for deep filtering |
| Sorting | Always for comparable items (price, date, popularity) — users often prefer sorting over filtering | Merging it into the filter panel (different mental model) | Separate, visible sort control |
| List vs. grid view | List: spec-comparison (model numbers, ratings). Grid: visual goods | Forcing one view for mixed content | Default to the fit; offer a view toggle |
Validate the result (orchestration)
Hand-offs name each lens by its installable skill
name. Invoke one only if that skill is installed; if it isn't, this skill's own core already carries these rules — proceed without it rather than blocking.
After generating or revising, hand the result to the audit lenses rather than declaring it done. These are candidate lenses — posture is set by docs/orchestration-policy.md, or route the whole thing through ux-design-review. Here, heuristics and microcopy are Tier A (auto-run); accessibility, aesthetics, information-architecture, and mobile-responsiveness are Tier B (offered) — under an existing design system aesthetics is suppressed and accessibility narrows to usage; mobile-responsiveness applies only on mobile. If the user invoked this skill for one specific thing, respect that scope.
ux-heuristics-audit(Tier A) — visibility of system status (loading, match counts, applied filters shown twice), user control (clear-all-filters, editable query), recognition over recall (recent searches).ux-accessibility-audit(Tier B — offer; narrow under a design system) — keyboard operability of the suggestion dropdown, touch targets (chips ≥48px, spacing ≥8px), contrast, focus management between input and results.ux-aesthetics-audit(Tier B — offer; suppress under a design system) — results-page density and scannability, dropdown clutter, filter-panel visual organization.ux-microcopy-audit(Tier A) — placeholder examples, filter labels in users' language, No-Results message tone and guidance.ux-information-architecture-audit(Tier B — offer) — whether the content structure feeding search (categories, facets, metadata) supports the seeking modes, and whether browse paths complement search; this skill designs the search journey, IA owns the structure it searches.ux-mobile-responsiveness-audit(Tier B — offer; applies only on mobile) — when the context is mobile: expandable/persistent pattern, concealed filters, one-handed reach.
If the audits surface a conflict (e.g., rich suggestions vs. dropdown speed and clarity), resolve back toward the primary task: the user wants to find the thing — every feature must shorten that path.
Common do/don't patterns
| ❌ Don't | ✅ Do |
|---|---|
| Search behind a hamburger / icon-only on desktop | Visible field, top center/right, every page |
| Tiny input that fits two words | ~27 characters — room to think in keywords |
| Suggestion dropdown with 25 scrolling entries | ≤10, no scroll, typed vs. suggested visually split |
| Query vanishes when results load | Query stays, editable |
| "No results found." and nothing else | Alternatives: corrected queries, categories, related items |
| Bare result list with no count | Match count + highlighted keywords |
| 20 filters dumped in a sidebar | 5–7 visible, popular first, rest behind "More filters" |
| Applied filters invisible once set | Shown twice: checked in panel + removable overview tags |
| Sorting buried inside filters | Separate sort control — different mental model |
| Radio buttons for combinable criteria | Checkboxes / multi-select chips |
| Blank screen while results load | Skeleton screens; spinner + explanation for long waits |
| Ship without checking | Hand off to heuristics + accessibility + aesthetics + microcopy |
