Card / Surface

미리보기

로컬 미리보기입니다. 실제 계정, 환경, 실행 데이터에는 영향을 주지 않습니다.

사용법

• 관련 정보와 액션을 한 표면에 모으세요. 기본 24px 패딩이 네 면을 균형 잡고, 간격이 제목·설명·본문·액션의 위계를 만듭니다. 카드 그리드 텍스트를 주변 본문 텍스트와 정렬하려면 Grid.bleed와 Card.Root.padding을 같은 토큰 단계로 설정하세요. 바깥 컨테이너에 확장된 표면과 포커스 표시기를 담을 공간이 있을 때만 이렇게 하세요.
• 한 줄에서 더 높은 옆 카드에 맞춰 늘어나도 카드는 내용을 위에, Footer를 아래에 둡니다. 그래서 같은 줄 카드의 푸터가 나란히 맞습니다. Meter 같은 막대는 Footer에서 한 줄을 다 씁니다.
• 항목 상세처럼 무언가를 여는 카드에는 Title 안에 Card.Action을 두세요. 버튼이나 href가 있는 링크가 카드 전체를 덮고, hover, press, focus가 카드 전체에 보입니다. 카드의 다른 컨트롤은 그 위에 남아 제 동작을 그대로 합니다.
• 비슷한 항목을 모은 컬렉션에서는 패딩을 카드와 밀도에 맡기세요. 그리드를 SizeProvider density='compact'로 감싸면 모든 카드가 한꺼번에 촘촘해집니다. 부분마다 놓을 자리는 레이아웃 파운데이션의 컬렉션 절을 보세요.

• 모든 페이지 구획을 카드로 감싸거나 카드 안에 카드를 쌓지 마세요. 대신 구획을 제목과 간격으로 나누세요. 데이터 패널마다 면이 되는 대시보드는 예외이니 Dashboard.Panel을 쓰세요.
• 카드 자체를 버튼으로 만들거나 링크로 감싸지 마세요. 대신 Card.Action을 쓰세요. 제목 안에 이름이 있는 대상 하나를 두고, 카드의 다른 컨트롤도 그대로 동작합니다.
• 카드의 띠, 테두리, 면에 색을 칠해 상태를 나타내지 마세요. 대신 StatusBadge로 상태를 글로 말하세요.

크기: SizeProvider size="small" 포털까지 포함해 구성 전체의 크기를 바꿉니다. 기본 크기는 Default입니다. 크기 안내 및 비교

구성

Root(Surface) → Header(Title(optional Action) + Description) + Body + Footer

키보드와 접근성

액션만 Tab 순서에 들어갑니다. Root는 포커스나 클릭 동작이 없는 일반 div입니다. Card.Action을 쓰면 카드에서 Tab이 멈추는 곳은 그 액션 하나이고, 포커스 링은 카드 전체를 둘러쌉니다. Title.level을 주변 제목 위계에 맞추세요. 카드에 그룹 이름이 필요하면 aria-labelledby로 연결하세요.

각 컨트롤에 목적을 설명하는 이름을 지정하세요. 오류 메시지를 해당 컨트롤에 연결하고, 상태를 색만으로 알리지 마세요. 자동 검사는 수동 키보드 및 보조 기술 테스트를 대신하지 않습니다.

예시 코드

공유 컴포넌트는 디자인 토큰에서 스타일을 가져옵니다. 각 예시는 자체 구성과 접근성 속성을 설정합니다. 호출하는 화면이 콜백, ref, 제품 데이터를 정의합니다.

import { Card, Button } from '@surflane/ui'

<Card.Root aria-labelledby='environment-title'>
  <Card.Header>
    <Card.Title id='environment-title' level={3}>
      DEMO main
    </Card.Title>
    <Card.Description>Platform API environment</Card.Description>
  </Card.Header>
  <Card.Body>Three services are ready to deploy.</Card.Body>
  <Card.Footer>
    <Button onClick={inspect}>Inspect environment</Button>
  </Card.Footer>
</Card.Root>

// The whole card opens the item: the title's action stretches over it.
<Card.Root>
  <Card.Header>
    <Card.Title>
      <Card.Action onClick={() => open(service)}>{service.name}</Card.Action>
    </Card.Title>
  </Card.Header>
  <Card.Body>{service.summary}</Card.Body>
</Card.Root>

주요 API

표는 공통 래퍼의 주요 props를 나열합니다. 전체 타입은 패키지 타입 선언을 참조하세요.

관련 토큰