Human–agent interaction

Composer

<forma-composer>

Natural-language composition surface for type, dictate, paste, and attach workflows without embedding agent behavior.

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

Purpose

A composer is a calm, large plain-language input: visible context and help, a labelled native textarea, a row of secondary input methods (attach, dictate), one continuation action and a status line. It is how a user tells an application something in their own words. Forma owns only the presentation. Interpretation, agent or model calls, speech recognition, uploads, drafts, permissions and whether anything is committed belong to the application or Limen. The composer must work as a plain text field when no assisted capability is available, and its status line must never imply that text has already been recorded.

Use when

  • Users describe a situation or request in free text that the application will interpret or route, such as a care note, an incident report or a request to an assistant.
  • The same surface should accept typing, paste, dictation and attachments.
  • The application will show its interpretation for review (for example with Understanding review) before anything consequential happens.

Avoid when

  • The input is a short structured value: use Text field or a specific input.
  • A normal multi-line form field is enough, with no alternative input methods or status: use Textarea.
  • The user is picking from a known set of commands: use Command palette or Search.
  • The history of the exchange matters more than the input: compose the composer under a Conversation.

Behavior to know

  • Bordered surface with responsive padding and a context block (kicker, heading, help text).
  • The textarea is at least 8rem tall, full width and vertically resizable.
  • The submit action uses the inverse surface so it is the single strongest control.
  • At 40rem and below input methods become a two-column grid of 2.75rem buttons and the submit button is full width.

Basic example

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

Canonical

Minimal composer

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.

Capture

What do you want this record to know?

Type, dictate, paste, or attach information in your own words. The application decides how it is interpreted and whether follow-up is required.

Nothing is added to the record until the application confirms the transition.

HTML · Minimal composer Raw HTML for HTML · Minimal composer
<forma-composer class="forma-component-tag">
<section class="forma-composer" aria-labelledby="composer-title">
  <div class="forma-composer__context">
    <span class="forma-component-kicker">Capture</span>
    <h2 id="composer-title">What do you want this record to know?</h2>
    <p id="composer-help">Type, dictate, paste, or attach information in your own words. The application decides how it is interpreted and whether follow-up is required.</p>
  </div>
  <label class="forma-composer__field">
    <span class="forma-sr-only">Tell the application what happened</span>
    <textarea rows="4" aria-describedby="composer-help" placeholder="Tell me what happened…"></textarea>
  </label>
  <div class="forma-composer__actions">
    <div class="forma-composer__input-actions" aria-label="Additional input methods">
      <button type="button">Attach</button>
      <button type="button">Dictate</button>
    </div>
    <button type="submit" class="forma-composer__submit">Continue</button>
  </div>
  <p class="forma-composer__status" role="status">Nothing is added to the record until the application confirms the transition.</p>
</section>
</forma-composer>

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

Examples

Scenario

Assistance unavailable

The interpretation service is down. The composer still works as a plain note field: dictation is not offered, attaching still is, and the status line says in words what will happen to the text.

Static specimen. Its buttons stand for application actions that the consuming application implements; this script-free documentation does not perform them. Submitting or resetting it needs the consuming application's form handling, which this documentation does not have. Its controls are shown for their markup and appearance and cannot be operated here.

Shift handover

Note for the next shift

Automatic summarizing is unavailable right now. Your note will be saved exactly as written.

Assisted summarizing unavailable. Nothing is saved until you choose Save note.

HTML · Assistance unavailable Raw HTML for HTML · Assistance unavailable
<forma-composer class="forma-component-tag">
  <form class="forma-composer" aria-labelledby="composer-no-assistance-title">
    <div class="forma-composer__context">
      <span class="forma-component-kicker">Shift handover</span>
      <h2 id="composer-no-assistance-title">Note for the next shift</h2>
      <p id="composer-no-assistance-help">Automatic summarizing is unavailable right now. Your note will be saved exactly as written.</p>
    </div>
    <label class="forma-composer__field">
      <span class="forma-sr-only">Handover note</span>
      <textarea name="handover-note" rows="4" aria-describedby="composer-no-assistance-help"></textarea>
    </label>
    <div class="forma-composer__actions">
      <div class="forma-composer__input-actions" role="group" aria-label="Additional input methods">
        <button type="button">Attach</button>
      </div>
      <button type="submit" class="forma-composer__submit">Save note</button>
    </div>
    <p class="forma-composer__status" role="status">Assisted summarizing unavailable. Nothing is saved until you choose Save note.</p>
  </form>
</forma-composer>

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

Scenario

Dictating with an attachment

Dictation is in progress, shown by the pressed state and label of the Dictate button, and one file is attached. The status reports both as text. Recording and upload are application behavior.

Static specimen. Its buttons stand for application actions that the consuming application implements; this script-free documentation does not perform them. Submitting or resetting it needs the consuming application's form handling, which this documentation does not have. Its controls are shown for their markup and appearance and cannot be operated here.

Incident report

What happened on site?

Describe the incident in your own words. You will review the extracted details before the report is filed.

Attached: aisle-7-rack.jpg (2.4 MB)

Listening… 1 photo attached. Nothing is filed until you confirm the report.

HTML · Dictating with an attachment Raw HTML for HTML · Dictating with an attachment
<forma-composer class="forma-component-tag">
  <form class="forma-composer" aria-labelledby="composer-dictating-title">
    <div class="forma-composer__context">
      <span class="forma-component-kicker">Incident report</span>
      <h2 id="composer-dictating-title">What happened on site?</h2>
      <p id="composer-dictating-help">Describe the incident in your own words. You will review the extracted details before the report is filed.</p>
    </div>
    <label class="forma-composer__field">
      <span class="forma-sr-only">Incident description</span>
      <textarea name="incident" rows="4" aria-describedby="composer-dictating-help composer-dictating-files">At about 10:15 a forklift clipped the rack in aisle 7. Nobody was hurt, but two pallets</textarea>
    </label>
    <p id="composer-dictating-files">Attached: aisle-7-rack.jpg (2.4 MB)</p>
    <div class="forma-composer__actions">
      <div class="forma-composer__input-actions" role="group" aria-label="Additional input methods">
        <button type="button">Attach</button>
        <button type="button" aria-pressed="true">Stop dictation</button>
      </div>
      <button type="submit" class="forma-composer__submit">Review report</button>
    </div>
    <p class="forma-composer__status" role="status">Listening… 1 photo attached. Nothing is filed until you confirm the report.</p>
  </form>
</forma-composer>

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 capture

At phone width the input methods form a two-column grid and the continuation action spans the full width below them.

Static specimen. Its buttons stand for application actions that the consuming application implements; this script-free documentation does not perform them. Submitting or resetting it needs the consuming application's form handling, which this documentation does not have. 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 the actions row becomes a stretched column: input methods as a two-column grid of equal buttons, then a full-width submit button.
  • Every button in the actions area gets a 2.75rem minimum height for touch.
  • Padding shrinks with clamp(1rem, 3vw, 1.5rem), and the textarea keeps its 8rem minimum height and full width, so text entry never overflows at 320px.
  • When the on-screen keyboard opens, the textarea and status remain in normal flow; nothing is fixed to the viewport, so the page can scroll the submit button into view.
HTML · Mobile capture Raw HTML for HTML · Mobile capture
<forma-composer class="forma-component-tag">
  <form class="forma-composer" aria-labelledby="composer-mobile-title">
    <div class="forma-composer__context">
      <span class="forma-component-kicker">Care log</span>
      <h2 id="composer-mobile-title">How is Dad today?</h2>
      <p id="composer-mobile-help">Type, dictate or attach a photo. You will confirm anything before it is added to his record.</p>
    </div>
    <label class="forma-composer__field">
      <span class="forma-sr-only">Care update</span>
      <textarea name="care-update" rows="4" aria-describedby="composer-mobile-help" placeholder="Tell me what happened…"></textarea>
    </label>
    <div class="forma-composer__actions">
      <div class="forma-composer__input-actions" role="group" aria-label="Additional input methods">
        <button type="button">Attach</button>
        <button type="button" aria-pressed="false">Dictate</button>
      </div>
      <button type="submit" class="forma-composer__submit">Continue</button>
    </div>
    <p class="forma-composer__status" role="status">Nothing is added to the record until you confirm.</p>
  </form>
</forma-composer>

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 form or sectionid of the context heading—Names the composer by its visible question or purpose.
aria-describedbytextareaid(s) of help and attachment text—Announces the help text (and attachment list) with the field.
nametextareastring—Form field name when the composer is a native form.
rowstextareanumber2Initial visible lines; Forma also sets an 8rem minimum height.
placeholdertextareastring—Optional example phrasing. Never a substitute for the label or help.
roleinput-actions group, statusgroup | status—group names the secondary input methods together; status makes the status line a polite live region.
aria-labelinput-actions groupstring—Names the group, for example "Additional input methods".
aria-pressedDictate buttontrue | false—Exposes whether dictation is active when the button toggles recording.
typebuttonssubmit | buttonsubmit inside a formOnly the continuation action submits; input-method buttons must be type="button".
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-composerBlock class—Root bordered surface. Use a form when the composer submits natively.
.forma-composer__actionsElement class—Row with input methods on one side and submit on the other; stacks at 40rem and below.
.forma-composer__contextElement class—Kicker, heading and help text block.
.forma-composer__fieldElement class—The label that wraps the textarea; the textarea is full width, 8rem minimum and vertically resizable.
.forma-composer__input-actionsElement class—Wrapping group of secondary input-method buttons; a two-column grid at 40rem and below.
.forma-composer__statusElement class—Small secondary-color status line, usually a role="status" region.
.forma-composer__submitElement class—The single continuation action, drawn on the inverse surface; full width at 40rem and below.
Keyboard interaction
KeysResult
Tab / Shift+TabMoves from the textarea to input-method buttons and the submit button.
Enter in the textareaInserts a new line (native textarea). Submitting on Enter or Ctrl+Enter is application behavior if wanted.
Enter / Space on a buttonActivates it natively. The submit button submits the form.
Events
EventDescription
inputNative event from the textarea as the user types or pastes.
pasteNative paste event; the application may inspect pasted content or files.
submitNative form submission from the continuation button when the root is a form.

Form behavior

The textarea is a native form control: it submits its name and value, supports required, maxlength and form reset. Attachments and dictation are application-managed, not form data, unless the application adds file inputs.

States

Composer states
StateHow it is expressedPresentation
Emptyempty textareaOptional placeholder shown; help text stays visible.
Dictatingaria-pressed="true" on the Dictate button plus status textApplication-owned recording state.
Assistance unavailablestatus and help text written by the applicationThe composer remains a plain text field.
Stacked actions@media (max-width: 40rem)Input methods in a two-column grid, full-width submit.
Forced colors@media (forced-colors: active)Root border uses CanvasText.

Accessibility

Forma provides

  • Keeps the native textarea as the input, so editing, selection, paste, spellcheck and form behavior come from the browser.
  • Gives the textarea a large minimum size and keeps every action at 2.75rem on narrow screens.
  • Separates the single continuation action from input methods by position and surface, not only color.

Your application supplies

  • Give the textarea an accessible label (visually hidden with .forma-sr-only if the heading already says it) and link help with aria-describedby.
  • Write status in text: listening, uploading, unavailable, and that nothing is committed until confirmed.
  • Offer dictation and attachment only when available, and never as the only way to enter information.
  • Use a form (or handle submission) so the submit button does something; a submit button outside a form is inert.
  • Preserve the user's text if interpretation fails.

Responsive behavior

  • Root is a grid with min-inline-size: 0 and clamp(1rem, 3vw, 1.5rem) padding.
  • Textarea: inline-size: 100%, min-block-size: 8rem, resize: vertical.
  • At 40rem and below: actions stack with align-items: stretch; input methods become repeat(2, minmax(0, 1fr)); submit is full width.
  • Long help text wraps; the composer never needs horizontal scrolling.

Motion

  • No animation: the composer is static. Buttons keep only the base perceptual hover and press color change, and any recording indicator animation is application-owned and must stop under reduced motion.

Usage guidance

Do

  • Ask a concrete question in the heading ("What happened on site?").
  • Say what happens next in the submit label ("Review report") and in the status line.

Avoid

  • Labels like "Send" that imply the text is committed immediately.
  • Showing agent or model branding as if it carried authority over the record.

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.