---
id: verbs
class: b2
sourced: 2026-07-12
source: "b2b-ux-patterns ch.3"
license: open
---
# Pass: verbs & actions

**Inputs:** per verb — `verbKind` (transition | edit | association | collaboration | communication | conversion | break-glass | approval-gated), `reversible`, `outwardFacing`, `bulk`, `blastRadius` (single-record | many-records | external-fanout), `thresholdVariant`.
**Owns:** `requiredMechanics`, `requiredStates`, `containers` (confirmation surfaces only), `clarifications`.
**Output artifact:** the verb matrix — object × state × role → available actions — the single inventory that generates every button, quick action, bulk action, row action, context-menu entry, and empty-state CTA. No surface invents its own buttons; each shows a slice of the matrix (header: the 1–3 highest frequency × criticality verbs for this state and role; row hover: 2–3 highest-frequency; bulk bar: the bulk-capable set; context menu: the full legal set). A verb keeps the same name, icon, and semantics on every surface.

## The rule

**Actions = f(object, state, role).** There is no fixed button set: transitions read directly off the state-machine graph (Refund only on succeeded, Void only on open), and role gates which legal verbs this viewer may perform, including threshold variants (refund up to $500; above that the verb becomes approval-gated).

**Reversibility dictates confirmation UX.** Reversible → optimistic commit + undo toast; confirm dialogs destroy flow and train users to click through them. Irreversible or outward-facing (leaves the building: send to customer, charge a card) → explicit confirmation scaled to stakes, up to typed confirmation. Undo requires the data model to be able to restore — soft-delete and the Logged class exist to guarantee it; decide reversibility in the model, then let the confirmation follow. If reversibility is undeclared on a mutating verb, clarify before choosing either treatment.

**Verb classes with hard invariants:**
- **Communication** — internal note and customer-facing send are *different verbs*, never a toggle buried in one composer: distinct affordance, distinct color, distinct confirmation weight. Sending to the wrong audience is a severity-1 failure.
- **Conversion** — born-from transformations (Lead → Account + Contact + Opportunity) create several records atomically and need a preview of what will be created and how fields map; conversion output never passes through a create form.
- **Break-glass** — overrides require reason capture at invocation and Logged history on everything touched; never bulk-capable — reason capture is per-incident by definition.
- **Approval-gated** — invocation submits, never executes: the object enters a pending-approval state and an approver receives Approve/Reject with required rationale in their queue.
- **Collaboration** — watch, assign, comment are ordinary asset-level verbs in the matrix; only their output (viewer-relative relationship data) is special.

**Bulk variants** get preview-before-commit when blast radius is large ("38 leads → owner: Priya") and per-row partial-failure reporting after ("34 updated, 4 failed" with reasons) — never a blanket success.

```json decision-table
{"pass": "verbs", "rows": [
  {"when": {"verbKind": "transition"}, "then": {"requiredMechanics": {"mustInclude": ["state-gated-availability", "verb-consistency-across-surfaces"]}}, "reason": "transitions-read-off-the-graph"},
  {"when": {"verbKind": "edit"}, "then": {"requiredMechanics": {"mustInclude": ["inline-edit-default"]}}, "reason": "edit-verbs-are-rarely-buttons"},
  {"when": {"verbKind": "communication"}, "then": {"requiredMechanics": {"mustInclude": ["audience-split-verbs", "distinct-send-affordances"], "mustNotInclude": ["audience-toggle-single-composer"]}}, "reason": "audience-safety-is-a-verb-split"},
  {"when": {"verbKind": "conversion"}, "then": {"requiredMechanics": {"mustInclude": ["conversion-preview-mapping", "atomic-multi-record-create"]}}, "reason": "conversion-shows-what-it-creates"},
  {"when": {"verbKind": "break-glass"}, "then": {"requiredMechanics": {"mustInclude": ["reason-capture-required", "logged-history-class"], "mustNotInclude": ["bulk-capability"]}}, "reason": "override-without-audit-is-liability"},
  {"when": {"verbKind": "approval-gated"}, "then": {"requiredMechanics": {"mustInclude": ["submit-not-execute", "approver-queue-routing", "approve-reject-rationale"]}, "requiredStates": {"mustInclude": ["pending-approval"]}}, "reason": "invocation-submits-not-executes"},
  {"when": {"verbKind": "collaboration"}, "then": {"requiredMechanics": {"mustInclude": ["ordinary-verb-treatment", "viewer-context-render-outputs"]}}, "reason": "collaboration-verbs-are-ordinary"},
  {"when": {"thresholdVariant": true}, "then": {"requiredMechanics": {"mustInclude": ["threshold-conditional-approval"]}}, "reason": "threshold-splits-direct-and-gated"},
  {"when": {"reversible": true, "outwardFacing": false}, "then": {"requiredMechanics": {"mustInclude": ["optimistic-commit", "undo-toast"], "mustNotInclude": ["confirm-dialog"]}, "containers": {"forbidden": ["center-modal"]}}, "reason": "undo-preserves-flow"},
  {"when": {"reversible": false}, "then": {"requiredMechanics": {"mustInclude": ["explicit-confirmation-scaled"]}, "containers": {"acceptable": ["center-modal"]}}, "reason": "irreversible-confirms"},
  {"when": {"outwardFacing": true}, "then": {"requiredMechanics": {"mustInclude": ["explicit-confirmation-scaled"]}}, "reason": "outward-facing-confirms"},
  {"when": {"bulk": true}, "then": {"requiredMechanics": {"mustInclude": ["bulk-preview-before-commit", "per-row-partial-failure-report"]}}, "reason": "blast-radius-needs-preview"},
  {"when": {"verbKind": ["transition", "edit"], "reversible": "__absent__"}, "then": {"clarifications": ["reversibility-unspecified"]}, "reason": "reversibility-decides-confirmation-ux"}
]}
```