Master-detail

Problem Context

• The source items are conversations, orders, tickets, files, contacts, tasks, articles, cases, settings sections, media, or records.
• The detail content is substantial enough to need its own heading, body, local actions, history, comments, edits, or route state.
• Users often switch between adjacent items while keeping enough context to know where the current detail came from.
• The same product must work in narrow stacked mode and wider side-by-side mode without losing selection or navigation history.

Selection Rules

• Choose master-detail when list selection opens or owns a full detail destination and the layout must coordinate source and detail state.
• Choose master-detail when wide screens should show list and detail together while narrow screens should show either list or detail with a return path.
• Use details panel when the detail is a concise adjacent inspector and does not need navigable page-like behavior.
• Use list view when users only need to scan and act on rows without a coordinated detail destination.
• Use window splitter when users need to resize panes; pair it with master-detail only if the list-detail behavior is also defined.
• Use drawer or sheet when detail is temporary, opened by command, and should close after a side task.
• Use preview panel when the detail is primarily rendered document, media, or file preview rather than full object work.
• Use full-page navigation when side-by-side context adds little value or the detail is too deep for a shared layout.
• Avoid master-detail when no stable selected item exists.
• Avoid master-detail when responsive transitions would lose detail state, list position, or back navigation.

Required States

• Wide default state with master list, selected item, and detail pane visible together.
• Wide empty-detail state with a prompt when no item is selected.
• Stacked list state where only the master list is visible.
• Stacked detail state with selected-item heading and Back to list control.
• Selection changed state where list highlight, detail heading, route state, and local actions update together.
• Filtered-away selected item state with explanation, clear-filter path, or selection replacement.
• Viewport widened, narrowed, rotated, or folded state preserving list position, selected item, and detail state.
• Loading, failed detail, deleted item, permission-limited detail, unsaved detail draft, and unavailable detail states.
• Back navigation, browser history, deep link, and no-selection return states.
• Multiple-pane or tertiary detail state when the layout can add supporting content on large screens.

Interaction Contract

• Selecting an item in the master list updates the selected marker and detail heading to the same object.
• In side-by-side mode, selection can update detail without hiding the master list.
• In stacked mode, opening detail moves to the detail view and Back to list returns to the same master list position and filters.
• Changing viewport size preserves the current selected object and chooses whether list, detail, or both panes should be visible based on the active navigation state.
• If the selected item becomes filtered, deleted, or unavailable, the detail pane explains the state instead of showing stale content.
• Detail-local actions state which selected item they affect and do not silently act on a different master row.
• Deep links can open the detail directly and still provide a path to the relevant master list when the product supports it.
• Unsaved changes, scroll position, focus, and local detail state survive layout changes or trigger explicit review before being discarded.

Implementation Checklist

• Define the master collection, selected-item ID, detail route or state owner, empty-detail rule, and compact versus expanded layout breakpoints.
• Render a visible selected state in the master list and repeat the selected object name or ID in the detail heading.
• Implement stacked navigation with Back to list, browser history, focus return, and preserved list scroll position.
• Implement side-by-side mode with synchronized selection, detail refresh, and an empty placeholder when no selection exists.
• Persist selected item, filters, sort order, list scroll, detail scroll, local edits, and focus across viewport changes.
• Handle loading, failed detail fetch, deleted item, permission-limited detail, filtered-away item, no results, and direct deep link states.
• Keep resizable splitters, drawers, previews, and inspectors separate from the master-detail ownership model unless deliberately combined.
• Test keyboard selection, screen reader pane names, Back behavior, browser history, mobile rotation, tablet resize, long titles, localization, zoom, and stale-detail prevention.

Common Generated-UI Mistakes

• Calling a small metadata inspector master-detail when the detail cannot act as a destination.
• Forgetting the stacked mobile return path from detail back to the master list.
• Showing stale detail after selection, filter, delete, permission, or refresh changes.
• Resetting selection, filters, draft edits, or scroll position when the viewport crosses a breakpoint.
• Using a splitter as the only implementation while leaving selected-item ownership and navigation history undefined.
• Showing an unrelated default detail on wide screens before the user has selected an item.
• Embedding full primary editing in the detail without unsaved-change protection across selection changes.
• Letting list and detail actions target different objects because they are keyed by visible index instead of stable item ID.

Critique Questions

• What is the master collection, and which exact selected item owns the detail right now?
• Can the detail stand as a navigable destination, or is it only an inspector suited to details panel?
• What happens to selection, list position, detail scroll, and draft state when the layout switches between stacked and side-by-side?
• How do users return from detail to the list on compact screens?
• What should the wide layout show when there is no selection, a hidden selection, or a deleted item?
• Would list view, details panel, preview panel, drawer, window splitter, table, or full-page route better fit the task?