HMDesign/packages/sw/ai/AI_USAGE.md

@hm-design/sw — AI 코딩 도구 사용 안내

이 폴더(node_modules/@hm-design/sw/ai/)는 다른 React 프로젝트에서 AI 코딩 도구가 SW 패키지를 재사용·조합·확장할 때 먼저 읽는 안내서입니다. 패키지 자체에는 AI 기능이 없습니다. 아래 문서는 실제 공개 API와 CSS에서 확인한 값만 적습니다.

문서	내용
COMPONENT_CATALOG.md	공식 공개 컴포넌트(Header·개별 컨트롤·Popup·도구 막대)·Props·Callback·크기·CSS 의존성
DESIGN_RULES.md	SW 전용 토큰·Typography·간격·Hover/Focus/Selected·Overlay·Motion·반응형·Popup 외형·도구 버튼
COMPOSITION_PATTERNS.md	완성형·간소화·기능 중심·확장 Header, Popup(자유 콘텐츠), 파일 열기 + 도구 막대
examples/	공개 API만 쓰는 예제 A~F(E = 사용자 정의 Popup, F = 파일 열기 + 도구 막대. 독립 소비 프로젝트에서 Typecheck·Build·브라우저 검증), H = 뷰어 모드
VIEWER.md	뷰어 모드 전용: SWViewerHeader(데이터 메뉴·More·외곽선·로고 규칙), SWViewerMenu(Dropdown·서브메뉴·우클릭), SWViewerPanel(팝업 프레임 + 자유 콘텐츠). 일반 SW 모드는 SWHeader·SWPopup을 그대로 씁니다

1. 작업 순서 (필수)

1. 먼저 검색한다. 요청 기능을 COMPONENT_CATALOG.md의 공개 컴포넌트에서 찾는다.
2. 있으면 재사용한다(1순위). 완성형 Header가 필요하면 SWHeader 하나만 쓴다. 기존 Props(hiddenControls, menuOrder, controls, documentOpenPlacement, leading, tools, 각 데이터 배열·Callback)로 해결되는지 먼저 본다. 팝업·설정창은 SWPopup, 버튼·탭·토글은 SWToolButton / SWToolGroup이다.
   • Popup 요청은 이렇게 판단한다: ① SWPopup이 프레임(외형·닫기·Escape·스크롤)을 제공한다 → ② 내용은 children으로 자유 구성(구조 제한 없음) → ③ 행 모양은 SWPopupSection / SWPopupRow + SWHeaderInput → ④ SW에 없는 컨트롤은 @hm-design/ui를 children에 → ⑤ 프레임을 다시 만들거나 없는 Props(content, renderContent 등)를 추측하지 않는다.
3. 없으면 조합한다(2순위). 개별 공개 컴포넌트(SWHeaderHome, SWHeaderDocumentTitle, SWHeaderLayerMenu …)를 <SWTheme> 안에 배치한다. 배치용 CSS만 소비 프로젝트에 작성한다(COMPOSITION_PATTERNS.md).
4. 조합으로도 안 될 때만 새로 만든다(3순위). 새 컴포넌트는 소비 프로젝트에 작성하고, 공개 컴포넌트(예: SWHeaderInput)를 내부에 재사용하며, 외형은 공개 토큰 --hm-sw-header-*만 읽는다(DESIGN_RULES.md, 예제 D).
5. 새 디자인 값을 만들지 않는다. 크기·색·간격은 토큰과 DESIGN_RULES의 확인값만 쓴다. 값이 없으면 추측하지 말고 사용자에게 확인한다.
6. 존재하지 않는 API를 추측하지 않는다. 카탈로그와 dist/index.d.ts에 없는 Export·Props는 없는 것이다.
7. 패키지 코드를 복사하지 않는다. node_modules/@hm-design/sw/dist의 구현이나 hm-sw-* CSS 블록을 복사해 같은 컴포넌트를 다시 만들지 않는다.
8. 실제로 검증한다. 소비 프로젝트에서 tsc, Production Build, 브라우저 렌더링(Dropdown 열기·Callback·Focus)을 확인한 뒤 완료로 보고한다. 실행하지 않은 검증은 PASS로 적지 않는다.

2. 설치·Import 규칙

import { SWHeader, SWTheme, SWHeaderLayerMenu } from "@hm-design/sw"
import "@hm-design/sw/styles.css" // 앱 진입점에서 한 번

• 공식 진입점은 @hm-design/sw(JS·타입)와 @hm-design/sw/styles.css 두 개뿐이다. package.json의 exports가 다른 경로를 막는다.
• 금지: @hm-design/sw/src/..., @hm-design/sw/dist/components/... 같은 내부 경로 Import. dist에 내부 모듈의 .d.ts가 보여도 공개 API가 아니다.
• Peer: react, react-dom ^19.0.0. 런타임 dependency 없음. @hm-design/ui·조직도 패키지와 무관하다.
• SVG·PNG 자산은 JS에 data URI로 포함되어 별도 설정이 없다.
• 글꼴 파일은 포함하지 않는다. 앱에서 Noto Sans KR(400/500/700)을 로드한다(없으면 Malgun Gothic → Apple SD Gothic Neo).
• CSS는 전역(html, body, *)을 건드리지 않는다. body margin 등 페이지 기본값은 소비 앱이 정한다.
• TypeScript에서 CSS side-effect import 오류가 나면 Vite의 vite/client 타입을 포함한다.

3. 스타일 규칙

• SWHeader 밖에서 하위 컴포넌트를 쓰면 반드시 <SWTheme>로 감싼다. 토큰·글꼴·버튼 초기화가 이 범위에서만 적용된다.
• 소비 코드는 hm-sw-* class를 붙이거나 재정의하지 않는다. 배치는 자기 class(className)와 style로 한다.
• 외형 변경은 --hm-sw-header-* 토큰을 SWTheme/SWHeader의 style로 바꾸는 방법만 쓴다. 사용자 확정 면(파일명·객체 수정·속성 입력)은 기본값 유지를 권장한다.
• Light/Dark 분기는 없다. SW 디자인은 하나다.

4. 판단 기록 남기기

새 UI를 만들 때 결과 보고에 다음을 남긴다.

요청 항목	판단	근거
예: 레이어	재사용	SWHeaderLayerMenu
예: 검색	신규(소비 프로젝트)	카탈로그 MISSING. SWHeaderInput 재사용 + 토큰 기반 표면

새 컴포넌트를 SW 패키지 공식 컴포넌트로 승격할지는 별도 검토 대상이다. 임의로 패키지에 추가하지 않는다.