Message Bubble
대화 화면에서 메시지 하나를 발신·수신 방향에 맞춘 말풍선으로 표시합니다. 작성자, 시간, 전달 상태, 읽지 않은 수와 메시지 action을 함께 갖습니다.
통합 채팅 예시
확정한 요소가 실제 대화 흐름에서 함께 작동하는지 확인합니다. 날짜는 Studio 검수용으로 눌러 예시를 변경할 수 있습니다.
10:05
Playground
방향, avatar, 콘텐츠 길이를 바꿔 기본 레이아웃을 검수합니다.
Conversation states
Typing indicator는 MessageBubble과 분리된 thread 상태입니다.
Delivery states
발신 메시지의 전송 상태를 한 번에 비교합니다.
전송 중
전송됨
모두 읽음
전송 실패
읽음 처리
대화를 자동으로 읽음 처리할지, 답장하거나 버튼을 눌렀을 때 처리할지 비교합니다.
채팅 테마
상위 화면 모드와 독립적으로 중립 및 브랜드 채팅방의 라이트·다크 조합을 검수합니다.
파일 첨부
파일은 말풍선에 포함하지 않고 독립된 첨부 요소로 표시합니다. 이미지 사례는 현재 검수 범위에서 제외합니다.
10:10
명세 문서
docs/system/components/message-bubble.md
Message Bubble
packages/ui/src/message-bubble.tsx
대화 화면에서 메시지 하나를 발신·수신 방향에 맞춘 말풍선으로 표시한다. 작성자, 시간, 전달 상태, 읽지 않은 수와 메시지 action 을 함께 소유한다.
역할과 경계
MessageBubble은 메시지 하나의 표시다. 대화 전체의 순서, 날짜 구분선, 읽지 않은 메시지의 경계(unread boundary)와 읽음 처리 action 은 conversation-level 동작이므로 대화 화면이 그린다. 컴포넌트는 그 결과를unreadMessageCount와unreadRecipientCount로 받아 Bubble 옆에 숫자로만 표시한다.TypingIndicator는 같은 파일이 내보내는 별도 컴포넌트다. 기존 메시지의 상태가 아니라 상대방이 새 메시지를 작성 중인 thread 상태이므로MessageBubble의 Property 로 두지 않는다.- 파일은
MessageBubble의 Content 에 넣지 않고 말풍선 바깥의 독립된MessageFileAttachment로 표시한다. 메시지 입력은MessageComposer가 담당한다. 둘은 아직초안이며 이 문서는 그 규칙을 소유하지 않는다. - 화면에 보이는 문구와 접근 가능한 이름은 모두 Property 로 받는다. 컴포넌트는 언어를 갖지 않으므로 어느 locale 에서나 같은 코드로 쓴다.
- 모서리는 interaction.md의 「공통 Control Radius」를 따르지 않는다. 컨트롤과 나란히 놓이는 요소가 아니므로 자기 값 16px 을 쓴다.
- 전달 상태에서
sent와delivered를 구분하지 않고sent하나만 쓴다. 상대가 읽었는지는unreadRecipientCount가 말한다.
Anatomy
- Avatar (Optional): 작성자 initials 를 담은 32px 원이다. Incoming 에서만 그린다
- Author: Bubble 위의 작성자 이름이다. Incoming 에서만 그린다
- Bubble: Content 를 담는 채움 면이다
- Content: 메시지 본문(
children)이다 - Sidecar (Optional): Bubble 옆 바깥 아래의 자리다. 읽지 않은 수, 모두 읽음 icon, 전송 실패 표시와 Action bar 가 이 한 자리를 나눠 쓴다
- Metadata row: Bubble 아래의 한 줄이다. Outgoing 의 Sender label (Optional), 시간, 전달 상태와 전송 실패 action 이 놓인다
- Action bar (Optional): hover 또는 keyboard focus 에서 Sidecar 자리에 나타나는 복사·삭제 button 이다
Message Bubble
├─ Avatar (Optional)
├─ Author
├─ Bubble
│ └─ Content
├─ Sidecar (Optional)
│ ├─ Unread count · Read icon · Failed mark
│ └─ Action bar (Optional)
└─ Metadata row
├─ Sender label (Optional)
├─ Time
├─ Delivery state
└─ Failed actions (Optional)
Incoming 은 왼쪽에서 Avatar → Author → Bubble 순으로 시작하고 Sidecar 를 Bubble 오른쪽에 둔다. Outgoing 은 오른쪽에서 Bubble 만으로 시작하고 Sidecar 를 Bubble 왼쪽에 둔다.
Properties
direction:incoming | outgoing. 필수다. Incoming 은 상대가 보낸 메시지, Outgoing 은 현재 사용자가 보낸 메시지다author,initials,time: 필수 문자열이다.author는 Incoming 의 Author 에,initials는 Avatar 에 쓰고,time은 Metadata row 에 그대로 표시한다. 시각의 형식은 화면이 정해서 넘긴다children: Content 다deliveryState:sending | sent | read | failed. 넘기지 않으면 전달 상태를 그리지 않는다. Outgoing 에 쓴다deliveryCopy:Record<MessageDeliveryState, string>. 네 상태의 표시 문구이자 접근 가능한 이름이다.deliveryState를 넘겨도 이것이 없으면 전달 상태를 그리지 않는다unreadRecipientCount:number. Outgoing 에서 아직 읽지 않은 참여자 수다. 1 이상이면 Sidecar 에 숫자로,0이면read와 함께 모두 읽음 icon 으로 표시한다. 넘기면(0포함) Metadata row 에는 전달 상태(icon 과failed문구)를 그리지 않는다unreadRecipientLabel: 그 숫자의 접근 가능한 이름이다. 「아직 읽지 않은 참여자 3명」처럼 수를 담은 문장으로 넘긴다unreadMessageCount:number. Incoming 에서 현재 사용자가 아직 읽지 않은 새 메시지 수다. 1 이상이면 Sidecar 에 숫자로 표시하며 최신 Incoming 하나에만 넘긴다unreadMessageLabel: 그 숫자의 접근 가능한 이름이다deleted:false | true, 기본값false. 삭제된 메시지다deletedLabel: 삭제 안내 문구다.deleted와 함께 넘긴다showDeletedContent:false | true, 기본값은 방향에 따른다. Outgoing 은true로 원문을 보존하고 Incoming 은false로 원문을 숨긴다showAvatar:false | true, 기본값true. Incoming 에서만 뜻을 가진다grouped:false | true, 기본값false. 같은 발신자의 연속 메시지 가운데 첫 메시지가 아닌 것이다. Avatar 와 Author 를 생략하고 Content 만 정렬한다showTime:false | true, 기본값은grouped의 반대다. Metadata row 전체의 표시 여부다. 연속 메시지의 첫 메시지는false로 감추고, 마지막 메시지는grouped여도true로 켠다outgoingSenderLabel: Outgoing 의 Sender label 이다. 다중 관리자 화면에서 「소속팀 이름」 꼴로 넘기며 컴포넌트가 뒤에·와 시간을 이어 붙인다outgoingSenderDescription: Sender label 앞의 Info trigger 가 여는 설명이다. 넘길 때만 trigger 를 그리며 trigger 의 접근 가능한 이름으로도 쓴다actions:{ copyLabel, deleteLabel, onCopy?, onDelete? }. hover·focus 에 나타나는 Action bar 다. Incoming 은 복사만, Outgoing 은 복사와 삭제를 그린다failedActions:{ retryLabel, deleteLabel, onRetry?, onDelete? }.failed인 Outgoing 의 Metadata row 가 보일 때 hover 없이 항상 보이는 재전송·삭제 button 이다
TypingIndicator
initials: Avatar 의 initials 다label:role="status"의 접근 가능한 이름이다. 「○○님이 작성 중입니다」처럼 문장으로 넘긴다showAvatar: 기본값trueclassName: Bubble 열을 감싸는 바깥 요소에 붙는다. 색·모양 규칙은 바꾸지 않는 자리다
색
- Incoming Bubble: 배경
oe-background-secondary, 글자oe-foreground-primary - Outgoing Bubble: 배경
oe-background-bold-primary, 글자oe-foreground-inverse - Avatar: 배경
oe-background-secondary, initialsoe-foreground-secondary - Author:
oe-foreground-primary - Metadata row:
oe-foreground-tertiary. Sender label 만oe-foreground-secondary다 - Sidecar 의 숫자와 모두 읽음 icon:
oe-foreground-tertiary - 전송 실패: Metadata row 의 문구는
oe-danger-foreground-primary, Sidecar 의!는oe-danger-foreground-primary원 위의oe-foreground-inverse - Action bar: 배경
oe-background-primary, 경계oe-border-secondary. icon 은oe-foreground-tertiary이고 hover 에서oe-foreground-primary로 올라간다. 삭제 icon 의 hover 는oe-danger-background-primary위의oe-danger-foreground-primary다 - Deleted Incoming: 배경
oe-background-secondary, 글자oe-foreground-secondary - Deleted Outgoing: 배경
oe-background-bold-primary, 원문oe-foreground-inverse-secondary, 안내 문구oe-foreground-inverse - Typing indicator: 배경
oe-background-secondary, 점oe-foreground-tertiary - Focus ring: 2px
oe-focus-ring
Bubble 의 배경·글자·경계는 Tailwind class 가 아니라 packages/ui/src/styles.css 의 .oe-message-bubble-incoming 과 .oe-message-bubble-outgoing 이 칠한다. 두 class 는 --oe-message-incoming-background·--oe-message-incoming-foreground·--oe-message-incoming-border 와 같은 꼴의 --oe-message-outgoing-* 변수를 먼저 읽고, 없으면 위 token 을 쓴다. 채팅방마다 다른 브랜드 색을 쓰는 화면은 이 변수만 덮어쓴다. 경계의 기본값은 투명이다.
방향과 grouping
- Incoming 은 왼쪽에서 Avatar → Author → Bubble 순으로 시작하고, Outgoing 은 오른쪽에서 Bubble 만으로 시작한다. Metadata row 도 각 방향의 시작 변에 맞춘다.
- Outgoing 은 방향만으로 현재 사용자의 메시지임을 알 수 있으므로 Author 와 Avatar 를 그리지 않는다.
author와initials는 받지만 화면에 쓰지 않으며, 「나」 나 사용자 이름을 반복 표시하지 않는다. - Author 는 Bubble 위에 두고, 시간과 전달 상태는 Bubble 채움에 넣지 않고 아래 Metadata row 에 둔다.
- 같은 발신자의 연속 메시지가 분 단위까지 같은 시각이면 첫 메시지에만 Author·Avatar 를, 마지막 메시지에만 Metadata row 를 둔다. 첫 메시지는
showTime={false}, 중간은grouped, 마지막은grouped showTime으로 넘긴다.groupedIncoming 은 Avatar 자리만큼 44px 들여 Content 의 왼쪽 시작점을 맞춘다. - Bubble 과 Sidecar 를 담는 열은 담는 폭의 82% 를 넘지 않으며
sm이상에서는 72% 다. Bubble 은 그 안에서 Sidecar 를 뺀 폭이다. - 루트 요소는
data-direction을 갖는다. 대화 화면은 메시지 목록에oe-conversation-stackclass 를 붙여 마지막이 아닌 Outgoing 아래에 20px 을 더 띄운다. Sender label 이 있는 Metadata row 가 다음 메시지와 붙지 않게 하려는 것이다. - Metadata row 는 Sender label 과 Info trigger 의 유무와 관계없이 같은 최소 높이 20px 을 유지해 1:1 과 다중 관리자 화면을 오갈 때 메시지 간격이 움직이지 않는다. Info trigger 의 click 영역에 자체 여백이 있으므로 trigger 와 Sender label 사이에는 gap 을 두지 않는다.
전달 상태와 읽지 않은 수
sending은 시계,sent는 체크 하나,read는 체크 두 개 icon 이다.failed는 icon 없이deliveryCopy.failed문구를 danger 색으로 남긴다. 어느 상태든 접근 가능한 이름은deliveryCopy의 문구다.unreadRecipientCount를 넘기지 않은 Outgoing 은 전달 상태를 Metadata row 의 시간 옆 12px icon 으로 그린다. 1:1 대화가 여기에 해당한다.- 그룹 대화의 Outgoing 은
unreadRecipientCount를 항상 넘긴다(모두 읽었으면0). 그러면 전달 상태 표시는 Sidecar 가 담당하고 Metadata row 에는 전달 상태(icon 과failed문구)를 두지 않는다. 아직 읽지 않은 참여자가 있으면 Sidecar 에 그 수를 숫자로 표시하고,read이고0이면 같은 자리에 체크 두 개 icon 을 표시한다. 모두 읽으면 숫자는 사라진다. - 전송 실패는 Sidecar 자리에
oe-danger-foreground-primary원 위의!를 표시한다.unreadRecipientCount를 넘기지 않은 Outgoing 은 Metadata row 의deliveryCopy.failed문구도 함께 남긴다. - Outgoing 의 Sidecar 는 Bubble 의 바깥 왼쪽 아래, Incoming 의 Sidecar 는 바깥 오른쪽 아래다. Outgoing 의 숫자는 읽지 않은 상대의 수, Incoming 의 숫자는 현재 사용자의 미확인 메시지 수로 뜻이 다르다.
unreadMessageCount는 unread boundary 뒤의 최신 Incoming 하나에만 넘긴다. 이전에 읽은 메시지에는 넘기지 않는다.
메시지 action
- Action bar 는 기본 상태에서 시각적으로 숨기고(
opacity: 0, pointer 무시) 루트의 hover 또는 내부 keyboard focus(focus-within)에서 나타난다. - Action bar 는 그림자 없이 Bubble 바깥의 Sidecar 자리에 놓이고 Bubble 하단선에 맞춘다. Content 영역과 배경색을 침범하지 않는다. 읽지 않은 수 숫자와 같은 자리에 겹쳐 나타나며 그동안 숫자를 가린다.
- Incoming 은 상대가 보낸 콘텐츠이므로 복사만 제공하고 삭제를 제공하지 않는다.
actions.deleteLabel과onDelete를 넘겨도 Incoming 에는 그리지 않는다. - Outgoing 은 복사와 삭제를 제공한다.
- 전송 실패는 사용자가 해결해야 하는 오류이므로 재전송·삭제 action 을 hover 에 숨기지 않는다. 두 action 은
deliveryCopy.failed문구 바로 오른쪽에 항상 보이며 모바일에서도 같은 자리에서 발견된다. 실패한 메시지에는 hover·focus Action bar 를 그리지 않는다. - 삭제된 메시지에는 Sidecar 를 만들지 않으므로 어떤 action 도 노출하지 않는다.
- 각 action button 은 Tooltip 으로 이름을 보이고 같은 문구를
aria-label로 갖는다. Tooltip 은 button 아래 가운데에 열리며 viewport 에 부딪히면 flip·shift 한다.
삭제 상태
deleted는 Bubble 안 첫 줄에 Info icon 과deletedLabel을 두고, 원문의 표시는showDeletedContent가 정한다.- Incoming 은 기본값으로 원문을 숨기고 안내 문구만 남긴다.
- Outgoing 은 발신 방향을 알 수 있도록 Outgoing 배경을 유지하고 원문을
oe-foreground-inverse-secondary로 보존한다. 별도 opacity 를 얹지 않으며showDeletedContent={false}로 원문을 숨길 수 있다. - 점선 경계를 쓰지 않고 추가 action 도 노출하지 않는다.
다중 관리자의 Sender label
- 1:1 대화의 Outgoing 은 발신자를 표시하지 않는다.
- 여러 관리자가 같은 사용자와 채팅하는 관리자 화면에서는 Metadata row 의 시간 왼쪽에
outgoingSenderLabel을 「소속팀 이름 · 시간」 꼴로 표시한다. outgoingSenderDescription을 함께 넘기면 Sender label 앞에 12px Info icon 의 trigger 를 두고, 누르면 그 설명을 Popover 로 보인다. Popover 는top-end에 열리며 viewport 와 clipping boundary 에 부딪히면 flip·shift 한다. 설명이 없으면 trigger 도 없다.- 이 이름은 관리자 사이의 구분을 위한 내부 정보다. 사용자 화면이나 사용자에게 전달되는 메시지 payload 에는 절대 노출하지 않는다.
Behavior
- Avatar 와 모든 icon 은
aria-hidden이다. 뜻은 문구 Property 가 담당한다. 숫자는unreadRecipientLabel·unreadMessageLabel, 전달 상태는deliveryCopy, action 은 각 label 이다. - 전달 상태 icon 은
aria-label과title을 함께 갖고sr-only문구를 담아 hover 와 screen reader 모두에서 읽힌다. - Action bar 의 button 은
focus-visible에서 2pxoe-focus-ring을 갖고, Tab 으로 들어오면 bar 가 나타난다. TypingIndicator는role="status"와label을 갖는다. 점 세 개는 160ms 간격으로 pulse 하며prefers-reduced-motion에서는 멈춘다.
Guidelines
Outgoing 에는 작성자와 avatar 를 두지 않기
- 방향만으로 현재 사용자의 메시지임이 읽히므로 Author 와 Avatar 를 두지 않는다. 컴포넌트가 이미 그리지 않으며, 화면이 바깥에 따로 그려 반복하지도 않는다.
- Incoming 은
showAvatar로 Avatar 를 끌 수 있다. 참여자가 둘뿐인 1:1 대화처럼 얼굴을 구분할 이유가 없는 자리가 여기에 해당한다.
Sender label 은 다중 관리자 화면에서만 넘기기
outgoingSenderLabel과outgoingSenderDescription은 여러 관리자가 같은 사용자를 상대하는 관리자 화면에서만 넘긴다. 1:1 대화와 사용자 화면에는 넘기지 않는다.- 이 값은 사용자에게 가는 payload 에 담지 않는다.
전달 상태는 Outgoing 에만 넘기기
deliveryState·deliveryCopy·failedActions·unreadRecipientCount는 현재 사용자가 보낸 메시지의 상태다. Incoming 에는 넘기지 않는다.- Incoming 이 갖는 숫자는
unreadMessageCount하나다.
읽음 처리는 대화 단위로 두기
- 대화의 읽음 상태와 읽음 처리 action 은 메시지마다 반복하지 않고 현재 대화의 마지막 메시지 아래에만 둔다.
- 수동 읽음 처리 action 은 hover action 이 아니며 읽지 않은 상태에서 항상 보인다. 그 안의 Info icon 은 hover 에서 답장으로도 읽음 처리된다는 것을 안내하고, tooltip 은
top-end에 두며 부딪히면 flip·shift 한다. - 수동 방식은 명시적인 읽음 처리 또는 답장 완료에 대화를 읽음으로 바꾸고, 자동 방식은 대화를 확인한 시점에 읽음으로 처리한다.
- 수동 방식의 미확인 메시지는 개별 Bubble 에 badge 를 반복하지 않고, 마지막으로 읽은 메시지와 새 메시지 사이에 unread boundary 와 개수를 둔다. boundary 뒤의 최신 Incoming 하나에만
unreadMessageCount를 넘겨 같은 개수를 Sidecar 에 보인다. - 읽음 처리 또는 답장 뒤에는 unread boundary, 읽음 처리 action 과 Sidecar 의 숫자가 함께 사라진다.
파일은 말풍선 바깥에 두기
- 파일은 Content 에 넣지 않고 Bubble 아래 같은 방향에
MessageFileAttachment로 둔다. Incoming 에서는 Avatar 자리만큼 들여 Content 의 시작점에 맞춘다.
모든 action 을 상시 펼치지 않기
- Desktop 에서는 hover·focus 의 contextual action 만 쓴다. 전송 실패의 재전송·삭제만 항상 보이는 예외다.
Specification
| 자리 | 값 |
|---|---|
| Bubble 모서리 | 16px |
| Bubble 안쪽 여백 | 좌우 14px, 위아래 8px |
| Bubble 과 Sidecar 를 담는 열의 최대 폭 | 82%, sm 이상 72% |
| Content 글자 | 14px, line-height 1.625 |
| Avatar | 32px 원, initials 11px Medium |
| Avatar 와 본문 열 사이 | 12px |
grouped Incoming 들여쓰기 |
44px |
| Author | text-oe-label 13px/16px Semibold |
| Metadata row | 12px, 최소 높이 20px, Bubble 과 4px |
| 전달 상태 icon | 12px |
| Sidecar | 최소 32×32px, Bubble 과 6px |
| Sidecar 의 모두 읽음 icon·실패 표시 | 14px |
| Action bar | 모서리 8px, 안쪽 여백 2px, 1px 경계 |
| Action button | 26px(icon 14px + 여백 6px), 모서리 6px |
| Info trigger | 20px, icon 12px |
| Sender description Popover | 최대 폭 288px, top-end, 6px 띄움 |
| Typing indicator | 높이 40px, 좌우 16px, 모서리 16px, 점 6px 셋, 간격 4px |
oe-conversation-stack 의 Outgoing 아래 간격 |
20px |
현재 정의하지 않은 항목
- Mobile 의 contextual action 방식을 정하지 않았다. Desktop 은 hover·focus 이며, 전송 실패 action 만 어느 기기에서나 항상 보인다.
- 브랜드 채팅 테마의 값을 정하지 않았다.
--oe-message-*변수 자리만 두고 기본값은 위 「색」의 token 이다. - 말줄임을 두지 않았다. 긴 메시지는 그대로 줄바꿈된다.