Contract: Controls + Selection

Shared Base

This pattern inherits the shared table-management contract: kit/patterns/table-management/contract.md.
Reuse shared toolbar/table/icon geometry from the base contract first, then define only controls-specific additions below.

Use a small stable button taxonomy: primary, secondary, ghost, danger, disabled.
The canonical visual baseline for demo/scaffold examples is the active dual baseline used in the demo/scaffold (Vapor Soft / Vapor Night, system-selected). A frozen Aqua snapshot bundle may be kept for archival reference, but examples should follow the active baseline.
Destructive actions (archive, delete, remove) must use danger styling and explicit labels.
Button text should describe the action outcome, not implementation detail.
Buttons are text-first; icons are optional and must not replace labels on primary/danger actions.
Base examples must show both disabled and loading states.

Row checkboxes support bulk actions from a shared action bar.
Header checkbox semantics must be explicit:
- select visible rows only, or
- select all rows in query scope (must be clearly labeled)
Selection summary must show count (N selected) near bulk actions.
In paginated views, the UI should distinguish selection on the current page from selection across the filtered/query scope.
Selection state should survive pagination/filter navigation via explicit state (query params, server session, or another deterministic mechanism).
Same-page interactions should preserve reading position (module anchor pattern is preferred in canonical server-rendered flows).

Segment/toggle filters are allowed for small enumerations (status, active/archived).
Segmented controls are grouped joined-buttons:
- one shared outer shell,
- rounded corners only on the first/last segment,
- straight internal separators between middle segments.
Active segment color may vary by context (for example blue preset selector vs dark status scope tabs), but geometry must remain consistent.
Segment changes should preserve other active filters where possible.

Bulk action click should preview count and target scope before execution.
Destructive bulk actions require confirmation.
Dense bulk action bars may move rare actions into an explicit overflow menu (More actions) while keeping primary actions visible.