Card

독립된 콘텐츠 단위를 필요한 경우에만 하나의 표면으로 묶습니다.

목적

Card는 다른 콘텐츠와 독립된 하나의 표면이 실제로 필요할 때 제목, 설명, 본문, 행동을 묶는다. 정보 구조를 만드는 기본 수단이 아니라 경계가 필요한 제한된 단위를 표현한다.

선택 기준

별도 배경, border, elevation으로 주변과 분리해야 하는 설정 묶음이나 독립 요약에 사용한다.
페이지의 모든 section을 Card로 만들지 않는다. 단순한 제목과 본문 묶음은 Section을 우선한다.
반복 데이터 비교에는 Card 목록보다 Table이나 record list를 사용한다.
Card 안에 다시 Card를 중첩하지 않는다.

실제 패키지 렌더링

기본 사용 예시

예시 데이터

검증 결과

발행 전에 해결해야 할 항목을 확인해요.

2개 확인 필요

구조

Card 안에 필요에 따라 다음을 배치한다.

CardHeader
CardTitle, CardDescription
CardContent
CardFooter

Header, Content, Footer는 각각 기본 24px padding을 공유하며 Content와 Footer는 위쪽 padding을 제거해 하나의 리듬을 만든다.

변형과 크기

별도 variant나 size prop은 없다. 기본은 둥근 border, card semantic 배경과 shadow를 가진다. 너비는 부모 layout이 결정한다. 크기나 밀도를 바꿀 때는 같은 그룹 안에서 일관된 padding과 높이를 유지한다.

상태와 동작

Card 자체는 interactive component가 아니다. 전체 Card가 하나의 목적지로 이동해야 한다면 내부에 명확한 anchor를 두고, 여러 행동이 섞인 Card 전체에 click handler를 붙이지 않는다. selected, disabled, loading 상태는 제공하지 않으므로 제품 흐름에 맞는 component와 문구를 조합한다.

콘텐츠

Title은 표면의 역할을 짧게 말하고 Description은 사용자가 판단하는 데 필요한 한두 문장만 제공한다. Footer에는 주 행동 하나와 제한된 보조 행동을 둔다. 수치만 나열하는 운영 지표는 MetricStrip을 우선한다.

접근성

CardTitle은 시각 스타일이 적용된 div이며 heading semantics를 자동으로 만들지 않는다. 문서 구조상 제목이면 CardTitle에 as prop을 기대하지 말고 내부에 실제 h2나 h3를 배치한다. Card가 클릭 가능하다는 것을 색이나 hover만으로 전달하지 않는다.

좁은 화면과 긴 콘텐츠

Card grid는 좁은 화면에서 자연스럽게 한 열로 바뀌어야 한다. 고정 높이로 긴 설명을 자르지 않는다. 반복 Card의 높이를 맞추기 위해 핵심 콘텐츠를 숨기지 말고 정보 구조 자체를 목록이나 표로 바꿀지 검토한다.

공개 API

Card: 표면 root
CardHeader: 제목 영역
CardTitle: 시각적 제목 div
CardDescription: 보조 설명 div
CardContent: 본문 영역
CardFooter: 하단 행동 영역

모든 요소는 해당 div의 HTML attributes와 className을 전달한다.

예제

import {
  Button,
  Card,
  CardContent,
  CardDescription,
  CardFooter,
  CardHeader,
  CardTitle,
} from '@classum/dot-design-system/ui';

export function PublishSummaryCard() {
  return (
    <Card>
      <CardHeader>
        <CardTitle>
          <h2>발행 준비</h2>
        </CardTitle>
        <CardDescription>질문과 기준 답안 검증을 모두 통과했어요.</CardDescription>
      </CardHeader>
      <CardContent>
        <p className="text-sm">학습자 24명에게 최신 버전이 공개돼요.</p>
      </CardContent>
      <CardFooter>
        <Button>커리큘럼 발행</Button>
      </CardFooter>
    </Card>
  );
}

피해야 할 사용

모든 section과 모든 행을 Card로 감싸지 않는다.
Card 안에 Card를 반복해서 중첩하지 않는다.
여러 목적지와 조작이 있는 Card 전체를 하나의 클릭 영역으로 만들지 않는다.
CardTitle만으로 heading semantics가 생긴다고 가정하지 않는다.
장식 목적의 shadow를 여러 단계로 쌓지 않는다.

목적