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

Dot Component Language

primitive, composition과 브랜드 컴포넌트의 역할과 선택 순서를 설명합니다.

구성 원칙

src/components/ui/*는 접근 가능한 primitive layer다. Dot 고유 사용성은 src/components/compositions/*의 composition layer에서 만든다. 제품 페이지는 primitive를 임의 조합하기보다 아래 공통 패턴을 우선 사용한다.

PageScaffold

페이지 폭과 세로 리듬을 정의한다.

  • content: 목록·운영·일반 설정
  • wide: 일정·복잡한 편집
  • 페이지마다 임의의 outer padding과 max-width를 만들지 않는다.

페이지 목적과 현재 맥락, 주 행동을 한 곳에 모은다.

  • eyebrow 또는 breadcrumb: 상위 맥락
  • title: 현재 작업 대상
  • description: 이 화면에서 할 수 있는 일
  • meta: 상태·최근 저장·version
  • actions: 주 행동 1개와 제한된 보조 행동
  • back action은 제목과 떨어진 독립 버튼이 아니라 헤더 맥락에 포함한다.

EnvironmentBanner

preview·sandbox처럼 데이터 신뢰도나 쓰기 가능 여부가 달라지는 환경을 페이지마다 같은 형식으로 알린다. 일반 정보 메시지에 남용하지 않는다.

PageToolbar

검색, 필터, 보기 전환, 새로고침처럼 현재 데이터에 영향을 주는 조작을 데이터 바로 위에 배치한다. 주 생성 행동은 PageHeader에 둔다.

Record list / table pattern

반복 데이터는 Table primitive나 제품별 record list composition으로 안정적인 행 구조를 만든다.

  • 행 전체가 같은 상세 화면으로 이동한다면 전체 행을 클릭 가능하게 한다.
  • 이름·설명은 왼쪽, 상태·수치는 중앙, 다음 행동은 오른쪽에 둔다.
  • 모바일에서는 열을 억지로 축소하지 않고 핵심 필드를 세로로 재배치한다.
  • 빈 상태, error, loading은 같은 frame 안에서 교체된다.

MetricStrip

운영 지표를 여러 개의 독립 카드로 분리하지 않고 한 표면 안의 균일한 셀로 비교한다. 지표 레이블, 값, 보조 설명을 제공하며 색은 예외 값에만 쓴다.

Section

제목·설명·보조 행동과 본문을 한 단위로 묶는다. 별도 표면이 필요할 때만 surface variant를 쓰며 모든 섹션을 Card로 만들지 않는다.

FormField와 form section pattern

  • Label은 항상 연결된 control을 가진다.
  • 도움말은 입력 전에 판단에 필요한 정보, 오류는 입력 후 복구 정보다.
  • FormSection은 한 번에 하나의 개념만 편집한다.
  • select, textarea, input은 공통 높이·border·focus를 사용한다.

StatusPill

상태를 짧은 텍스트와 semantic tone으로 보여준다. 운영 중, 초안, 검증 필요, 발행됨, 실패처럼 사용자가 이해하는 용어를 쓴다. 색상만으로 상태를 구분하지 않는다.

DotTheme

제품에서 디자인 시스템을 적용할 범위를 .dot-theme로 묶는다. 이 경계는 typography와 최소 reset을 제공하며 앱의 body, 라우팅, 레이아웃을 소유하지 않는다. 디자인 시스템의 Radix overlay는 DotTheme가 관리하는 layout-neutral portal root로 자동 이동하므로 theme token과 scoped reset을 그대로 상속한다. 제품이 별도 portal primitive를 만들 때에도 같은 경계 안의 container를 명시한다.

SidebarProvider는 기본적으로 브라우저 cookie를 쓰거나 전역 keyboard shortcut을 등록하지 않는다. 제품이 상태 보존이나 단축키를 필요로 할 때에만 충돌하지 않는 이름을 명시한다.

사용 코드 · TSX
<SidebarProvider stateCookie={{ name: 'daily_backoffice_sidebar' }} keyboardShortcut="d">
  {/* sidebar와 content */}
</SidebarProvider>

Cookie 이름은 제품 단위로 namespace하고, 입력 중이거나 content-editable 영역에서는 단축키를 가로채지 않는다.

DotCharacter

catalog에 active로 등록된 3D 정적 에셋만 렌더한다. assetId는 의미를 추측한 별칭이 아니라 catalog ID를 사용한다. 컴포넌트가 100px 최소 크기와 AVIF→WebP source 순서를 보장한다.

DotIcon

내비게이션과 작은 제품 identity에는 DotIcon을 사용한다. 컴포넌트는 승인 logo SVG에서 재생성한 192×233 lossless sRGB WebP를 사용하며 size·framed API는 asset 경로와 분리한다. 기존 SVG 렌더러 contract가 필요한 제품은 ui entry의 dotIconUrl을 <image> 또는 <img>에 연결할 수 있다. 원본 dotLogoUrl은 큰 logo 사용과 호환성을 위해 root entry에 유지하지만 일반 UI bundle에서는 가져오지 않는다.

DotMotion

별도 @classum/dot-design-system/motion entry에서 가져온다. viewport 근처에서만 Lottie를 불러오고 모션 감소 설정, 실패, 로딩 중에는 정적 fallback을 보여준다. processing은 실제 AI 생성·채점·분석 중일 때, avatar는 AI DOT의 실제 발화나 안내가 진행되는 동안만 반복한다.

Avatar는 avatar-body-trace-path-v1 호환성 패치와 실제 renderer smoke를 통과한 package derivative만 사용한다. 제품에서 JSON expression을 다시 치환하거나 직접 asset 경로로 우회하지 않는다. expression 실행을 허용하지 않는 CSP에서는 보안 정책을 완화하지 않고 정적 fallback을 사용한다.

WorkflowBar

저장→검증→발행처럼 순서가 있는 작업에서 다음 행동 하나를 주 행동으로 제안한다.

  • 변경 있음: 초안 저장
  • 저장됨, 미검증: 검증 실행
  • 검증 통과: 커리큘럼 발행
  • 발행됨: 완료 상태와 다음 관리 행동

템플릿 적용, 복제, 새로고침은 보조 메뉴 또는 낮은 강조도로 분리한다. 같은 행동을 페이지 아래에 중복 배치하지 않는다.

ConfirmActionDialog

브라우저 기본 window.confirm을 사용하지 않는다. 대상, 결과, 되돌릴 수 있는지, 주 행동을 구체적으로 설명한다. 파괴 행동만 destructive tone을 사용한다.

EmptyState

무엇이 없는지 → 왜 그런지 또는 가치 → 다음 행동 순서로 쓴다. 캐릭터는 넓고 드문 빈 상태에서만 사용할 수 있고 3D 원본을 직접 번들하지 않는다.

컴포넌트 상태

모든 interactive component는 최소 다음을 정의한다.

  • default
  • hover
  • focus-visible
  • active/selected
  • disabled
  • loading
  • error(해당 시)

상세 컴포넌트 계약

모든 public component의 목적, 선택 기준, 구조, 변형과 크기, 상태, 콘텐츠, 접근성, 좁은 화면 동작, 실제 API와 예제는 Button 상세 문서와 같은 개별 문서에서 확인한다. 전체 파일 목록과 source module 연결은 문서 catalog가 기준이다.