패턴 — 알림 · 상태 · 권한 · 도메인 컴포넌트

이 문서는 CoUI 로 만드는 모든 서비스 화면에서 알림 두 가지(Alert · Toast), 빈 상태 · 진행 · 실패 · 확인 대화상자, 11가지 상태 점검, 권한 구조, 도메인 컴포넌트를 어디에 어떻게 놓는지 정합니다. 부품의 생김새와 색은 CoUI 가 정합니다. 이 문서는 색 값을 하나도 정하지 않고, 어느 CoUI 부품을 어느 자리에 언제 몇 개의 행동과 함께 놓는가만 정합니다. 토큰은 Figma 변수 이름(color/surface-container)으로 적고 코드 이름(CoreColors.surfaceContainer)을 괄호에 둡니다. CoUI 에 없는 것은 「CoUI 에 없음」 + 가장 가까운 CoUI 방법을 적고 「CoUI 후보」로 표시합니다. 부품 API 는 cc-coui:coui-index 에서 찾습니다. 글자 단계 · 면의 층은 token-usage.md, 화면 구성은 layout.md, 문구는 copy.md 를 따릅니다.

CoUI Alert 와 Toast 를 그대로 씁니다. 다시 칠하지 않고 변형을 더하지 않습니다. 이 문서가 정하는 것은 자리 · 때 · 행동 수입니다.

판정 한 줄: 결과가 화면에 기록으로 남아야 하면 Alert, 잠깐 알리고 사라져도 되면 Toast 입니다.

Alert 가 놓이는 자리 네 가지입니다.

• 여백 없는 영역에 Alert 를 바로 끼우지 않습니다. 가장자리에 붙는 띠는 Banner(모서리 0) 입니다. Alert 는 여백 안의 카드입니다.
• 한 영역에 Alert 는 하나입니다. 둘이 겹치면 범위가 넓은 것 하나만 남기고 나머지는 그 흐름 안으로 보냅니다.
• 예외 — 이용 전 확인 목록. 알림이 아니라 화면의 내용 자체가 「시작 전에 꼭 알아야 할 것」일 때(가입 · 첫 이용 · 위험이 있는 거래 전)는 Alert(layout: stacked) 를 최대 셋까지 세로로 쌓습니다. 톤은 뜻으로 고릅니다 — 권하는 것 success, 하지 말 것 warning, 규정 · 한도 info. 맨 아래에 Checkbox 하나(「위 내용을 모두 확인했어요」)와 비활성 주 행동을 두고, 체크하면 주 행동이 켜집니다. 예: 병원 「진료 전 확인」, 커머스 「중고 거래 전 확인」, 교육 「실습실 이용 전 확인」.
• layout 의 기본은 stacked(제목 + 설명, 최소 높이를 지키는 판)입니다. inline 은 한 줄 띠라 설명을 그리지 않으므로, 설명이 있는 알림은 stacked 입니다. 상태 아이콘 대신 다른 아이콘이 필요하면 leading 에 넣습니다 — 부품은 둘을 함께 그리지 않습니다.
• 다크 모드는 변수 모드가 처리합니다. Alert · Toast 색을 모드별로 손대지 않습니다.

Toast 절제 조건입니다.

• 성공 Toast 는 결과가 지금 화면에 바로 보이지 않을 때만 띄웁니다. 저장한 값이 눈앞에서 바뀌면 띄우지 않습니다(cc-designer:critique-restraint). 예: 사내 도구 「문서 묶음을 게시했어요」 + 「열기」는 띄웁니다. 커머스 상품명 수정은 표가 바뀌므로 띄우지 않습니다. 「되돌리기」 행동이 있는 Toast 는 결과가 보여도 띄웁니다. 행동이 있어 지우기 시험을 통과합니다.
• 실패를 Toast 로 끝내지 않습니다. 사라진 뒤 다시 볼 수 없으면 Alert 로 바꾸거나 둘 다 둡니다.
• 잠깐 알릴 경고 · 정보는 neutral Toast 에 문장으로 말합니다. Toast info · warning 변형은 「CoUI 후보」 입니다.
• 작고 되돌릴 수 있는 동작은 확인 대화상자 대신 「되돌리기」 행동이 있는 Toast 를 씁니다.

• 알림 안에서는 면이 있는 버튼(secondary · tonal)을 쓰지 않습니다. 상태색 면 위에 또 면을 얹으면 버튼이 알림 면과 다툽니다. 반투명 변형은 CoUI 에 없음 → ghost 로 대체합니다.
• 알림 안 버튼이 화면의 주 행동과 같은 곳으로 가면 하나를 지웁니다. 되돌리기 어려운 행동은 알림에서 바로 하지 않고 확인 대화상자로 보냅니다(5절).

참고 구현(한 사내 도구의 v2 시안)은 Alert · Toast 를 같은 계열의 표면으로 그렸습니다. 패널 면 위 상태색의 아주 옅은 톤 전체, 한쪽 모서리에서 번지는 은은한 사선 그라디언트, 상태색 옅은 테두리, 상태색 원 아이콘, 제목만 상태색(본문은 보조 글자), 라이트는 다크보다 더 옅게. 이 생김새는 규칙이 아니라 후보입니다.

• CoUI Alert 는 불투명 컨테이너(color/info-container, CoreColors.infoContainer 등) 위에 중립 제목(coui_flutter 0.165 부터 톤의 글자색 on{Tone}Container)을 두고 테두리 · 반투명 틴트를 쓰지 않도록 설계했습니다. Toast 는 반전 판입니다. CoUI 에 있는 부품을 서비스에서 다시 만들지 않습니다(cc-blueprint/rules/figma-workflow.md R5).
• 기록 방법: CoUI 변형 요청으로 올립니다(cc-blueprint/rules/figma-workflow.md R5 — 변형이 필요하면 CoUI 에 variant 를 요청. 올리는 절차와 draft 모드는 cc-blueprint/rules/coui-library-consumption.md §6). 속성은 Alert 계약 그대로 둡니다 — title · description · variant 5종 · layout · leading · onDismiss · action.
• CoUI 에 없음: 상태색 테두리(success-outline 같은 이름 없음. 테두리 칸은 분류색 color/category-blue-outline 계열에만 있음), 모드별 그라디언트 세기. 가장 가까운 것은 color/success-container + color/on-success-container 짝입니다.
• 그동안은 CoUI Alert · Toast 기본값을 그대로 씁니다.

EmptyState 를 씁니다. 슬롯은 title · description · action · icon, 축은 variant normal / compact, tone neutral / failure 입니다.

• 영역 가운데에 둡니다(부품 기본). 패널 안이면 compact.
• 일러스트 없음. 슬롯 자체가 없고 이 스킬의 금지 사항입니다. icon 은 선택입니다. 뜻이 분명한 아이콘 하나만 두거나 showIcon 을 끕니다.
• 문구 세 칸: title = 무엇이 없는지, description = 무엇을 하면 되는지, action = 버튼 1~2개.
• 행동 슬롯: Figma 는 Action 교체 칸 하나(Show action)입니다. 버튼 둘은 교체할 묶음 인스턴스를 따로 만듭니다. 코드는 action 에 Row 로 둘을 넣습니다.
• 주 행동 하나: 빈 상태가 영역의 유일한 내용이고 그 행동이 화면의 주 행동이면 primary 입니다. 페이지 머리에 같은 행동이 이미 primary 로 있으면 빈 상태 버튼은 outline 입니다. 같은 행동을 primary 로 두 번 두지 않습니다.
• 처음 쓰는 화면의 빈 상태는 시작 화면으로 짭니다. 질문형 제목, 할 수 있는 것 한 줄, 첫 행동. 역시 일러스트 없이.

단계 목록 + 경과 시간 + 「다른 화면으로 가도 계속돼요」 + 멈추기. 페이지 안 패널에 둡니다. 모달에 가두지 않습니다.

• CoUI 에 없음: 지금 단계의 도는 표시 — 지금 단계의 행은 점 표시입니다. 진행 중임은 머리의 Status 점과 글자가 말합니다.
• 「CoUI 후보 — 진행 단계」: 지금 단계의 도는 표시. 번호 단계(variant: numbered)는 제목 아래 description 을 그리고 trailing 은 그리지 않으므로, 단계별 시간이 필요한 진행 화면은 list 변형입니다.
• 10초가 넘는 작업의 원칙(단계 · 백그라운드 · 취소)은 cc-designer:ix-loading-states 를 따릅니다.
• 예: 교육 「성적표 만들기」(「채점 반영」 → 「PDF 만들기」 → 「발송」), 병원 「청구 파일 만들기」, 커머스 「상품 1,200개 불러오기」, 사내 도구 「운영 배포」.

세 칸입니다. 무엇이 안 됐는지(title) + 그대로인 것(description 첫 문장) + 할 일(action). 「그대로인 것」이 이 스킬의 추가분입니다. 사용자는 실패 뒤에 무엇을 잃었는지를 먼저 걱정합니다.

• 실패는 실패한 만큼만 덮습니다. 홈처럼 섹션이 여럿인 화면에서 한 섹션의 데이터만 못 불러왔는데 화면 전체를 오류 화면으로 바꾸지 않습니다. 이미 불러온 내 정보 · 다른 섹션이 남아 있다는 것이 그 자체로 「그대로인 것」입니다. 예: 커머스 홈 「추천 상품을 불러오지 못했어요」 아래 「장바구니와 주문 내역은 그대로 볼 수 있어요」.
• 오류 코드 · 예외 이름 · 서버 메시지를 고객 화면에 드러내지 않습니다. 매핑은 cc-writing:product-writing · cc-i18n:failure-message-i18n 을 따릅니다.
• 「왜」는 할 일을 고르는 데 필요할 때만 한 문장 넣습니다(cc-designer:ix-error-handling).

언제: 되돌리기 어려운 행동 — 삭제 · 해지 · 결제 · 발송. 「끄기」는 끄면 데이터나 설정이 사라질 때만 확인합니다. 작고 되돌릴 수 있는 동작(보관 · 숨김 · 장바구니 빼기)은 확인 창 대신 「되돌리기」 Toast 입니다(cc-designer:critique-restraint). 되돌릴 수 있어도 영향이 큰 동작(운영 배포처럼)은 primary 확인 대화상자로 묻습니다.

• Dialog 에는 변형이 없습니다. 위험은 버튼이 말합니다. Button(variant: CoreButtonVariant.destructive) 는 평소 오류색 선, 올리면 오류색 채움입니다.
• 행동 배치는 한 규칙만 씁니다. 오른쪽 정렬, 「취소」 왼쪽, 확인 맨 오른쪽. 세 번째 행동이 꼭 필요하면 맨 왼쪽에 ghost 로 둡니다.
• 입력 확인은 전용 부품이 없습니다. 조합으로 충분하고 새 부품을 만들지 않습니다.
• Figma 구멍: 라이브러리 Dialog 의 행동 줄은 Button 인스턴스가 아니라 모양만 흉내 낸 프레임입니다. 확인 대화상자 화면에서는 Button 인스턴스(destructive · ghost)로 바꿔 넣습니다. 속성은 title · content, Show barrier.
• 예: 병원 「환자 기록을 삭제할까요?」(본문 「진료 기록 24건도 함께 지워요.」 「30일 안에는 복구를 요청할 수 있어요.」) → destructive. 커머스 「정기 배송을 해지할까요?」 → destructive. 교육 「반을 닫을까요?」(본문 「학생 32명의 출석 기록은 남아요」) → destructive. 사내 도구 「운영에 v2.3.0을 배포할까요?」(본문 「문제가 생기면 이전 버전으로 자동으로 되돌려요」) → primary.

모든 기능은 11가지 상태를 점검합니다. 해당 없는 상태는 「해당 없음」과 이유를 적습니다. Figma 프레임 상태 이름은 cc-blueprint/rules/figma-workflow.md R2 의 어휘(필수 Default, 기본 Loading · Empty · Error, 공통 추가 Long · Typing · Collapsed · NoPermission)를 쓰고, 그 밖은 제품 어휘로 정해 DDR 에 남깁니다.

• Figma 아이콘은 별도 라이브러리(「CoUI Icons - Lucide」)에 Lucide 한 벌로 있습니다 — lucide/lock · lucide/wifi-off 도 있습니다. 컴포넌트 검색과 따로, 그 라이브러리 키로 찾습니다(cc-blueprint/rules/coui-library-consumption.md §3). 오프라인은 글자로 충분하면 아이콘을 두지 않습니다(mood.md 2-5).
• 오프라인 · 한도 같은 상태가 상단 바의 역할 칩 자리를 차지하지 않습니다. 지금 역할은 늘 보여야 합니다(7절).

서비스마다 역할을 먼저 정하고 권한표를 만듭니다. 권한표는 Figma Overview 페이지에 둡니다(figma-file.md 9절).

• 기호는 ● 쓸 수 있음 · ○ 보기만 · — 안 보임 셋입니다. 결제 주체 열을 함께 둡니다. 「누가 돈을 내는가」가 업그레이드 자리와 문구를 정하기 때문입니다.
• 역할이 달라도 같은 셸입니다. 메뉴만 줄입니다. 메뉴 이름은 기능에 따라 자랍니다(「주문」 → 「주문과 배송」).
• 안 되는 기능은 메뉴에서 숨깁니다. 숨긴 기능이 필요한 화면 안에는 잠긴 카드(6절 잠김)를 둡니다. 「권한 없음」 페이지를 메뉴로 열지 않습니다.
• 업그레이드 안내는 흐름 안 자리에만 둡니다 — 한도 Alert · 잠긴 카드 · 만들기 전 Dialog · 요금제 화면. 한 화면에 업그레이드 버튼은 하나입니다. 사이드바의 플랜 · 사용량 카드는 정보만 보여 주고 버튼을 두지 않거나 ghost 로 둡니다.
• 직접 주소 · 공유 링크로 들어온 경우를 위해 권한 없음 상태(NoPermission)를 따로 만듭니다.
• 상단 바의 지금 역할 칩은 Badge(variant: CoreBadgeVariant.outlined, size: CoreComponentSize.sm) 입니다. Chip 은 누르는 컨트롤이라 쓰지 않습니다. 채운 Badge(filled)는 상단 바에서 무겁습니다.
• 역할 색은 기본으로 두지 않습니다. 꼭 필요하면 상태색(success · warning · info · error)과 겹치지 않게 분류색 color/category-blue-container(CoreColors.categoryBlueContainer) + color/on-category-blue-container 계열에서 고르고, 문서와 화면에서 같게 씁니다. 분류색은 코드와 Figma 라이브러리에 같은 이름으로 있습니다.

CoUI 에 없고 이 서비스에만 쓰는 부품은 서비스 파일의 「도메인 컴포넌트」 섹션에 둡니다. Figma 에서는 900 components 페이지의 {domain}/{Component} 입니다(cc-blueprint/rules/coui-library-consumption.md §4).

1. CoUI 에 있는 부품은 다시 만들지 않습니다. Alert · Toast · Card · Dialog 의 생김새가 마음에 안 들면 CoUI 에 변형을 요청합니다.
2. CoUI와 제품 브랜드 토큰을 사용합니다. 로컬 컬렉션·컴포넌트 스타일을 정의하고 코드 대응을 기록합니다. 공통 API에 없는 속성도 디자인에 표현하고 구현 gap으로 관리합니다.
3. 구조를 유지합니다. 속성 · 축 · 변형 이름은 가장 가까운 CoUI 계약에서 가져옵니다. 예: 페이지 머리는 AppBar 의 header · title · subtitle · trailing, 진행 단계는 Steps 의 items · currentStep.
4. 구조를 바꿔야 하면 근거를 적고 먼저 묻습니다. 이것은 이 스킬의 규칙입니다(cc-designer:design-decision 은 묻지 않고 확정하는 프로토콜이라 그쪽에 기대지 않습니다). 무인 실행이면 바꾸지 않고 DDR 에 제안만 남깁니다(figma-file.md 8절).
5. 부품마다 두 줄을 남깁니다 — 왜 CoUI 에 없는지, 안쪽은 어떤 CoUI 재료로 조립했는지. 조립 재료는 OutlinedContainer · Icon · 글자 · Button 같은 CoUI 부품입니다.
6. 여러 서비스에 쓸 만하면 「CoUI 후보」로 표시합니다. Figma 에서는 promote/{Component} 접두가 그 표시이고, CoUI 승격 제안을 함께 올립니다(consumption §6).
7. 서비스 하나의 결정(역할 이름 · 한도 수치 · 요금제 구조)은 도메인 컴포넌트 안에 굽지 않고 속성으로 받습니다.