Components / Feedback

Toast

v2.0 Updated: Feb 17, 2026

일시적인 피드백 메시지를 표시하는 비침습적 알림입니다. 자동 소멸되며, 성공/오류/정보 상태를 지원합니다.

사용법

Toast는 화면 상단 또는 하단에 잠시 나타났다가 자동으로 사라집니다. 기본 3초 후 소멸됩니다.

✓ 찜 목록에 추가했습니다

toast.success('찜 목록에 추가했습니다')
toast.error('네트워크 오류가 발생했습니다')
toast.info('새로운 작품이 등록되었습니다')

HTML

<div style="position:fixed;bottom:24px;left:50%;transform:translateX(-50%);background:var(--charcoal);color:var(--white);padding:10px 20px;font-size:var(--text-sm);font-weight:500;box-shadow:var(--shadow-lg);z-index:9999">
  Toast message here
</div>

상태별 스타일

success(초록), error(빨강), info(파랑) 3가지 상태를 제공합니다.

✓ 찜 목록에 추가했습니다

✕ 네트워크 오류가 발생했습니다

ℹ 새로운 작품이 등록되었습니다

toast.success('메시지')  {/* ✓ 초록 아이콘 */}
toast.error('메시지')    {/* ✕ 빨간 아이콘 */}
toast.info('메시지')     {/* ℹ 파란 아이콘 */}

액션 버튼

Toast에 되돌리기 등 액션 버튼을 추가할 수 있습니다.

찜 목록에서 삭제했습니다

toast.success('찜 목록에서 삭제했습니다', {
  action: { label: '되돌리기', onClick: () => undo() },
  duration: 5000,
})

접근성

속성	값	설명
`role`	`"alert"`	중요 알림으로 스크린 리더에 즉시 전달합니다.
`aria-live`	`"assertive"`	에러 토스트에 적용, polite는 정보 토스트입니다.
`aria-atomic`	`"true"`	전체 메시지를 한 번에 읽습니다.

사용 방법 예시

작품 상세

✓ 찜 목록에 추가했습니다

인터페이스

ToastOptions

속성	필수	기본값	타입	설명
`message`	✓	—	`string`	표시할 메시지 텍스트입니다.
`type`	—	`success`	`success \| error \| info`	토스트 상태입니다.
`duration`	—	`3000`	`number (ms)`	자동 소멸 시간입니다.
`position`	—	`top`	`top \| bottom`	표시 위치입니다.
`action`	—	—	`{ label, onClick }`	액션 버튼 정보입니다.

크기 (Size)

3단계 사이즈 스케일을 지원합니다. 기본값은 md입니다.

SM

✓ 저장됨

MD · 기본

✓ 찜 목록에 추가했습니다

LG

✓ 찜 목록에 추가했습니다

Components / Feedback

Modal

v2.0 Updated: Feb 17, 2026

사용자의 확인이 필요한 대화 상자입니다. Alert(텍스트) / Action Sheet(옵션 목록) / Bottom Sheet(자유 콘텐츠) 3가지 타입을 지원합니다.

사용법

Modal은 오버레이와 함께 표시되며, 배경 클릭 또는 닫기 버튼으로 닫을 수 있습니다.

작품을 삭제할까요?

삭제된 작품은 복구할 수 없습니다.

<Modal type="alert" open={isOpen} onClose={close}>
  <Modal.Title>작품을 삭제할까요?</Modal.Title>
  <Modal.Description>삭제된 작품은 복구할 수 없습니다.</Modal.Description>
  <Modal.Actions>
    <Button variant="weak" onClick={close}>취소</Button>
    <Button color="danger" onClick={handleDelete}>삭제</Button>
  </Modal.Actions>
</Modal>

HTML

<!-- Overlay -->
<div style="position:fixed;inset:0;background:rgba(0,0,0,0.5);z-index:999;display:flex;align-items:center;justify-content:center">
  <!-- Modal Card -->
  <div style="background:var(--bg-card);width:min(90vw,560px);max-height:90vh;overflow-y:auto;box-shadow:var(--shadow-lg)">
    <div style="padding:var(--space-6);border-bottom:1px solid var(--border)">
      <h2 style="font-size:var(--text-lg);font-weight:700;color:var(--charcoal);margin:0">Modal Title</h2>
    </div>
    <div style="padding:var(--space-6)">Content here</div>
    <div style="padding:var(--space-4) var(--space-6);border-top:1px solid var(--border);display:flex;justify-content:flex-end;gap:var(--space-3)">
      <button class="ch-btn ch-btn--ghost">Cancel</button>
      <button class="ch-btn ch-btn--primary">Confirm</button>
    </div>
  </div>
</div>

Alert 타입

화면 중앙에 표시되는 기본 대화 상자입니다. 확인/취소 버튼으로 결정을 유도합니다.

구매 확인

₩ 2,400,000에 구매를 진행합니다.

<Modal type="alert">...</Modal>
{/* 화면 중앙, 최대 너비 280px */}

Action Sheet 타입

화면 하단에서 올라오는 옵션 목록입니다. 여러 액션 중 하나를 선택합니다.

신고하기

삭제하기

취소

<Modal type="actionSheet">
  <Modal.Option onClick={share}>공유하기</Modal.Option>
  <Modal.Option onClick={report}>신고하기</Modal.Option>
  <Modal.Option color="danger" onClick={del}>삭제하기</Modal.Option>
  <Modal.Cancel />
</Modal>

Bottom Sheet 타입

하단에서 올라오는 자유 콘텐츠 컨테이너입니다. 필터, 폼 등 복잡한 UI에 사용합니다.

필터

회화 조각 사진

<Modal type="bottomSheet" height="auto">
  <Modal.Header>필터</Modal.Header>
  <Modal.Content>{children}</Modal.Content>
</Modal>

접근성

속성	값	설명
`role`	`"dialog"`	대화 상자 역할을 명시합니다.
`aria-modal`	`"true"`	모달 컨텍스트임을 표시합니다.
`aria-labelledby`	`"{titleId}"`	제목 요소를 참조합니다.
`focus trap`	—	모달 내부에서만 포커스가 이동합니다.
`Escape`	—	Escape 키로 모달을 닫습니다.

사용 방법 예시

작품 상세

삭제할까요?

복구할 수 없습니다.

인터페이스

ModalProps

속성	필수	기본값	타입	설명
`type`	—	`alert`	`alert \| actionSheet \| bottomSheet`	모달 타입입니다.
`open`	✓	—	`boolean`	모달 표시 상태입니다.
`onClose`	✓	—	`() => void`	닫기 핸들러입니다.
`closable`	—	`true`	`boolean`	배경 클릭으로 닫기 가능 여부입니다.
`children`	✓	—	`ReactNode`	모달 내부 콘텐츠입니다.

크기 (Size)

3단계 사이즈 스케일을 지원합니다. 기본값은 md입니다.

SM

알림

저장되었습니다.

MD · 기본

알림

성공적으로 저장되었습니다.

LG

알림

성공적으로 저장되었습니다.

반응형 (Responsive)

브레이크포인트별 동작 변화입니다.

Mobile · 360px

Title Description text

fullscreen, 100vh

Tablet · 768px

Title

Description

centered, max-w: 480px

Desktop · 1024px

Title

Description text here

centered, max-w: 560px

Components / Feedback

Notification

v2.0 Updated: Feb 17, 2026

CHAART. 전용 알림 리스트 아이템입니다. 거래 알림, 찜 변동, 시스템 공지 등을 유형별로 표시합니다.

사용법

Notification은 아이콘 + 타이틀 + 설명 + 시간 + 읽음 상태로 구성됩니다.

♡

새로운 찜 알림

'빨래터' 작품이 찜 목록에 추가되었습니다.

3분 전

<Notification
  type="wishlist"
  title="새로운 찜 알림"
  description="'빨래터' 작품이 찜 목록에 추가되었습니다."
  time="3분 전"
  isRead={false}
/>

HTML

<div style="display:flex;gap:var(--space-3);padding:var(--space-4);border-bottom:1px solid var(--border);background:rgba(150,30,35,0.02)">
  <div style="width:8px;height:8px;background:var(--red-brand);border-radius:50%;margin-top:6px;flex-shrink:0"></div>
  <div>
    <div style="font-size:var(--text-sm);font-weight:600;color:var(--charcoal)">New notification</div>
    <div style="font-size:var(--text-xs);color:var(--text-muted);margin-top:2px">2 minutes ago</div>
  </div>
</div>

알림 유형

거래(trade), 찜(wishlist), 시스템(system), 이벤트(event) 4가지 유형을 지원합니다.

₩

거래 완료

구매가 확정되었습니다

♡

찜 알림

찜한 작품 가격이 변동되었습니다

ℹ

시스템 공지

서비스 업데이트가 예정되어 있습니다

★

이벤트

신진 작가 할인전이 시작되었습니다

<Notification type="trade" />     {/* ₩ 초록 */}
<Notification type="wishlist" />  {/* ♡ 빨강 */}
<Notification type="system" />   {/* ℹ 파랑 */}
<Notification type="event" />    {/* ★ 주황 */}

읽음/안읽음 상태

안읽음 알림은 배경 하이라이트 + 우측 Red Bean dot으로 구분됩니다.

♡

안읽은 알림

♡

읽은 알림

<Notification isRead={false} />  {/* 배경 하이라이트 + dot */}
<Notification isRead={true} />   {/* 일반 배경 */}

접근성

속성	값	설명
`role`	`"listitem"`	알림 리스트의 한 항목입니다.
`aria-label`	`"{title}: {desc}"`	알림의 전체 내용을 전달합니다.
`aria-current`	`"true"`	안읽음 상태의 알림에 적용됩니다.

사용 방법 예시

알림

₩

거래 완료

'빨래터' 구매가 확정됨

5분 전

♡

찜 변동

찜한 작품 가격 ↓12%

1시간 전

ℹ

시스템 업데이트

v2.0 업데이트 안내

어제

인터페이스

NotificationProps

속성	필수	기본값	타입	설명
`type`	✓	—	`trade \| wishlist \| system \| event`	알림 유형입니다.
`title`	✓	—	`string`	알림 제목입니다.
`description`	—	—	`string`	알림 상세 설명입니다.
`time`	—	—	`string`	시간 표시 텍스트입니다.
`isRead`	—	`false`	`boolean`	읽음 상태입니다.
`onClick`	—	—	`() => void`	알림 클릭 핸들러입니다.

크기 (Size)

3단계 사이즈 스케일을 지원합니다. 기본값은 md입니다.

SM

●

새 매물

작품이 등록되었습니다

MD · 기본

●

새 매물 알림

새로운 작품이 등록되었습니다

LG

●

새 매물 알림

새로운 작품이 등록되었습니다

상태 (States)

Notification 아이템의 인터랙션 상태입니다.

Unread

♡

새 찜 알림

Read

♡

읽은 알림

Hover

♡

새 찜 알림

Components / Feedback

Bottom Info

v1.0 Updated: Feb 17, 2026

화면 하단에 고정되는 정보/경고 메시지 바입니다. 배경색으로 유형(info, warning, error)을 구분합니다.

사용법

Bottom Info는 현재 화면에 관련된 안내 사항이나 경고를 하단에 고정 표시합니다. 사용자의 시선이 자연스럽게 도달하는 위치입니다.

화면 콘텐츠 영역

ℹ 감정서가 필요한 작품입니다

<BottomInfo type="info" message="감정서가 필요한 작품입니다" />

HTML

<div style="position:fixed;bottom:0;left:0;right:0;background:var(--charcoal);color:var(--white);padding:var(--space-3) var(--space-5);font-size:var(--text-xs);display:flex;justify-content:space-between;align-items:center">
  <span>Information bar</span>
  <button style="color:var(--white);background:none;border:none;cursor:pointer;font-size:var(--text-xs)">Close</button>
</div>

Info 타입

일반 안내 메시지를 전달합니다. 파란색 배경으로 표현됩니다.

ℹ 인증 완료된 작품입니다

<BottomInfo type="info" message="인증 완료된 작품입니다" />

Warning / Error 타입

경고는 주황색, 에러는 빨간색 배경으로 긴급도를 구분합니다.

⚠ 결제 기한이 24시간 남았습니다

✕ 결제에 실패하였습니다. 다시 시도해 주세요

<BottomInfo type="warning" message="결제 기한이 24시간 남았습니다" />
<BottomInfo type="error" message="결제에 실패하였습니다. 다시 시도해 주세요" />

접근성

속성	값	설명
`role`	`"status"`	상태 메시지 영역임을 명시합니다.
`aria-live`	`"polite"`	info 타입에 적용됩니다.
`aria-live`	`"assertive"`	error 타입에 적용되어 즉시 알립니다.
`aria-label`	`"{type}: {message}"`	메시지 유형과 내용을 전달합니다.

사용 방법 예시

작품 상세

빨래터

박수근 · 유화 · 45.5 x 38cm

₩12,000,000

⚠ 결제 기한 임박 (12시간 남음)

인터페이스

BottomInfoProps

속성	필수	기본값	타입	설명
`type`	✓	—	`info \| warning \| error`	메시지 유형입니다.
`message`	✓	—	`string`	표시할 메시지 텍스트입니다.
`icon`	—	`자동`	`ReactNode`	커스텀 아이콘입니다. 미지정 시 타입별 기본 아이콘이 사용됩니다.
`dismissible`	—	`false`	`boolean`	닫기 버튼 표시 여부입니다.
`onDismiss`	—	—	`() => void`	닫기 버튼 클릭 핸들러입니다.
`action`	—	—	`{ label: string; onClick: () => void }`	우측 액션 버튼 설정입니다.

Components / Feedback

Bottom Sheet

v1.2 Updated: Mar 09, 2026

하단에서 올라오는 반투명 시트 컴포넌트입니다. 필터, 옵션 선택, 약관 동의, 상세 정보 등을 표시합니다.
애니메이션: var(--dur-medium) · var(--ease-ios-spring) — iOS 네이티브 스프링 커브.
딤 오버레이: rgba(26,26,26,0.45) · var(--dur-slow) · var(--ease-material).
약관 상세: iOS Push Navigation (400ms, --ease-ios-spring) · Exception Case A~F 인터랙티브 테스트 지원.

사용법

Bottom Sheet는 현재 화면 위에 오버레이 형태로 표시되며, 배경 딤 처리와 함께 하단에서 슬라이드업 됩니다.

메인 콘텐츠 영역

작품 필터

유화 수채화 판화 조각

<BottomSheet isOpen={true} onClose={handleClose} title="작품 필터">
  <FilterChips options={["유화", "수채화", "판화", "조각"]} />
</BottomSheet>

HTML

<div style="position:fixed;bottom:0;left:0;right:0;background:var(--bg-card);box-shadow:0 -4px 24px rgba(0,0,0,0.1);z-index:999;max-height:80vh;overflow-y:auto">
  <div style="width:36px;height:4px;background:var(--alpha-16);border-radius:2px;margin:12px auto"></div>
  <div style="padding:var(--space-4) var(--space-6)">
    <h3 style="font-size:var(--text-base);font-weight:700;margin:0 0 var(--space-4)">Sheet Title</h3>
    <p style="font-size:var(--text-sm);color:var(--text-muted)">Content here</p>
  </div>
</div>

핸들 바

상단 핸들 바를 드래그하여 시트의 높이를 조절할 수 있습니다. showHandle prop으로 제어합니다.

핸들 있음

시트 콘텐츠

핸들 없음

시트 콘텐츠

<BottomSheet showHandle={true} />   {/* 드래그 가능 */}
<BottomSheet showHandle={false} />  {/* 고정 높이 */}

풀 스크린

fullScreen 모드는 화면 전체를 차지하며, 상단에 닫기 버튼이 표시됩니다. 복잡한 필터나 설정에 적합합니다.

가격 범위 설정 ×

가격대를 선택하세요

최소 금액

~

최대 금액

100만원 이하 100~500만원 500만원 이상

<BottomSheet fullScreen title="가격 범위 설정" onClose={handleClose}>
  <PriceRangeFilter />
</BottomSheet>

접근성

속성	값	설명
`role`	`"dialog"`	모달 대화상자임을 명시합니다.
`aria-modal`	`"true"`	모달 컨텍스트를 선언합니다.
`aria-labelledby`	`title id`	시트 제목을 참조합니다.
`Escape`	닫기	Esc 키로 시트를 닫을 수 있습니다.

사용 방법 예시

갤러리

작품 목록 영역...

배송 옵션

미술품 전문 배송

직접 수령

인터페이스

BottomSheetProps

속성	필수	기본값	타입	설명
`isOpen`	✓	—	`boolean`	시트 열림 상태입니다.
`onClose`	✓	—	`() => void`	시트 닫기 핸들러입니다.
`title`	—	—	`string`	시트 상단 제목입니다.
`showHandle`	—	`true`	`boolean`	핸들 바 표시 여부입니다.
`fullScreen`	—	`false`	`boolean`	풀 스크린 모드 여부입니다.
`snapPoints`	—	`[0.5]`	`number[]`	스냅 포인트 배열 (0~1)입니다.
`children`	✓	—	`ReactNode`	시트 내부 콘텐츠입니다.

크기 (Size)

3단계 사이즈 스케일을 지원합니다. 기본값은 md입니다.

SM

옵션

MD · 기본

옵션 선택

LG

옵션 선택

상태 (States)

BottomSheet의 인터랙션 상태입니다.

Open

필터

Closed

콘텐츠 영역

Full

전체 필터

Components / Feedback

Bubble

v1.0 Updated: Feb 17, 2026

말풍선형 툴팁/가이드 컴포넌트입니다. 특정 UI 요소를 가리키는 화살표 방향을 지정할 수 있습니다.

사용법

Bubble은 사용자에게 기능 안내, 가이드 메시지, 힌트 등을 전달하는 말풍선입니다. 가리킬 방향(top, bottom, left, right)을 지정합니다.

여기를 눌러 작품을 등록하세요

<Bubble direction="bottom" message="여기를 눌러 작품을 등록하세요" />

HTML

<div style="background:var(--alpha-4);padding:var(--space-3) var(--space-4);border-radius:var(--radius-md);max-width:280px;font-size:var(--text-sm)">
  Chat message bubble content
</div>

방향: top / bottom

화살표가 위 또는 아래를 가리킵니다. 대상 요소의 위치에 따라 선택합니다.

Top (화살표 위)

위쪽 대상을 가리킵니다

Bottom (화살표 아래)

아래쪽 대상을 가리킵니다

<Bubble direction="top" message="위쪽 대상을 가리킵니다" />
<Bubble direction="bottom" message="아래쪽 대상을 가리킵니다" />

방향: left / right

화살표가 좌측 또는 우측을 가리킵니다. 사이드 네비게이션이나 아이콘 옆 가이드에 적합합니다.

Left

좌측 안내

Right

우측 안내

<Bubble direction="left" message="좌측 안내" />
<Bubble direction="right" message="우측 안내" />

접근성

속성	값	설명
`role`	`"tooltip"`	툴팁 역할임을 명시합니다.
`aria-describedby`	대상 요소에 연결	버블이 설명하는 대상 요소를 참조합니다.
`aria-hidden`	`"true"`	장식용 화살표에 적용합니다.

사용 방법 예시

작품 등록

첫 작품을 등록해 보세요

여기를 눌러 작품을 등록하세요

이미지를 드래그하세요

인터페이스

BubbleProps

속성	필수	기본값	타입	설명
`message`	✓	—	`string`	말풍선에 표시할 텍스트입니다.
`direction`	—	`bottom`	`top \| bottom \| left \| right`	화살표 방향입니다.
`variant`	—	`dark`	`dark \| light`	말풍선 색상 테마입니다.
`visible`	—	`true`	`boolean`	말풍선 표시 여부입니다.
`dismissible`	—	`true`	`boolean`	닫기 가능 여부입니다.
`onDismiss`	—	—	`() => void`	닫기 시 호출되는 핸들러입니다.

Components / Feedback

Dialog

v1.0 Updated: Feb 17, 2026

사용자 확인 또는 입력이 필요한 모달 다이얼로그 컴포넌트입니다. 중요한 작업 전 사용자의 명시적 동의를 구하거나 추가 정보를 입력받을 때 사용합니다.

사용법

작품을 삭제하시겠습니까?

이 작업은 되돌릴 수 없습니다. 작품 정보와 관련 데이터가 모두 삭제됩니다.

<Dialog
  open={isOpen}
  title="작품을 삭제하시겠습니까?"
  description="이 작업은 되돌릴 수 없습니다."
  confirmText="삭제"
  cancelText="취소"
  variant="confirm"
  onConfirm={() => handleDelete()}
  onCancel={() => setIsOpen(false)}
/>

HTML

<div style="position:fixed;inset:0;background:rgba(0,0,0,0.5);display:flex;align-items:center;justify-content:center;z-index:999">
  <div style="background:var(--bg-card);padding:var(--space-6);width:min(90vw,400px);text-align:center">
    <h3 style="font-size:var(--text-base);font-weight:700;color:var(--charcoal);margin:0 0 8px">Confirm Action?</h3>
    <p style="font-size:var(--text-sm);color:var(--text-muted);margin:0 0 24px">This cannot be undone.</p>
    <div style="display:flex;gap:var(--space-3);justify-content:center">
      <button class="ch-btn ch-btn--ghost">Cancel</button>
      <button class="ch-btn ch-btn--primary">Confirm</button>
    </div>
  </div>
</div>

변형

Confirm (확인)

변경사항을 저장하시겠습니까?

수정된 내용이 즉시 반영됩니다.

Alert (알림)

업로드 완료

작품 이미지가 성공적으로 업로드되었습니다.

Prompt (입력)

컬렉션 이름

새 컬렉션의 이름을 입력해주세요.

접근성

속성	값	설명
`role`	`dialog`	다이얼로그 역할을 스크린 리더에 전달합니다
`aria-modal`	`true`	모달 상태를 전달하여 배경 요소 접근을 차단합니다
`aria-labelledby`	제목 ID	다이얼로그 제목을 연결합니다
`aria-describedby`	설명 ID	다이얼로그 설명을 연결합니다
키보드	Escape	ESC 키로 다이얼로그를 닫습니다
포커스 트랩	Tab 순환	다이얼로그 내부에서만 포커스가 이동합니다

사용 방법 예시

작품 관리

무제 No.203

김환기

봄의 소리

이우환

작품을 삭제하시겠습니까?

“무제 No.203” 작품이 영구적으로 삭제됩니다. 관련 거래 내역과 이미지도 함께 삭제됩니다.

인터페이스

DialogProps

속성	필수	기본값	타입	설명
`open`	✓	—	`boolean`	다이얼로그 표시 상태
`title`	✓	—	`string`	다이얼로그 제목
`description`		—	`string`	다이얼로그 설명 텍스트
`confirmText`		`"확인"`	`string`	확인 버튼 텍스트
`cancelText`		`"취소"`	`string`	취소 버튼 텍스트
`onConfirm`		—	`() => void`	확인 버튼 클릭 시 콜백
`onCancel`		—	`() => void`	취소 버튼 클릭 시 콜백
`variant`		`"confirm"`	`"confirm" \| "alert" \| "prompt"`	다이얼로그 변형 타입

크기 (Size)

3단계 사이즈 스케일을 지원합니다. 기본값은 md입니다.

SM

삭제

삭제하시겠습니까?

MD · 기본

작품 삭제

이 작업은 되돌릴 수 없습니다.

LG

작품을 삭제하시겠습니까?

이 작업은 되돌릴 수 없습니다.

상태 (States)

Dialog의 변형 상태입니다.

Confirm

삭제하시겠습니까?

취소 삭제

Alert

업로드 완료

확인

Prompt

이름 입력

취소 저장

Components / Feedback

Loader

v1.0 Updated: Feb 17, 2026

콘텐츠 로딩 중임을 시각적으로 알려주는 인디케이터입니다. 스피너, 도트, 프로그레스 바 세 가지 타입을 지원하며 작품 이미지 로딩, 데이터 패칭 등에 활용됩니다.

사용법

기본 로더는 스피너 타입으로 렌더링됩니다. 데이터 요청 중이거나 콘텐츠를 준비할 때 사용합니다.

<Loader />
<Loader type="spinner" label="로딩 중…" />

HTML

<div style="width:24px;height:24px;border:2px solid var(--alpha-12);border-top-color:var(--red-brand);border-radius:50%;animation:spin 0.8s linear infinite"></div>
<!-- Add @keyframes spin { to { transform: rotate(360deg) } } -->

타입

세 가지 로더 타입을 제공합니다. 맥락에 맞는 시각 표현을 선택하세요.

spinner

dots

bar

<Loader type="spinner" />
<Loader type="dots" />
<Loader type="bar" />

사이즈

로더 크기를 small, medium, large로 조절할 수 있습니다.

small

medium

large

<Loader size="small" />
<Loader size="medium" />
<Loader size="large" />

접근성

속성	값	설명
`role`	`status`	로딩 상태를 나타내는 라이브 영역임을 명시합니다
`aria-live`	`"polite"`	상태 변경 시 스크린 리더에 비간섭적으로 알립니다
`aria-label`	`"로딩 중"`	로더의 목적을 설명합니다
`aria-busy`	`true`	콘텐츠가 아직 준비 중임을 표시합니다

사용 방법 예시

갤러리 탐색

작품 이미지 로딩 중…

인터페이스

LoaderProps

속성	기본값	타입	설명
`type`	`"spinner"`	`"spinner" \| "dots" \| "bar"`	로더 시각 유형
`size`	`"medium"`	`"small" \| "medium" \| "large"`	로더 크기
`color`	`"brand"`	`"brand" \| "inherit" \| string`	인디케이터 색상
`label`	—	`string`	로더 아래 표시할 텍스트
`overlay`	`false`	`boolean`	오버레이 배경 사용 여부
`fullScreen`	`false`	`boolean`	전체 화면 로딩 표시 여부

크기 (Size)

3단계 사이즈 스케일을 지원합니다. 기본값은 md입니다.

SM · 16px

MD · 24px

LG · 32px

상태 (States)

Loader는 단일 상태(Loading)를 가집니다. 세 가지 타입의 시각 표현을 비교합니다.

Spinner

Dots

Bar

Components / Feedback

Progress Bar

v1.0 Updated: Feb 17, 2026

진행 상태를 수평 바로 시각적으로 표시하는 컴포넌트입니다. 파일 업로드, 작업 완료율, 단계별 진행 등 다양한 상황에서 사용자에게 현재 진행 상태를 직관적으로 전달합니다.

사용법

기본 Progress Bar는 value와 max 속성을 통해 진행률을 표시합니다. 기본 최대값은 100이며, 퍼센트 라벨을 함께 표시할 수 있습니다.

기본65%

라벨 표시40%

완료100%

<ProgressBar value={65} />
<ProgressBar value={40} showLabel />
<ProgressBar value={100} max={100} color="success" />

HTML

<div style="height:8px;background:var(--alpha-4);border-radius:4px;overflow:hidden">
  <div style="width:65%;height:100%;background:var(--red-brand);border-radius:4px;transition:width var(--dur-slow)"></div>
</div>

크기와 색상

다양한 크기와 색상 옵션을 제공합니다. 크기는 sm, md, lg를 지원하며, 색상은 primary, success, warning, error를 사용할 수 있습니다.

sm (4px)

md (8px) — 기본

lg (12px)

primary

success

warning

error

<ProgressBar value={50} size="sm" />
<ProgressBar value={50} size="md" />
<ProgressBar value={50} size="lg" />
<ProgressBar value={70} color="primary" />
<ProgressBar value={70} color="success" />
<ProgressBar value={70} color="warning" />
<ProgressBar value={70} color="error" />

접근성

속성	값	설명
`role`	`progressbar`	진행 바 역할을 명시합니다
`aria-valuenow`	`{value}`	현재 진행 값을 전달합니다
`aria-valuemin`	`0`	최소값을 전달합니다
`aria-valuemax`	`{max}`	최대값을 전달합니다
`aria-label`	`string`	스크린 리더에 표시할 라벨을 지정합니다

사용 방법 예시

작품 이미지 업로드 시 진행률을 표시하는 예시입니다.

작품 업로드

모란도_2024.jpg

4.2 MB

72%

산수화_원본.png

8.7 MB

✓

세부샷_01.jpg

2.1 MB

대기 중

인터페이스

ProgressBarProps

속성	필수	기본값	타입	설명
`value`	✓	—	`number`	현재 진행 값 (0 이상)
`max`		`100`	`number`	최대값
`color`		`'primary'`	`'primary' \| 'success' \| 'warning' \| 'error'`	진행 바의 색상 테마
`size`		`'md'`	`'sm' \| 'md' \| 'lg'`	진행 바의 높이 크기
`showLabel`		`false`	`boolean`	퍼센트 라벨 표시 여부
`animated`		`false`	`boolean`	애니메이션 활성화 여부

크기 (Size)

3단계 사이즈 스케일을 지원합니다. 기본값은 md입니다.

SM · 4px

MD · 8px

LG · 12px

상태 (States)

ProgressBar의 시각적 상태입니다.

In Progress

Complete

Error

Indeterminate

Components / Feedback

Result

v1.0 Updated: Feb 17, 2026

작업 결과(성공, 실패, 경고, 정보)를 전체 화면 또는 섹션 단위로 표시하는 피드백 컴포넌트입니다. 아이콘, 제목, 설명, 그리고 후속 액션 버튼을 포함하여 사용자에게 명확한 결과를 전달합니다.

사용법

기본 Result는 상태(status)와 제목(title)을 필수로 받습니다. 선택적으로 설명 텍스트와 액션 버튼을 추가할 수 있습니다.

✓

작품이 성공적으로 등록되었습니다

등록된 작품은 관리자 검토 후 24시간 내에 플랫폼에 공개됩니다.

작품 확인

홈으로

<Result
  status="success"
  title="작품이 성공적으로 등록되었습니다"
  description="등록된 작품은 관리자 검토 후 24시간 내에 플랫폼에 공개됩니다."
  primaryAction={{ label: '작품 확인', onClick: handleView }}
  secondaryAction={{ label: '홈으로', onClick: handleHome }}
/>

HTML

<div style="text-align:center;padding:var(--space-12)">
  <div style="font-size:48px;margin-bottom:var(--space-4)">✓</div>
  <h2 style="font-size:var(--text-xl);font-weight:700;color:var(--charcoal);margin:0 0 8px">Success</h2>
  <p style="font-size:var(--text-sm);color:var(--text-muted)">Your action was completed.</p>
</div>

상태 변형

4가지 상태 변형을 지원합니다: success, error, warning, info. 각 상태에 따라 아이콘과 색상이 자동으로 변경됩니다.

✓

성공

작업이 완료되었습니다

✗

실패

작업을 완료할 수 없습니다

경고

주의가 필요합니다

ℹ

정보

참고 정보입니다

<Result status="success" title="성공" description="작업이 완료되었습니다" />
<Result status="error" title="실패" description="작업을 완료할 수 없습니다" />
<Result status="warning" title="경고" description="주의가 필요합니다" />
<Result status="info" title="정보" description="참고 정보입니다" />

접근성

속성	값	설명
`role`	`alert`	결과 메시지가 알림임을 명시합니다
`aria-live`	`assertive`	결과가 즉시 스크린 리더에 전달됩니다
`aria-label`	`string`	결과 상태에 대한 전체 설명을 제공합니다
`role (아이콘)`	`img`	상태 아이콘이 이미지 역할임을 명시합니다

사용 방법 예시

작품 등록이 완료된 후 결과를 표시하는 예시입니다.

작품 등록

✓

작품 등록 완료

김환기 작가의 «무제 #24» 작품이 성공적으로 등록되었습니다.

등록번호: ART-2024-0847

등록 작품 확인

추가 작품 등록

홈으로 돌아가기

인터페이스

ResultProps

속성	필수	기본값	타입	설명
`status`	✓	—	`'success' \| 'error' \| 'warning' \| 'info'`	결과 상태 유형
`title`	✓	—	`string`	결과 제목 텍스트
`description`		—	`string`	결과 설명 텍스트
`icon`		—	`ReactNode`	상태 아이콘을 커스텀으로 지정
`primaryAction`		—	`{ label: string; onClick: () => void }`	주요 액션 버튼 설정
`secondaryAction`		—	`{ label: string; onClick: () => void }`	보조 액션 버튼 설정

Components / Feedback

Skeleton

v1.0 Updated: Feb 17, 2026

콘텐츠 로딩 중 표시하는 플레이스홀더 컴포넌트입니다. 실제 콘텐츠의 레이아웃과 유사한 형태의 회색 블록을 표시하여 사용자에게 로딩 상태를 자연스럽게 전달하고, 체감 로딩 시간을 줄여줍니다.

사용법

기본 Skeleton은 variant 속성으로 형태를 지정합니다. text, circle, rect 3가지 형태를 제공하며, 기본적으로 shimmer 애니메이션이 적용됩니다.

text

circle

rect

<Skeleton variant="text" />
<Skeleton variant="circle" width={40} height={40} />
<Skeleton variant="rect" width="100%" height={120} borderRadius={0} />

HTML

<div style="height:16px;background:linear-gradient(90deg,var(--alpha-4) 25%,var(--alpha-8) 50%,var(--alpha-4) 75%);background-size:200% 100%;animation:shimmer 1.5s infinite;border-radius:var(--radius-xs)"></div>

형태 변형

text, circle, rect 3가지 기본 형태를 조합하여 다양한 로딩 레이아웃을 구성할 수 있습니다. 애니메이션을 비활성화하여 정적 플레이스홀더로 사용할 수도 있습니다.

리스트 아이템 조합

카드 조합

animated: false (정적)

<!-- 리스트 아이템 -->
<div style={{ display: 'flex', gap: 12 }}>
  <Skeleton variant="circle" width={44} height={44} />
  <div>
    <Skeleton variant="text" width="70%" />
    <Skeleton variant="text" width="45%" />
  </div>
</div>

<!-- 카드 -->
<Skeleton variant="rect" width="100%" height={100} />
<Skeleton variant="text" width="80%" />
<Skeleton variant="text" width="50%" />

<!-- 정적 (애니메이션 없음) -->
<Skeleton variant="circle" width={44} height={44} animated={false} />

접근성

속성	값	설명
`role`	`status`	로딩 상태를 나타내는 역할을 명시합니다
`aria-busy`	`true`	콘텐츠가 로딩 중임을 전달합니다
`aria-label`	`"로딩 중"`	스크린 리더에 로딩 상태를 전달합니다
`prefers-reduced-motion`	`reduce`	사용자 접근성 설정 시 애니메이션을 비활성화합니다

사용 방법 예시

작품 카드 목록이 로딩 중인 상태를 표시하는 예시입니다.

작품 갤러리

인터페이스

SkeletonProps

속성	기본값	타입	설명
`variant`	`'text'`	`'text' \| 'circle' \| 'rect'`	스켈레톤의 형태
`width`	`'100%'`	`number \| string`	너비 (px 또는 퍼센트)
`height`	`14`	`number \| string`	높이 (px 또는 퍼센트)
`borderRadius`	`0`	`number`	모서리 둥글기 (기본 0 · 직각)
`animated`	`true`	`boolean`	shimmer 애니메이션 활성화 여부

상태 (States)

Skeleton은 로딩 중 단일 상태를 가지며, 세 가지 형태(text, circle, rect)로 표현됩니다.

Shimmer

Static

Circle

Rect

Components / Feedback

Tooltip

v1.0 Updated: Feb 17, 2026

호버 또는 포커스 시 추가 정보를 표시하는 툴팁 컴포넌트입니다. 간결한 보조 설명이나 레이블을 제공하여 사용자 경험을 향상시킵니다.

사용법

작품 상세 정보 보기

?

<Tooltip content="작품 상세 정보 보기" placement="top">
  <IconButton icon="info" />
</Tooltip>

HTML

<div style="position:relative;display:inline-block">
  <span>Hover target</span>
  <div style="position:absolute;bottom:calc(100% + 8px);left:50%;transform:translateX(-50%);background:var(--charcoal);color:var(--white);padding:6px 12px;font-size:var(--text-xs);white-space:nowrap;pointer-events:none">
    Tooltip text
    <div style="position:absolute;top:100%;left:50%;transform:translateX(-50%);border:4px solid transparent;border-top-color:var(--charcoal)"></div>
  </div>
</div>

위치와 테마

위치 (Placement)

Top

Bottom

Left

Right

테마 (Theme)

Dark 테마

Dark

Light 테마

Light

접근성

속성	값	설명
`role`	`tooltip`	툴팁 역할을 스크린 리더에 전달합니다
`aria-describedby`	툴팁 ID	트리거 요소와 툴팁을 연결합니다
`id`	고유 ID	접근성을 위한 고유 식별자입니다
키보드	Focus / Blur	포커스 시 표시, 블러 시 숨김 처리됩니다
키보드	Escape	ESC 키로 툴팁을 닫을 수 있습니다

사용 방법 예시

작품 상세

□

무제 No.203

김환기 · 1970

감정 완료 작품입니다

?

매체 유화 (캔버스)

크기 130 × 97 cm

컨디션

양호

전문가 감정 기준

₩85,000,000

인터페이스

TooltipProps

속성	필수	기본값	타입	설명
`content`	✓	—	`string`	툴팁에 표시할 텍스트
`placement`		`"top"`	`"top" \| "bottom" \| "left" \| "right"`	툴팁 표시 위치
`theme`		`"dark"`	`"light" \| "dark"`	툴팁 테마
`trigger`		`"hover"`	`"hover" \| "click"`	툴팁 트리거 방식
`delay`		`200`	`number`	표시 지연 시간 (ms)

크기 (Size)

3단계 사이즈 스케일을 지원합니다. 기본값은 md입니다.

SM

작은 툴팁

MD · 기본

기본 크기 툴팁

LG

큰 크기 툴팁

Feedback.

Toast

사용법

상태별 스타일

액션 버튼

접근성

사용 방법 예시

인터페이스

ToastOptions

크기 (Size)

Modal

사용법

Alert 타입

Action Sheet 타입

Bottom Sheet 타입

접근성

사용 방법 예시

인터페이스

ModalProps

크기 (Size)

반응형 (Responsive)

Notification

사용법

알림 유형

읽음/안읽음 상태

접근성

사용 방법 예시

인터페이스

NotificationProps

크기 (Size)

상태 (States)

Bottom Info

사용법

Info 타입

Warning / Error 타입

접근성

사용 방법 예시

인터페이스

BottomInfoProps

Bottom Sheet

사용법

핸들 바

풀 스크린

접근성

사용 방법 예시

인터페이스

BottomSheetProps

크기 (Size)

상태 (States)

Bubble

사용법

방향: top / bottom

방향: left / right

접근성

사용 방법 예시

인터페이스

BubbleProps

Dialog

사용법

변형

접근성

사용 방법 예시

인터페이스

DialogProps

크기 (Size)

상태 (States)

Loader

사용법

타입

사이즈

접근성

사용 방법 예시

인터페이스

LoaderProps

크기 (Size)

상태 (States)

Progress Bar

사용법

크기와 색상

접근성