Playground로 바로 이동
Components

Message File Attachment

메시지에 붙은 파일 하나를 말풍선 바깥의 카드로 표시합니다. 파일 아이콘과 이름, 형식과 크기, 내려받는 동작을 소유합니다.

명세 문서 보기

🚩 Playground

파일 이름과 곁들이 줄, icon과 다운로드 자리를 조합해 카드를 검수합니다. 조작의 초기값은 컴포넌트 API의 기본값과 같으므로 처음에는 icon과 이름만 있는 카드입니다.

메시지_명세.pdf

Content

Format
Size

Elements

Icon
Download

마지막 동작

아직 누르지 않았습니다.

Anatomy

Message File Attachment를 구성하는 실제 요소와 문서에서 사용하는 명칭입니다. Container와 File icon, Name이 필수이고 Meta와 Download action은 선택입니다. File icon 자리는 aria-hidden이며 뜻은 Name과 Meta 글자가 담당합니다.

  1. 1.Container
  2. 2.File icon
  3. 3.Name
  4. 4.Meta(Optional)
  5. 5.Download action(Optional)

Structure map

Message File Attachment
├─ File icon
├─ Name
├─ Meta (Optional)
└─ Download action (Optional)

Properties · Content

파일 이름과 곁들이 줄입니다. format과 size는 넘어온 것만 가운데 점으로 이어 한 줄로 섭니다.

Name만

format과 size를 넘기지 않으면 곁들이 줄이 없습니다. 카드 높이는 icon 자리가 정하므로 그대로입니다.

메시지_명세.pdf

Name · Format · Size

둘을 모두 넘기면 가운데 점으로 잇습니다.

메시지_명세.pdfPDF · 2.4 MB

Format만

하나만 넘기면 점 없이 그 하나만 섭니다.

메시지_명세.pdfPDF

Size만

메시지_명세.pdf2.4 MB

Name · 긴 이름

이름 줄만 말줄임하고 카드 폭과 다른 자리는 움직이지 않습니다.

정산내역_2026년_08월_가맹점별_최종_확정본.xlsxXLSX · 812 KB

className

Container에 덧붙습니다. 폭과 여백, 경계는 지워지지 않습니다.

메시지_명세.pdfPDF · 2.4 MB

Properties · Elements

File icon과 Download action입니다. 두 자리 모두 전달한 값에 따라 모습과 요소가 달라집니다.

Icon · Default

icon을 넘기지 않으면 문서 icon이 섭니다.

메시지_명세.pdfPDF · 2.4 MB

Icon · 전달한 요소

받은 icon도 같은 16px로 섭니다.

매장_사진.pngPNG · 1.1 MB

Download action 없음

download를 넘기지 않으면 그 자리를 그리지 않고 이름 열이 그만큼 넓어집니다.

메시지_명세.pdfPDF · 2.4 MB

Download action · onDownload

callback만 넘기면 button입니다.

메시지_명세.pdfPDF · 2.4 MB

Download action · href

주소를 넘기면 download 속성을 가진 anchor입니다. 겉모습은 button과 같습니다.

메시지_명세.pdfPDF · 2.4 MB

Property map

상위 Property와 현재 허용하는 값을 한 번에 확인합니다.

PropertyValuesDefaultStatus
namestringrequiredConfirmed
formatstringnoneOptional
sizestringnoneOptional
iconReactNodefile iconOptional
download{ label, href?, onDownload? }noneOptional

명세 문서

docs/system/components/message-attachment.md

Message File Attachment

packages/ui/src/message-attachment.tsx

메시지에 붙은 파일 하나를 말풍선 바깥의 카드로 표시한다. 파일 icon, 이름, 형식과 크기 한 줄, 내려받는 action 을 소유한다.

역할과 경계

  • MessageFileAttachment 는 파일 하나의 표시다. 여러 파일은 카드를 여럿 세워 대화 화면이 쌓는다.
  • 파일을 열거나 받아 오지 않는다. 누르면 무엇이 일어나는지는 download 로 받는다.
  • 말풍선 안에 넣지 않고 말풍선 바깥에 같은 방향으로 둔다. 그 배치 규칙은 message-bubble.md의 「파일은 말풍선 바깥에 두기」가 소유한다. 시각과 메시지의 전달 상태도 말풍선이 갖고 이 카드는 갖지 않는다.
  • 카드가 보이는 값은 모두 이 파일 하나의 것이다. 그래서 Property 이름에 file 을 앞에 붙이지 않고 name·format·size 로 받는다. 시각적인 크기 단계가 없으므로 size 가 다른 것을 뜻할 자리도 없다.
  • 크기와 형식의 표기는 화면이 정해서 넘긴다. 컴포넌트는 바이트 수를 받아 「2.4 MB」로 바꾸지 않는다. 「2.4 MB」와 「2,516 KB」 가운데 무엇으로 보일지는 화면의 결정이다.
  • 화면에 보이는 문구와 접근 가능한 이름은 모두 Property 로 받는다. 컴포넌트는 언어를 갖지 않으므로 어느 locale 에서나 같은 코드로 쓴다.
  • 모서리는 interaction.md의 「공통 Control Radius」를 따르지 않는다. 컨트롤과 나란히 놓이는 요소가 아니므로 자기 값 14px 을 쓴다.

Anatomy

  1. Container: 카드 하나의 면이다. 폭과 경계를 소유한다
  2. File icon: 중립 면 위의 파일 icon 이다. 받지 않으면 문서 icon 이다
  3. Name: 파일 이름 한 줄이다. 넘치면 말줄임한다
  4. Meta (Optional): 형식과 크기를 가운데 점으로 이은 한 줄이다
  5. Download action (Optional): 오른쪽의 내려받는 자리다. download 를 넘길 때만 그린다
Message File Attachment
├─ File icon
├─ Name
├─ Meta (Optional)
└─ Download action (Optional)

Properties

  • name: 필수 문자열이다. Name 에 그대로 표시하며 카드 폭을 넘으면 말줄임한다
  • format: 「PDF」처럼 파일 형식을 가리키는 짧은 표기다. Meta 의 앞자리다
  • size: 「2.4 MB」처럼 이미 꼴을 갖춘 파일 크기다. Meta 의 뒷자리다
  • icon: File icon 자리에 서는 요소다. 넘기지 않으면 문서 icon 을 쓴다
  • download: { label, href?, onDownload? }. Download action 이다. 넘기지 않으면 그 자리를 그리지 않는다
    • label: 필수다. Download action 의 접근 가능한 이름이다. 「계약서.pdf 다운로드」처럼 파일 이름을 담은 문장으로 넘긴다
    • href: 주소로 바로 받을 수 있는 파일의 주소다. 넘기면 Download action 이 <a download> 가 된다
    • onDownload: 눌렀을 때다. href 와 함께 넘기면 anchor 의 click 에서도 불린다

색

  • Container: 배경 oe-background-primary, 경계 oe-border-secondary, 글자 oe-foreground-primary
  • File icon 자리: 배경 oe-background-secondary, icon oe-foreground-secondary
  • Name: oe-foreground-primary
  • Meta: oe-foreground-tertiary
  • Download action: icon 은 oe-foreground-tertiary 이고 hover 에서 oe-foreground-primary 로 올라간다. hover 면은 공용 hover 겹이다
  • Focus ring: 2px oe-focus-ring

카드는 상태를 뜻하지 않으므로 어느 자리에도 brand·status 색을 쓰지 않는다.

폭과 경계

  • 카드 폭은 224px 로 고정이고 담는 폭이 그보다 좁으면 그 폭까지 줄어든다. 좌우 어느 방향에 놓여도 같은 폭으로 서서 연속된 파일 카드의 변이 어긋나지 않는다.
  • 경계는 1px 선이지만 폭을 차지하지 않는 겹으로 그린다. 카드가 224px 바깥으로 1px 씩 자라 말풍선과 변이 어긋나는 것을 막는다.
  • 긴 파일 이름은 Name 한 줄만 말줄임한다. 카드를 늘리지 않고 Meta 와 Download action 의 자리도 움직이지 않는다.
  • Meta 는 format 과 size 가운데 넘어온 것만 그린다. 둘 다 넘기면 가운데 점으로 잇고, 하나만 넘기면 점 없이 그 하나만 선다. 둘 다 없으면 Meta 줄 자체가 없다. 카드 높이는 그래도 달라지지 않는다 — 높이를 정하는 것은 글자가 아니라 36px icon 자리이고, Name 한 줄만 그 가운데에 선다.

Download action

  • download 를 넘기지 않으면 자리를 그리지 않는다. 받을 수 없는 파일에 눌리지 않는 button 을 남기지 않는다.
  • href 를 넘기면 <a download> 로, onDownload 만 넘기면 <button type="button"> 으로 그린다. 둘의 겉모습은 같다.
  • 주소로 바로 받을 수 있는 파일에는 href 를 쓴다. anchor 여야 가운데 클릭과 「다른 이름으로 저장」이 살아 있다. download 속성은 같은 출처의 주소에만 걸린다.
  • 토큰을 붙여 받아 와야 하는 파일, 받기 전에 확인을 받아야 하는 파일에는 onDownload 를 쓴다.
  • Download action 은 icon 하나이고 글자를 두지 않는다. 뜻은 download.label 이 aria-label 로 담당한다.

Behavior

  • File icon 자리는 aria-hidden 이다. 뜻은 Name 과 Meta 글자가 담당하므로 받은 icon 이든 기본 icon 이든 화면 낭독기가 읽지 않는다.
  • File icon 은 받은 것이든 기본 것이든 16px 로 선다. 크기를 icon 이 아니라 자리가 걸어 36px 자리의 가운데가 흔들리지 않는다.
  • Download action 은 focus-visible 에서 2px oe-focus-ring 을 갖는다.
  • 뿌리는 data-slot="message-attachment" 를 갖고, 조각은 message-attachment-icon·message-attachment-name·message-attachment-meta·message-attachment-download 다.
  • className 은 Container 에 붙는다. 폭과 여백, 경계를 지우지 않고 덧붙으며 같은 축의 값만 덮는다.

Guidelines

말풍선 바깥에 같은 방향으로 두기

  • 파일은 말풍선의 Content 에 넣지 않고 말풍선 아래 같은 방향에 둔다. Incoming 에서는 Avatar 자리만큼 들여 Content 의 시작점에 맞춘다.
  • 시각은 카드 아래 한 줄에 대화 화면이 둔다. 카드는 시각을 갖지 않는다.

형식과 크기를 나눠 넘기기

  • 가운데 점은 컴포넌트가 이어 붙인다. 화면마다 구분 기호를 다시 적지 않는다.
  • 파일 이름에 확장자가 있어도 format 을 함께 넘긴다. 이름이 말줄임되면 확장자가 먼저 사라지므로 형식은 Meta 가 지킨다.
  • 크기를 모르는 파일은 size 를 넘기지 않는다. 「알 수 없음」 같은 문구를 넣지 않는다.

받을 수 있을 때만 Download action 을 두기

  • 지워진 파일, 권한이 없는 파일에는 download 를 넘기지 않는다. 눌러도 되지 않는 button 을 보이지 않는다.
  • download.label 에 파일 이름을 담는다. 카드가 여럿 쌓인 대화에서 「다운로드」만으로는 어느 파일인지 갈리지 않는다.

형식마다 icon 을 바꿀 때 바깥에서 고르기

  • 형식에 따라 icon 을 가르는 표는 컴포넌트가 갖지 않는다. 쓰는 화면이 icon 으로 넘긴다.
  • 그림 파일에도 이 카드를 쓴다. 썸네일로 보이는 길은 아직 없다.

Specification

자리 값
Container 폭 224px, 담는 폭이 좁으면 그 폭까지
Container 모서리 14px
Container 경계 1px, 폭을 차지하지 않는 겹
Container 안쪽 여백 10px
조각 사이 간격 8px
File icon 자리 36px 정사각, 모서리 10px
File icon 16px
Name 12px Medium, line-height 16px
Meta 11px, line-height 16.5px
Download action 32px(icon 16px + 여백 8px), 모서리 10px
카드 높이 56px. icon 자리 36px 과 위아래 여백 10px 이 정하므로 Meta 가 없어도 같다

현재 정의하지 않은 항목

  • 여러 파일을 한 카드에 담는 길을 두지 않았다. 파일 하나가 카드 하나이며 묶음을 알리는 표시가 없다.
  • 올리는 중의 진행률을 두지 않았다. 카드는 다 올라간 파일만 보인다.
  • 미리보기 썸네일을 두지 않았다. 그림 파일도 icon 과 이름으로 보인다.
  • 형식에 따른 icon 표를 두지 않았다. 형식의 목록은 제품이 정하므로 icon 으로 받는다.
  • 파일을 눌러 여는 길을 두지 않았다. 카드 전체는 누르는 자리가 아니고 Download action 하나만 누른다.
  • 지우는 action 을 두지 않았다. 보낸 파일을 거두는 것은 메시지를 삭제하는 것이며 그 규칙은 message-bubble.md가 소유한다.
  • 받을 수 없는 파일의 표시를 두지 않았다. 지워진 파일이나 권한이 없는 파일을 알리는 상태가 없다.