Chat

Agent conversations with unboxed answers, activity disclosures, user bubbles, long-message collapse, waiting queues, and steering

Messages wrap long text and links; pre blocks scroll within their message body instead of widening the transcript. Keep readable link text and native keyboard focus. Scrollable code blocks should use tabindex="0" and a descriptive accessible label so Safari keyboard users can reach and scroll them. Transcript height, message updates, announcement policy and scroll-indicator navigation belong to the application. Existing chat-scroll / data-chat-tl contracts remain unchanged. Do not treat timeline styling as automatic message loading or scroll-position management.

Chat

Chat provides CSS-only primitives for agent conversations. User messages appear in rounded bubbles; agent answers render directly in the transcript, with optional avatars, activity disclosures, reasoning traces, tool calls, and streaming states.

Basic Usage

Use .chat.chat-end with .chat-bubble for user messages. Use .chat.chat-start.chat-agent with .chat-content for agent output: it takes the available width with no bubble background, border, or padding. Put any existing .avatar inside an optional .chat-avatar; omit the slot when no avatar is needed. Start and end alignment follow the text direction, including RTL transcripts.

Wrap a transcript in .chat-scroll when the conversation should scroll inside a fixed-height panel. Scroll behavior defaults to smooth. Pair agent replies with matching indicators via data-chat-tl so Scroll-Driven Animations can sync the rail with visible assistant rows.

Basic Chat

AI
Agent - 2:15 PM
How can I help you today?
GA
You - 2:16 PM
Show me a compact chat transcript.

Agent Answers And Activity

Keep the answer in a direct .chat-content block, adding .markdown-body for rich text. Group work records in native <details class="chat-work"> with a .chat-work-summary and .chat-work-body. The compact summary can show Worked, tool or command counts, and failed operations; the application supplies those labels and values.

Place the work disclosure before a completed answer. During progress, a brief content update may come first, with the activity summary below it. The answer stays visible when the work disclosure is closed. Reasoning and tool records can be nested inside the work body or placed directly in the agent row. All disclosures use native <details> / <summary> interaction and need no toggle script.

This static example illustrates completed checks and a pending preview retry; it does not execute tools or make network requests.

You
Review the chat components and summarize the checks, including any failures.
AI
Worked · 3 tool calls · 1 failed
Review approach
Check the source, run the focused tests, then inspect the narrow-screen layout.
read_component_sourceDone
User bubbles and agent content use separate primitives.
run_scoped_testsDone
Queue, steer, and long-message checks passed.
capture_mobile_previewFailed
The preview server was unavailable. The mobile capture still needs a retry.

Reviewed the chat components. The focused behavior checks passed; the mobile preview needs another attempt.

  • Waiting messages keep their sending order.
  • Steer adds a message to the active conversation immediately.
  • Sent user messages taller than six lines can be expanded.

Use a direct agent content block for the answer:

Agent answerhtml
<div class="chat-content markdown-body">Answer</div>
AI
I will retry the mobile preview and keep its result separate from the completed checks.
2 commands · 1 other operation · 1 failed
check_preview_serverFailed
The preview server did not respond.
start_preview_serverDone
A fresh preview server was started.
retry_mobile_previewRunning...
Waiting for the documentation preview to respond.
<div class="chat chat-end">
  <div class="chat-bubble chat-bubble-primary">Review the chat components.</div>
</div>
<div class="chat chat-start chat-agent">
  <div class="chat-avatar"><div class="avatar avatar-sm avatar-primary">AI</div></div>
  <details class="chat-work">
    <summary class="chat-work-summary">Worked · 3 tool calls · 1 failed</summary>
    <div class="chat-work-body">
      <p>Source and scoped tests checked. The mobile preview needs a retry.</p>
    </div>
  </details>
  <div class="chat-content markdown-body">
    <p><strong>Review complete.</strong> Queue, steer, and long-message checks passed.</p>
  </div>
</div>

Collapsible Sent Messages

Add .chat-bubble-collapsible to sent user bubbles to keep messages taller than six rendered lines compact. Put the message text in a direct .chat-bubble-content child and a native .chat-bubble-toggle button after it. The collapsed content preserves newlines and wraps naturally; Show more reveals the complete message and changes to Show less. Short messages and messages of exactly six rendered lines need no toggle. Assistant replies and waiting queue items keep their existing presentation.

You · Short message
Please summarize the accessibility checks.
You · Exactly six lines
Check keyboard focus. Check accessible names. Check contrast. Check touch targets. Check reduced motion. Share the results.
You · More than six lines
Review the chat view. Keep the waiting queue. Support immediate steer. Preserve message order. Keep multiline text. Check keyboard focus. Check narrow screens. Share the results.
<div class="chat chat-end">
  <div class="chat-header">You</div>
  <div class="chat-bubble chat-bubble-primary chat-bubble-collapsible">
    <div class="chat-bubble-content" id="demo-long-message" tabindex="-1">Review the chat view.
Keep the waiting queue.
Support immediate steer.
Preserve message order.
Keep multiline text.
Check keyboard focus.
Check narrow screens.
Share the results.</div>
    <button class="btn btn-ghost btn-xs chat-bubble-toggle" type="button"
      aria-controls="demo-long-message" aria-expanded="false" hidden>Show more</button>
  </div>
</div>

The application wires the toggle and decides when it is needed. After rendering, compare the content’s natural scrollHeight against six times its computed line height, allowing one pixel for rounding. Reveal the button only when content exceeds that limit. On click, switch its aria-expanded value and Show more / Show less label; core CSS reads aria-expanded="true" to remove the height limit. Give each content element a unique ID and reference it through aria-controls.

Use ResizeObserver to remeasure actual wrapped lines when the available width changes, and refresh after message text updates (or observe them with MutationObserver). If a message becomes short enough, hide its button and reset aria-expanded to false. Before hiding a focused button, move focus to the controlled content with tabindex="-1". Disconnect observers when removing messages or leaving the page. The demos use a shared controller with cleanup on Astro navigation; this controller is documentation code, and core remains CSS-only. Sent, steered, and automatically dispatched user messages in the waiting-queue demo all use this same behavior.

Waiting Queue And Steer

Keep messages sent during an active reply in a separate .chat-queue, in sending order. A waiting message enters the transcript when the application dispatches it after the current reply completes. Steer dispatches that message immediately: remove it from the waiting queue, add its user row to the current conversation, and use it to guide the active reply. Steer does not cancel the active reply or start another assistant turn. Remove discards a waiting message without sending it.

This demo starts with an active simulated reply and two waiting messages so the queue is visible immediately. Use a row’s Steer to add it to the same current reply, or Complete response to finish that reply and send the oldest waiting message first. Start fresh returns to the idle greeting. The demo has no backend or generated answer.

Agent
What would you like to work on?
Enter sends your draft, or queues it while a reply is active. Shift+Enter adds a new line. Ctrl/⌘+Enter steers the current reply. Empty drafts cannot be sent. The checkmark completes the demo response; the reset arrow starts fresh.

Ready. 0 messages waiting.

Place the queue and composer in one .chat-input-area. The queue forms a shallow, inset tray tucked behind the rounded composer, with one message per row and no individual card borders or colored fills. A leading .chat-queue-icon introduces the single-line preview; a native title preserves the full message. Keep the queue’s accessible heading and ordered positions visually hidden, and announce the waiting count through the polite status region. Every row keeps its icon-only Steer and Remove actions available, with accessible names and descriptions in native Popover tooltips. The application still marks the next message with .chat-queue-item-active and updates its position when the queue changes; the leading icon provides emphasis without an active border highlight.

Multiple rows share the same tray. Add an optional .chat-queue-attachment thumbnail beside a message preview when the caller already has attached media. The caller supplies the image source and meaningful alternative text; this presentation primitive does not upload files or manage attachment state. The live demo uses text-only drafts.

Use .chat-composer with a labelled native .chat-composer-input textarea and adjacent icon-only ghost actions. The primary action is named Send while idle and Queue during a reply; its name and shortcut appear in a native Popover tooltip. The composer’s Steer action sends the current draft directly into the active conversation without adding it to the waiting queue. It is disabled while idle or when the draft is blank. Disable submission for empty or whitespace-only drafts without native validation bubbles. The draft clears only after successful admission. The help icon opens usage instructions in a native Popover. Use .chat-composer-ghost for the reference’s transparent border while retaining its keyboard focus treatment.

Key Action
Enter Send while idle; queue while a reply is active
Shift+Enter Insert a native textarea newline
Ctrl+Enter or ⌘+Enter Steer the current draft immediately while a reply is active

Ignore shortcuts during input-method composition, including isComposing and legacy key code 229, so pressing Enter to confirm an IME candidate never sends the draft. Keep native selection and editing. The textarea grows and shrinks with its content, scrolls internally at 16rem, and has no manual resize handle. Complete response is a separate demo control that simulates completion; it is not a composer action.

<div class="chat-input-area">
  <section class="chat-queue" aria-labelledby="demo-waiting-title">
    <div class="chat-queue-header sr-only">
      <h3 class="chat-queue-title" id="demo-waiting-title">Message Queue (1)</h3>
      <span class="chat-queue-count">1 Queued</span>
    </div>
    <ol class="chat-queue-list" role="list" tabindex="0" aria-label="Waiting messages">
      <li class="chat-queue-item chat-queue-item-active">
        <svg class="chat-queue-icon" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="m8 6 4 4-4 4"/><path d="M12 10H5m10-4h4m-4 6h4m-4 6h4"/></svg>
        <span class="chat-queue-number sr-only">#1</span>
        <img class="chat-queue-attachment" src="mockup.png" alt="Attached mockup" />
        <div class="chat-queue-content" title="Also include the accessibility checks.">Also include the accessibility checks.</div>
        <div class="chat-actions chat-queue-actions">
          <button class="btn btn-ghost btn-sm btn-square chat-queue-steer" type="button" aria-label="Steer waiting message 1">
            <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="m15 4 5 5-5 5"/><path d="M20 9h-9a6 6 0 0 0-6 6v4"/></svg>
          </button>
          <button class="btn btn-ghost btn-sm btn-square chat-queue-remove" type="button" aria-label="Remove waiting message 1">
            <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="M3 6h18M9 6V3h6v3M5 6l1 15h12l1-15M10 10v7m4-7v7"/></svg>
          </button>
        </div>
      </li>
    </ol>
  </section>
  <form class="chat-composer chat-composer-ghost">
    <label class="sr-only" for="demo-waiting-message">Message</label>
    <textarea class="chat-composer-input" id="demo-waiting-message" name="message" rows="1" placeholder="Message the agent…"></textarea>
    <div class="chat-composer-actions">
      <button class="btn btn-ghost btn-sm btn-square" type="submit" aria-label="Queue message" aria-keyshortcuts="Enter" disabled>
        <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="M12 19V5m-7 7 7-7 7 7"/></svg>
      </button>
      <button class="btn btn-ghost btn-sm btn-square" type="button" aria-label="Steer current message" aria-keyshortcuts="Control+Enter Meta+Enter" disabled>
        <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="m15 4 5 5-5 5"/><path d="M20 9h-9a6 6 0 0 0-6 6v4"/></svg>
      </button>
    </div>
  </form>
</div>
<p class="chat-status" role="status" aria-live="polite" aria-atomic="true">1 message waiting.</p>

Core supplies presentation only; the application owns queue state, completion events, network requests, steering support, and keyboard handlers. Wire Enter to the form’s native submission and Ctrl/⌘+Enter to immediate steering, keeping Shift+Enter native. The sample buttons need application handlers and composition guards. Enable them only when a nonblank draft is available. Use .tooltip[popover="hint"] with interestfor and aria-describedby for action names and shortcut descriptions; use a help button with popovertarget for longer instructions. For real asynchronous integrations, await successful dispatch or steering acknowledgment before dequeuing a message; keep rejected messages available for retry. Give each message a stable identity so a completed or steered message cannot be dispatched twice. Hide an empty queue with hidden rather than leaving an empty panel in the layout.

Composer Parts

Compose the existing shell with optional references, quote previews, attachments, suggestions, and a toolbar. These are visual parts: Core does not create an editor, resolve a reference, upload a file, submit a draft, or mutate a waiting queue. The compact examples below use local demo handlers for configuration, file previews, and send/stop. No files are uploaded and no model request is made.

Anatomy And States

Only the shell and a labelled editor are required for an editable composer. Keep submission actions outside scrolling editor, attachment, and suggestion regions. All other parts are optional; reuse existing button, chip, popover, and progress classes.

Part / classes Expected element and visual state contract
.chat-composer Form or container; retains the currentColor border/focus ring, seven semantic variants, and ghost variant. data-state="readonly", data-state="disabled" / aria-disabled="true", and data-state="error" / aria-invalid="true" describe the displayed shell state.
.chat-composer-input, .chat-composer-editor Labelled native <textarea> or scoped contenteditable editor; shared text, caret, selection, content-based sizing, and bounded overflow. Existing .chat-composer-input usage remains supported.
.chat-composer-editor[contenteditable] Give the editable surface role="textbox", aria-multiline="true", and an accessible name. data-placeholder plus application-managed data-empty="true" supplies the rich-editor placeholder. Native textareas use placeholder.
.chip.chat-composer-reference Atomic reference label, optionally with an existing button. Use data-selected="true", aria-invalid="true", or aria-busy="true" for selected, invalid, and resolving presentation; put contenteditable="false" on atomic nodes inside an editor.
.chat-composer-label Flexible, truncated label for references or suggestion rows. Retain full text and a native title when the preview is truncated.
.chat-composer-quote, .chat-composer-quote-text Quote preview container and <blockquote> text, with optional attribution and removal button. data-selected="true" marks a selected quote. The application retains the complete quote behind a bounded preview.
.chat-composer-attachments, .chat-composer-attachment Named <ul role="list"> and <li> items. Item data-state values: validating, uploading, ready, error, cancelled. State text and available actions come from the application.
.chat-composer-preview, .chat-composer-attachment-info, .chat-composer-filename Optional image/icon preview, flexible metadata wrapper, and truncated filename. Images need alternative text; use existing native .progress for upload values.
.chat-composer-description Supporting text such as attribution, file status, or suggestion details.
.chat-composer-toolbar, .chat-composer-actions Wrapping control row and submission action group. Add .chat-composer-toolbar-compact for a single compact row and .chat-composer-config to let a configuration trigger truncate before the icon actions.
.chat-composer-thumbnails, .chat-composer-attachment-tile, .chat-composer-attachment-remove Optional horizontal attachment strip, square image tile, and overlaid icon removal action. Place the strip above the editor and hide it when empty.
.popover.chat-composer-menu, .chat-composer-menu-end Native configuration Popover, bounded to the viewport with anchor flip fallbacks. Use the end modifier for settings on the right. Compose rows with .popover-menu-item, .chat-composer-menu-option[aria-pressed], .chat-composer-menu-row, and .chat-composer-menu-field.
.chat-composer-status Optional status text with data-state="pending", "unknown", or "error". Use role="status" for polite updates or role="alert" for actionable validation errors, and connect the editor with aria-describedby.
.chat-composer-completions In-flow suggestion surface or native [popover] surface. The host supplies a unique position-anchor; Core supplies viewport bounds and block/inline flip fallbacks.
.chat-composer-breadcrumb, .chat-composer-group Optional directory navigation and labelled suggestion group heading. The application owns directory queries and drill-down behavior.
.chat-composer-option, .chat-composer-completions > [role="option"] Suggestion row; data-active="true" or aria-selected="true" displays the active row, and aria-disabled="true" displays an unavailable choice. Nested rows require .chat-composer-option; the host prevents unavailable selection.
.chat-queue-item[data-state] Existing queue row with optional editing, stale, conflict, or consuming presentation. Preserve stable row identities, visible actions, and application-owned queue revisions.

State attributes supply presentation only. Enforce disabled/read-only behavior with native disabled / readonly, contenteditable="false", or the host’s appropriate interaction boundary. Do not make an active model run imply a read-only editor. A selected visual node does not acquire selection or removal behavior from CSS.

Compact Composition

Compact Composer

Add
Approval mode
Medium
Low → Maximum
Model
components /
Ctrl/⌘+Enter sends. Enter adds a new line. Add files with +, change approval with the shield, and choose a model or reasoning effort on the right. These controls use local demo state; files stay in your browser.

Keep the editor above one toolbar: add and approval icons on the left, model and reasoning configuration on the right, followed by a circular Send/Stop action. The configuration label truncates at narrow widths so the icon controls stay available. Menus use native Popovers anchored to their triggers; Escape and outside clicks dismiss them. Usage instructions live under + → Composer help.

This demo uses Enter for a newline and Ctrl/⌘+Enter for submission. The Waiting Queue demo above uses Enter to queue and Ctrl/⌘+Enter to steer. Core does not impose either policy. Action descriptions must match the application’s shortcuts, and IME composition must never submit a draft. Empty or whitespace-only drafts keep Send disabled without a native validation bubble. An attached file also counts as draft content. Sending switches the arrow to Stop; stopping returns to Send and preserves any newly typed draft.

Model names, reasoning levels, approval choices, and available add-menu actions come from the application. These sample choices only change local demo state. Core supplies layout and presentation without granting permissions or calling providers.

Settings Trigger Styles

Compose native buttons with .chat-composer-access (pushes following controls toward the end), .chat-composer-model (rounded surface pill), and .chat-composer-effort (muted effort text). Set data-active="true" on the access trigger for a warning foreground when a dangerous permission is active. The application supplies labels and values; opening a menu or choosing an item does not grant permission or change a setting in Core.

Public Settings Triggers

Use the same triggers in .chat-composer-toolbar-compact; the model label truncates via .chat-composer-config and .chat-composer-label. Native Popovers retain their anchor positioning, Escape dismissal, and keyboard focus behavior. The host owns choice selection, nested model menus, slider commits, reset behavior, and announcements.

Attached Context Bar

Place .chat-composer-context as the first direct child of .chat-composer, above the editor. It shares the composer’s surface and top corners; its inset follows --chat-composer-inset (1rem by default, 0.625rem with .chat-composer-compact). The compact shell also uses the medium radius. .chat-composer-ghost retains its transparent border, including when combined with compact.

Composer With Attached Context

workspace/project/src
Plan mode Connected

Items use .chat-composer-context-item, optional .chat-composer-context-icon, and .chat-composer-context-label for truncation. Retain the full value in the DOM and provide a title or another accessible way to inspect truncated values. Put trailing items in .chat-composer-context-end; both groups wrap at narrow widths. Optional actions are native labelled buttons. .chat-composer-connection[data-state] supports connected, connecting, and disconnected; always include a visible text label, and use role="status" for host-driven polite updates. Core never changes connection state.

Attachment Previews

Composer With An Attachment

  • Mountain landscape attachment
Add
Approval mode
Medium
Low → Maximum
Model
components /
Ctrl/⌘+Enter sends. Enter adds a new line. Add files with +, change approval with the shield, and choose a model or reasoning effort on the right. These controls use local demo state; files stay in your browser.

Selected images appear as thumbnail tiles above the editor. Use + → Files to preview local files and the tile’s icon to remove one. The strip scrolls horizontally when full; it does not displace the toolbar or impose an editor height. The sample landscape uses the documentation site’s existing local image asset.

The application supplies file policy, picker/paste/drop intake, upload progress, retry, cancellation, and removal. File rows still support validating, uploading, ready, error, and cancelled states; show the states relevant to the current attachment. Use the existing .progress component for an actual upload value. A restored filename is not proof that an upload is ready. Keep pending admission separate from attachment progress and announce relevant updates through one polite status region.

Native Suggestion Surface

The compact demo’s + → Source reference opens a native Popover and inserts a sample source name into the draft. Real source lookup and directory navigation belong to the host. Use .chat-composer-completions for editor completion results, with .chat-composer-option, .chat-composer-group, and .chat-composer-breadcrumb for options and navigation. Core supplies viewport bounds and anchor flip fallbacks.

For a real editor completion, retain native textarea semantics and use aria-haspopup="listbox", aria-controls, and aria-activedescendant while the listbox is open. Keep the active option’s ID and aria-selected synchronized, ignore unavailable rows, and consume suggestion-selection keys before submission keys. Do not add role="combobox" to a textarea. Loading, empty, or failed provider results can use .chat-composer-status; do not expose loading text as a selectable result.

Pending Admission And Queue Mutations

Apply queue row data-state="editing", "stale", "conflict", or "consuming" only when the application’s current state calls for it. The interactive Waiting Queue above shows the ordinary queue flow.

An unknown submission outcome is separate from rejection. Do not automatically resend it, clear its snapshot, or invent a confirmed queue item. Keep the editor available while checking the earlier submission. Use .chat-composer-status with data-state="pending", "unknown", or "error" and a relevant status or recovery action. Connect validation text to the editor with aria-describedby and expose aria-invalid="true" when the draft is invalid. Server admission and queue mutations remain authoritative.

Compatibility And Delivery

The base composer parts and state attributes shipped in Core 1.21.0. The compact toolbar, configuration menu, thumbnail modifiers, and content-sized textarea shown here are development changes and require the matching Core build; they are not in the published 1.21.0 package. Existing class names remain supported. The toolbar wraps by default; the compact modifier opts into a single row. Textarea autosizing uses field-sizing: content; applications targeting browsers without it need their own textarea height handler.

All parts ship through the aggregate CSS, component CSS, generated component ESM stylesheet, and standalone plugin outputs. With the package’s token-only @duskmoon-dev/core/plugin entry, also import Core CSS as before. The generated @duskmoon-dev/core/components/chat module exports CSS text and a nullable constructable stylesheet, so server-side consumers can import it without a browser CSSStyleSheet implementation. No editor runtime is included in Core.

Scroll-Driven Indicators

.chat-scroll hoists named view timelines with timeline-scope (--chat-1 … --chat-24). Pair agent / assistant rows only (.chat-start) with matching indicators: .chat[data-chat-tl="N"] declares view-timeline-name, and .chat-scroll-indicator[data-chat-tl="N"] binds animation-timeline + animation-range: entry 0% exit 100%.

User turns stay in the transcript but do not get ticks. Click an indicator to jump to that agent response inside .chat-scroll — use button + data-chat-target (not bare href="#…"), otherwise the document will scroll. Docs demos wire the click handler; app code should call scroller.scrollTo(...) the same way.

The dashes keep their visual spacing, while adjacent buttons have continuous hover and click areas. Moving through the space between dashes still selects an indicator.

Requires a browser that supports Scroll-Driven Animations. Unsupported browsers still scroll smoothly; indicators stay in the idle style.

Keep .chat-input-area outside .chat-scroll so the composer stays visible while browsing replies. Connect the Send button to your application’s message handler.

Scroll-Driven Chat Indicators

AI
Agent - 2:00 PM
Welcome back. The left ticks mark each assistant reply — scroll or click a tick to jump to that response.
GA
You - 2:01 PM
Can we use Scroll-Driven Animations for the rail?
AI
Agent - 2:01 PM
Yes. Each agent row exposes a named view-timeline. The parent raises timeline-scope so indicators can bind animation-timeline without living in the same subtree.
GA
You - 2:02 PM
Should user messages also get ticks?
AI
Agent - 2:02 PM
No. Ticks only navigate to the start of an agent response. User turns stay in the transcript but are skipped by the rail.
GA
You - 2:03 PM
What about animation-range?
AI
Agent - 2:03 PM
Indicators use entry 0% exit 100%, so they brighten while the paired assistant message is in view and fade as it leaves.
GA
You - 2:04 PM
Why not use href hash links for the ticks?
AI
Agent - 2:04 PM
Hash navigation scrolls the document. For an overflow panel, use a button with data-chat-target and scroll the .chat-scroll container itself.
GA
You - 2:05 PM
Can clicks land exactly on the agent row start?
AI
Agent - 2:05 PM
Yes. The handler computes the target offset inside the scroller and calls scrollTo with smooth behavior, aligning to the agent row top (plus scroll-margin).
GA
You - 2:06 PM
Add one more long answer so the list actually overflows.
AI
Agent - 2:06 PM
Here is a denser turn for scrolling practice: timeline-scope lifts --chat-N names, view-timeline-name is set on each agent .chat, and indicators stay sticky in .chat-scroll-track while .chat-scroll-body carries the messages.
GA
You - 2:07 PM
Great — last tick should jump to that reply.
AI
Agent - 2:07 PM
Done. Click the last dash to return to this agent response start without moving the page behind the panel.

Bubble Variants

User bubble color variants use soft container tones by default. Add .chat-bubble-filled when a saturated bubble is needed.

Bubble Colors

Default bubble
Primary bubble
Secondary bubble
Tertiary bubble
Info bubble
Success bubble
Warning bubble
Error bubble
Filled primary bubble

Right-To-Left Chat

Set dir="rtl" on the transcript. Agent rows start on the right and user bubbles move to the left; optional avatars follow the same direction.

RTL User And Agent Alignment

AI
المساعد
كيف يمكنني مساعدتك اليوم؟
GA
أنت
أرني مثالاً للمحادثة.

Bubble Sizes

Use user bubble size modifiers for dense history views or larger conversational layouts.

Bubble Sizes

Extra small transcript bubble
Small dense chat bubble
Medium default chat bubble
Large accessible chat bubble

LLM Chat

Put reasoning and tool calls in an agent row, optionally grouping them in .chat-work-body. Streaming tool calls may nest inside .chat-reasoning-body. Put the final answer in a separate .chat-content block so closing work records does not hide it.

Reasoning, Tool Call, and Streaming

AI
Agent - 2:18 PM
Working · 2 tool calls · 0 failed
Thinking (3s)
I should call the weather tool, then summarize the result in one sentence.
get_weather Running...
Call json
{"city":"Tokyo"}
Tool returned cloudy at 18 C. Drafting the final answer.
get_weather Done
Call json
{"city":"Tokyo"}
Result json
{"temperature":"18 C","condition":"cloudy"}
It is 18 C and cloudy in Tokyo right now.

Live States

Use .chat-typing inside .chat-content while waiting for the first token. Add .chat-streaming to .chat-content while message text is still arriving. The existing .chat-bubble-streaming modifier remains a compatibility alias.

Typing and Streaming

AI
AI
Generating a response

Message Status And Actions

Place .chat-status below agent content or a user bubble to show generation state, token speed, and token count. Group each metric in .chat-status-item and emphasize its number with .chat-status-value. Metrics wrap on narrow screens and use tabular numerals.

Use .chat-actions for a row of existing buttons. Add .chat-actions-hover to reveal the actions when the message is hovered or contains keyboard focus. Actions remain visible on devices without hover. Omit the modifier when actions should always be visible.

Use square icon buttons with descriptive aria-label attributes. Pair each button with a native Tooltip through interestfor and aria-describedby to show its action name.

The application supplies status text and metric values and handles each action. The buttons below demonstrate styling; they do not edit, retry, copy, or stop a response.

Token Metrics and Message Actions

GA
You
Summarize the deployment checks.
Sent 12 tokens
AI
Agent · Generating
Checking the build and smoke-test results
Generating 42 token/s 256 tokens
AI
Agent · Completed
The build completed and all deployment smoke tests passed.
Completed 42 token/s 1,248 tokens

Tool Status

Tool blocks use status modifiers so state is visible in both color and text.

Tool Statuses

search_docs Pending
run_query Running...
get_profile Done
deploy_preview Failed

Timeline Approval Requests

Use .chat-approval inside a .chat-agent .chat-content timeline, alongside .chat-tool. The host supplies command, file, and reason children in .chat-approval-details, and sets data-state to pending, approved, approved-for-session, declined, expired, or answer-elsewhere. These are presentation states; Core never resolves a request.

Timeline Approval Request

Run checks
npm test

Allow this command?

Awaiting approval
npm test

Runs the project's test suite in the workspace.

.chat-approval-header contains the title and a text status. .chat-approval-actions keeps host DOM order and wraps responsively; reuse .btn-primary for the primary decision and .btn-error for a danger action. While awaiting a decision acknowledgment, set aria-busy="true" on the request and native disabled on every decision button. An attribute alone does not disable interaction. Keep data-state="pending" until the host confirms the outcome. The following example deliberately has disabled actions.

Decision Awaiting Host Confirmation

Run npm testSending decision…

Resolved and unanswerable examples retain request details in the timeline. Omit actions when no decision is available. answer-elsewhere also hides an accidentally retained action group; provide an explanation of where the user must answer.

Approval Outcomes

Run npm testApproved
npm test

The host accepted this command.

Run npm testApproved for session
npm test

The host accepted this permission for this session.

Run npm testDeclined
npm test

The command will not run.

Run npm testExpired
npm test

This request is no longer valid.

Run npm testAnswer elsewhere
npm test

Respond in the terminal where this command was requested.

Give horizontally scrollable command blocks tabindex="0", role="region", and an accessible name so keyboard users can inspect long commands.

The host owns callbacks, pending enforcement, polite announcements, and focus restoration when actions disappear. Do not autofocus a new request or steal focus from the composer. Use .chat-approval-status[role="status"] for updates, and keep an accessible name on each request and action. Core supplies no networking, permission decisions, or focus scripts.

With Markdown

Use .chat-content.markdown-body directly in the agent row for a rich answer. Agent content handles available width and long text; markdown supplies typography without enclosing the answer in a bubble.

Agent Markdown Answer

AI

Summary: the deployment is ready.

  • Build completed
  • Smoke test passed

For user messages, nest .markdown-body inside .chat-bubble. Prose, links and quotations inherit the bubble foreground in tonal and filled variants; code, keyboard keys and table surfaces keep their matching surface foreground.

User Bubble with Markdown

Please review the deployment summary.

Keep the public API compatible.

console.log("Ready to deploy");

Press Enter to continue.

API Reference

Structure

Class / Attribute Description
.chat-scroll Scrollable transcript (overflow-y: auto, scroll-behavior: smooth, timeline-scope for --chat-1…--chat-24)
.chat-scroll-track Sticky indicator rail (use aria-hidden="true" when indicators are decorative/duplicative)
.chat-scroll-body Message column that holds .chat rows
.chat-scroll-indicator Visually spaced dash with a continuous hover/click area beside adjacent indicators; bind with data-chat-tl="N" + data-chat-target="message-id" (prefer <button>, not hash links)
[data-chat-tl="N"] Shared slot 1–24 on agent .chat rows and their indicators
[data-chat-target] Message id to scroll to inside .chat-scroll (docs demo wires the click handler)
.chat Row wrapper for avatar and message stack
.chat-start Row aligned to the inline start (left in LTR, right in RTL); compose with .chat-agent for agent output
.chat-end User row aligned to the inline end (right in LTR, left in RTL)
.chat-agent Full-width agent row with top-aligned optional avatar; uses one column when the avatar is omitted
.chat-content Transparent unboxed agent answer or progress block; compose with .markdown-body for rich text
.chat-streaming Streaming caret for .chat-content; respects reduced motion
.chat-avatar Optional avatar slot; compose with the existing .avatar component
.chat-header Small muted metadata above the message stack
.chat-footer Small muted metadata below the message stack
.chat-status Wrapping muted status and metrics row below the message body, with tabular numerals
.chat-status-item Inline group for one state label or metric
.chat-status-value Emphasized number within a metric
.chat-actions Always-visible action row; compose with existing button classes
.chat-actions-hover Modifier for .chat-actions; reveals on message hover or keyboard focus and stays visible on devices without hover
.chat-bubble Rounded user message bubble; agent output uses .chat-content
.chat-bubble-content Text slot for a collapsible sent user message
.chat-bubble-collapsible Opt-in sent user bubble; limits its direct .chat-bubble-content child to six rendered lines until expanded
.chat-bubble-toggle Native Show more / Show less button; connect its aria-controls to the content ID and synchronize aria-expanded

Waiting Queue

Class Description
.chat-input-area Structural stack attaching an inset waiting-message tray above the rounded composer
.chat-queue Subdued waiting-message tray above the composer; supports the native hidden attribute
.chat-queue-header Queue heading/count wrapper; use .sr-only for the attached-strip layout
.chat-queue-title Queue heading; use it to name the section with aria-labelledby
.chat-queue-count Optional queue count; keep it visually hidden in the attached strip and announce counts through status text
.chat-queue-list Vertical list with one full-width message per row; use <ol role="list"> and a named keyboard scroll target
.chat-queue-item One unboxed waiting-message row with inline actions; respects hidden
.chat-queue-item-active Next message to dispatch; the application updates this state marker after queue changes
.chat-queue-icon Decorative leading queue glyph
.chat-queue-attachment Optional small image thumbnail; the caller supplies media and alternative text
.chat-queue-number Current ordered position; use .sr-only in the attached-strip layout
.chat-queue-content Single-line message preview; preserve the full text and provide a native title
.chat-queue-actions Queue action group; compose with .chat-actions and existing button classes
.chat-queue-steer Plain Steer action with a curved-arrow icon; compose with .btn.btn-ghost.btn-sm
.chat-queue-remove Remove icon action; compose with a ghost square button and a specific accessible name
.chat-composer Message form or container with a labelled editor and adjacent submission/steering actions; see Composer Parts for optional anatomy
.chat-composer-{primary,secondary,tertiary,info,success,warning,error} Semantic composer color variants; focus treatment follows the chosen color
.chat-composer-ghost Transparent composer border
.chat-composer-input Native borderless textarea that grows with content up to 16rem, then scrolls; no resize handle. .chat-composer-editor adds the same surface for textarea or contenteditable use
.chat-composer-actions Wrapping icon-button action group for Send/Queue and Steer, with accessible names and native Popover descriptions
.chat-composer-hint Compact native <kbd> shortcut hint inside a composer action

Bubble Modifiers

Class Description
.chat-bubble-primary Primary color bubble
.chat-bubble-secondary Secondary color bubble
.chat-bubble-tertiary Tertiary color bubble
.chat-bubble-info Info color bubble
.chat-bubble-success Success color bubble
.chat-bubble-warning Warning color bubble
.chat-bubble-error Error color bubble
.chat-bubble-filled Saturated filled style for color variants
.chat-bubble-xs Extra small bubble
.chat-bubble-sm Small bubble
.chat-bubble-md Medium bubble, explicit alias of the base size
.chat-bubble-lg Large bubble
.chat-bubble-streaming Existing streaming caret modifier; compatibility alias on agent content (prefer .chat-streaming)

LLM Classes

Class Description
.chat-work Native <details> activity disclosure in an agent row; place before an answer or after a progress update
.chat-work-summary Compact native <summary> with application-supplied work labels/counts and a disclosure chevron
.chat-work-body Stack of disclosed work records, reasoning, and tool calls
.chat-reasoning Collapsible reasoning trace using <details> in an agent row or its work body
.chat-reasoning-body Reasoning content stack; may nest streaming .chat-tool blocks
.chat-tool Collapsible tool call block using <details> in an agent row, its work body, or reasoning
.chat-tool-header Summary content for tool name and status text
.chat-tool-call Tool call payload slot
.chat-tool-result Tool result payload slot
.chat-tool-pending Pending tool status
.chat-tool-running Running tool status with activity indicator
.chat-tool-success Successful tool status
.chat-tool-error Failed tool status
.chat-typing Typing indicator dots

Accessibility

  • Use visible text for tool statuses such as Pending, Running..., Done, and Failed.
  • Add aria-label="Agent is typing" to the content that contains .chat-typing, or let the application announce the state through a polite status region.
  • Use native <details> and <summary> for activity, reasoning, and tool records so keyboard interaction works without custom JavaScript. Keep work counts and failures readable as text; keep the final answer outside the disclosure.
  • Use native buttons for message actions, with descriptive accessible names when repeated labels need context. Hover actions reveal when a button receives keyboard focus; they remain visible on touch devices without hover.
  • Keep status and token metrics readable as text. Let the application choose which state changes to announce; avoid announcing every token-count update.
  • Use a native Show more / Show less button for long sent messages, with aria-expanded and aria-controls synchronized to the controlled content. Hide it for six or fewer rendered lines; move focus to the content before hiding a focused toggle after remeasurement.
  • Name the waiting queue and its list. Keep role="list" when list markers are removed, and use tabindex="0" with an accessible name on the scrollable list so keyboard users can scroll it.
  • Give repeated Steer and icon-only Remove buttons names that identify their waiting message. Keep all row actions reachable, including rows after the next message to dispatch. After consuming or removing a focused queue row, move focus to a surviving row action or the message textarea.
  • Announce queue transitions and the waiting count through one polite role="status" region. Avoid announcing the same change through a live transcript as well.
  • Label the native textarea or rich textbox. Show keyboard hints and expose configured shortcuts through aria-keyshortcuts; retain ordinary multiline editing and never dispatch during IME composition. The Waiting Queue demo uses Enter to send and Shift+Enter for a newline; the existing React default uses Enter for a newline. Render user input as text, such as with textContent, instead of interpolating it into HTML.
  • Composer state styling does not implement disabled/read-only semantics, reference selection, or a listbox keyboard model. The host maintains native control attributes, active-descendant relationships, focus restoration, and complete semantic data behind truncated previews. Keep attachment Retry/Remove and queue actions available without hover.
  • Give bounded quote or suggestion content a named tabindex="0" scroll target when it has no keyboard-focusable descendant. A suggestion list with only tabindex="-1" options still needs a reachable scroll target; alternatively, an application-managed roving-focus model keeps its active option keyboard-focusable.
  • .chat-scroll respects prefers-reduced-motion by switching scroll-behavior to auto and disabling indicator animations. Give the scroll container a reachable height. Map ticks only to agent reply starts. Prefer <button data-chat-target> over hash links so navigation stays inside the panel; give each indicator an aria-label.