---
title: "Operator UX Conventions"
audience: [developer]
summary: "The convention layer atop the design-system primitives: when and how to apply HTMX request shapes, feedback, confirmation modals, and validation when building operator forms and actions."
---

# Operator UX conventions

This is the **convention layer** that sits on top of the design-system primitives. It says *when* and *how* to use each primitive — not what they look like. Primitive definitions live in [`design-system.md`](design-system.md); this doc decides which one a new form or action picks up. It exists because each operator tab had grown its own confirmation, error, and success patterns — the pain point M7a's research named — and M7e replaced them with one vocabulary.

Status: M7e deliverable. Cited by 7f's audit as the convention-drift baseline.

---

## 1. Scope & non-goals

**In scope:**
- HTMX request shape on mutation surfaces (forms, destructive actions)
- Success and error feedback patterns
- Confirmation modal coverage rules
- Server-side validation rendering
- HTTP status-code discipline for mutation handlers

**Out of scope** (covered elsewhere):
- Component primitives (modal markup, toast markup, badge styles) — see [`design-system.md`](design-system.md) §2–3
- IA / routes / breadcrumbs — see [`operator-ia.md`](operator-ia.md) and the `operator-panel-navigation` spec
- A11y audit (keyboard nav, ARIA correctness, contrast checks) — M7f
- Spacing, typography, color tokens — `design-system.md` §1

---

## 2. HTMX request shape

Every mutation form on the operator surface uses HTMX, not native `<form method="POST">`. The native path hit a brittle gorilla-CSRF failure mode: gorilla checks the `Origin` header against its trusted origins, so a submission that arrives with `Origin: null` is rejected — which is what the operator lookup form did for at least one user, and what CDP-driven form clicks do reliably. HTMX routes through the `X-CSRF-Token` header on body's `hx-headers` instead, which is the same path every other form uses successfully.

**The triad** every form sets:

```html
<form hx-post="/partials/operator/<capability>/<action>"
      hx-target="#<swap-target-id>"
      hx-swap="innerHTML">
```

- `hx-post` / `hx-put` / `hx-delete` — never use bare `method="POST"`
- `hx-target` — CSS selector for the element to swap (default page-shell target is `#operator-main`; in-page partials use their own container ID)
- `hx-swap` — `innerHTML` for content-area swaps; `outerHTML` only when replacing the wrapper itself (rare)

**For redirects:** a mutation that lands somewhere new (a create page landing on the record, a settings save returning to a page) answers through one shared helper, `redirectToRecord` (`internal/server/redirect.go`, design D9): an htmx submit gets `HX-Redirect` to the destination and a 200 with an empty body; a native submit gets a `303` to the same destination directly. Both carry `?flash=` with the toast key (§3, §6 below). A bare `303` is never the answer to an htmx submit: htmx follows it itself and swaps the destination's full page into the form's own target, nesting the operator shell inside itself. `HX-Redirect` on a refusal is still wrong (§9); a refusal is `422` with the form re-rendered, never a redirect of either kind.

---

## 3. Success feedback

**Rule:** mutation success fires a toast. Page-load durable notices use a banner.

| Pattern | When |
|---------|------|
| `HX-Trigger: {"showSuccessToast": "<message>"}` response header | A mutation handler returns success |
| `<div class="alert alert-info">` rendered in the response body | The page itself is reporting a durable in-progress state (e.g., "Backfill in progress") |

The toast container lives outside the swap target so it survives `hx-boost` navigations and partial swaps (see [`design-system.md`](design-system.md) §3 "Success feedback"). The toast driver is `internal/embeds/static/success-toast.js`.

**Standard message framing:**

| Action | Toast message |
|--------|---------------|
| Created | `<Resource> created` |
| Updated | `Changes saved` |
| Deleted | `<Resource> deleted` |
| Revoked | `Grant revoked` |
| Backfilled | `Backfill complete (<N> orgs processed)` |

Keep it short. Operators read toasts in <1s of glance time — every extra word is friction.

**A toast reports the outcome of the work, not that the handler reached its end.** A handler that iterates rows states how many succeeded and how many failed; a run in which every row failed answers with `fireErrorToast`, because a green toast beside a failure banner leaves the operator with two contradictory readings of one mass mutation.

**Retired:** rendering `<div class="alert alert-success">` inside the response body of a mutation. That pattern pre-dated `showSuccessToast`; the forms library's outcome contract (`form-library`, `form-conventions`; `docs/design-system.md` §8) names the two mechanisms above as the only ones a mutation answers with, and the two remaining alert-in-body successes (org types, workspaces) were converted to the toast when their forms moved onto the library.

---

## 4. Error feedback

`internal/embeds/static/error-handler.js` is the **single funnel** for HTTP error feedback. Under htmx 4 every response swaps by default; suppression is declared once in each page's `htmx-config` meta tag (`"noSwap": [204, 304, 403, "5xx"]`), not scripted. The funnel listens for `htmx:response:error` and `htmx:error`:

- 422 → silent (the body is the re-rendered form and swaps inline; see §6)
- 403 (CSRF expired) → red toast; the swap is suppressed by `noSwap`, so user input is preserved
- other 4xx with body → the body swaps (server returns rendered error context) + backup toast
- 5xx → red toast; suppressed by `noSwap`, user input preserved
- network failure / timeout → red toast

**Handler responsibility:** return proper HTTP status codes. Never return a 200 with an `.alert-danger` banner for a failure — the error handler keys off status, not body content.

| Failure type | Status to return |
|--------------|------------------|
| Validation failure | 422; the declared form re-rendered in submission mode (see §6) |
| Auth failure | 401 / 403 |
| Resource not found | 404 |
| Conflict (e.g., concurrent edit) | 409 |
| Server bug | 500 (let the error handler show a generic toast; details go to logs) |

**Database write failures never render `err.Error()`.** Raw driver text ("duplicate key value violates unique constraint … SQLSTATE 23505") is not operator-facing copy — it leaks schema internals and reads as a crash. The contract for a failed write:

1. **Constraint violation** → translate with `web.FieldErrorsFromDB(err, web.ConstraintMessages{…})` (`internal/web/dberrors.go`) and route the result through the page's 422 + `FieldErrors` path (§6/§8). Name the constraints the form can plausibly hit in a map next to the handler — constraint names live beside the form they belong to, not in a global registry — each mapped to the form field to flag and a friendly, actionable message. Violations without a named entry fall back to a per-SQLSTATE-class message on the form-level `""` key. Surfaces without FieldErrors machinery (member partials, formless actions like revoke/delete buttons) render the translated message through their existing banner/toast shape instead — friendly text, never driver text.
2. **Everything else** (`ok == false`) → `slog.Error` the real error and render a *generic* message ("Failed to update the product. Details are in the server logs."). The operator can't act on driver text; the log line is where the details belong.

`member-console lint` enforces this with the `raw-error-render` rule: any line under `internal/server` that passes `err.Error()` into a `render*` helper, `fireErrorToast`/`fireSuccessToast`, or `http.Error` is flagged (lines containing `slog.` are exempt; `_test.go` files are skipped).

**A collection whose backing query failed renders an error state, never the empty state.** The empty state asserts that no rows exist, so falling back to it after a failed load tells the person their data is gone when it is only unreadable — and it takes away the actions those rows carried. A handler that loads a list renders the failure and leaves the rows it already holds in place.

---

## 5. Confirmation modals

**The rule:** require the modal for actions that (a) delete data, or (b) revoke user-visible access via the composite path (the revoke handler: decree + `end_conferral`). The same modal and contract serve the member surface (plan cancel, domain release and cancel-verification, FedWiki archive and delete); `hx-confirm` is banned everywhere and lint-caught.

**Not required** for: grant issuance, grant extend, create, update, save. These are forward-only — mistakes are revocable. Adding friction to high-frequency operator actions doesn't earn its weight.

**Special case, retired:** the org-type backfill's confirmation modal is gone with the action itself. High blast-radius mass mutations now follow the org-type default-change pattern instead: the selection immediately renders a **server-side read-only preview** (classified affected-population counts, named where a disposition is required), and the commit button lives inside that preview — the operator cannot reach the mutation without having seen its projection. Prefer this preview-then-commit shape over a modal for any future mass mutation: a modal interrupts with a question; the preview answers it. Tier drag-to-reorder and tier removal follow the same shape: the action renders the preview and the commit lives inside it — pending state is server-rendered, never browser-only, so no swap can silently discard it. Affected-population lists inside previews render **count-first**: the bucket line carries only the count and one sentence of consequence; the org names live behind a `show all N` `<details>` disclosure (`.org-disclosure-list` — one org per row, scrollable), so a hundred-org preview reads as one line until the operator asks for names.

**Trigger contract** (from `internal/embeds/static/confirm-action-modal.js`):

```html
<button type="button"
        data-bs-toggle="modal"
        data-bs-target="#confirmActionModal"
        data-action-url="/partials/operator/<resource>/<id>"
        data-action-method="delete"
        data-action-target="#<swap-target-id>"
        data-action-title="Delete plan ladder"
        data-action-body="Delete '<resource-name>'? This cannot be undone."
        data-action-confirm-label="Delete ladder"
        data-action-style="danger">
    Delete
</button>
```

| Attribute | Required | Default | Notes |
|-----------|----------|---------|-------|
| `data-action-url` | yes | — | endpoint hit on confirm |
| `data-action-method` | yes | `post` | `post` or `delete` |
| `data-action-target` | yes | — | HTMX swap target; `closest <selector>` resolves against the trigger element |
| `data-action-swap` | no | `innerHTML` | HTMX swap style |
| `data-action-title` | no | `Confirm` | modal heading |
| `data-action-body` | no | empty | body copy; name the resource being affected |
| `data-action-confirm-label` | no | `Confirm` | submit-button label |
| `data-action-style` | no | `danger` | `danger` / `primary` / `warning` |
| `data-action-fields` | no | — | JSON map of hidden form fields |

**Failed requests leave the modal open** so the operator sees the error in the swap target and can retry. Successful requests close the modal automatically.

**Body copy convention:** name the affected resource. "Delete 'Standard tier'?" beats "Are you sure you want to delete this?" by a wide margin — operators routinely manage many similarly-named entities. State the effect the primitive actually has: when confirmation or preview copy and the handler disagree, the disagreement is a finding against the copy rather than a wording preference, and it is settled by correcting the copy or by changing the primitive, never by leaving the two apart.

---

## 6. Server-side validation

**The rule:** every form that mutates is a declared `forms.FormSpec`
(spec `form-library`, `form-conventions`; `docs/design-system.md` §8),
parsed through `spec.Parse(r)` (never `r.FormValue`), and revalidated
server-side regardless of what the browser already checked. This section
used to describe a hand-built `FieldErrors` map and a form-field partial
written per form; the forms library replaced both, and this doc no
longer prescribes either.

The ban on `r.FormValue` holds for a handler reading a request outside
the library too: `r.FormValue` merges the query string into the posted
body, so a URL parameter can shadow a submitted field, and it returns
only the first of a repeated field's values. Read `r.PostForm` instead.

**The outcome contract** (design D9, restated here; the full statement
is `docs/design-system.md` §8 "The outcome contract"):

- A refusal for any reason, field-level or not, answers **422** with the
  same declaration re-rendered in submission mode: every submitted value
  carried back (checkbox and radio state included), each field's error
  under its control, a refusal that names no field in the form-level slot
  every declared form renders, and `autofocus` on the first errored
  control.
- Every mutation form carries `novalidate`, so a cleared required field's
  submission always reaches the server, and the refusal a person sees is
  the server's own message under the control, not the browser's transient
  bubble. The constraint attributes (`required`, `maxlength`, `min`,
  `max`, `pattern`) stay on the control regardless, generated from the
  same declaration `Parse` reads, so the browser's rule and the server's
  rule cannot differ.
- A handler adds its own errors by field name (uniqueness, a domain rule)
  or at the form level, on the `forms.Errors` value `Parse` returns, and
  builds the domain object only once that value is empty.

**A constraint-violation refusal from the database** still translates
through `web.FieldErrorsFromDB` (§4 above); its result is copied onto the
same `forms.Errors` value (`applyWebErrors` in the packages that need it)
so a DB-constraint refusal renders through the identical 422 path as a
field-validation one, never a second mechanism.

Keep messages concrete and actionable: "Enter a name." not "Invalid
input."

---

## 7. Optimistic updates

**Rule:** don't.

Every mutation waits for server confirmation before the UI updates. HTMX's request-response cycle is the contract.

**No exception currently in the codebase.** `grant-toggle.js`, the one prior exception (a grant active/inactive switch that flipped immediately and reconciled on server response), is deleted; grant issuance and extension are declared forms now (`operator.enrollment.grant.issue`, `.extend`) and wait for the server like every other mutation (design D15). A future optimistic update should not be added without explicit precedent and a writeup.

---

## 8. Mutation status codes

| Outcome | Status | Body |
|---------|--------|------|
| Success, stays | 200 | the region's re-render (plus `HX-Trigger: showSuccessToast` header) |
| Success, navigates | 200 (htmx) or 303 (native) | `redirectToRecord` (`internal/server/redirect.go`): `HX-Redirect` + empty body for an htmx submit, `Location` for a native one, both to `?flash=<key>` on the landing page, rendered as a success toast there (design D9) |
| Validation failure | 422 | the same declared form re-rendered in submission mode, every field's error under its control |
| CSRF expired | 403 | `error-handler.js` handles the toast |
| Not found | 404 | error-handler funnel |
| Conflict | 409 | error-handler funnel |
| Server error | 500 | error-handler funnel |

**The 422 distinction matters:** 422 swaps natively under htmx 4 (the operator sees the form re-rendered with field errors) while 403/5xx sit in the declared `noSwap` list (the original input must be preserved). 422 is the validation-failure signal; nothing in JavaScript steers the swap.

---

## 9. Anti-patterns

| Don't | Do instead |
|-------|------------|
| `<form method="POST" action="...">` | `hx-post` (CSRF Origin-check is brittle on native POST) |
| `<div class="alert alert-success">` in a mutation response (retired, design D9) | `HX-Trigger: {"showSuccessToast": "..."}` header for a mutation that stays, or `redirectToRecord`'s `HX-Redirect`/`303` pair for one that navigates |
| `HX-Redirect` on a refusal (retired, design D9; integration settings did this before this change) | `422` with the same declared form re-rendered in submission mode |
| Return 200 + `.alert-danger` for a failure | Return proper status code (422 / 4xx / 5xx); let `error-handler.js` funnel it |
| `hx-confirm="Are you sure?"` | The confirm-action-modal contract |
| `<span class="badge bg-info">` | `<span class="badge text-bg-info">` (bare `bg-*` fails WCAG AA contrast against Bootstrap defaults) |
| Inline `<script>` in templates | Put JS in `internal/embeds/static/` and reference via `<script defer src>` (CSP `script-src 'self'` blocks inline) |
| `http.Redirect(w, r, ...)` as the only answer to a navigating mutation, regardless of `HX-Request` | `redirectToRecord` (`internal/server/redirect.go`, design D9): `HX-Redirect` + 200 with an empty body when the submit is htmx, `http.Redirect(..., http.StatusSeeOther)` when it is native |
| Validation in the client only (HTML5 `required` alone) | A declared `forms.FormSpec`, parsed server-side through `spec.Parse(r)` (`form-library`; `docs/design-system.md` §8); `required` stays on the control, generated from the same declaration, for assistive technology |
| `for _, g := range grants { if g.Status != "active" { continue } … }` to build an "active grants" list | Use a query that joins to active provisions (`ListDeliveringGrantsByOrgID` / `ListGrantsWithDeliveryByOrgID`) — see §9a |
| `hx-get="/operator/foo/{{ .ID }}"` — interpolated URL string in any `hx-*` or `data-action-url` attribute | `hx-get="{{ routeURL "/operator/foo/{id}" .ID }}"` — `member-console lint` cross-checks the pattern against `mux.HandleFunc` registrations. Helper is `web.RouteURL` in `internal/web/route_url.go`; register on each template FuncMap as `"routeURL": web.RouteURL`. |
| `"Failed to save: " + err.Error()` in a render/toast/`http.Error` call | `web.FieldErrorsFromDB` → 422 + `FieldErrors` for constraint violations; `slog.Error` + generic message otherwise (§4; enforced by the `raw-error-render` lint rule) |
| Writing the row first and running the invariant guard after it (`CreateGrant` then the same-tier check) | Every guard runs before the first write — a guard that short-circuits after the row exists leaves an orphan no later flow can reach |
| Leaving a control visible whose effect nothing implements ("until the behaviour is built") | Hide it, or relabel it to what it actually does; a rendered control is a promise, and the handler is what has to keep it |

### 9a. Grant lifecycle ≠ delivery state

`core.grants.status` is a **lifecycle field** with three values — `active`, `expired`, `revoked` — and it only changes through explicit revocation or time-based expiry. `status='active'` means *"this commitment has never been formally retracted"*; it does **not** mean *"this grant is currently delivering entitlements to a pool."*

Operational delivery lives one layer down, on `pool_provisions.status` and `pool_provision_ladders.status` — and the schema's GiST exclusion constraint guarantees **at most one active provision per `(pool, ladder)`**. A grant whose provision was ended by a later conferral (supersession, extend-as-replace, or `end_conferral` from another flow) stays `grants.status='active'` (audit ledger), but it stops delivering.

These two facts get confused in code that filters grants by `status='active'` and treats the result as "what this org is getting right now." The result is a UI lie: 5+ rows shown as "active" for a product that the data model guarantees is delivered by exactly one of them.

**Rule.** Any operator or member surface that answers "what is this org/pool getting right now?" MUST use a query that joins to `pool_provisions` (and `pool_provision_ladders` when ladder-scoped):

- **Members** (Sources panel, Plans page, anything user-facing): use `ListDeliveringGrantsByOrgID` — INNER JOIN on `pool_provisions.status='active'`. Returns only live grants. Audit history is noise here.
- **Operators** (per-org composite, audit-shaped views): use `ListGrantsWithDeliveryByOrgID` — LEFT JOIN, returns every grant tagged with `delivery_state ∈ {live, superseded, inactive}`. Render the column. Gate destructive actions on `live`. History is the point.

Don't filter on `grants.status` for the "currently active" question. The status field answers a different question. If you're tempted to write a third such query, name it after what it actually returns (`ListGrantsCurrentlyDeliveringTo…`, not `ListActiveGrants…`) so the trap doesn't reappear.

---

## 10. Future

- **Cascade-preview pattern** — for catalog edits at criticality ≥4 (product edit, entitlement-set edit, tier reorder), surface "this change will affect: N products, M orgs, K members" before confirmation. Deferred to M11 (audit log & observability; renumbered from M10 on 2026-07-03) because the projected-change set is audit-log adjacent.
- **Convention-drift guard** — automated lint that flags `bg-info` without `text-`, native `method="POST"`, etc. M7f.1 delivered `member-console lint` covering dead routes, dead swap targets, stale `?tab=`, and interpolated URL literals; additional §9 rules can be added there as static-detectable patterns emerge.
- **Real-time validation** — on-blur server validation pings vs. on-submit. Not pursued unless operator feedback demands it.

---

## See also

- [`design-system.md`](design-system.md) — primitive definitions (modal, toast, badges, error handler)
- [`operator-ia.md`](operator-ia.md) — IA contract that forms/actions must not break
- [`openspec/specs/operator-panel-navigation/spec.md`](../openspec/specs/operator-panel-navigation/spec.md) — the spec these conventions implement