Human–agent interaction

Handoff summary

<forma-handoff-summary>

Exposes agent identity, proposal, uncertainty, evidence scope, and retained human authority.

Authoring tag
<forma-handoff-summary>
Behavior owner
Application / Ordo
Canonical source
patterns/handoff-summary.html

Purpose

A handoff summary is the point where an agent stops and a human decides. It names the agent that did the work, states the proposed consequence, the evidence the agent relied on and its scope, what remains uncertain, and who holds the authority to approve. It is a labelled definition list with the decision actions after it. Forma lays out the labelled facts and nothing more: which actions exist, whether the current user may take them, and what happens when they do are Ordo or application decisions. The summary must make uncertainty and missing evidence as visible as the proposal itself.

Use when

  • An automated agent has prepared a consequential change (publishing, sending, merging, paying) and a person must approve, reject or redirect it.
  • Reviewers need to see which agent acted, on what evidence and with what known gaps.
  • Human authority over the outcome must be stated explicitly, not implied by the presence of a button.

Avoid when

  • The user needs to review many interpreted facts one by one: use Understanding review.
  • The decision needs a deliberate recognize, verify, act structure with low-context values: use Verification frame, optionally with a handoff summary inside the Verify part.
  • It is an ordinary conversational reply: use a Conversation turn.
  • No human decision is required: report the outcome with Operation status or Toast.

Behavior to know

  • Fact rows are a two-column grid: a label column of 9rem to 12rem and a flexible value column.
  • Labels are semibold dt text; values are plain dd text, so every fact is readable without styling.
  • At 30rem and below each row stacks its label above its value.
  • No border or background of its own: place it in a Surface or another frame when it needs separation.

Basic example

The smallest correct markup: the canonical pattern from patterns/handoff-summary.html inside its public tag. Copy this first, then adapt labels, names and state.

Canonical

Minimal handoff summary

Rendered from the canonical pattern file.

Static specimen. Its buttons stand for application actions that the consuming application implements; this script-free documentation does not perform them. Its controls are shown for their markup and appearance and cannot be operated here.

Agent proposal

Publish release

Agent: OpenAI implementation agent

Proposed consequence
Publish version 1.4.0
Evidence
Tests and validation passed
Uncertainty
Production consumer smoke test not observed
Human authority
Approval required before publication
HTML · Minimal handoff summary Raw HTML for HTML · Minimal handoff summary
<forma-handoff-summary class="forma-component-tag">
<section class="forma-handoff-summary" aria-labelledby="handoff-title"><header><p class="forma-component-kicker">Agent proposal</p><h2 id="handoff-title">Publish release</h2><p>Agent: OpenAI implementation agent</p></header><dl><div><dt>Proposed consequence</dt><dd>Publish version 1.4.0</dd></div><div><dt>Evidence</dt><dd>Tests and validation passed</dd></div><div><dt>Uncertainty</dt><dd>Production consumer smoke test not observed</dd></div><div><dt>Human authority</dt><dd>Approval required before publication</dd></div></dl><div class="forma-cluster"><button type="button">Approve</button><button type="button">Reject</button><button type="button">Request changes</button></div></section>
</forma-handoff-summary>

Click or tap the code once to select all of it, then copy.

Examples

Scenario

Database migration proposal

An agent proposes a schema migration. The summary names the agent, the exact migration identifier, the evidence and its scope, the uncertainty that remains, and who must approve. The decision actions follow the facts.

Static specimen. Its buttons stand for application actions that the consuming application implements; this script-free documentation does not perform them. Its controls are shown for their markup and appearance and cannot be operated here.

Agent proposal

Apply migration to production

Agent: Schema maintenance agent (run 7715)

Proposed consequence
Apply 2026_09_30_add_invoice_currency to prod-billing
Evidence
Migration applied cleanly to staging; 312 integration tests passed
Evidence scope
Staging holds 4% of production row volume
Uncertainty
Lock duration on the 38-million-row invoices table was not measured
Human authority
A database owner must approve; the agent cannot apply it
HTML · Database migration proposal Raw HTML for HTML · Database migration proposal
<forma-handoff-summary class="forma-component-tag">
  <section class="forma-handoff-summary" aria-labelledby="handoff-summary-database-migration-title">
    <header>
      <p class="forma-component-kicker">Agent proposal</p>
      <h2 id="handoff-summary-database-migration-title">Apply migration to production</h2>
      <p>Agent: Schema maintenance agent (run 7715)</p>
    </header>
    <dl>
      <div><dt>Proposed consequence</dt><dd>Apply <span class="forma-identifier">2026_09_30_add_invoice_currency</span> to prod-billing</dd></div>
      <div><dt>Evidence</dt><dd>Migration applied cleanly to staging; 312 integration tests passed</dd></div>
      <div><dt>Evidence scope</dt><dd>Staging holds 4% of production row volume</dd></div>
      <div><dt>Uncertainty</dt><dd>Lock duration on the 38-million-row invoices table was not measured</dd></div>
      <div><dt>Human authority</dt><dd>A database owner must approve; the agent cannot apply it</dd></div>
    </dl>
    <div class="forma-cluster"><button type="button">Approve migration</button><button type="button">Reject</button><button type="button">Request lock-time test</button></div>
  </section>
</forma-handoff-summary>

Click or tap the code once to select all of it, then copy.

Scenario

Reviewer without approval authority

The current user can review but does not hold the authority to approve. The summary says so in text and the application renders only the actions this user may take; there is no disabled Approve button pretending to be available.

Static specimen. Its buttons stand for application actions that the consuming application implements; this script-free documentation does not perform them. Its controls are shown for their markup and appearance and cannot be operated here.

Agent proposal

Send 1,240 renewal reminders

Agent: Customer communications agent

Proposed consequence
Email renewal reminders to customers whose plans end in October
Evidence
Customer list exported 30 September, 09:00
Uncertainty
Unknown: 17 addresses bounced last month and were not re-verified
Human authority
Marketing lead approval required. You can comment or forward.
HTML · Reviewer without approval authority Raw HTML for HTML · Reviewer without approval authority
<forma-handoff-summary class="forma-component-tag">
  <section class="forma-handoff-summary" aria-labelledby="handoff-summary-review-only-title">
    <header>
      <p class="forma-component-kicker">Agent proposal</p>
      <h2 id="handoff-summary-review-only-title">Send 1,240 renewal reminders</h2>
      <p>Agent: Customer communications agent</p>
    </header>
    <dl>
      <div><dt>Proposed consequence</dt><dd>Email renewal reminders to customers whose plans end in October</dd></div>
      <div><dt>Evidence</dt><dd>Customer list exported 30 September, 09:00</dd></div>
      <div><dt>Uncertainty</dt><dd>Unknown: 17 addresses bounced last month and were not re-verified</dd></div>
      <div><dt>Human authority</dt><dd>Marketing lead approval required. You can comment or forward.</dd></div>
    </dl>
    <div class="forma-cluster"><button type="button">Forward to marketing lead</button><button type="button">Add comment</button></div>
  </section>
</forma-handoff-summary>

Click or tap the code once to select all of it, then copy.

Mobile

Each mobile example renders in its own document inside a real narrow viewport, so Forma's media and container queries run exactly as they would on a phone. Choose a width to compare.

Mobile example

Mobile approval

At phone width each fact stacks its label above its value, and the actions wrap below the facts.

Static specimen. Its buttons stand for application actions that the consuming application implements; this script-free documentation does not perform them. Its controls are shown for their markup and appearance and cannot be operated here.

Viewport width

Frames narrower than the selected width show the component at the width available.

What changes at narrow widths

  • At 30rem and below each fact row becomes one column with a small gap: label, then value.
  • Values wrap within the viewport; long identifiers inside .forma-identifier wrap anywhere, so nothing scrolls sideways at 320px.
  • Actions in an .forma-cluster wrap onto new lines and keep the 2.75rem base height; they always come after the facts.
  • The order of facts is fixed in the source, so uncertainty and authority are never pushed off-screen by rotation.
HTML · Mobile approval Raw HTML for HTML · Mobile approval
<forma-handoff-summary class="forma-component-tag">
  <section class="forma-handoff-summary" aria-labelledby="handoff-summary-mobile-title">
    <header>
      <p class="forma-component-kicker">Agent proposal</p>
      <h2 id="handoff-summary-mobile-title">Merge dependency update</h2>
      <p>Agent: Dependency update agent</p>
    </header>
    <dl>
      <div><dt>Proposed consequence</dt><dd>Merge pull request #482 into main</dd></div>
      <div><dt>Uncertainty</dt><dd>End-to-end tests were skipped on Safari</dd></div>
      <div><dt>Human authority</dt><dd>Your approval required</dd></div>
    </dl>
    <div class="forma-cluster"><button type="button">Approve merge</button><button type="button">Reject</button></div>
  </section>
</forma-handoff-summary>

Click or tap the code once to select all of it, then copy.

Baseline

Mobile · 320px

The canonical pattern in a true 320px viewport, the minimum width every Forma component must support without page-level horizontal scrolling.

Static specimen. Its buttons stand for application actions that the consuming application implements; this script-free documentation does not perform them. Its controls are shown for their markup and appearance and cannot be operated here.

Viewport width

Frames narrower than the selected width show the component at the width available.

API and configuration

Forma components have no JavaScript API. Their public contract is the markup: native elements and attributes you write, and the CSS hooks below. The CSS hook table is generated from the built stylesheet, so it always matches the shipped implementation.

Native and ARIA attributes
AttributeOnValuesDefaultDescription
aria-labelledbyroot sectionid of the proposal heading—Names the handoff region by the proposed consequence.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-handoff-summaryBlock class—Root grid with a 1rem gap. Styles a dl inside it as rows of label and value (minmax(9rem, 12rem) minmax(0, 1fr)), with semibold labels; rows stack at 30rem and below.
Keyboard interaction
KeysResult
Tab / Shift+TabMoves to the decision actions after the facts. No added keyboard behavior.
Enter / SpaceActivates the focused native button; the decision is performed by the application after checking authority.
Events
EventDescription
clickNative click on decision actions.

Form behavior

Not a form control. A decision that needs a reason can be collected in an application Dialog or form.

States

Handoff summary states
StateHow it is expressedPresentation
Awaiting decisionfacts plus the actions the application rendersThe actions shown are exactly those the current user may take.
Review onlyauthority text and a reduced action setThe user cannot approve; the text says who can.
Stacked facts@media (max-width: 30rem)Each label sits above its value.

Accessibility

Forma provides

  • Presents every fact as a native definition list, so labels and values are paired for assistive technology.
  • Keeps facts before actions in source, visual and focus order.
  • Stacks label and value on narrow screens so neither is truncated.

Your application supplies

  • Always include agent identity, the proposed consequence, evidence and its scope, uncertainty and human authority, even when uncertainty is "none reported".
  • State unknown or unobserved evidence as unknown, never as passed.
  • Render only actions the current user is allowed to take, and re-check authority in Ordo or application state when an action runs.
  • Name actions by their consequence ("Approve migration"), not generically ("OK").

Responsive behavior

  • Fact rows: minmax(9rem, 12rem) minmax(0, 1fr); values wrap in the flexible column.
  • At 30rem and below: rows become minmax(0, 1fr) with a 0.25rem gap.
  • Actions composed with Cluster wrap as needed.

Motion

  • No animation: the summary is static. Buttons keep only the base perceptual hover and press color change.

Usage guidance

Do

  • Put uncertainty and human authority in their own labelled rows so they cannot be skimmed past.
  • Include the evidence scope (what was and was not checked).

Avoid

  • Showing the agent's recommendation as a pre-selected or visually dominant Approve.
  • Using vendor or model branding as a substitute for naming the agent and its run.

Verification specimens

Generated fault-injection specimens expose content, spacing, color-cue, and reduced-effective-contrast risks. They screen presentation robustness as engineering screens without claiming human-subject validation.