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.
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.
<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
<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.
<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.
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.
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.
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
Attribute
On
Values
Default
Description
aria-labelledby
root section
id of the proposal heading
—
Names the handoff region by the proposed consequence.
CSS hooks (derived from dist/all.css)
Hook
Kind
Values or default
Description
.forma-handoff-summary
Block 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
Keys
Result
Tab / Shift+Tab
Moves to the decision actions after the facts. No added keyboard behavior.
Enter / Space
Activates the focused native button; the decision is performed by the application after checking authority.
Events
Event
Description
click
Native 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
State
How it is expressed
Presentation
Awaiting decision
facts plus the actions the application renders
The actions shown are exactly those the current user may take.
Review only
authority text and a reduced action set
The 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.