An understanding review shows what an application or agent understood from the user's input, item by item, before anything consequential is recorded. Each item has an explicit text state (Understood, Unknown, Conflict), a short label and summary, and an application-supplied action such as viewing the source, answering a question or resolving a conflict. Unknown and conflicting items get an extra side bar so they stand out without relying on color. Forma never decides that an item is accepted, blocking or resolved; those states and whether the transition may proceed come from Ordo or application state.
Use when
Free text, dictation or a document has been interpreted into structured facts that will change a record.
Some facts may be missing or contradict what is already recorded, and the user must see them before confirming.
Each fact needs a path back to its source for checking.
Avoid when
The facts are already confirmed and only need display: use Key-value list or Facts.
The user is checking prerequisites rather than interpreted facts: use Readiness checklist.
Two versions of a record are being reconciled field by field: use Conflict review.
An agent is asking for approval of a single consequence: use Handoff summary.
Behavior to know
Each item is a three-column grid: state label, label and summary, action.
State labels are mono uppercase text with a symbol from CSS: ✓ for accepted, ? for unknown, ! for conflict.
Unknown and conflict items have a 0.3rem inline-start bar, a shape cue in addition to the text.
At 40rem and below items and the header stack, and item actions become full width.
Basic example
The smallest correct markup: the canonical pattern from patterns/understanding.html inside its public tag. Copy this first, then adapt labels, names and state.
Canonical
Minimal understanding review
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.
Understanding
I found 4 things
Review what the application understood before any consequential transition.
<forma-understanding class="forma-component-tag">
<section class="forma-understanding" aria-labelledby="understanding-title">
<header class="forma-understanding__header">
<div>
<span class="forma-component-kicker">Understanding</span>
<h2 id="understanding-title">I found 4 things</h2>
<p>Review what the application understood before any consequential transition.</p>
</div>
<span class="forma-status-lozenge" data-state="attention">1 question</span>
</header>
<ol class="forma-understanding__items">
<li class="forma-understanding__item" data-forma-state="accepted">
<span class="forma-understanding__state">Understood</span>
<div><strong>Medication change</strong><p>Medication increased to 40 mg.</p></div>
<button type="button">Source</button>
</li>
<li class="forma-understanding__item" data-forma-state="accepted">
<span class="forma-understanding__state">Understood</span>
<div><strong>Symptom</strong><p>Ankle swelling returned.</p></div>
<button type="button">Source</button>
</li>
<li class="forma-understanding__item" data-forma-state="unknown">
<span class="forma-understanding__state">Unknown</span>
<div><strong>Medication frequency</strong><p>The dose frequency was not supplied.</p></div>
<button type="button">Answer</button>
</li>
<li class="forma-understanding__item" data-forma-state="accepted">
<span class="forma-understanding__state">Understood</span>
<div><strong>Visit</strong><p>Dr. Smith visit occurred yesterday.</p></div>
<button type="button">Source</button>
</li>
</ol>
</section>
</forma-understanding>
Click or tap the code once to select all of it, then copy.
Examples
Scenario
Conflict with the existing record
The application found that a new statement contradicts what is recorded. The conflict item states both values in text and offers resolution; the header summarizes how many items need attention.
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.
Understanding
I found 3 things
One item conflicts with the current record. Nothing is saved until it is resolved.
1 conflict
Conflict
Allergy
You said "no known allergies"; the record lists penicillin (added 2024).
<forma-understanding class="forma-component-tag">
<section class="forma-understanding" aria-labelledby="understanding-conflict-title">
<header class="forma-understanding__header">
<div>
<span class="forma-component-kicker">Understanding</span>
<h2 id="understanding-conflict-title">I found 3 things</h2>
<p>One item conflicts with the current record. Nothing is saved until it is resolved.</p>
</div>
<span class="forma-status-lozenge" data-state="attention">1 conflict</span>
</header>
<ol class="forma-understanding__items">
<li class="forma-understanding__item" data-forma-state="conflict">
<span class="forma-understanding__state">Conflict</span>
<div><strong>Allergy</strong><p>You said "no known allergies"; the record lists penicillin (added 2024).</p></div>
<button type="button">Resolve</button>
</li>
<li class="forma-understanding__item" data-forma-state="accepted">
<span class="forma-understanding__state">Understood</span>
<div><strong>Appointment</strong><p>Follow-up with Dr. Smith on 14 October at 09:30.</p></div>
<button type="button">Source</button>
</li>
<li class="forma-understanding__item" data-forma-state="accepted">
<span class="forma-understanding__state">Understood</span>
<div><strong>Weight</strong><p>82 kg, measured today.</p></div>
<button type="button">Source</button>
</li>
</ol>
</section>
</forma-understanding>
Click or tap the code once to select all of it, then copy.
Scenario
Everything understood
Every item is understood. The header states this in text with an ok lozenge, and each item still links to its source so the user can check before the application moves on.
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-understanding class="forma-component-tag">
<section class="forma-understanding" aria-labelledby="understanding-all-understood-title">
<header class="forma-understanding__header">
<div>
<span class="forma-component-kicker">Understanding</span>
<h2 id="understanding-all-understood-title">Expense details from your receipt</h2>
<p>Check these before the claim is submitted.</p>
</div>
<span class="forma-status-lozenge" data-state="ok">No questions</span>
</header>
<ol class="forma-understanding__items">
<li class="forma-understanding__item" data-forma-state="accepted">
<span class="forma-understanding__state">Understood</span>
<div><strong>Merchant</strong><p>Lisbon Airport Taxi Cooperative</p></div>
<button type="button">Source</button>
</li>
<li class="forma-understanding__item" data-forma-state="accepted">
<span class="forma-understanding__state">Understood</span>
<div><strong>Amount</strong><p><span class="forma-critical-value">€42.60</span> on 29 September</p></div>
<button type="button">Source</button>
</li>
</ol>
</section>
</forma-understanding>
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 review with a question
At phone width each item stacks state, content and action, and every action is a full-width button so answering and checking sources stay reachable.
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 40rem and below the header stacks its text above the status lozenge, stretched to the full width.
Each item becomes one column: state label, then label and summary, then a full-width action button at the 2.75rem base height.
The unknown item keeps its inline-start bar when stacked, so it remains distinguishable while scrolling.
Long summaries wrap within the item; no horizontal scrolling at 320px in either orientation.
<forma-understanding class="forma-component-tag">
<section class="forma-understanding" aria-labelledby="understanding-mobile-title">
<header class="forma-understanding__header">
<div>
<span class="forma-component-kicker">Understanding</span>
<h2 id="understanding-mobile-title">I found 2 things</h2>
</div>
<span class="forma-status-lozenge" data-state="attention">1 question</span>
</header>
<ol class="forma-understanding__items">
<li class="forma-understanding__item" data-forma-state="accepted">
<span class="forma-understanding__state">Understood</span>
<div><strong>Symptom</strong><p>Ankle swelling returned.</p></div>
<button type="button">Source</button>
</li>
<li class="forma-understanding__item" data-forma-state="unknown">
<span class="forma-understanding__state">Unknown</span>
<div><strong>Since when</strong><p>The start date of the swelling was not given.</p></div>
<button type="button">Answer</button>
</li>
</ol>
</section>
</forma-understanding>
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 header heading
—
Names the review region.
data-forma-state
.forma-understanding__item
accepted | unknown | conflict
absent
Presentation of an application-supplied state: adds the state symbol, and for unknown and conflict the side bar. The text in .forma-understanding__state must say the same thing.
data-state
.forma-status-lozenge
ok | attention | blocked | unknown
absent
Adds a symbol to the header summary status.
CSS hooks (derived from dist/all.css)
Hook
Kind
Values or default
Description
.forma-understanding
Block class
—
Root bordered region.
.forma-understanding__header
Element class
—
Flex row of heading block and summary status, with a bottom rule; stacks at 40rem and below.
.forma-understanding__item
Element class
—
One item: grid of state, content and action with a bottom rule; one column at 40rem and below.
.forma-understanding__items
Element class
—
Unstyled ordered list of items.
.forma-understanding__state
Element class
—
Visible state text in small mono uppercase; receives a CSS symbol for known states.
[data-forma-state]
Attribute hook
"accepted", "conflict", "unknown"
Item state hook: accepted (✓), unknown (? and side bar), conflict (! and side bar). Presentation only; Ordo or the application owns the state.
Keyboard interaction
Keys
Result
Tab / Shift+Tab
Moves through the item actions in list order. No added keyboard behavior.
Enter / Space
Activates the focused native button; opening sources or answering is application behavior.
Events
Event
Description
click
Native click on item actions; the application opens the source, asks the question or resolves the conflict.
Form behavior
Not a form control. Answers are collected by application UI such as a Dialog or inline fields.
States
Understanding review states
State
How it is expressed
Presentation
Understood
data-forma-state="accepted" plus state text
✓ symbol before the state label.
Unknown
data-forma-state="unknown" plus state text
? symbol and a 0.3rem inline-start bar.
Conflict
data-forma-state="conflict" plus state text
! symbol and a 0.3rem inline-start bar.
Other application states
state text without data-forma-state
States such as Unresolved render as text only; add them as text rather than inventing hook values.
Stacked
@media (max-width: 40rem)
Header and items stack; item actions are full width.
Forced colors
@media (forced-colors: active)
Root border and the side bars use CanvasText.
Accessibility
Forma provides
Requires and styles a visible text state on every item; the symbol and side bar are extra cues, not replacements.
Uses an ordered list, so the number of items and their positions are announced.
Keeps source and answer actions reachable as full-width buttons on phones.
Your application supplies
Write the state text for every item and keep data-forma-state consistent with it.
Give action buttons specific names when several appear together, for example with visually hidden text ("Source for Allergy").
Summarize in the header how many items need attention and whether anything will be saved yet.
Decide in Ordo or application state whether unknown or conflicting items block the transition, and say so in text.