Search result highlighting

Problem Context

• Search results include long titles, summaries, transcripts, records, documents, tickets, messages, products, logs, or knowledge articles.
• Users need to scan many results quickly and decide which result is worth opening.
• Search logic may match across several fields, synonyms, snippets, or semantic fragments that are not obvious from the result title alone.

Selection Rules

• Choose search result highlighting when returned results need visible evidence of where the submitted query matched.
• Highlight specific terms, phrases, or backend-provided fragments rather than entire result cards.
• Show highlighted snippets only for fields that participated in matching or that the system can explain honestly.
• Use field labels when matches can appear in title, body, metadata, comments, attachments, or hidden indexed fields.
• Show surrounding text and fragment boundaries so a highlighted term has readable context.
• Use mark semantics or equivalent text-level markup for highlighted passages, then style the match with contrast, border, weight, or underline in addition to color.
• Sanitize backend-provided highlight markup or convert it into safe text nodes before rendering result cards.
• Clear stale highlights when users clear the query, change scope, alter filters, or move to a no-results state.
• Explain fuzzy, synonym, semantic, or analyzer-driven highlights when the displayed match is not an exact query-word match.
• Avoid highlighting if the query is empty, sensitive, hidden for privacy, or too broad to produce meaningful match emphasis.

Required States

• No query state with no highlighted terms.
• Submitted query with one or more highlighted result fields.
• Multiple matching fields state with title, snippet, and metadata labels.
• Snippet truncation state with ellipsis or fragment boundaries around removed text.
• No highlighted fragment available state that still explains why the result appears when possible.
• Fuzzy, synonym, or semantic match state with a cue that the highlight may not be an exact word match.
• Updated query state where old highlights are removed before new ones appear.
• No-results state with all previous highlights cleared.
• Unsafe or invalid highlight markup fallback state that renders safe plain text.

Interaction Contract

• A highlight represents the submitted query or configured highlight query, not a decorative emphasis chosen independently from search matching.
• Changing the query updates highlighted words, snippets, match counts, and result summaries together.
• Toggling which fields are highlighted changes only the emphasis layer, not the underlying result set or ranking.
• Opening a result preserves the query context or provides a path back to the highlighted result list.
• Highlight styling remains readable in selected, focused, hover, dark, high-contrast, and printed states.
• Screen-reader and keyboard users can understand match location from result text, field labels, counts, and context rather than color alone.
• Backend highlight markup is treated as untrusted content unless it has already been sanitized by the rendering layer.
• If the highlighter is approximate for complex or semantic queries, the UI does not overclaim exact boolean satisfaction.

Implementation Checklist

• Keep a canonical submitted query separate from draft input so highlights match the result set currently shown.
• Tokenize or request highlight fragments from the search service using the same analyzer or highlight configuration as the search query.
• Render matches as safe text nodes and mark elements, or use a trusted highlight component that escapes raw content.
• Include field labels and match counts when more than one result field can contain highlighted fragments.
• Limit snippet length, show ellipses or boundaries, and keep enough surrounding words for comprehension.
• Style mark elements with sufficient contrast and at least one non-color cue such as weight, border, underline, or background shape.
• Test exact, phrase, prefix, fuzzy, synonym, CJK, diacritic, punctuation, and case-insensitive queries against the displayed highlight behavior.
• Remove stale highlight state before showing no-results, error, loading, or empty-query states.

Common Generated-UI Mistakes

• Highlighting whole cards, rows, or table columns instead of the matching terms.
• Using color-only yellow text as the sole signal that a word matched.
• Showing highlights that come from popularity, ads, categories, or business rules instead of the submitted query.
• Injecting backend highlight HTML directly into result cards without sanitization.
• Leaving old highlighted terms visible after the query changed.
• Treating approximate semantic snippets as exact proof that every query condition matched.

Critique Questions

• Can users tell exactly which words, phrases, or fragments caused each result to match?
• Does the highlight map to the submitted query and field labels rather than unrelated metadata or ranking rules?
• Is there enough surrounding snippet text to judge relevance without opening every result?
• Can users distinguish exact, fuzzy, synonym, and semantic highlights when that difference affects trust?
• Does the implementation sanitize backend markup and avoid raw HTML injection?
• Are highlights still understandable without color perception or with assistive technology verbosity disabled?