kandev/docs/specs/ui/system-design/adaptive-kanban.md

status, system, requirements, created, owners

status	system	requirements	created	owners
current	ui	REQ-UI-ADAPTIVE-KANBAN-001	2026-09-05	kandev

Adaptive Kanban System Design

Purpose and boundaries

The UI system owns the desktop Kanban grid, its contained horizontal overflow, and its drag-time geometry.

This design covers desktop column sizing and drag scroll anchoring. It does not change workflow data, move permissions, or task persistence.

Requirement mapping

Requirement	Design sections
REQ-UI-ADAPTIVE-KANBAN-001	Components and responsibilities, Drag control flow, Responsive boundaries

Components and responsibilities

• getKanbanColumnGridTemplate defines each desktop column as minmax(280px, 1fr).
• AdaptiveDesktopKanban owns the horizontal scroll window and the lane grid.
• AdaptiveDesktopKanban adds drag-only end space after the grid's overflowing tracks.
• useKanbanDragScrollAnchor records the source column position before drag state changes the rendered steps.
• SwimlaneKanbanContent derives normal steps, move-target steps, temporary steps, and the active drag state.

The lane grid keeps min-width: 100%. Columns share available width until their 280px minimum requires contained horizontal overflow.

Drag end-space contract

A drag can reveal auto-hidden destinations before or after the source column. The scroll window needs end space to restore the source position.

The drag reserve uses a trailing spacer after a width-constrained lane grid. The spacer extends the scrollable area after overflowing tracks without reducing space for grid tracks.

The lane grid must not use end padding or margin for this reserve. Padding reduces the grid content box, and margin starts at the grid border edge instead of after overflowing tracks.

The reserve exists only while a task drag is active. The normal board has no additional end space.

The desktop scroll window hides its native horizontal scrollbar while drag state is active. The window keeps its internal scroll range so pointer-driven and automatic drag scrolling continue to work. Document width remains unchanged.

Drag control flow

1. The drag-start handler records the source step and its viewport position.
2. The handler starts the existing drag state.
3. SwimlaneKanbanContent adds temporary auto-hidden destinations when required.
4. AdaptiveDesktopKanban sizes the lane grid to the viewport or its minimum track width, then adds the end spacer after it.
5. useKanbanDragScrollAnchor adjusts scrollLeft after the rendered step key changes.
6. A drop or cancellation clears the drag state and removes the end spacer.
7. The anchor hook restores the final scroll position and then clears its saved anchor.

If the source step no longer exists, the hook keeps the current scroll position. The authoritative task update controls the final rendered steps.

Responsive boundaries

The desktop layout uses this design. The tablet layout keeps its two-column snap-scrolling surface.

The phone layout keeps one focused column and separate touch drop targets. This correction does not change mobile composition or touch behavior.

The existing mobile auto-hide E2E scenario covers the nearest mobile surface. It proves touch destinations and document-width containment.

Test strategy

• Component tests assert that drag state uses a trailing spacer and does not use end padding.
• The Chromium Kanban E2E scenario compares every rendered desktop column before and during drag.
• The same Chromium scenario covers a board whose minimum track width exceeds the viewport and verifies the added scroll range.
• The Chromium scenario verifies document containment and the absence of a transient drag-only scrollbar.
• The same E2E scenario proves temporary destinations, cancellation, and a successful drop.
• The existing mobile-chrome scenario continues to prove mobile drag destinations and document-width containment.

Related decisions

No architecture decision record applies. This design keeps the existing grid and drag-anchor boundaries.