Section

제목, 설명, 보조 행동과 본문을 의미 있는 콘텐츠 단위로 묶습니다.

목적

Section은 제목, 설명, 보조 행동과 관련 콘텐츠를 하나의 의미 단위로 묶는다. 복잡한 페이지를 사용자의 판단 순서에 맞는 덩어리로 나누면서도 모든 내용을 카드로 만들지 않게 한다.

선택 기준

하나의 h2 아래에서 같은 질문이나 작업을 다루는 콘텐츠에 사용한다.
이미 SectionCard나 semantic section을 가진 컴포넌트를 불필요하게 중첩하지 않는다.
서로 다른 저장 단위나 권한 범위를 한 Section에 섞지 않는다.
별도 표면이 실제 그룹 이해를 도울 때만 surface를 사용한다.

구조

title: section의 h2
description: section의 목적 또는 범위
actions: section에만 영향을 주는 보조 행동
children: 실제 콘텐츠

변형과 크기

surface={false}: 기본. 페이지 배경 위에서 간격과 제목만으로 묶는다.
surface={true}: border와 raised surface가 필요한 독립 그룹에 사용한다.
별도 size prop은 없다.
actions는 작은 화면에서 제목 아래, 넓은 화면에서 오른쪽에 배치된다.

상태와 동작

자체 상호작용 상태는 없다.
loading, empty, error는 children 영역에서 같은 frame 안에 교체한다.
section 전체가 비활성인 경우 opacity만 낮추지 말고 이유와 가능한 다음 행동을 설명한다.
actions의 비동기 상태는 전달한 control이 소유한다.
접기·펼치기가 필요하면 Section을 클릭 가능하게 만들지 말고 접근 가능한 Accordion을 사용한다.

콘텐츠

title은 짧은 명사형 또는 작업 단위를 쓴다.
description은 설정하세요를 반복하기보다 이 section이 영향을 주는 범위를 설명한다.
actions는 추가, 편집, 새로고침처럼 section 내부에만 영향을 주어야 한다.
페이지의 주 행동을 Section.actions에 중복하지 않는다.

접근성

semantic section과 h2를 제공한다.
페이지 제목의 h1 다음에 논리적인 h2 순서를 유지한다.
actions의 접근 가능한 이름만으로 대상이 모호하면 section 이름을 포함한다.
status와 error는 색상뿐 아니라 텍스트로 제공한다.
aria-labelledby, aria-describedby 같은 표준 section 속성을 전달할 수 있다.

좁은 화면과 긴 콘텐츠

header는 좁은 화면에서 세로로 쌓인다.
title과 description이 길면 actions보다 먼저 읽히고 자연스럽게 줄바꿈된다.
surface 내부에 넓은 table이 있으면 section 전체가 아니라 데이터 영역만 가로 스크롤되게 한다.
작은 화면에서 actions가 여러 개면 주로 쓰는 하나만 보이고 나머지는 menu로 정리한다.

공개 API

SectionProps는 title을 제외한 HTMLAttributes<HTMLElement>를 확장한다.

속성	타입	기본값	설명
`title`	`ReactNode`	필수	section h2
`description`	`ReactNode`	없음	목적 또는 범위 설명
`actions`	`ReactNode`	없음	section 전용 행동
`surface`	`boolean`	`false`	raised surface 표시 여부
`children`	`ReactNode`	없음	section 콘텐츠
`className`	`string`	없음	section 클래스
기타	`HTMLAttributes<HTMLElement>`	없음	표준 section 속성

예제

import { Button, Section } from '@classum/dot-design-system/ui';

export function MembersSection() {
  return (
    <Section
      title="검토자"
      description="발행 전에 변경 내용을 확인할 구성원을 관리해요."
      actions={<Button variant="outline">검토자 추가</Button>}
    >
      {/* member list */}
    </Section>
  );
}

피해야 할 사용

모든 작은 문단을 Section으로 분리
한 페이지에 의미 없는 surface 카드 반복
h1 없이 Section title을 페이지 제목으로 사용
페이지 주 행동을 여러 Section에 중복
접기·펼치기 행동을 section 전체 클릭으로 구현
서로 다른 저장 단위를 하나의 Section에 혼합

목적