Cmd+K Search Modal UI: Results Lists, Keyboard Hints, and Empty States (HTML/CSS-First)

What “good” looks like in a Cmd+K modal

A Cmd+K search modal is not a toy feature. It becomes the hidden front door to your product. When it’s good, users build muscle memory and stop hunting through navigation. When it’s bad, they stop trusting it—and then they stop using it. And once people stop using search, your carefully curated information architecture becomes the only way out, which is… ambitious.

One dry truth: a search modal is like a pager. It’s quiet when everything’s fine, and when it’s needed, it’s needed now. Build it like you’ll be debugging it at 2 a.m. with one eye open.

Facts and historical context you can steal for decisions

Here are concrete bits of history and industry drift that explain why users expect Cmd+K to work a certain way. These aren’t trivia. They’re constraints disguised as fun facts.

1. Command palettes weren’t born on the web. Power-user editors (notably IDEs) normalized “type to search commands” long before browsers did, so users arrive with strong expectations about keyboard behavior.
2. Spotlight popularized “search as a launcher.” OS-level search taught people that search isn’t just finding documents; it’s a universal action picker.
3. Cmd+K became a de facto convention on the modern web because it’s memorable, doesn’t conflict with “Find in page” (Cmd+F), and platforms needed a shared muscle-memory shortcut.
4. The WAI-ARIA combobox/listbox patterns evolved slowly because accessible “typeahead + list” is surprisingly tricky; many early patterns broke screen readers or keyboard navigation.
5. Modal dialogs have a long history of focus bugs because focus-trapping is not a native browser primitive; you’re approximating a desktop window manager inside a page.
6. “Instant search” expectations track hardware progress. As devices got faster, the tolerance for “wait after each keystroke” evaporated; UX norms tightened.
7. CDNs made asset delivery cheap, not state delivery. Shipping a big index to the client can feel “fast” locally, then melt low-end devices with memory pressure.
8. Mobile changed the meaning of keyboard hints. A footer full of keycaps is noise on touch-only devices; hints must adapt.

Decision use: treat Cmd+K as a muscle-memory feature. Your primary KPI is not “time to implement,” it’s “time to succeed per query under stress.”

Anatomy: input, results list, footer hints, and states

A Cmd+K modal is a small UI, but it has distinct sub-systems. If you don’t name them, you’ll debug them as one blob. Name them. It helps.

Most palettes are 70% results list behavior, 20% focus semantics, 10% everything else. The list is where UX dreams go to die—because it’s where latency, ranking, accessibility, and human impatience meet.

HTML/CSS-first structure (progressive enhancement)

HTML/CSS-first doesn’t mean “no JavaScript.” It means the markup expresses intent, states are visible, and JS enhances behavior rather than inventing it from scratch. In reliability terms: you want graceful degradation and observable states.

Baseline markup: dialog + input + list + footer

Use a real dialog if you can, but treat it as a UI primitive, not a magic spell. You still need focus management and scroll locking around it. Your HTML should still make sense if the selection logic fails.

Accessibility semantics you should not freestyle

Pick a known ARIA pattern and follow it. For a “typeahead + results list” you’ll generally end up with a combobox-ish pattern or a simpler textbox + listbox with active descendant. The specific pattern depends on whether results are “suggestions” or a separate results list. Whatever you do, make sure screen readers can announce:

• Where focus is (input vs list)
• How many results exist
• Which item is selected

Opinion: if your app already has mature a11y infrastructure, implement the full active-descendant pattern. If not, keep it simpler but correct: don’t ship half a combobox.

One joke, short and practical: A modal without focus management is like a data center without doors—technically “open,” operationally terrifying.

Results list that survives reality

Results lists in command palettes tend to be built like a social feed: lots of nested elements, icons, metadata, tags, highlighting, buttons, hover menus. Then someone asks why arrow-key navigation stutters. Because you built a mini DOM cathedral and you’re asking it to reflow 60 times per second.

Rules for a list that stays fast

• Keep the row DOM shallow. A row should be: title, optional snippet, right-aligned hint. Not a nested UI framework.
• Stable identity. Don’t key results by index. Key by a stable identifier or URL path. Otherwise selection jumps when results update.
• Selection is a state, not a hover effect. Use aria-selected and a visible style that works without hover.
• Scroll the list, not the page. Give the results container a max-height and overflow:auto.
• Don’t highlight by rebuilding innerHTML. Use a render function that splits text safely, or precompute highlight ranges. InnerHTML is where XSS and performance issues shake hands.

Keyboard behavior: pick one model

There are two common models. Choose explicitly:

• Focus stays in the input, and arrow keys change “active descendant” in the list. This keeps typing stable and makes IME/composition easier. It’s also more complex a11y-wise.
• Focus moves into the list on first arrow down, and back to input on typing. Simpler semantics, but you must ensure typing doesn’t get swallowed, and focus restoration is correct.

From a reliability angle, “focus stays in input” usually leads to fewer “I can’t type anymore” bugs. It’s harder to implement correctly, but it fails less catastrophically.

Ranking + grouping without confusing the user

Grouping is useful: recent items, top matches, commands vs documents. But grouping can also make keyboard navigation feel broken if selection jumps across group headers. If you show group headers, make them non-selectable and visually quiet.

Also: keep ranking consistent. If you mix “recent” and “best match,” label it. People will forgive weird ranking if it’s explained. They will not forgive a list that changes order mid-typing without telling them why.

Keyboard hints: show them without yelling

Keyboard hints are UI documentation that you ship into production. That means they need to be:

• True (they match actual behavior)
• Contextual (don’t show “Enter to open” if there is nothing selected)
• Adaptive (don’t force keycap art on touch devices; don’t show Cmd on Windows)

Keycap rendering that doesn’t look like a ransom note

Use simple CSS for keycaps. Avoid inline SVG per key. You’ll bloat the DOM and make them hard to theme. Keep keycap components consistent: border, background, and slight inset shadow. It’s small, but it makes the palette feel “native.”

Hints as a state machine

Hints should reflect state:

• Idle (no query yet): show examples (/ for scope, or “Type to search…”)
• Searching: show “Searching…” and Esc to close
• Results available: show navigation + action keys
• Empty: show how to broaden the query, and optionally a “search everywhere” fallback
• Error/offline: show retry key or “Open in browser search” fallback

The other joke (and the last one, relax): If your footer says “Press Esc to close” and Esc doesn’t close, congratulations—you’ve invented a trust regression test.

Empty states: silence is a bug

An empty state is not “no results.” It’s a branch in the user’s story. And in production systems, every branch needs observability because it’s where confusion lives.

Three empty states you need (not one)

• No matches: query returned zero results. Provide suggestions and explain scope.
• Not indexed yet: the data exists but isn’t searchable. Say so. Provide a fallback path.
• Access-limited: the user might not see items due to permissions. Acknowledge this without leaking sensitive info.

Empty state content that reduces tickets

Good empty states answer three questions:

1. Did the system hear me? Echo the query (sanitized if needed).
2. Where did it search? “Docs only” vs “Everything.”
3. What now? Suggestions, scope operators, or a way to request access.

Operational angle: if you can’t differentiate “no results” from “search backend timed out,” you’ll spend weeks chasing “search is flaky” reports that are actually UX ambiguity.

When “No results” is a lie

Two classic causes:

• Race conditions: you show the empty state for a fast response to an older query, then overwrite it with results from the latest query, or vice versa.
• Over-aggressive debouncing: your UI delays requests, but your empty state triggers immediately based on local filtering, so it briefly shows “No results” on every keystroke.

Fix it with request sequencing (monotonic request IDs) and by tying states to the same lifecycle: if you debounce requests, debounce empty-state transitions too.

Performance and reliability: the boring constraints

Cmd+K feels like a frontend feature until it takes down a search endpoint, and suddenly it’s an SRE feature. You need budgets and backpressure.

Latency budgets: what to aim for

• Open modal: under 100 ms, including focus placement.
• First results after typing: under 150–250 ms perceived, ideally with optimistic local results if available.
• Arrow navigation: should feel instant; any jank is a bug.

Backpressure: do not DDOS yourself

Typing generates burst traffic. If you call the backend on each keystroke, you must use:

• Debounce (small, like 80–150 ms) and/or throttle
• Cancellation (abort in-flight requests)
• Client-side caching for recent queries
• Server-side rate limits that return a user-friendly response, not a 429 tantrum

Observability: measure what matters

Track:

• Time to open (keydown → input focused)
• Time to first results (query change → list populated)
• Empty-state rate, by scope and by user agent family
• Error rate and timeout rate (and whether UI showed “No results” instead)
• Backend query rate per user (spikes mean debouncing or caching broke)

SRE brain trick: treat the modal as a client that produces load. It’s not “the UI.” It’s a traffic generator with a keyboard attached.

Three corporate mini-stories from the trenches

1) Incident caused by a wrong assumption: “Search results are public anyway”

A mid-sized company built a unified Cmd+K palette that searched docs, tickets, and internal service dashboards. The team assumed that if an item appears in navigation, it’s safe to show in search results. That assumption held for the docs. It failed spectacularly for tickets and service metadata.

What went wrong wasn’t a data breach of content. It was a metadata leak. The results list showed titles and project names for items the user couldn’t open. “Access denied” appeared after selection, which the team thought was acceptable. In practice, the title alone contained sensitive clues: incident names, customer names, acquisition code names. The palette became an accidental gossip pipeline.

The bug survived code review because everyone tested with admin accounts. It survived staging because staging data was sanitized. It survived launch because “nobody complained” until one person did, loudly, in the sort of meeting you don’t want to attend.

The fix was not just adding permission checks. They changed the UI contract: results returned only items you can open, and for borderline cases they returned a generic “Restricted item” entry without revealing identifying metadata. They also added an empty-state hint: “If you expected something, you may not have access.” That single sentence reduced “search is broken” tickets and made the security posture obvious.

2) Optimization that backfired: client-side preindexing to “make it instant”

Another team decided to ship a precomputed index to the browser so the Cmd+K palette could work offline and feel instantaneous. It worked in demos. The index was compressed, delivered via CDN, and cached aggressively. The UI felt sharp on a MacBook.

Then it hit lower-end devices and long-lived browser sessions. Memory usage climbed. The app’s GC churn increased. The palette itself was fast, but everything around it got slower. Users didn’t say “the index is heavy.” They said “the app feels sluggish after lunch.” Classic.

Worse, the index update strategy was brittle. Because the index was cached aggressively, users got stale results after role changes and content updates. The empty state became misleading: “No results” for something that definitely existed… yesterday.

The rollback lesson: “offline” is not a free feature. The team moved to a hybrid: small local cache for recent and pinned items, server search for the long tail, and strict cache invalidation keyed to authorization versioning. The palette became slightly less magical, but the application stopped quietly eating RAM like it was a hobby.

3) Boring but correct practice that saved the day: feature flag + canary + error budget

A large enterprise rolled out a new command palette implementation across multiple internal apps. The UI team did the right boring things: feature flag, canary cohorts, and a clear SLO: “Search request error rate < X, p95 latency < Y.” No heroics. Just discipline.

During canary, metrics showed a strange spike: error rates increased only for a certain region and only on Monday mornings. The UI itself looked fine. The team could have blamed the backend and moved on. Instead, they correlated the spike with a specific keyboard behavior: people opening the palette and pasting long strings (ticket bundles, meeting notes) which exploded query complexity downstream.

The fix wasn’t glamorous: input length limits with a friendly message, and backend-side query guards. The canary prevented a broad outage, and the feature flag allowed a quick disable in affected apps while the patch baked.

It wasn’t a “cool UI win.” It was a small operational win that prevented the kind of outage that earns you more observability work than you wanted for the quarter.

Practical tasks: commands, outputs, and decisions

UI bugs often live at the seam between frontend behavior and backend reality. These tasks are what you run when someone says “Cmd+K search is slow” or “search shows nothing” and you want to stop guessing. Each task includes a command, what the output means, and the decision you make from it.

1) Confirm the UI bundle didn’t regress in size

cr0x@server:~$ ls -lh /srv/web/assets/search-palette.*.js
-rw-r--r-- 1 root root 412K Dec 18 09:12 /srv/web/assets/search-palette.8b2c1a.js

What it means: The palette chunk is 412K on disk (pre-compression). If this used to be 120K, you probably shipped a dependency bomb.

Decision: If the chunk grew meaningfully, audit imports (fuzzy search libs, icon packs), and split “rare” features (highlighting, recent items) behind async boundaries.

2) Check gzip/brotli effectiveness for the palette chunk

cr0x@server:~$ gzip -c /srv/web/assets/search-palette.8b2c1a.js | wc -c
118902

What it means: Gzipped size is ~119KB. That’s plausible. If gzip size is close to raw size, the file might already be compressed/minified poorly or contains lots of incompressible data.

Decision: If compression is ineffective, remove embedded datasets, large JSON blobs, or base64 assets from the JS bundle.

3) Validate the server actually serves brotli when expected

cr0x@server:~$ curl -I -H 'Accept-Encoding: br' https://app.example.internal/assets/search-palette.8b2c1a.js
HTTP/2 200
content-type: application/javascript
content-encoding: br
cache-control: public, max-age=31536000, immutable

What it means: Brotli is active. If you don’t see content-encoding: br, your “fast” UI may be paying extra download costs.

Decision: Fix CDN/origin config before you touch the UI code. Bandwidth is the dumbest bottleneck and the most common.

4) Detect backend timeouts vs “No results” ambiguity

cr0x@server:~$ tail -n 20 /var/log/nginx/access.log | grep "/api/search" | tail -n 5
10.2.4.19 - - [28/Dec/2025:10:31:44 +0000] "GET /api/search?q=kafka HTTP/2.0" 200 4821 "-" "Mozilla/5.0"
10.2.4.19 - - [28/Dec/2025:10:31:45 +0000] "GET /api/search?q=kafak HTTP/2.0" 504 164 "-" "Mozilla/5.0"
10.2.4.19 - - [28/Dec/2025:10:31:45 +0000] "GET /api/search?q=kaf HTTP/2.0" 200 9912 "-" "Mozilla/5.0"
10.2.4.19 - - [28/Dec/2025:10:31:46 +0000] "GET /api/search?q=kafak%20runbook HTTP/2.0" 504 164 "-" "Mozilla/5.0"
10.2.4.19 - - [28/Dec/2025:10:31:47 +0000] "GET /api/search?q=kafka%20runbook HTTP/2.0" 200 10532 "-" "Mozilla/5.0"

What it means: You’re seeing 504s for certain queries. If the UI translates these into “No results,” users will think indexing is broken.

Decision: Update the UI to show an error state on non-200 responses, and add backend guards for query complexity.

5) Measure API latency distribution quickly

cr0x@server:~$ awk '$7 ~ /\/api\/search/ {print $(NF-1)}' /var/log/nginx/access.log | tail -n 10
0.021
0.034
0.112
0.487
1.902
0.029
0.041
0.055
0.078
0.090

What it means: Those numbers (if your log format includes request time as the penultimate field) show occasional multi-second responses. A palette will feel “flaky” even if the average is fine.

Decision: If tail latency exists, pursue p95/p99 improvements: caching, query limits, or precomputed popular results.

6) Confirm rate limiting isn’t punishing typing bursts

cr0x@server:~$ grep -E " 429 " /var/log/nginx/access.log | grep "/api/search" | tail -n 5
10.2.4.19 - - [28/Dec/2025:10:32:02 +0000] "GET /api/search?q=kafka%20runb HTTP/2.0" 429 89 "-" "Mozilla/5.0"
10.2.4.19 - - [28/Dec/2025:10:32:02 +0000] "GET /api/search?q=kafka%20runbo HTTP/2.0" 429 89 "-" "Mozilla/5.0"
10.2.4.19 - - [28/Dec/2025:10:32:02 +0000] "GET /api/search?q=kafka%20runboo HTTP/2.0" 429 89 "-" "Mozilla/5.0"
10.2.4.19 - - [28/Dec/2025:10:32:02 +0000] "GET /api/search?q=kafka%20runbook HTTP/2.0" 200 10532 "-" "Mozilla/5.0"

What it means: A burst of queries gets throttled until the last one squeaks through. The UI will “flash” empty/error states.

Decision: Debounce on the client, but also tune rate limits to allow short bursts per user. Rate limiting should protect infrastructure, not punish typing.

7) Check whether search requests are cacheable and cached

cr0x@server:~$ curl -I "https://app.example.internal/api/search?q=runbook"
HTTP/2 200
content-type: application/json
cache-control: private, max-age=0
vary: authorization

What it means: Not cached. Sometimes correct (personalized results), sometimes wasteful (public docs).

Decision: If results are safe to cache per-user, consider short-lived caching keyed by auth context. If results are not safe, at least add server-side memoization for identical queries within a time window.

8) Confirm the search backend is healthy (systemd service)

cr0x@server:~$ systemctl status search-api.service --no-pager
● search-api.service - Search API
     Loaded: loaded (/etc/systemd/system/search-api.service; enabled)
     Active: active (running) since Sun 2025-12-28 09:41:10 UTC; 52min ago
   Main PID: 2147 (search-api)
      Tasks: 24
     Memory: 612.4M
        CPU: 18min 22.118s

What it means: Service is up; memory is significant. If memory climbs continuously, you might have a cache leak or unbounded result sets.

Decision: If memory is suspicious, inspect heap/metrics; cap caches; enforce maximum response sizes.

9) Identify CPU saturation that correlates with typing storms

cr0x@server:~$ mpstat -P ALL 1 3
Linux 6.1.0 (search01)  12/28/2025  _x86_64_  (8 CPU)

10:34:21 AM  CPU   %usr %nice %sys %iowait %irq %soft %steal %guest %gnice %idle
10:34:22 AM  all   78.12 0.00  9.34   0.17 0.00  0.42   0.00   0.00   0.00 11.95
10:34:23 AM  all   82.55 0.00 10.02   0.12 0.00  0.38   0.00   0.00   0.00  6.93
10:34:24 AM  all   80.10 0.00  9.77   0.09 0.00  0.40   0.00   0.00   0.00  9.64

What it means: CPU is heavily used in userspace. That’s consistent with expensive ranking, fuzzy matching, or per-request index loading.

Decision: Profile backend query handling; pre-load indexes; reduce per-request allocations; limit fuzzy algorithms for short queries.

10) Determine whether you’re I/O bound (storage latency)

cr0x@server:~$ iostat -xz 1 3
Linux 6.1.0 (search01)  12/28/2025  _x86_64_  (8 CPU)

avg-cpu:  %user   %nice %system %iowait  %steal   %idle
          71.20    0.00    8.90    9.80    0.00   10.10

Device            r/s     w/s   rkB/s   wkB/s  rrqm/s  wrqm/s  %util  await
nvme0n1         980.0   220.0  7840.0  1960.0     0.0     0.0   92.0   7.80

What it means: High %util and meaningful await. If your search backend hits disk for every query (index on disk, cold cache), you’ll get p95 spikes that users feel.

Decision: Keep hot indexes in memory; tune page cache; reduce random reads; or move to a search engine designed for this workload.

11) Check for network-level issues between UI and API

cr0x@server:~$ ss -s
Total: 1382
TCP:   921 (estab 612, closed 245, orphaned 3, synrecv 0, timewait 245/0), ports 0

Transport Total     IP        IPv6
RAW       0         0         0
UDP       42        36        6
TCP       676       498       178
INET      718       534       184
FRAG      0         0         0

What it means: High timewait can indicate many short-lived connections. If HTTP keepalive is misconfigured, every keystroke might open a new connection.

Decision: Fix keepalive settings at the load balancer or Nginx; prefer HTTP/2 where possible; reduce per-request overhead.

12) Verify that the UI is not calling search when the modal is closed

cr0x@server:~$ journalctl -u search-api.service --since "10 minutes ago" | grep "q=" | tail -n 8
Dec 28 10:28:01 search01 search-api[2147]: request_id=2b7b q=runbook user=anon status=200
Dec 28 10:28:02 search01 search-api[2147]: request_id=2b7c q=runboo user=anon status=200
Dec 28 10:28:02 search01 search-api[2147]: request_id=2b7d q=runbook user=anon status=200
Dec 28 10:28:03 search01 search-api[2147]: request_id=2b7e q= user=anon status=400
Dec 28 10:28:03 search01 search-api[2147]: request_id=2b7f q= user=anon status=400
Dec 28 10:28:04 search01 search-api[2147]: request_id=2b80 q= user=anon status=400
Dec 28 10:28:05 search01 search-api[2147]: request_id=2b81 q= user=anon status=400
Dec 28 10:28:06 search01 search-api[2147]: request_id=2b82 q= user=anon status=400

What it means: Empty queries (q=) are being sent repeatedly. That’s often a UI lifecycle bug: clearing input triggers a request even when modal closes.

Decision: Add a client guard: don’t query for empty string; don’t query when modal is not open; cancel pending work on close.

13) Inspect database slow queries if search hits SQL

cr0x@server:~$ sudo -u postgres psql -c "select now() - query_start as age, state, left(query,120) from pg_stat_activity where datname='searchdb' order by query_start asc limit 5;"
   age   | state  | left
---------+--------+--------------------------------------------------------------
 00:00:05| active | select id,title from docs where title ilike '%kafka runbook%' l
 00:00:02| active | select id,title from docs where title ilike '%kafka runb%' limi
 00:00:01| active | select id,title from docs where title ilike '%kafka run%' limit

What it means: You’re doing wildcard ILIKE on every keystroke. That’s a predictable way to buy a bigger database bill and sadness.

Decision: Move to a proper full-text index, or at least constrain queries (prefix search, trigram index) and debounce harder.

14) Check index/cache hit ratio when using Redis for search caching

cr0x@server:~$ redis-cli info stats | egrep "keyspace_hits|keyspace_misses"
keyspace_hits:1829012
keyspace_misses:712334

What it means: Misses are high relative to hits. If your cache isn’t helping, you’re doing extra work for nothing.

Decision: Revisit cache keys (normalize queries), TTL, and whether caching is per-user vs global. If personalization kills caching, cache only the public subset.

Fast diagnosis playbook

When “Cmd+K search is slow” shows up in chat, you have two jobs: stop the bleeding and identify the actual bottleneck. Don’t start by rewriting ranking. Start by proving where time goes.

First: decide if it’s UI jank or backend latency

• UI jank symptoms: arrow navigation stutters, typing lags, selection highlight “teleports,” CPU spikes on the client.
• Backend latency symptoms: typing is smooth but results appear late; “loading” persists; retries help; errors correlate with traffic peaks.

Fast check: look for 5xx/429 in access logs for /api/search and compare with user reports.

Second: verify request patterns (you might be spamming)

• Are you sending requests for empty queries?
• Are you sending requests while the modal is closed?
• Do you cancel in-flight requests?
• Is there caching for repeated partial queries (k, ka, kaf)?

Third: isolate the slow layer

• If backend is slow: check CPU (mpstat), I/O (iostat), DB activity (pg_stat_activity), cache hit rate (Redis), then logs for query complexity spikes.
• If UI is slow: reduce list rendering complexity, avoid re-rendering the whole list on selection changes, and ensure highlight logic isn’t O(n*m) per keystroke.

On-call heuristic: if you see 429s, fix client request rate first. If you see 504s, fix timeouts and query guards. If neither exists, you likely have UI jank.

Common mistakes (symptoms → root cause → fix)

1) “Typing feels delayed”

Symptom: characters appear late; the cursor stutters.

Root cause: synchronous work on each keystroke (rendering too many DOM nodes; expensive highlighting; JSON parsing; fuzzy matching in the main thread).

Fix: keep DOM small; limit results shown; precompute highlights; move heavy search to a web worker if client-side; debounce network calls but not local input rendering.

2) “Arrow keys sometimes stop working”

Symptom: navigation works, then randomly doesn’t; focus appears lost.

Root cause: focus moved to a non-focusable element, or the modal closes and reopens without restoring focus; group headers accidentally become focusable.

Fix: keep focus in input (active-descendant model) or ensure list items are consistently focusable; on open, set focus deterministically; on close, restore focus to trigger.

3) “Esc closes, but background scroll is still possible”

Symptom: user scrolls and the page behind moves; modal stays put.

Root cause: body scroll lock not applied, or applied incorrectly for iOS/overflow containers.

Fix: lock scroll using a tested approach; ensure the scrollable region is the results container. Verify on mobile Safari specifically.

4) “No results” flashes while results are loading

Symptom: empty state shows briefly, then results appear.

Root cause: empty state tied to “results array length === 0” without considering “loading” state; race between requests.

Fix: explicit states: idle, loading, loaded, error. Tie each rendered view to a request ID.

5) “Results look right but open the wrong item”

Symptom: selection highlight is on item A; Enter opens item B.

Root cause: keys based on array index; list reorders; selection index points to old order.

Fix: store selection by stable result ID; update selection when results change; avoid index-based mapping for activation.

6) “Search worked yesterday; today it’s empty for some users”

Symptom: subset of users see empty state for known items.

Root cause: permission-aware search mismatch, stale client-side index, or caching that doesn’t vary by auth.

Fix: ensure search responses are authorization-correct; vary caches by auth context; version user entitlements and invalidate accordingly.

7) “Cmd+K stops working inside text areas”

Symptom: shortcut conflicts with editing or is blocked.

Root cause: global key handler ignores event target context or prevents default incorrectly.

Fix: don’t trigger inside editable elements; allow opt-out; keep key handling scoped and conservative.

8) “Screen reader users can’t tell what’s selected”

Symptom: list updates but no announcement; selection is silent.

Root cause: missing roles/ARIA relationships; active descendant not wired; selection only indicated visually.

Fix: implement a known pattern; ensure announcements; test with real screen readers, not just audits.

Checklists / step-by-step plan

Step-by-step build plan (HTML/CSS-first)

1. Define the contract: what can be searched (docs, commands, people), what metadata can be shown, and what happens on permission boundaries.
2. Mark up the dialog shell: include title, input, results container, and footer hints. Make it readable without JS behavior.
3. Implement focus rules: on open focus the input; on close restore focus; trap focus inside the modal; ensure Esc always closes.
4. Implement list navigation: decide focus model (active descendant vs moving focus). Make ↑/↓ deterministic.
5. Add states: idle, loading, loaded, empty, error/offline. Make each state visually distinct and copy-edited.
6. Add keyboard hints: only show keys that work in the current state. Adapt modifier keys by platform.
7. Performance guardrails: cap results shown; cap request rate; cancel in-flight requests; cache recent queries safely.
8. Observability: log request IDs and durations; instrument time-to-open and time-to-results; track empty-state rate.
9. Accessibility testing: verify with keyboard only; then screen reader; then high-contrast mode; then reduced motion.
10. Rollout plan: ship behind a feature flag; canary; watch error budgets; roll forward or back with intent.

Pre-launch checklist (things that break at scale)

• Modal open is under 100 ms on mid-tier hardware.
• Results navigation has no layout thrash (no scroll jump; selection stays in view).
• API can handle typing bursts without 429 storms.
• Timeouts produce an error state, not “No results.”
• Permission model: you do not leak titles of restricted objects.
• Empty state explains scope and offers a next action.
• Hints are correct on macOS and Windows, and not noisy on mobile.
• Closing the modal cancels work and restores focus reliably.

On-call checklist (when it’s already broken)

• Check access logs for 429/504 on /api/search.
• Check backend CPU and I/O saturation.
• Check whether the UI is issuing empty queries or background queries.
• Flip feature flag off if it’s causing load spikes.
• Communicate a user workaround (nav search, dedicated search page) while you fix the palette.

FAQ

Should Cmd+K search be a “command palette” or “search box”?

Make it both, but separate results types visually and semantically. Users will type “create invoice” as readily as “invoice 10492.” Don’t force them to guess which mode they’re in.

Do I need ARIA combobox, or can I just use a list under an input?

You can use a simpler textbox + listbox model, but you must still provide correct roles and selection announcements. A half-implemented combobox is worse than a well-implemented simple model.

How many results should I show?

Start with 8–12 visible rows and allow scrolling for more. A palette is for quick actions; showing 50 results without virtualization is a performance tax and a cognition tax.

Should the list update on every keystroke?

Yes, but that doesn’t mean you call the backend on every keystroke. Update the UI immediately (loading state), then fetch with debounce + cancellation.

How do I handle IME/composition input?

Don’t treat composition updates like finalized queries. Avoid firing requests during composition; trigger search when composition ends, or when you receive a committed input event.

What’s the best empty state copy?

Echo the query, state the scope, give two suggestions, and acknowledge permissions as a possibility. Avoid blaming the user. You’re not their English teacher.

Should I show “recent searches” or “recent items”?

Prefer recent items (what they opened) over recent queries (what they typed). Queries can be sensitive. Items are usually less personal and more actionable. If you store anything, keep it local and bounded.

How do I prevent the palette from hammering the backend?

Client debounce (small), cancel in-flight requests, cache recent queries, and add backend query guards. Then instrument query-per-user rates so you notice regressions.

Should I virtualize the results list?

Only if you truly show large lists. Virtualization increases complexity and can harm accessibility. For a palette, it’s often better to cap results and keep DOM simple.

How do I make keyboard hints platform-correct?

Detect platform at runtime and render Cmd vs Ctrl. Also don’t show modifier-heavy hints if the user is on a touch-only device.

Conclusion: next steps you can actually do

If you want a Cmd+K modal that feels like a native tool instead of a fragile overlay, do three things this week:

1. Make states explicit: idle, loading, loaded, empty, error. Stop letting “No results” cover for timeouts.
2. Audit the results list DOM: shallow rows, stable IDs, selection as state, and no innerHTML highlight hacks.
3. Put an SRE hat on it: measure request rates, tail latency, and empty-state frequency. Add backpressure before you need it.

Then ship behind a feature flag. Canary it. Watch it like you’d watch any service that can create load spikes. Because that’s exactly what it is: a service, with a keyboard.