A conversation renders an ordered history of turns between people and an application or agent. It is an ol of .forma-turn items, each with a visible speaker label, content that can hold any structured HTML, and optional application-supplied actions. It deliberately avoids chat-bubble conventions: turns are full-width rows with the speaker in a label column, so position, alignment or color never suggest who is right, trusted or in charge. Application turns get a tinted background only to separate them; the speaker text is the real cue. Sending, streaming, retrying and what the turns mean are application or Limen behavior.
Use when
Users exchange messages with an assistant or application and need to inspect what each party said.
Turns contain structured content (lists, facts, links) and actions such as reviewing a proposal.
The history must be readable as a document, for audit or handover, not only as a live chat.
Avoid when
Only the latest input matters: use Composer alone.
The application's interpretation needs item-by-item review before a transition: use Understanding review.
The content is an activity log of system events: use Timeline or Feed item.
An agent is handing a proposed consequence to a human for approval: use Handoff summary.
Behavior to know
Each turn is a two-column grid: speaker label (minmax(6rem, 0.22fr)) and content; actions align under the content.
The speaker label is mono uppercase text on every turn, including the user's.
data-forma-speaker="assistant" tints the turn background; any other value is unstyled.
At 40rem and below each turn is one column and turn actions are full width.
Basic example
The smallest correct markup: the canonical pattern from patterns/conversation.html inside its public tag. Copy this first, then adapt labels, names and state.
Canonical
Minimal conversation
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.
Conversation
Record assistant
You
Dad saw Dr. Smith yesterday. He increased the medication to 40 mg because the ankle swelling returned.
Record assistant
I found a medication change, a returning symptom, and a visit. One detail may need clarification before the medication change can be recorded precisely.
<forma-conversation class="forma-component-tag">
<section class="forma-conversation" aria-labelledby="conversation-title">
<header class="forma-conversation__header">
<span class="forma-component-kicker">Conversation</span>
<h2 id="conversation-title">Record assistant</h2>
</header>
<ol class="forma-conversation__turns">
<li class="forma-turn" data-forma-speaker="user">
<p class="forma-turn__speaker">You</p>
<div class="forma-turn__content">
<p>Dad saw Dr. Smith yesterday. He increased the medication to 40 mg because the ankle swelling returned.</p>
</div>
</li>
<li class="forma-turn" data-forma-speaker="assistant">
<p class="forma-turn__speaker">Record assistant</p>
<div class="forma-turn__content">
<p>I found a medication change, a returning symptom, and a visit. One detail may need clarification before the medication change can be recorded precisely.</p>
</div>
<div class="forma-turn__actions">
<button type="button">Review understanding</button>
</div>
</li>
</ol>
</section>
</forma-conversation>
Click or tap the code once to select all of it, then copy.
Examples
Scenario
Multi-party care conversation
Two people and an application in one history. Every turn names its speaker; the application turn contains a structured list and an action to review its proposal. Nothing about layout or color says whose statement is correct.
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.
Care team
Medication follow-up
Maria (daughter)
The pharmacy gave Dad 20 mg tablets, but the doctor said 40 mg.
Nurse Kim
Two 20 mg tablets once a day is correct until the new prescription arrives.
<forma-conversation class="forma-component-tag">
<section class="forma-conversation" aria-labelledby="conversation-multi-party-title">
<header class="forma-conversation__header">
<span class="forma-component-kicker">Care team</span>
<h2 id="conversation-multi-party-title">Medication follow-up</h2>
</header>
<ol class="forma-conversation__turns">
<li class="forma-turn" data-forma-speaker="user">
<p class="forma-turn__speaker">Maria (daughter)</p>
<div class="forma-turn__content"><p>The pharmacy gave Dad 20 mg tablets, but the doctor said 40 mg.</p></div>
</li>
<li class="forma-turn" data-forma-speaker="user">
<p class="forma-turn__speaker">Nurse Kim</p>
<div class="forma-turn__content"><p>Two 20 mg tablets once a day is correct until the new prescription arrives.</p></div>
</li>
<li class="forma-turn" data-forma-speaker="assistant">
<p class="forma-turn__speaker">Care record assistant</p>
<div class="forma-turn__content">
<p>I can propose these record updates:</p>
<ul>
<li>Dose: 40 mg once daily, taken as 2 × 20 mg</li>
<li>Note: new prescription pending</li>
</ul>
</div>
<div class="forma-turn__actions"><button type="button">Review proposed updates</button></div>
</li>
</ol>
</section>
</forma-conversation>
Click or tap the code once to select all of it, then copy.
Scenario
Application turn that could not complete
The application could not finish a request. Its turn says so in text with a status lozenge and offers a retry, and the user's original message stays visible so nothing they wrote is lost.
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.
Conversation
Travel booking
You
Move my Lisbon flight to Friday morning and keep the aisle seat.
Booking assistant
Not completed
The airline did not respond, so I don't know whether Friday seats are available. Your current booking is unchanged.
<forma-conversation class="forma-component-tag">
<section class="forma-conversation" aria-labelledby="conversation-failed-turn-title">
<header class="forma-conversation__header">
<span class="forma-component-kicker">Conversation</span>
<h2 id="conversation-failed-turn-title">Travel booking</h2>
</header>
<ol class="forma-conversation__turns">
<li class="forma-turn" data-forma-speaker="user">
<p class="forma-turn__speaker">You</p>
<div class="forma-turn__content"><p>Move my Lisbon flight to Friday morning and keep the aisle seat.</p></div>
</li>
<li class="forma-turn" data-forma-speaker="assistant">
<p class="forma-turn__speaker">Booking assistant</p>
<div class="forma-turn__content">
<p><span class="forma-status-lozenge" data-state="unknown">Not completed</span></p>
<p>The airline did not respond, so I don't know whether Friday seats are available. Your current booking is unchanged.</p>
</div>
<div class="forma-turn__actions"><button type="button">Try again</button><button type="button">Contact an agent</button></div>
</li>
</ol>
</section>
</forma-conversation>
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 history
At phone width the speaker label sits above each turn's content and actions become full-width buttons.
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 each turn is a single column: speaker label, then content, then actions.
Turn action buttons become full width and keep the 2.75rem base height for touch.
Turns are full-width rows, not side-aligned bubbles, so nothing is squeezed into a narrow column at 320px and long words wrap within the content.
Order is the document order of the list; the application decides whether to scroll to the newest turn after rotation or a new message.
<forma-conversation class="forma-component-tag">
<section class="forma-conversation" aria-labelledby="conversation-mobile-title">
<header class="forma-conversation__header">
<span class="forma-component-kicker">Conversation</span>
<h2 id="conversation-mobile-title">Expense help</h2>
</header>
<ol class="forma-conversation__turns">
<li class="forma-turn" data-forma-speaker="user">
<p class="forma-turn__speaker">You</p>
<div class="forma-turn__content"><p>Can I claim the taxi from the airport?</p></div>
</li>
<li class="forma-turn" data-forma-speaker="assistant">
<p class="forma-turn__speaker">Expense assistant</p>
<div class="forma-turn__content"><p>Airport taxis are claimable up to $80 with a receipt.</p></div>
<div class="forma-turn__actions"><button type="button">Start a taxi claim</button></div>
</li>
</ol>
</section>
</forma-conversation>
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 conversation heading
—
Names the conversation region.
data-forma-speaker
.forma-turn
assistant | user
absent
Speaker category for presentation. assistant tints the turn; user (or absent) is untinted. The visible speaker label is the authoritative cue.
data-state
.forma-status-lozenge
ok | attention | blocked | unknown
absent
Adds a symbol to a text status inside a turn.
CSS hooks (derived from dist/all.css)
Hook
Kind
Values or default
Description
.forma-conversation
Block class
—
Root bordered region.
.forma-conversation__header
Element class
—
Padded header with a bottom rule for kicker and heading.
.forma-conversation__turns
Element class
—
The ordered list of turns, unstyled and gapless; turns are separated by their own rules.
.forma-turn
Block class
—
One turn: a two-column grid of speaker label and content with a bottom rule.
.forma-turn__actions
Element class
—
Wrapping row of application-supplied actions under the content; full-width buttons at 40rem and below.
.forma-turn__content
Element class
—
Flow content of the turn; any structured HTML, allowed to shrink.
.forma-turn__speaker
Element class
—
Visible speaker name in small mono uppercase. Required on every turn.
[data-forma-speaker]
Attribute hook
"assistant"
Presentation hook. assistant gives the turn the secondary surface background so application turns are distinguishable at a glance; it implies nothing about correctness or authority.
Keyboard interaction
Keys
Result
Tab / Shift+Tab
Moves through links and action buttons in turn order. No added keyboard behavior.
Events
Event
Description
click
Native click on turn actions; the application handles it.
Form behavior
Not a form control. Pair with a Composer form for new input.
States
Conversation states
State
How it is expressed
Presentation
User or person turn
data-forma-speaker="user" or absent
Untinted row with a speaker label.
Application turn
data-forma-speaker="assistant"
Secondary surface background; speaker label still required.
Turn outcome
text and optional .forma-status-lozenge in the content
Application-reported outcomes such as not completed or pending, written as text.
Stacked turns
@media (max-width: 40rem)
One column per turn; actions full width.
Forced colors
@media (forced-colors: active)
Root border uses CanvasText; the tint disappears and speaker labels carry the distinction.
Accessibility
Forma provides
Uses an ordered list so turn count and position are exposed.
Puts a visible speaker label on every turn, so speakers are distinguishable without color or alignment.
Keeps turns full width and stacks the speaker label above content on phones, avoiding narrow bubbles and overflow.
Your application supplies
Write the real speaker name on every turn, including agents and the user.
Announce new turns politely (for example through a separate status region) without moving focus away from the composer.
Report failures, pending work and uncertainty in text inside the turn.
Wide: turn grid minmax(6rem, 0.22fr) minmax(0, 1fr); content can shrink.
At 40rem and below: grid-template-columns: 1fr, actions move to the single column and buttons become full width.
Long content wraps inside the content column; wide tables or code in a turn need a Bounded overflow container.
Motion
No animation: turns appear without transitions and there is no typing indicator. Streaming or typing animations are application-owned and must stop under prefers-reduced-motion: reduce.
Usage guidance
Do
Keep the user's original words visible next to the application's interpretation.
Put actions that change records behind a review step rather than directly in a turn.
Avoid
Styling turns as left/right bubbles to signal speaker.
Omitting the speaker label on consecutive turns from the same speaker.
Record assistant · Extended localized content for verification and layout resilience
You
Dad saw Dr. Smith yesterday. He increased the medication to 40 mg because the ankle swelling returned.
Record assistant
I found a medication change, a returning symptom, and a visit. One detail may need clarification before the medication change can be recorded precisely.
Text spacingengineering screen
Conversation
Record assistant
You
Dad saw Dr. Smith yesterday. He increased the medication to 40 mg because the ankle swelling returned.
Record assistant
I found a medication change, a returning symptom, and a visit. One detail may need clarification before the medication change can be recorded precisely.
Cue dropout · grayscaleengineering screen
Conversation
Record assistant
You
Dad saw Dr. Smith yesterday. He increased the medication to 40 mg because the ankle swelling returned.
Record assistant
I found a medication change, a returning symptom, and a visit. One detail may need clarification before the medication change can be recorded precisely.
Reduced effective contrastengineering screen
Conversation
Record assistant
You
Dad saw Dr. Smith yesterday. He increased the medication to 40 mg because the ankle swelling returned.
Record assistant
I found a medication change, a returning symptom, and a visit. One detail may need clarification before the medication change can be recorded precisely.