Adaptive layouts (list-detail, supporting-pane, feed)
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.
Spec — Adaptive layouts
*tatus* v0.1.0 — Draft. Mirrors Material 3 adaptive foundations at the spec level; implementation in
koder_kit/koder_web_kitis per-surface and out of this spec's scope.
R1 — Three canonical layouts
| Layout | Use case | Reference |
|---|---|---|
| *ist-detail* | Inbox, library, file list with preview pane | Material 3 list-detail-pane-scaffold |
| *upporting-pane* | Primary canvas + dismissable side panel (filters / details / chat) | Material 3 supporting-pane-scaffold |
| *eed* | Single-column scrollable content (timeline, blog, news) | Material 3 + USWDS content-feed pattern |
Products MUST pick one of these three by default. Other geometries (multicolumn dashboards, masonry grids, kanban boards) are caseby-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 |
R3 — Navigation contract
- *ist
detail (xs)* tap row → push detail; back button or systemback pops detail and restores list scroll position. - *ist
detail (sm+)* tap row → highlight + detailpane swap; URL updates per detail id; backstack carries lastselected. - *upporting-pane* pane open/close is local state; URL does NOT reflect pane state by default.
- *eed* no navigation; pure scroll.
R4 — Back-stack semantics
Per specs/navigation/back-behavior.kmd: listdetail twopane on xs is a stack (list → detail); on sm+ it is a single screen with sidebyside 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 — Prefersreducedmotion
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).