# Interaction conventions — channels-manager > Status: **BINDING on every sweep mockup and every build that follows one** > (operator, 2026-07-29: the sweep is worthless unless grounded in researched > principles rather than model memory). Sits under `design/tokens.md` in > precedence: tokens rule how a screen looks, this rules how it behaves. Where > a line here collides with `docs/DECISIONS.md`, DECISIONS wins and you surface > the collision instead of reconciling it. > > Every line carries a source key, resolved in **§4**. A line marked > `(judgment)` is a house call with no external source; those are few and > deliberate. Nothing else here is allowed to be a vibe. This is an **operator console**: a handful of named people, all day on a desktop monitor, doing investigative work under time pressure (`PRODUCT`). Not a consumer app, not a marketing site. Density, keyboard reach and honest state are the whole job. ## §1 Principles 1. **Speed is a feature and the bands are known.** 0.1s reads as instant, 1.0s is the limit for uninterrupted thought, 10s is the limit of held attention and owes a progress readout plus an escape. Over ~1s: optimistic state or a skeleton at once. Over 10s: progress plus cancel. (`NN-RT`) 2. **Every action gets feedback**, appropriate and within a reasonable time. No silent success, no silent failure. (`NN-H1`, `SHN-3`, `PRODUCT`) 3. **Plain words, the operator's words.** User's language and familiar concepts, no internal jargon. Only the integrator pages (ApiDocs, curl panel) are excepted. (`NN-H2`, `DEC`) 4. **Undo beats confirm, and the operator stays in control.** Reserve modal confirms for the irreversible; over-used confirms stop preventing anything ("cry wolf too many times, people stop paying attention"). Ship undo anyway, plus a marked exit from any unwanted state. (`NN-CD`, `NN-H3`, `SHN-6/7`) 5. **Direct manipulation.** Act on the displayed object with physical, incremental, reversible actions whose effect is immediately visible. Edit the row before opening a form about the row. (`NN-DM`) 6. **One pattern per job, and it is the conventional one.** Follow platform and industry convention rather than inventing; one job never gets two treatments. Opinionated defaults beat configurability: "flexible software lets everyone invent their own workflows, which eventually creates chaos". (`NN-H4`, `SHN-1`, `LIN-M`, `CLAUDE.md`) 7. **Prevent the error before catching it.** Eliminate error-prone conditions or confirm at the point of commitment. (`NN-H5`, `SHN-5`) 8. **Recognition over recall.** Options, filters and current state stay visible; never make the operator carry an ID or a filter in their head across screens. (`NN-H6`, `NN-RR`) 9. **Accelerators for the expert, invisible to the novice.** Frequent actions reachable without the mouse; the full list one `?` away. (`NN-H7`, `LIN-KS`) 10. **Minimalist by subtraction, then progressive disclosure.** "Every extra unit of information competes with the relevant units." Rare controls defer to a second layer and the reveal mechanism is obvious. (`NN-H8`, `NN-PD`, `NOTION-W`) 11. **Errors name the cause and the fix**, in plain language, never a dead end. (`NN-H9`, `B2`) 12. **Fewer choices and bigger targets are faster.** Decision time grows with option count, acquisition time falls with size and proximity. Floor 24x24 CSS px, house floor 36px. (`IXDF-HICK`, `NN-FL`, `WCAG-258`, `PRODUCT`) 13. **Keyboard operability is not optional and focus is always visible.** All functionality keyboard-operable (2.1.1), focus order preserves meaning (2.4.3), the indicator is visible (2.4.7) and not hidden behind sticky chrome (2.4.11, new in 2.2). Sticky toolbars and selection bars are the usual 2.4.11 offenders. (`WCAG-211/243/247/2411`) 14. **Every dynamic surface designs all six states**: empty, loading, error, success, partial, offline, each with its entry trigger and its exits. Shipping the happy path alone is the named failure. (`B2`, `PRODUCT`) 15. **Colour carries meaning, never identity and never decoration.** One indigo accent on zinc; status is a word plus a colour, never colour alone. Restricting the palette is an accessibility decision: Stripe limits app colours "because color contrast is an important aspect of accessible UI". (`TOKENS`, `DEC`, `WCAG-141`, `STRIPE-D`) ## §2 Pattern conventions ### Tables and lists - Default column order reflects importance to the operator; related columns sit adjacent so the eye travels less. (`NN-DT`) - The first column is a **human-readable identifier** (name, phone, subject), never an auto-generated ID. (`NN-DT`) - **Text left-aligned, numbers right-aligned**, headers copying the alignment of the data beneath. (`EU-TBL`) - Numbers use **tabular figures** (`font-variant-numeric: tabular-nums`, OpenType `tnum`) in tables and stat tiles. (`MDN-FVN`, `BUTTERICK`, `TOKENS`) - Number formatting is consistent within a column: same rounding, same digits, same or no prefix. Missing values render as the em-dash glyph, the only place that character appears. (`EU-TBL`, `TOKENS`) - **Row density is a house value, not a per-screen choice**: row padding 9px, cells 13px. Carbon offers four row heights as a system-level decision; we made ours once and screens do not override it. (`TOKENS`, `CARBON-DT`) - **Header rows freeze** when the table outgrows the viewport. (`NN-DT`) - Hairline separators plus **whole-row hover highlight** to hold place. We use hover rather than zebra striping because rows already carry hairlines. (`NN-DT`, `TOKENS`) - **Sorting** lives on the header, ascending/descending, with the active column and direction visibly marked. (`CARBON-DT`, `EU-TBL`) - **Row click navigates to the record's detail. It never mutates.** (`POLARIS-IT`) - **Row actions**: one or two inline in a trailing right-aligned cell; three or more collapse to an overflow menu, since single-record actions "work only for one or two operations". Visible on hover *and* on keyboard focus. (`NN-DT`, `WCAG-211`) - **Pagination, not infinite scroll**, past roughly 50 rows. (`POLARIS-IT`, `CARBON-DT`) - Column hide/reorder, where offered, is easy and shows what is hidden. (`NN-DT`) ### Selection and bulk actions - Checkbox in the leading cell; **shift-click extends a contiguous range**; `Cmd/Ctrl+A` selects the page. (`POLARIS-IT`, `LIN-SEL`) - Selection reveals a **batch action toolbar placed with the table**, not floating detached over the page. (`CARBON-DT`, `DEC`) - The bar states the count and offers **select-across-pages explicitly** ("N selected on this page", then "Select all {total}"), never silently. (`POLARIS-IT`, `DEC`) - `Escape` clears the selection. (`LIN-SEL`) - Destructive bulk actions confirm; everything else offers undo. (`NN-CD`) ### Inbox and threads - **Master/detail**: list left, thread right, list stays visible so context survives. (`MD-WIKI`, secondary source) - Conversation navigation is `j`/`k` and `u` back to the list. (`GMAIL-KB`) - Conversation verbs: `r` reply, `a` reply all, `e` archive/resolve, `s` snooze, `x` select. Assignment `Shift+A` to self, `Shift+G` to a teammate. Front ships three interchangeable schemes, which proves the set is a preference, not a law: pick one and hold it. (`GMAIL-KB`, `FRONT-KB`) - **Internal notes read as internal at a glance**: `warn-soft` fill plus an explicit "Internal note" label, never colour alone. The yellow-note convention is real but third-party-reported for Zendesk, so ours derives from our tokens. The composer remembers its mode per conversation. (`ZD-NOTE` third-party, `TOKENS`, `WCAG-141`) - **Snooze in a shared inbox snoozes for everyone**, and the UI says so. (`FRONT-SNOOZE`) - Sending is never silent: an optimistic row appears at once, then resolves to sent or failed with a reason. (`NN-H1`, `NN-RT`) ### Canvas editors (the flow builder) Figma is the convention set. Where Figma has no answer it is marked. - **Pan**: hold `Space` and drag; arrow keys pan with nothing selected, `Shift` for a larger step. (`FIG-KB`) - **Zoom**: `Shift+1` fit, `Shift+2` to selection, `Shift +`/`Shift -` to step, modifier-scroll to zoom. (`FIG-ZOOM`) - **Multi-select**: `Shift`+click adds or removes, drag on empty canvas marquees, `Cmd/Ctrl+A` selects all. (`FIG-SEL`) - **Quick add / command menu**: `Cmd/Ctrl+K`. That is the current Figma binding; older docs say `Cmd/Ctrl+/`, so cite the current one. (`FIG-QA`) - **Inline rename**: double-click the node name on canvas, `Escape` to leave. (`FIG-REN`) - **Undo/redo** `Cmd/Ctrl+Z` and `Cmd/Ctrl+Shift+Z` (plus `Ctrl+Y`), no-ops while the caret is in a text field so the field owns its own undo. **Save** is `Cmd/Ctrl+S` and works even while typing. Both already correct in `useCanvasShortcuts.ts`; keep it. (`CODE`, `SHN-6`) - **A minimap is optional, not a Figma convention.** Figma ships none; every one on offer is a community plugin. Zoom-to-fit plus a node list is the cheaper answer for an oversized flow. (`FIG-MINI` verified absence; substitute is `judgment`) - Node deletion stays with the canvas library's own `Delete` handling, not a second global handler. (`CODE`) ### Filters and facets - Only the **one or two filters used on most visits stay inline**; the rest collapse behind one "Filters" control with a badge counting active ones. (`NN-PD`, `DEC`) - **Active filters stay visible and individually removable** without reopening the panel. (`NN-H6`, `NN-RR`) - Filter state lives in the **URL**; saved views are URL-only. (`DEC`) - Every option list is pulled from code or the API, never hand-written in a mockup. (`DEC`) - Filtered-to-zero is a **different empty state** from never-had-data and offers "clear filters", not "create your first thing". (`STRIPE-EMPTY`, `B2`) ### Detail panels - Side panel enters from the right over a scrim at `min(440px, 100%)` and **never replaces the page's own header, action row or tabs**. Escape, scrim and explicit close all dismiss. Only the panel body scrolls. (`TOKENS`) - **Default to side-by-side context, not a takeover.** Stripe's rule is "default to `ContextView`", reserving the full canvas for a workflow that genuinely does not need the page behind it. (`STRIPE-D`) - Opening a panel never loses list position or selection. (`NN-H3`) - A panel is a dialog for focus: focus moves in on open, `Escape` closes, focus returns to the invoker. (`APG-DLG`) ### Forms - **Composite widgets (select, dialog, menu, tooltip, tabs, toggle, combobox) build on the chosen headless primitives library**, skinned with `--cm-*`. Plain text inputs stay dependency-free. A native `