본문으로 건너뛰기
Dot Design System
v0.3.1

SectionCard

독립 표면이 필요한 섹션을 제한된 카드 형태로 구성합니다.

목적

SectionCard는 제목과 설명, 선택적 행동, 본문을 하나의 raised card로 묶는다. 주변 콘텐츠와 독립된 설정 단위, 요약 패널 또는 경계가 필요한 복합 영역에 사용한다.

선택 기준

  • border가 그룹의 범위와 소유 관계를 이해하는 데 도움이 될 때 사용한다.
  • 페이지의 모든 section을 자동으로 card로 만들지 않는다. 간격만으로 충분하면 Section을 사용한다.
  • 반복 데이터의 각 행을 SectionCard로 만들지 않는다.
  • 단일 숫자 요약은 StatCard, 관련 지표 묶음은 MetricStrip을 사용한다.

구조

  1. card header
    • title
    • 선택적 description
    • 선택적 actions
  2. card content
    • children

변형과 크기

  • padded={true}: 기본. 본문에 좌우와 아래 padding을 제공한다.
  • padded={false}: table, list처럼 자체 행 padding과 경계를 가진 콘텐츠에 사용한다.
  • bodyClassName은 본문 영역만 조정한다.
  • className은 card 전체 배치를 조정한다.
  • 별도 size와 tone prop은 없다.

상태와 동작

  • 자체 상호작용 상태는 없다.
  • loading, empty, error는 children 안에서 card의 바깥 크기와 header를 유지한 채 교체한다.
  • actions는 card 내부 데이터에만 영향을 주어야 한다.
  • card 전체를 클릭 가능하게 만들지 않는다. 목적지가 하나인 요약 항목이라면 semantic link 구조를 제품에서 별도로 구성한다.
  • padded={false}일 때 children이 가장자리와 맞는 자체 padding을 제공해야 한다.

콘텐츠

  • title은 card 안의 데이터 또는 설정 단위를 말한다.
  • description은 범위, 기준 시각, 사용자의 판단에 필요한 맥락을 제공한다.
  • actions는 전체 보기, 편집처럼 card 범위가 명확한 레이블을 쓴다.
  • header에 상태와 행동을 과도하게 모으지 않는다.

접근성

  • 내부 CardTitle은 시각적 제목이지만 heading element가 아니다. 문서 heading 탐색이 필요한 핵심 영역은 Section 또는 별도 heading 구조를 검토한다.
  • actions는 키보드로 접근 가능하고 focus-visible을 유지한다.
  • icon-only action은 card 대상을 포함한 접근 가능한 이름을 제공한다.
  • 상태와 오류는 card 색상이나 border만으로 표현하지 않는다.

좁은 화면과 긴 콘텐츠

  • header는 title 영역과 actions를 한 행에 두므로 긴 title과 많은 action을 함께 사용하지 않는다.
  • 작은 화면에서 action 레이블이 길면 menu나 card 본문 내 별도 행동 영역을 검토한다.
  • padded={false} table은 작은 화면에서 record list로 바꾸거나 명시적인 scroll 영역을 제공한다.
  • 긴 description은 핵심을 첫 문장에 두고 정책 전문은 분리한다.

공개 API

속성타입기본값설명
titleReactNode필수card 제목
descriptionReactNode없음card 범위 설명
actionsReactNode없음card 전용 행동
childrenReactNode필수card 본문
classNamestring없음card 클래스
bodyClassNamestring없음content 영역 클래스
paddedbooleantrue기본 본문 padding 여부

예제

사용 코드 · TSX
import { Button, SectionCard, StatusPill } from '@classum/dot-design-system/ui';

export function RecentFailuresCard() {
  return (
    <SectionCard
      title="최근 실패"
      description="최근 24시간 동안 자동 복구되지 않은 작업이에요."
      actions={<Button variant="ghost">전체 실패 보기</Button>}
      padded={false}
    >
      <ul className="divide-y" aria-label="최근 실패 작업">
        <li className="flex items-center justify-between gap-4 px-5 py-4">
          <span>신규 입사자 과정 동기화</span>
          <StatusPill tone="destructive">재시도 필요</StatusPill>
        </li>
      </ul>
    </SectionCard>
  );
}

피해야 할 사용

  • 모든 Section을 card로 바꿔 카드 안의 카드가 되는 구성
  • 반복 목록의 각 row를 독립 SectionCard로 표현
  • padded={false}인데 children에 여백과 경계가 없는 경우
  • card 전체에 onClick을 추가해 semantic button/link를 대체
  • header에 여러 주 행동을 경쟁시키는 구성
  • 문서 heading이 필요한데 CardTitle만 사용하는 경우

관련 항목