EnvironmentBanner

데이터 신뢰도나 쓰기 조건이 다른 환경을 지속적으로 알립니다.

목적

EnvironmentBanner는 미리보기, 개발, sandbox처럼 데이터 신뢰도나 쓰기 가능 여부가 운영 환경과 다른 상황을 지속적으로 알린다. 사용자가 테스트 데이터를 실제 데이터로 오해하거나 제한된 환경에서 운영 행동을 시도하지 않게 돕는다.

선택 기준

환경 차이가 현재 페이지의 데이터 해석이나 행동 결과에 영향을 줄 때 사용한다.
일반 공지, 프로모션, 일시적인 성공 메시지에는 사용하지 않는다.
서비스 전체에 영향을 주는 환경이라면 페이지마다 반복하기보다 공통 shell에서 일관된 위치에 둔다.
특정 섹션에만 적용되면 해당 섹션 바로 앞에 둔다.

구조

flask 아이콘: 실험 또는 비운영 맥락을 보조한다.
title: 환경 성격을 짧게 식별한다.
description: 실제 운영과 다른 점을 설명한다.
label: 짧고 반복 가능한 환경 표식이다.

변형과 크기

별도 tone, variant, size prop은 없다.
기본 스타일은 중립 표면과 secondary badge를 사용해 오류나 경고처럼 과장하지 않는다.
className으로 배치를 조정할 수 있으나 semantic status banner를 흉내 내기 위한 임의 색상 변경은 피한다.

상태와 동작

자체 상호작용은 없다.
환경 전환 행동이 필요하면 banner 내부에 억지로 넣기보다 인접한 페이지 행동 또는 명확한 링크를 제품에서 구성한다.
환경 정보가 비동기로 바뀌면 화면의 데이터도 같은 기준으로 갱신되었는지 확인한다.
운영 환경에서는 필요하지 않은 banner를 렌더하지 않는다.

콘텐츠

title은 UI 미리보기, 테스트 환경처럼 현재 맥락을 말한다.
description은 변경 내용은 저장되지 않아요, 실제 사용자에게 알림이 발송되지 않아요처럼 차이를 구체적으로 쓴다.
label은 짧게 유지하고 내부 코드명만 단독으로 쓰지 않는다.
사용자가 취할 수 없는 행동을 장황하게 나열하지 않는다.

접근성

aside로 렌더되어 본문과 구분되는 보조 정보를 제공한다.
아이콘은 장식 처리된다. 환경의 의미는 항상 텍스트로 전달한다.
문서 안에서 여러 banner가 반복되면 스크린 리더 탐색을 방해하므로 가장 관련 있는 위치에 한 번만 제공한다.
배경과 텍스트 대비를 임의 클래스 변경으로 약화하지 않는다.

좁은 화면과 긴 콘텐츠

작은 화면에서는 본문과 label이 세로로 쌓이고, 넓은 화면에서는 한 행으로 정렬된다.
긴 설명은 여러 문장을 넣기보다 가장 중요한 환경 차이 하나를 먼저 쓴다.
label은 내용 폭만 차지한다. 긴 환경 이름이 필요하면 label이 아니라 title 또는 description에 쓴다.

공개 API

EnvironmentBannerProps는 React.HTMLAttributes<HTMLDivElement>를 확장한다.

속성	타입	기본값	설명
`description`	`ReactNode`	필수	운영 환경과 다른 점
`title`	`string`	`'UI 미리보기'`	환경 제목
`label`	`string`	`'development only'`	짧은 환경 표식
`className`	`string`	없음	컨테이너 클래스
기타	`HTMLAttributes<HTMLDivElement>`	없음	표준 div 속성

예제

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

export function PreviewNotice() {
  return (
    <EnvironmentBanner
      title="발송 미리보기"
      description="이 화면의 메시지는 실제 사용자에게 발송되지 않아요."
      label="preview"
    />
  );
}

피해야 할 사용

오류, 점검, 성공 toast를 대신하는 사용
실제 운영과 차이가 없는데 장식 목적으로 표시
환경의 영향을 설명하지 않고 내부 환경 코드만 표시
같은 페이지의 모든 섹션에 반복 배치
위험 상태를 전달하기 위해 임의의 destructive 색을 적용

목적