Adaptive layouts (list-detail, supporting-pane, feed)

app-layout specs/app-layout/adaptive-layouts.kmd

Three canonical responsive layouts — list-detail, supporting-pane, feed — that every Koder product surface SHOULD instantiate instead of inventing one-off two-pane / multi-column / scroll geometries. Modeled after Material 3 adaptive foundations; covers phone / foldable / tablet / desktop.

When this spec applies

Primary triggers

Pick a responsive layout for a new Koder product surface

All triggers

Lay out an inbox-style two-pane (list + detail)
Show a primary canvas with a dismissable side panel
Render a single-column scrollable feed

Spec — Adaptive layouts

Status: v0.1.0 — Draft. Mirrors Material 3 adaptive foundations at the spec level; implementation in koder_kit / koder_web_kit is per-surface and out of this spec's scope.

R1 — Three canonical layouts

Layout	Use case	Reference
list-detail	Inbox, library, file list with preview pane	Material 3 `list-detail-pane-scaffold`
supporting-pane	Primary canvas + dismissable side panel (filters / details / chat)	Material 3 `supporting-pane-scaffold`
feed	Single-column scrollable content (timeline, blog, news)	Material 3 + USWDS content-feed pattern

Products MUST pick one of these three by default. Other geometries (multi-column dashboards, masonry grids, kanban boards) are case-by-case and SHOULD open a follow-up KDS ticket if recurring across products.

R2 — Breakpoints (canonical, Verge-derived)

Token	Pixels	List-detail	Supporting-pane	Feed
`--kds-bp-xs`	< 600	List only; tap row → push detail	Primary only; pane → bottom sheet	Single column, full width
`--kds-bp-sm`	600–900	List + detail stacked vertical OR list only with push	Primary + pane collapsible (60/40 split)	Single column, max-width 720px
`--kds-bp-md`	900–1240	List left (320px) + detail right	Primary 70% + pane 30%	Single column, max-width 760px
`--kds-bp-lg`	≥ 1240	List left (360px) + detail right (max-width clamp)	Primary + pane up to 400px	Single column, max-width 780px

list-detail (xs): tap row → push detail; back button or system-back pops detail and restores list scroll position.
list-detail (sm+): tap row → highlight + detail-pane swap; URL updates per detail id; back-stack carries last-selected.
supporting-pane: pane open/close is local state; URL does NOT reflect pane state by default.
feed: no navigation; pure scroll.

R4 — Back-stack semantics

Per specs/navigation/back-behavior.kmd: list-detail two-pane on xs is a stack (list → detail); on sm+ it is a single screen with side-by-side canvas. Esc on desktop closes detail / supporting-pane.

R5 — Focus order on resize

When the viewport crosses a breakpoint mid-session:

Currently-focused element retains focus if still visible.
If focus would land on a now-hidden element (e.g., detail content hidden when xs collapses to list-only), focus moves to the parent surface (list row or page heading).
Live-region announce: "Layout updated for narrower / wider viewport".

R6 — Prefers-reduced-motion

Layout transitions (pane slide, detail push) MUST honor prefers-reduced-motion: reduce: replace slide with instant swap.

R7 — Live demo

/<locale>/app-layout/adaptive-layouts/ renders 3 interactive iframes (one per layout) sized via a slider so reviewers can test breakpoint transitions without resizing the browser. Backlog: separate UI ticket in design-gen for the demo page (this spec ratifies the contract).

Não-escopo

Per-product implementation in koder_kit (separate tickets).
Animated transitions between adjacent layouts (out of v0).
Specific data fetching / pagination per layout (transport-agnostic).

References

specs/app-layout/safe-area.kmd
specs/navigation/back-behavior.kmd
specs/themes/verge.kmd