HMDesign/docs/sw/figma-additional/ai-home-menu-guide.md

AI 가이드 초안 — SW 로고 클릭 메뉴 (SWHomeMenu)

상태: 통합 전 초안입니다(Task B 2단계, 2026-10-19). 통합 승인 후 packages/sw/ai/COMPONENT_CATALOG.md·COMPOSITION_PATTERNS.md·DESIGN_RULES.md로 옮깁니다. 지금은 @hm-design/sw 진입점에서 export되지 않으므로 소스 경로 packages/sw/src/components/sw-home-menu를 사용합니다. 기준: Figma rj6wpsfk24lOWvWiVRAANP 26:10591(메뉴), 26:11355…26:11631(타일 15개), 26:12604…(섹션 제목), 662:67267·662:67331·662:67471(최근파일 하위 패널). 구현: SWHomeMenu.tsx, SWRecentFiles.tsx, theme/sw-home-menu.css.

1. 무엇인가

• SW Header의 로고(홈) 버튼을 누르면 Header 위에 겹쳐 나타나는 2단 메뉴입니다. 기본은 숨김이고, 로고를 다시 누르면 닫힙니다.
• 구성: 섹션(제목 badge + 타일 그룹) 여러 개 → 섹션마다 80 × 46 타일 여러 개. 타일 하나가 하위 패널(예: 최근파일 목록)을 열 수 있습니다.
• 운영체제 파일 선택창이 아닙니다. "찾아열기" 같은 항목의 실제 동작(파일 대화상자 등)은 host가 onSelect에서 수행합니다.

2. 최소 사용법

import { SWHeader, SWTheme } from "@hm-design/sw"
import { SWHomeMenu, type SWHomeMenuSectionData } from "@hm-design/sw" // 통합 후 경로

const sections: SWHomeMenuSectionData[] = [
  { id: "file", title: "작업중인 파일", items: [
    { id: "save", label: "저장", icon: <SaveIcon />, toggle: false, onSelect: () => host.save() },
    { id: "export", label: "내보내기", icon: <ExportIcon /> },
  ] },
]

function App() {
  const [open, setOpen] = useState(false)
  return (
    <div style={{ position: "relative" }}>
      <SWHeader onHomeClick={() => setOpen(v => !v)} /* 기존 props */ />
      {/* 통합 전: host가 위치를 지정합니다(Header 객체 수정 영역 왼쪽 - 2px, 창 영역 왼쪽까지). */}
      <div style={{ position: "absolute", top: 0, left: objectAreaLeft - 2, maxWidth: windowLeft - objectAreaLeft + 2, zIndex: 3 }}>
        <SWTheme><SWHomeMenu sections={sections} open={open} onOpenChange={setOpen} /></SWTheme>
      </div>
    </div>
  )
}

3. 데이터 규칙 (새 메뉴를 만들 때)

하고 싶은 것	방법
항목 추가	섹션 items에 { id, label, icon }을 추가합니다. 폭·구분선·모서리·섹션 폭은 자동입니다
섹션 추가	{ id, title, items }를 추가합니다. 제목 badge 폭은 글자 + 46px로 자동입니다
숨김	hidden: true. 자리를 남기지 않습니다
비활성	disabled: true. 기존 SW 규칙대로 opacity .4이며 Hover가 없습니다
실행만 하는 버튼	toggle: false. Active(Variant3)가 되지 않습니다
켜고 끄는 버튼	기본값(toggle 생략)입니다. 클릭하면 Active, 다시 클릭하면 Default입니다
Active 제어	activeIds + onActiveChange(controlled) 또는 defaultActiveIds. 하나만 켜려면 selection="single"
하위 패널	panel: <SWRecentFiles files={…} onFileOpen={…} />. 패널은 한 번에 하나만 열리고 열린 동안 하단 강조가 전체 외곽선이 됩니다
아이콘	currentColor SVG 하나를 권장합니다(Default #B6B4AF, Hover·Active #FF5C00 자동). 색이 고정된 이미지 쌍이면 hoverIcon을 함께 줍니다
이벤트	항목 onSelect(event) → 메뉴 onItemSelect(event). event.active는 클릭 후 상태입니다

4. 상태와 닫기 (Figma 기준 + 접근성 보완)

동작	결과	근거
로고 클릭	열기 / 다시 클릭하면 닫기	Figma btn_home ON_CLICK → OVERLAY, 재클릭 닫기는 사용자 확정
타일 Hover	Variant2: 주황 gradient 1px 테두리, 아이콘·글자 #FF5C00. 아이콘·글자 위치·크기는 Default와 같음(2026-10-20 사용자 확정: Figma의 1px 위·왼쪽 이동은 적용하지 않음)	Figma Default ON_HOVER → V2
타일 클릭	Variant3(Active, V2와 같은 모양) → 다시 클릭하면 Default	Figma V2 → V3 → Default
메뉴 빈 곳 클릭	닫기	Figma Group ON_CLICK → CLOSE (closeOnBackgroundClick)
Escape	열린 패널을 먼저 닫고, 다시 누르면 메뉴를 닫은 뒤 로고로 Focus 복귀	Figma 없음 · 접근성 (closeOnEscape)
메뉴 밖 클릭	기본은 닫지 않음	Figma overlay에 바깥 동작 없음 (closeOnOutsideClick)
←/→/Home/End	타일 사이 이동. 열린 패널 타일에서 ↓를 누르면 패널로 이동, ↑/↓로 행 이동, Enter로 파일 열기	Figma 없음 · 접근성
최근파일 행 선택	onFileOpen(file) 후 메뉴 닫기(closeOnOpen)	Figma 없음 · 검토 대상

5. 하지 말 것

• 타일·섹션·제목을 Figma 화면별로 따로 만들지 않습니다. 모든 메뉴는 sections 데이터 하나로 표현합니다.
• hm-sw-home-menu* class를 소비 코드에서 붙여 외형을 만들지 않습니다(className은 확장용입니다).
• 새 색·크기를 임의로 정하지 않습니다. 필요한 값은 --hm-sw-home-menu-*·--hm-sw-recent-files-* 토큰을 style로 덮어씁니다.
• Font Weight는 400/500/700만 씁니다(타일 라벨·파일명 700, 섹션 제목 400).
• 홈 버튼이나 창 영역을 메뉴 안에 다시 그리지 않습니다. 그것은 SWHeader가 담당합니다.