An open source design system that's fully customizable and agent ready
schema_version: 3 template_version: 7 kind: component id: component:ChatMessageBubble authority: current archive_reason: null superseded_by: null approved_by: cixzhang approved_at: 2026-11-01 owners: [cixzhang] review_triggers: [public-api, behavior, layout, theming, accessibility, testing] verified_by: [ packages/core/src/Chat/ChatMessageBubble.test.tsx, packages/core/src/Chat/tests/ChatMessageBubble.a11y.chromium.spec.ts, apps/storybook/stories/ChatMessageBubble.stories.tsx, apps/storybook/rtl-audit/targets.json, packages/core/src/theme/themingTargets.test.ts, ] modules: [] families: [] design_specs: [] architecture: [ architecture:public-component-api, architecture:component-style-authoring, architecture:component-theming-surface, architecture:theme-tokens, architecture:component-test-sufficiency, architecture:knowledge-contracts, ] contributing: []
system_specs: [spec:AST-029]
ChatMessageBubble component contract
Contract at a glance
| Area | Contract |
|---|---|
| Public contract | Required children; optional variant, name, metadata, group, and width; root div passthrough, styles, and ref. |
| Behavior | The bubble derives sender and density from Chat message context, paints filled or ghost content, groups logical sender-side corners, and keeps renderable scalar name/metadata content inside aligned wrappers. |
| End-user impact | Conversation content reads as sender-aware bubbles; numeric zero stays aligned with its bubble, and slot values that paint nothing leave no empty gap. |
| Builder impact | None. |
| Compatibility/readiness | Records shipped behavior; no public change. No implementation gap; three owner questions stay open. |
| Review checks | Reject a dropped root passthrough/ref, missing target metadata, physical grouped-corner logic, an explicit width that retains the default cap, scalar 0 outside its wrapper, empty scalar wrappers, or a claim that settles the open composite boundary. |
| Governing rules | architecture:public-component-api/INV1, INV5, INV6, INV8–INV9; architecture:component-theming-surface/INV4, INV6–INV8; architecture:component-test-sufficiency/INV1–INV7, INV10–INV11; WCAG 2.2 SC 1.4.10. |
This table is a review projection; the body below is authoritative.
Intent
ChatMessageBubble is the optional sender-aware painted content surface inside a ChatMessage. It gives conversation content a bubble boundary, text inset, grouped-corner treatment, and aligned name/metadata placement that raw message content does not have.
Compatibility and migration
- Released default preserved:
yes - Compatibility class: records shipped behavior; no public change
- Controlled/uncontrolled behavior: not applicable; the component owns no state
- Migration decision: none
Consumer migration instructions belong in consumer docs and release notes.
Ownership boundary
Owns
- The bubble root's fill, text color, typography, radius, padding, wrapping, and width cap.
- Mapping message sender and density context to bubble paint and geometry.
- Grouped corner geometry on the sender side, using logical corners.
- The aligned wrappers around optional
nameandmetadatacontent. - Root DOM passthrough, consumer style composition, and the root ref.
Does not own / non-goals
- Message semantics, sender layout, avatar placement, or message-level names and metadata — owned by ChatMessage or the shared Chat composition surface.
- Timestamp, delivery status, and footer semantics — owned by ChatMessageMetadata.
- The meaning, accessibility, lifetime, or eventual rendered output of caller-supplied React nodes.
- List scrolling, transcript semantics, composer behavior, or system notices — owned by their Chat components.
Public concepts
| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
|---|---|---|---|---|---|---|---|
children |
any ReactNode |
Content rendered inside the bubble root | always | required | caller | stable | n/a — required |
variant |
filled, ghost |
Selects a filled sender-aware boundary or transparent aligned content | always | filled |
component | stable | closed union; rejected by types |
name |
omitted; any ReactNode |
Optional content above the bubble in an aligned wrapper | always | omitted | caller/component wrapper | stable | non-rendering scalars omit; visible scalars including 0 align; see FR7 and OQ1 |
metadata |
omitted; any ReactNode |
Optional content below the bubble in an aligned wrapper | always | omitted | caller/component wrapper | stable | non-rendering scalars omit; visible scalars including 0 align; see FR7 and OQ1 |
group |
omitted, first, middle, last |
Tightens sender-side corners for consecutive bubbles | filled, ghost | omitted | component | stable | omitted keeps full radius; other values rejected by types |
width |
omitted; any SizeValue |
Replaces the default width cap with an explicit width | filled, ghost | omitted | caller | stable | numbers become CSS pixels; strings pass through |
| message context | sender user, assistant, system; density compact, balanced, spacious; absent |
Selects reflected sender/density and corresponding paint and geometry | when nested or standalone | assistant and balanced | Chat context / this projection | observational | absent context uses component fallbacks |
root div |
BaseProps<HTMLDivElement> and ref |
Extends and references the element carrying children, paint, target, and bubble geometry | always | none | architecture:public-component-api |
stable | component target data and consumer styling compose |
chat-message-bubble target |
sender, variant, and density reflected as data-*; exact guaranteed-property set not separately declared in docs |
Public selector for the painting bubble root | always | one target per bubble | architecture:component-theming-surface |
stable | undeclared generic properties remain best effort |
Consumer syntax and prop defaults remain in ChatMessageBubble.doc.mjs.
Behavioral and layout contract
| ID | Invariant | Basis |
|---|---|---|
| FR1 | The component MUST always render one root div for children, including when the caller supplies non-rendering child content. |
Current source and tests |
| FR2 | The root MUST reflect the resolved sender. user selects user paint; assistant, system, and absent context use the non-user paint path; absent context reflects assistant. |
Current source and tests |
| FR3 | The root MUST reflect the resolved density. compact uses the compact radius and inset; balanced is the fallback; spacious uses its wider block and inline inset. |
Current source and tests |
| FR4 | filled MUST paint sender-aware bubble styles; ghost MUST remove the fill and block-axis padding while preserving inline alignment. |
Current source and tests |
| FR5 | first, middle, and last MUST tighten the logical sender-side end, both, and start corner respectively. User uses inline-end; every non-user sender uses inline-start. |
Current source and tests |
| FR6 | Omitted width MUST keep max(80%, 280px). An explicit number or string MUST set width and replace the default cap with none. |
Current source and tests |
| FR7 | name and metadata MUST omit their aligned wrappers for null, undefined, booleans, and the empty string. Visible scalar values, including numeric zero, MUST remain inside their aligned wrappers. Non-scalar React nodes remain opaque. |
Current source and tests |
| FR8 | Root ref, neutral DOM/data/ARIA props, class, style, and xstyle MUST reach or combine on the painting root without losing the component target or owned styles. |
architecture:public-component-api/INV5, INV6, INV8 |
| FR9 | Exactly one chat-message-bubble target MUST ride the painting root and reflect sender, variant, and density. |
architecture:component-theming-surface/INV4, INV6–INV8; public Chat docs |
The public type also admits arrays, Fragments, elements, one-shot iterables, lazy content, and promises. FR7 does not traverse, clone, consume, await, or materialize those values: each remains caller-owned opaque content. Whether any composite or asynchronous category should be normalized is OQ1.
Allowed variation
- AV1 — Theme tokens. Resolved colors, radii, spacing, and typography may vary by theme while the semantic token roles remain.
- AV2 — Caller content. Child, name, and metadata node structure and semantics remain caller-owned.
- AV3 — Absolute geometry. Token-resolved padding and radius may vary; logical sender-side grouping and width precedence do not.
Representative states
| State | Required invariant | Allowed variation |
|---|---|---|
| standalone | assistant sender and balanced density fallback; one painting target | caller content |
| assistant/system, filled | non-user paint; inline-start grouped corners | token-resolved paint |
| user, filled | user paint; inline-end grouped corners | token-resolved paint |
| any sender, ghost | transparent surface; inline inset retained; block inset removed | themed text and padding |
| compact/balanced/spacious | reflected density and corresponding padding/radius path | resolved token scale |
| group first/middle/last | logical sender-side corner sequence in LTR and RTL | token-resolved radii |
numeric slot 0 |
visible zero remains inside the aligned wrapper | none |
| non-rendering scalar slot | null, undefined, booleans, and empty string emit no aligned wrapper | none |
| opaque name/metadata | non-scalar inputs emit wrappers without traversal or materialization | eventual caller-owned React output |
| width omitted/explicit | default cap retained / explicit width replaces cap | valid CSS length |
| narrow/long text | text wraps with no horizontal overflow at 320 CSS px | line breaks and resulting height |
Transformation and precedence order
- ORD1 — Context to paint. Resolve sender/density from the nearest message
context or local fallback, select paint and geometry, then merge component
theme props, StyleX output, and consumer styling inputs through the shared
mergePropscontract. - ORD2 — Width. Apply the default maximum width when omitted; when explicit, set width and replace that cap before consumer styling composition.
- ORD3 — Grouping. Resolve sender side first, then group position, then use logical corner properties so CSS direction mirrors the physical edge.
Performance and resources
- PR1 — Pure render derivation. The component owns no state, Effect, event listener, observer, timer, or animation frame. Every output derives from props and context during render.
- PR2 — Caller content is not inspected. The component does not traverse, clone, consume, await, or materialize caller-supplied React nodes. Whether to preserve that boundary or normalize selected inputs is OQ1.
Accessibility contract
- AR1 — Display surface. ChatMessageBubble adds no widget role, tab stop, keyboard behavior, focus management, announcement, or accessible name of its own. Semantics belong to the enclosing ChatMessage and caller content.
- AR2 — Content preservation. Caller DOM and ARIA passthrough reach the bubble root under FR8; component target metadata MUST NOT overwrite neutral caller ARIA.
- AR3 — Reflow. At a 320 CSS-px parent width, long content and the documented full-width case MUST wrap without horizontal page overflow (WCAG 2.2 SC 1.4.10).
- AR4 — Color. Bubble text remains meaningful content and requires WCAG 2.2 AA text contrast against the final rendered bubble/backdrop in light and dark. The component uses semantic token pairs.
Design relationships
| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
|---|---|---|---|---|
| bubble content | sender-aware filled boundary or aligned ghost surface | unsettled | primary | FR2–FR4 |
| grouped corners | visually connect consecutive bubbles on sender side | unsettled | supporting | FR5 |
| name | align auxiliary content with bubble text inset | unsettled | supporting | FR7 |
| metadata | align auxiliary content with bubble text inset | unsettled | supporting | FR7 |
No authority: current design record owns ChatMessageBubble's local
representation (OQ3). These rows describe shipped appearance; they do not
authorize a redesign.
Family and system relationships
- The shared Chat consumer docs own composition guidance across message, bubble, metadata, list, layout, and composer components.
architecture:public-component-apiowns export, passthrough, styling-input, and ref behavior.architecture:component-theming-surfaceowns the painting target and reflected axes. It does not independently require this closed variant axis to become extensible; that would need a component-level public API decision.architecture:component-test-sufficiencyowns the risk-based evidence inventory.spec:AST-029owns the audit evidence inventory this record's verification map follows.
Verification map
| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
|---|---|---|---|---|
| FR1–FR3 | ChatMessageBubble.test.tsx children, sender, fallback, and compact density tests |
standalone; user and assistant; compact | A missing root, fallback, or reflected axis fails. | audit:ChatMessageBubble/behavior |
| FR4, FR9 | ChatMessageBubble.test.tsx variant and ghost tests; themingTargets.test.ts |
filled; ghost | Dropping reflection, removing the ghost inset entirely, or losing the target fails. | audit:ChatMessageBubble/theming |
| FR5 | ChatMessageBubble.a11y.chromium.spec.ts visible-state and RTL grouped-corner tests |
user and assistant × first, middle, last; LTR and RTL | Physical corner logic or the wrong sender side fails the corner assertions. | audit:ChatMessageBubble/rtl |
| FR6 | ChatMessageBubble.test.tsx width tests |
omitted; string; number | Retaining the cap or changing numeric pixels fails. | audit:ChatMessageBubble/behavior |
| FR7 | ChatMessageBubble.test.tsx slot tests; the Chromium visible-state test's numeric alignment |
zero; true; false; empty string; nullish | A truthiness check loses zero's alignment or restores an empty wrapper. | audit:ChatMessageBubble/behavior |
| FR8, AR2 | ChatMessageBubble.test.tsx "forwards the ref and neutral DOM props to the bubble root" and data-testid test |
ref; DOM, data, and ARIA props | Dropped forwarding fails. | audit:ChatMessageBubble/public-api |
| AR3 | ChatMessageBubble.a11y.chromium.spec.ts "keeps long content inside a 320px fixture" |
320 CSS px | Horizontal overflow fails. | audit:ChatMessageBubble/accessibility |
| AR4 | ChatMessageBubble.a11y.chromium.spec.ts visible-state test's contrast assertion |
light and dark | Bubble text below 4.5:1 fails. | audit:ChatMessageBubble/accessibility |
Read from source, with no focused test yet:
- FR1: rendering one root when
childrenisnull. - FR2: the
systemsender taking the non-user paint path. - FR3: the standalone
balancedfallback, the compact radius, and thespaciousinset. - FR4:
filledpainting the sender fill;ghostremoving the fill and block-axis padding, and its inline alignment matching each density. - FR8:
className,style, andxstylecomposition. - AR1: no role, tab stop, or name of the component's own.
- PR1–PR2: no state or Effect, and no inspection of caller content.
Decision log
No component-local decision is recorded.
Open questions
- OQ1 — Should ChatMessageBubble keep every non-scalar
ReactNodename/metadata value as caller-owned opaque content, or normalize selected arrays, Fragments, one-shot iterables, lazy values, or promises into a stable, rerender-safe empty/non-empty contract? (human-api) - OQ2 — Should the aligned name and metadata wrappers become independently
themeable, inherit a current owner, or remain intentionally unreachable?
(
human-api) - OQ3 — Which current design owner, if any, should make filled/ghost usage and
grouped-corner representation durable?
(
human-design)
Content boundary
This file does not duplicate the consumer prop table/examples, implementation steps, or shared architecture rules. Those remain in
ChatMessageBubble.doc.mjs and their canonical owners.