Files
kandev/docs/specs/ui/settings-discovery.md
T
2026-08-05 14:07:52 +01:00

123 lines
7.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
status: shipped
created: 2026-08-05
owner: kandev
---
# Settings Discovery
## Why
Kandev has enough settings that users cannot reliably infer which page owns a control. The
settings tree and command palette should help users find a setting by the language they remember,
without requiring them to browse every section or making the default command palette noisy.
## What
- The Settings tree shows a search field above its existing navigation on desktop and phone.
- On desktop, the search field follows the compact density of the surrounding navigation instead
of using phone-sized vertical chrome.
- An empty query preserves the existing tree, ordering, active route, accordion state, badges, and
plugin navigation.
- A non-empty query shows only matching first-party pages, sections, and controls, grouped by their
settings area. Each result shows its own label and an owning-page breadcrumb.
- As the query changes, matching rows use a brief layout transition instead of snapping between
positions. Newly matching rows enter softly, while reduced-motion users get immediate updates.
- Search matches translated labels and curated translated aliases. It never indexes saved values,
secrets, paths, URLs, prompts, or other user-entered configuration.
- At least one query token must match the result's own label or aliases. Other tokens may narrow by
breadcrumb. A parent name by itself does not flood results with every descendant.
- Exact labels rank above prefixes, aliases, and contextual matches; ties retain catalog order.
- Every indexed control has a canonical settings URL and stable fragment. Selecting it opens the
owning page, scrolls the control into view, focuses it without changing its value, and briefly
highlights it.
- Same-page targeting does not trigger the unsaved-settings leave confirmation. Cross-page
targeting uses the normal guarded router.
- Cmd+K exposes the same settings catalog only after the user types. The default palette retains
its compact top-level Go to Settings destination.
- Cmd+K setting results show Settings plus the owning hierarchy as secondary context. Selecting a
result navigates to the same exact target as Settings-tree search; it never edits the value.
- Typed Cmd+K results keep regular actions under Commands and place granular setting results in a
separate localized Settings section. Empty sections are omitted.
- Discovery respects the same auth, admin, feature, capability, and resource availability rules as
the rendered settings surface.
- Stable first-party pages and inline controls are indexed. Transient dialog fields, destructive
confirmations, generated collection rows, and opaque plugin-authored controls are explicitly
excluded.
## Permissions
Discovery does not grant access. Account, user-management, feature-gated, and capability-gated
entries appear only when the current user and runtime could render the destination. Installed
plugin pages may be discoverable from host-known metadata, but plugin-authored form internals are
not indexed without a plugin discovery contract.
## Failure modes
- Dynamic resource loading failures leave static settings searchable and omit unresolved dynamic
profile or workspace entries; no error replaces the command palette or settings tree.
- A stale or manually entered target fragment that has no registered control leaves the page
usable and does not move focus.
- A target rendered after asynchronous data arrives is revealed when it registers; discovery does
not use fixed-delay retries.
- Canceling the existing unsaved-settings navigation confirmation leaves the current page and draft
unchanged.
## Mobile contract
- The existing full-height Settings Sheet remains the phone entry point because the hierarchy is
dense and frequently searched; this feature does not introduce another overlay.
- Desktop and phone share catalog, filtering, ranking, navigation, and target state.
- The Sheet keeps one navigation scroll owner. The settings page keeps its existing content scroll
owner. Search does not add nested vertical or document horizontal scrolling.
- Search and clear controls have at least 44 px touch targets. Selecting a result closes the Sheet
and leaves the destination control focused.
## Scenarios
- **GIVEN** an empty Settings search, **WHEN** the tree renders, **THEN** its current groups, active
route, badges, and plugin slot remain unchanged below the search field.
- **GIVEN** the desktop Settings tree, **WHEN** the search field renders, **THEN** its visible height
aligns with a neighboring navigation row rather than the 44 px phone control height.
- **GIVEN** the query `font size`, **WHEN** results render, **THEN** Terminal font size appears under
General › Terminal and unrelated sections are absent.
- **GIVEN** visible Settings search results, **WHEN** the query changes and surviving results move,
**THEN** rows settle into their new positions with restrained motion rather than snapping.
- **GIVEN** reduced motion, **WHEN** Settings search results change, **THEN** rows update immediately
without layout or presence animation.
- **GIVEN** the query `General`, **WHEN** results render, **THEN** the General page can match without
every General descendant appearing solely because of its breadcrumb.
- **GIVEN** the query `workflows`, **WHEN** a dynamic workspace result renders, **THEN** its label is
the same translated `Workflows` navigation label, never a lowercase raw-key fallback.
- **GIVEN** a matching control on another settings page, **WHEN** the user selects it, **THEN** the
guarded router opens its canonical URL and the control is scrolled, focused, and highlighted.
- **GIVEN** a matching control on the current page with unsaved changes, **WHEN** the user selects
it, **THEN** the fragment changes and the control is revealed without a leave confirmation.
- **GIVEN** Cmd+K with no query, **WHEN** the palette opens, **THEN** granular settings are absent and
Go to Settings remains available.
- **GIVEN** Cmd+K with `terminal font size`, **WHEN** results render, **THEN** the exact setting and
Settings › General › Terminal context appear and Enter reveals the input.
- **GIVEN** a Cmd+K query matches both a regular action and a granular setting, **WHEN** results
render, **THEN** the action appears under Commands and the granular result appears under Settings.
- **GIVEN** a delayed agent or executor profile list, **WHEN** matching commands register, **THEN**
stable command IDs prevent the current matching selection from jumping.
- **GIVEN** reduced motion, **WHEN** an exact target opens, **THEN** scrolling is instant and the
highlight does not pulse.
- **GIVEN** a 390 px phone viewport, **WHEN** the user searches and selects a setting, **THEN** the
Sheet remains contained, closes after selection, and the destination is usable without horizontal
overflow.
## Out of scope
- Editing or toggling settings directly from Cmd+K.
- Server-side, semantic, or saved-value search.
- A broader Settings Sheet/Drawer or settings-layout redesign.
- Direct targets inside transient dialogs, confirmations, or individual generated rows.
- A public discovery metadata contract for plugin-authored controls.
- Backend, database, or persistence changes.
## Implementation plan
See [the implementation plan](../../plans/settings-discovery/plan.md) and
[ADR-2026-08-04-navigation-manifest-boundaries](../../decisions/2026-08-04-navigation-manifest-boundaries.md).