Human–agent interaction

Conversation

<forma-conversation>

Inspectable user/application turns with explicit speakers and no consumer-chat authority assumptions.

Authoring tag
<forma-conversation>
Behavior owner
Application / Limen
Canonical source
patterns/conversation.html

Purpose

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

  1. You

    Dad saw Dr. Smith yesterday. He increased the medication to 40 mg because the ankle swelling returned.

  2. 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.

HTML · Minimal conversation Raw HTML for HTML · Minimal conversation
<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

  1. Maria (daughter)

    The pharmacy gave Dad 20 mg tablets, but the doctor said 40 mg.

  2. Nurse Kim

    Two 20 mg tablets once a day is correct until the new prescription arrives.

  3. Care record assistant

    I can propose these record updates:

    • Dose: 40 mg once daily, taken as 2 × 20 mg
    • Note: new prescription pending
HTML · Multi-party care conversation Raw HTML for HTML · Multi-party care conversation
<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

  1. You

    Move my Lisbon flight to Friday morning and keep the aisle seat.

  2. Booking assistant

    Not completed

    The airline did not respond, so I don't know whether Friday seats are available. Your current booking is unchanged.

HTML · Application turn that could not complete Raw HTML for HTML · Application turn that could not complete
<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.

Viewport width

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.
HTML · Mobile history Raw HTML for HTML · Mobile history
<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.

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 conversation heading—Names the conversation region.
data-forma-speaker.forma-turnassistant | userabsentSpeaker category for presentation. assistant tints the turn; user (or absent) is untinted. The visible speaker label is the authoritative cue.
data-state.forma-status-lozengeok | attention | blocked | unknownabsentAdds a symbol to a text status inside a turn.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-conversationBlock class—Root bordered region.
.forma-conversation__headerElement class—Padded header with a bottom rule for kicker and heading.
.forma-conversation__turnsElement class—The ordered list of turns, unstyled and gapless; turns are separated by their own rules.
.forma-turnBlock class—One turn: a two-column grid of speaker label and content with a bottom rule.
.forma-turn__actionsElement class—Wrapping row of application-supplied actions under the content; full-width buttons at 40rem and below.
.forma-turn__contentElement class—Flow content of the turn; any structured HTML, allowed to shrink.
.forma-turn__speakerElement 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
KeysResult
Tab / Shift+TabMoves through links and action buttons in turn order. No added keyboard behavior.
Events
EventDescription
clickNative 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
StateHow it is expressedPresentation
User or person turndata-forma-speaker="user" or absentUntinted row with a speaker label.
Application turndata-forma-speaker="assistant"Secondary surface background; speaker label still required.
Turn outcometext and optional .forma-status-lozenge in the contentApplication-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.
  • Do not present generated text as fact or approval; route consequential proposals to Understanding review or Handoff summary.

Responsive behavior

  • 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.

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.