StatusPill

짧은 상태 레이블과 의미 기반 tone을 함께 제공합니다.

목적

StatusPill은 객체나 작업의 현재 상태를 짧은 텍스트와 semantic tone으로 표시한다. 목록, 상세 header, workflow에서 같은 상태를 같은 언어와 위치로 연결해 사용자가 맥락을 잃지 않게 한다.

선택 기준

운영 중, 초안, 검증 필요, 실패처럼 짧고 열거 가능한 상태에 사용한다.
긴 설명, 경고 원인, 복구 방법을 pill 안에 넣지 않는다.
분류 tag와 상태를 혼동하지 않는다. 분류에는 일반 Badge가 더 적합할 수 있다.
숫자 알림이나 선택 control로 사용하지 않는다.

실제 패키지 렌더링

기본 사용 예시

예시 데이터

운영 중검증 필요발행 실패초안

구조

semantic span
선택적 상태 dot
children 상태 텍스트

dot은 의미를 보조할 뿐 상태 이름을 대체하지 않는다.

변형과 크기

`tone`	의미
`neutral`	초안, 대기처럼 특별한 판단이 없는 상태
`primary`	현재 선택, 주요 진행 상태
`info`	참고할 정보 상태
`success`	완료되었거나 명확히 정상인 상태
`warning`	확인이나 조치가 필요하지만 즉시 실패는 아닌 상태
`destructive`	실패, 중단, 위험 상태

dot={true}가 기본이다.
별도 size prop은 없고 최소 높이 24px의 compact 상태 표시에 고정된다.

상태와 동작

자체 상호작용은 없다.
상태가 바뀌면 텍스트도 함께 갱신한다.
실시간 변경이 작업 성공·실패처럼 중요하면 제품의 live region과 함께 전달한다.
클릭 가능한 필터처럼 사용하지 않는다. 선택 행동이 필요하면 Badge 형태의 button이나 ToggleGroup을 별도로 사용한다.

콘텐츠

1~3개의 짧은 단어로 현재 상태를 말한다.
내부 enum이나 영문 코드 대신 사용자가 이해하는 운영 용어를 쓴다.
warning, destructive tone은 실제 조치 우선순위와 일치해야 한다.
문장과 복구 안내는 pill 인접 영역에 둔다.
같은 상태는 제품 전체에서 같은 레이블과 tone을 사용한다.

접근성

상태는 children 텍스트로 항상 전달되므로 색과 dot에 의존하지 않는다.
목록에서 상태 header와 cell 관계가 분명하도록 table semantics를 유지한다.
동적 상태를 전달할 때 pill 자체에 매번 role="alert"를 붙이지 않는다. 중요도에 맞는 상위 live region을 사용한다.
contrast를 약화하는 임의 class를 피한다.

좁은 화면과 긴 콘텐츠

pill은 한 줄 상태에 적합하다. 긴 레이블이 필요하면 용어 체계를 다시 정리한다.
좁은 목록에서 상태를 아이콘만으로 축약하지 않는다.
여러 pill을 한 행에 과도하게 나열하지 말고 핵심 상태와 분류 정보를 구분한다.
상태가 가장 중요한 정보면 작은 화면에서도 숨기지 않는다.

공개 API

StatusPillProps는 React.HTMLAttributes<HTMLSpanElement>를 확장한다.

속성	타입	기본값	설명
`tone`	`'success' \| 'warning' \| 'destructive' \| 'info' \| 'neutral' \| 'primary'`	`'neutral'`	상태 의미 tone
`dot`	`boolean`	`true`	상태 dot 표시 여부
`children`	`ReactNode`	없음	상태 레이블
`className`	`string`	없음	span 클래스
기타	`HTMLAttributes<HTMLSpanElement>`	없음	표준 span 속성

공개 타입은 StatusPillProps, Tone이다.

예제

import { StatusPill } from '@classum/dot-design-system/ui';

export function ValidationStatus({ failed }: { failed: boolean }) {
  return failed ? (
    <StatusPill tone="destructive">검증 실패</StatusPill>
  ) : (
    <StatusPill tone="success">검증 통과</StatusPill>
  );
}

피해야 할 사용

텍스트 없이 dot만으로 상태 표시
실제 의미와 무관한 장식 색 선택
긴 오류 원인과 해결책을 pill 안에 넣기
클릭 가능한 filter나 action처럼 사용
같은 상태를 화면마다 다른 레이블·tone으로 표현
모든 정상 상태를 success pill로 반복해 시각적 소음을 만들기

목적