docs(sw): ask the user before substituting or omitting a missing icon

When no official public icon export covers a requested icon, the AI guides now
require asking the user first: approval to use the Storybook icon or an SVG asset
(3-A), or an asset / replacement choice when HMDesign has none (3-B). Creating,
copying, replacing or finally omitting the icon before the answer is not allowed.
Consumer-project use approval is kept separate from official package export
registration. AI_GUIDE shared copies synced.

packages/sw/ai/AI_USAGE.md

@@ -171,9 +171,9 @@ SW 토큰(`--hm-sw-header-*`, `--hm-sw-property-*`, `--hm-sw-viewer-*`, `--hm-sw
 |---|---|---|
 | 1 | 사용자가 이번 작업에 제공했거나 사용을 승인한 이미지·SVG, 또는 소비 프로젝트에 이미 등록된 공식 아이콘이 있음 | 그 에셋을 씁니다. 상태별 그림이 있으면 기본은 `icon`, Hover 그림은 `hoverIcon`에 넣습니다(§5.4) |
 | 2 | 제공된 에셋이 없고, `@hm-design/sw`가 **공개 Export**하는 아이콘·부품 중 **기능과 의미가 같은 것**이 있음 | 그것을 재사용합니다. 시안과 모양이 조금 달라도 기능이 같고 그 아이콘의 사용 위치·크기·상태 규칙 안이면 HMDesign 것을 우선합니다 |
-| 3 | 1·2 모두 없음 | 대체하지 않고 **미지원으로 보고**합니다(아래) |
+| 3 | 1·2 모두 없음 | 대체·생략하지 않고 **코드를 쓰기 전에 사용자에게 먼저 묻습니다**(아래 3-A·3-B) |
 
-- **시안 속 아이콘의 사용 권한:** Figma 등 시안에 그려져 있다는 사실만으로 사용 권한이 있다고 보지 않습니다. 시안에서 아이콘을 추출해 쓰려면 사용자가 그 에셋을 제공했거나 사용을 명시적으로 승인했는지 먼저 확인하고, 확인 전에는 1순위로 쓰지 않습니다(2·3순위로 판단). 이 승인은 해당 소비 프로젝트에서의 사용에만 해당하며, HMDesign 패키지 공식 등록·공개 배포 권한은 별도로 확인합니다(§5.3).
+- **시안 속 아이콘의 사용 권한:** Figma 등 시안에 그려져 있다는 사실만으로 사용 권한이 있다고 보지 않습니다. 시안에서 아이콘을 추출해 쓰려면 사용자가 그 에셋을 제공했거나 사용을 명시적으로 승인했는지 먼저 확인하고, 확인 전에는 1순위로 쓰지 않습니다(2·3순위로 판단). 이 승인은 해당 소비 프로젝트에서의 사용에만 해당하며, HMDesign 패키지 공식 등록·공개 배포 권한까지 포함하지 않습니다(3순위 4번, §5.3).
 
 **2순위 — 현재 공개된 아이콘·아이콘 포함 부품**(목록 밖 이름은 [COMPONENT_CATALOG.md](./COMPONENT_CATALOG.md)와 `dist/index.d.ts`에서 확인):
 
@@ -188,13 +188,25 @@ SW 토큰(`--hm-sw-header-*`, `--hm-sw-property-*`, `--hm-sw-viewer-*`, `--hm-sw
 
 - 모양이 비슷하다는 이유만으로 기능이 다른 아이콘을 쓰지 않습니다(예: `swFooterToolIcons.rect`를 최대화 아이콘으로 쓰기 금지).
 - `SWViewerIcon`은 외곽선만 더하는 감싸기 부품이며 그림을 제공하지 않습니다.
-- **Header 도구 버튼용 범용 아이콘(도움말·3D 보기·설정·메뉴·나가기 등)은 현재 공개 Export가 없습니다.** 이런 아이콘이 시안에 있고 1순위 에셋도 없으면 3순위입니다.
+- **Header 도구 버튼용 범용 아이콘(도움말·3D 보기·설정·메뉴·나가기 등)은 현재 공개 Export가 없습니다.** 이런 아이콘이 시안에 있고 1순위 에셋도 없으면 3순위(사용자 확인)입니다.
 
-**3순위 — 공식 아이콘이 없을 때:**
+**3순위 — 공개 Export가 없을 때(사용자 확인 필요):**
 
-1. 외부 아이콘 라이브러리(`lucide-react` 등 — Web 패키지 의존성이지만 SW 화면에 쓰지 않음), AI가 그린 SVG, Storybook 파일 복사로 대신하지 않습니다.
-2. 코드를 쓰기 전에 필요한 아이콘·기능·필요한 상태(기본·Hover 등)를 사용자에게 알리고 에셋 제공 또는 HMDesign 공식 아이콘 등록이 필요하다고 요청합니다.
-3. 답을 기다리지 않고 진행해야 하면 그 도구 버튼을 넣지 않거나, 사용자가 승인한 임시 표시만 쓰고 결과 보고에 "미지원 아이콘 — 에셋 필요"로 적습니다. 승인 없이 임시 아이콘을 최종 디자인으로 확정하지 않습니다.
+기능과 의미가 같은 아이콘이 HMDesign에 있는지 먼저 확인한 뒤, 해당하는 질문을 **코드를 쓰기 전에** 합니다. 질문에는 필요한 아이콘·기능·필요한 상태(기본·Hover 등)를 적습니다.
+
+| 구분 | 상황 | 사용자에게 묻는 것 |
+|---|---|---|
+| 3-A | HMDesign 내부나 Storybook(예: `SW / Step Header` Story, §5.3)에 같은 기능의 아이콘이 있지만 공식 공개 Export가 없음 | 이번 소비 프로젝트에서 그 아이콘을 사용하도록 승인할지, 또는 별도 SVG 에셋을 제공할지. 공식 패키지 등록은 별도 검토가 필요하다는 점을 함께 알림 |
+| 3-B | HMDesign 어디에도 같은 기능의 아이콘이 없음 | 에셋을 제공할지, 대체 아이콘을 쓸지(쓴다면 어떤 아이콘인지) |
+
+> 3-A 질문 예: "요청하신 아이콘이 HMDesign Storybook에는 있지만 공식 공개 Export는 제공되지 않습니다. 해당 아이콘을 이번 프로젝트에서 사용하도록 승인하시겠습니까? 아니면 별도 SVG 에셋을 제공하시겠습니까? 공식 패키지 등록은 별도 검토가 필요합니다."
+>
+> 3-B 질문 예: "요청하신 아이콘은 HMDesign에 같은 기능의 아이콘이 없습니다. 에셋을 제공해 주시겠습니까, 아니면 대체 아이콘을 사용하시겠습니까?"
+
+1. **답변 전에는 임의로 처리하지 않습니다.** 아이콘을 만들거나(AI가 그린 SVG), Storybook 파일을 복사하거나, 외부 아이콘 라이브러리(`lucide-react` 등 — Web 패키지 의존성이지만 SW 화면에 쓰지 않음)·다른 아이콘으로 대체하거나, 해당 버튼을 최종 화면에서 생략하는 것으로 확정하지 않습니다.
+2. **답을 받을 수 없어 나머지를 진행해야 하면** 아이콘과 무관한 부분만 진행하고, 해당 도구 버튼은 구현하지 않은 채 "확인 대기"로 남깁니다(생략 확정이 아님). 결과 보고에 "아이콘 확인 대기 — 사용 승인 또는 에셋 제공 필요(기능·필요 상태)"로 적고, 답변을 받은 뒤 반영하거나 제거합니다. 임시 표시는 사용자가 승인한 것만 쓰며 최종 디자인으로 확정하지 않습니다.
+3. **승인·제공을 받으면** 1순위로 처리합니다. 승인받은 Storybook 아이콘도 Storybook 파일 경로를 Import·참조하지 않고, 승인받은 SVG를 소비 프로젝트 자체 에셋으로 두어 그 경로를 씁니다(§5.3).
+4. **소비 프로젝트 사용 승인은 공식 패키지 배포 권한이 아닙니다.** 사용 승인을 받아도 그 아이콘을 `@hm-design/sw`의 공식 Export로 등록하거나 등록된 것처럼 안내하지 않습니다. 출처·사용 권한(공개 패키지 배포 포함)이 확인되지 않은 아이콘은 공식 Export로 등록하지 않으며, 등록은 별도 검토·승인 대상으로만 보고합니다.
 
 ### 5.3 Storybook 전용 에셋과 공개 에셋의 차이
 
@@ -202,10 +214,11 @@ SW 토큰(`--hm-sw-header-*`, `--hm-sw-property-*`, `--hm-sw-viewer-*`, `--hm-sw
 |---|---|---|
 | 위치 | `@hm-design/sw` 진입점 Export(카탈로그에 이름이 있음). SVG는 JS에 data URI로 포함 | HMDesign 저장소의 Story 데모 파일. 설치 패키지(`dist`·`ai`)에 포함되지 않음 |
 | 보장 | 버전 호환·사용 규칙 문서화 대상 | 데모용. 출처·사용 권한·유지를 보장하지 않음 |
-| 소비 프로젝트 | Import해서 사용 | Import·복사·경로 참조 금지(Git Submodule로 저장소 파일이 보여도 같음) |
+| 소비 프로젝트 | Import해서 사용 | 사용자 승인 전에는 Import·복사·경로 참조 금지(Git Submodule로 저장소 파일이 보여도 같음) |
 
 - Storybook 화면에 보인다는 것은 공개 API라는 뜻이 아닙니다. Storybook은 조합·외형 참고용입니다([AI_GUIDE.md](./AI_GUIDE.md) 4단계 "Git Submodule 사용 규칙").
-- **2026-11-05 현재 Storybook 전용(공개 API 아님):** `SW / Step Header` Story의 도구 아이콘 — Multi Step의 도움말·3D 보기·설정·메뉴·나가기, Default의 View Property·Sub 창. 출처·사용 권한 확인 전이라 패키지에 등록하지 않았습니다. 시안에 이 아이콘이 있으면 1순위(사용자·프로젝트 제공)로 받거나 3순위로 보고합니다.
+- Storybook 전용 에셋의 사용 승인은 **그 소비 프로젝트의 사용**에 한정됩니다. 승인 후에도 Storybook 경로를 Import하거나 공식 Import 경로로 안내하지 않으며, 공식 패키지 등록·공개 배포 권한은 승인된 것이 아닙니다(§5.2 3순위 3·4번).
+- **2026-11-05 현재 Storybook 전용(공개 API 아님):** `SW / Step Header` Story의 도구 아이콘 — Multi Step의 도움말·3D 보기·설정·메뉴·나가기, Default의 View Property·Sub 창. 출처·사용 권한 확인 전이라 패키지에 등록하지 않았습니다. 시안에 이 아이콘이 있으면 3-A로 사용자에게 사용 승인 또는 별도 SVG 제공을 먼저 묻고(§5.2), 답변 전에는 사용·복사·생략 확정을 하지 않습니다. 승인·제공을 받으면 1순위로 처리합니다.
 
 ### 5.4 아이콘 상태 처리 — 기존 공개 API 방식 그대로
 
@@ -268,5 +281,5 @@ import helpIconHover from "./assets/help-hover.svg"
 
 | 요청 항목 | 판단 | 근거 |
 |---|---|---|
-| 예: 도움말 아이콘 | 1순위 사용 / 2순위 재사용 / 3순위 미지원 | 사용자 제공 파일명 / 재사용한 공개 Export 이름 / "공개 아이콘 없음 — 에셋 제공 또는 공식 등록 필요(기능·필요 상태)" |
+| 예: 도움말 아이콘 | 1순위 사용 / 2순위 재사용 / 3순위 확인 대기 / 3순위 승인·제공 후 사용 | 사용자 제공 파일명 / 재사용한 공개 Export 이름 / "공개 Export 없음 — 사용 승인 또는 에셋 제공 확인 필요(3-A·3-B, 기능·필요 상태)" / 사용자 승인 내용. 승인은 이 소비 프로젝트 사용에 한하며 공식 패키지 등록은 별도 검토 |
 | 예: 창 제어 버튼 | 구현 / 생략 / 보류 / 원본 유지 / 확인 필요 | 시안에 보인 버튼 목록, 사용한 `hiddenControls` 값, 시안 잘림·웹/데스크톱·플랫폼 요구 여부, 기존 화면이면 원본 구성과 사용자 승인 여부 |