fix(sw): add default tooltip for pill tool buttons

- SWToolButton appearance="pill": a non-blank string children is also
  the native title; an explicit title wins and title="" turns it off;
  numbers, JSX and arrays are never converted. text / document keep
  passing only the given title. Accessible name, DOM and classes unchanged
- DESIGN_RULES §15: Header UX principles (ellipsis full text, icon-only
  tool buttons, print class shared by pill, font-dependent widths, scope)
- Reference them from DESIGN_RULES §3·§9, COMPONENT_CATALOG §4·§11,
  AI_USAGE §5.4, SW Header spec §17 and Step Header spec §12

packages/sw/ai/DESIGN_RULES.md

@@ -50,7 +50,7 @@
 | Weight | 400, 500, 700만 사용(600 없음). SWHeader 안의 필드 값(레이어·색상·선스타일·가중치·스케일·문자/치수스타일 값)은 400(14px · 자간 0.56px), Composed Controls(SWHeader 밖 단독 메뉴)의 필드 값은 700(2026-10-20). 파일명·제목·토글·버튼·메뉴 글자 700 |
 | 자간 | 값 0.04em, 라벨 0.02em, 파일명 0.06em |
 | Text Stroke | Figma Stroke가 있는 텍스트만 검정 외곽선: 14·16px `--hm-sw-header-text-outline`(1.3px), 12px `--hm-sw-header-label-outline`(1px). 자기 색 Stroke 없음. More·Tooltip·`+ New`/`Open` 제외 |
-| 말줄임 | 값은 한 줄 `ellipsis`, `title`로 전체 표시 |
+| 말줄임 | 값은 한 줄 `ellipsis`, `title`로 전체 표시. 적용 범위·키보드·터치 기준과 Header별 현재 구현은 §15.1 |
 
 ## 4. 상태
 
@@ -127,6 +127,7 @@
 | `pill` | 인쇄·K: pill(`rgba(0,0,0,.8)`, 1px `#092920`, radius 4px) 안 40 × 38 버튼, 아이콘 영역 24 × 23 | Hover 노란 gradient 링 + `hoverIcon`(생략 시 기본 아이콘 유지). 아이콘 색은 기존 인쇄 아이콘 `#B6D0C9` → Hover `#FFC600`(`--hm-sw-header-selected-color`) — 인쇄 이미지 두 장의 색입니다. `currentColor` 아이콘은 상속 글자색이며 Hover에서 바뀌지 않고 `pressed`만 `#FFC600`(링·`hoverIcon` 전환 없음). Process Header `tools`는 §14, 상태 비교는 [AI_USAGE.md](./AI_USAGE.md) §5.4 |
 | `document` | 파일명 면: 48px, gradient 표면, 위·오른쪽·아래 1px gradient 테두리(`--hm-sw-header-document-border-gradient`), 글자 `#F0F7F5` 700 · 자간 0.06em | 글자만 Hover `#FFC600`. Home 바로 뒤면 로고 사선 접점 공유, 그 뒤 파일명은 왼쪽 여백 12px |
 
+- 아이콘 전용 `pill`의 이름·툴팁 기준은 §15.2, `pill`이 인쇄 버튼 class를 공유하는 구조는 §15.3입니다.
 - 이 절은 상태 값만 정합니다. 디자인 시안의 아이콘을 어디서 가져올지(제공 에셋 → 공개 Export → 미지원 보고)와 시안에 없는 창 제어 버튼 생략은 [AI_USAGE.md](./AI_USAGE.md) §5입니다(§14 Process Header 도구 pill에도 적용).
 
 ## 10. 새 컴포넌트 체크리스트
@@ -259,3 +260,44 @@
 | 탭 | 높이 25, 글자 폭 + 25(padding 13 / 12), 14px 700, 간격 0. 모서리: 단독 50, 첫 50 0 0 50, 마지막 0 50 50 0, 가운데 0. 좁으면 선택 탭 포함 비례 축소 + `…`. 화살표 칸·그룹 사이 36 고정. 그룹 접기·좌우 스크롤·More 없음(넘침 정책 확정 2026-11-03) | — |
 | 탭 상태 | 기본(미진행) 70% `rgba(52,143,114,.8) → rgba(2,50,35,.8)` · `#0C3125`. 밝음(켜진·진행 완료) 100% `rgba(68,178,143,.8) → rgba(0,61,41,.8)` · `#0A5940`. 선택 `#113228 → #28735C`(아래 → 위) · `#001E15` · 안쪽 그림자, 글자 `#FFC600`. Disabled 50% 속성 필드 면 · `#021912`, 글자 `#7D9F91`. 공통 그림자 `1px 1px 1px rgba(31,148,113,.7)`. Hover 글자 `#FFC600`, Focus 2px `#F0F7F5` | `--hm-sw-process-multi-tab-*`, `--hm-sw-header-property-background` |
 - 새 프로세스 UI는 위 토큰을 `var(--…)`로 읽고 `hm-sw-process-*` class를 쓰거나 덮어쓰지 않습니다.
+
+## 15. Header 공통 UX·레이아웃 원칙 (`SWHeader` · `SWViewerHeader` · `SWProcessHeader`, 2026-11-05)
+
+세 Header와 그 안의 SW 도구 버튼에 공통으로 적용합니다. 크기·반응형·말줄임 시점 같은 Header별 값은 각 절(§7 SWHeader, §11·[VIEWER.md](./VIEWER.md) 뷰어, §14 Process)과 디자인 명세를 따르며 이 절은 그 정책을 바꾸지 않습니다. "현재 구현"은 소스 기준 사실이고, "개선 필요"는 아직 구현되지 않은 권고입니다(구현 완료가 아님).
+
+### 15.1 말줄임 텍스트의 원문 확인
+
+- 말줄임 때문에 전체 내용을 알 수 없는 텍스트(파일명·단계명·그룹명·값 등)에는 원문을 확인할 수단을 둡니다. 기본 수단은 그 요소나 버튼의 `title`이고, SW 툴팁(창 이동·K 가이드 등)은 해당 컴포넌트에 이미 있는 경우에만 씁니다. 모든 텍스트에 툴팁을 일괄로 붙이지 않습니다.
+- 기존 접근성 이름(`aria-label`, 연결된 label)은 원문 그대로 유지합니다. 툴팁은 접근성 이름을 대신하지 않습니다.
+- `title`은 마우스 Hover에서만 보이고 키보드 Focus·터치에서는 표시되지 않습니다. 키보드·터치 사용자에게도 원문이 필요한 곳은 다른 확인 경로(목록·More·Popup 등)나 Focus 표시를 컴포넌트별로 검토합니다. 현재 공통 구현은 없습니다.
+- 잘렸을 때만 `title`을 붙이는 방식은 `SWFooterToolButton`에 선례가 있습니다(Hover·Focus 때 실제 폭을 측정하고, 전달된 `title`이 없을 때만 적용). 적용 여부는 컴포넌트별로 판단합니다.
+
+| Header | 현재 구현: 원문 `title` 있음 | 개선 필요: 말줄임되지만 `title` 없음(접근성 이름은 원문) |
+|---|---|---|
+| `SWHeader` | 파일명, 문서 목록 항목(`title ?? name`), 필드 값, 문자스타일 글꼴명, 레이어 목록 이름, 속성Bar 객체명 | 메뉴 타이틀(필드 12px 라벨, 버튼 `aria-label`) |
+| `SWViewerHeader` | 파일명(`documentTooltip`, 기본 이름), 상태 표시(`detail`), 아이콘만 남은 버튼·토글(`title ?? label`) | Model / Layout 탭 이름(`option.title`을 줄 때만), 아이콘만 남은 `menu` 항목(`item.title`을 줄 때만), 말줄임된 일반 항목 라벨 |
+| `SWProcessHeader` | 파일명, Layer 값(`layer.value`) | 단계 탭 이름, `multi` 그룹 제목(그룹 이름은 `aria-describedby`로 연결) |
+
+### 15.2 아이콘 전용 도구 버튼
+
+- 아이콘만 보이는 버튼은 의미를 식별할 수 있는 접근성 이름이 있어야 합니다. `SWToolButton appearance="pill"`은 `children`을 시각적으로 숨긴 글자(`hm-sw-tool__label`)로 그려 접근성 이름으로 씁니다(또는 `aria-label`).
+- **현재 구현(`SWToolButton` 자동 툴팁, 2026-11-05):** `appearance="pill"`만 적용합니다. 우선순위는 ① 명시한 `title`(`title=""`이면 툴팁 없음 — 공식 비활성화 방법) → ② 공백이 아닌 문자열 `children`을 원문 그대로 `title`로 사용 → ③ 툴팁 없음입니다. 빈 문자열·공백만 있는 문자열·숫자·JSX·배열(`{label} 보기`처럼 값을 이어 쓴 JSX 포함) `children`은 문자열로 변환하지 않아 툴팁이 생기지 않으므로, 이때는 템플릿 문자열(`` {`${label} 보기`} ``)이나 `title`을 씁니다. `text`·`document`는 전달한 `title`만 그대로 붙입니다(자동 툴팁 없음). 접근성 이름(`children`·`aria-label`·`aria-labelledby`)과 클릭·키보드 동작, DOM·class는 그대로입니다. `aria-label`과 `children`이 다르면 툴팁은 `children`, 접근성 이름은 `aria-label`입니다.
+- `SWProcessSplitButton`은 `label`(기본 `화면 분할`)을 `children`과 `title`에 함께 전달합니다. SWHeader의 인쇄·창 버튼과 Process 창 버튼은 `SWToolButton`이 아니며 `aria-label`만 있고 `title`이 없습니다(창 이동은 SW 툴팁).
+- Hover 툴팁은 보조 수단이며 접근성 이름·Focus 표시·키보드 동작을 대신하지 않습니다. 자동 툴팁도 네이티브 `title`이라 키보드 Focus·터치에서는 보이지 않습니다(§15.1, 미해결). 툴팁을 더할 때 기존 `aria-*`와 클릭·Enter·Space 동작을 바꾸지 않습니다.
+
+### 15.3 CSS 클래스 역할 구분
+
+- 여러 버튼이 공유하는 외형(공통)과 특정 기능 전용 스타일은 class 이름으로 구분합니다. 기능 이름이 붙은 class를 다른 기능의 버튼이 재사용하면 그 class의 변경·선택자가 모든 사용처에 영향을 주므로, 변경 전에 사용처(TSX·CSS·테스트·QA baseline)를 검색합니다.
+- **현재 구조:** `hm-sw-header__action--print`는 SWHeader 인쇄 버튼(`SWHeader.tsx`, `SWHeaderActions.tsx`)과 `SWToolButton appearance="pill"`(→ `SWHeader`·`SWProcessHeader`의 `tools`, `SWProcessSplitButton`)에 함께 붙습니다. pill 버튼의 1px 테두리·radius·파일명 면 배경은 이 class에서 오고, `> img` 아이콘 위치 규칙은 `<img>`를 직접 자식으로 둔 인쇄 버튼에만 맞습니다(pill은 `.hm-sw-tool__icon`). Process는 `.hm-sw-tool__pill-button`으로 자기 값을 덮습니다. `tests/header-composition.browser.mjs`(인쇄 버튼 수)와 `docs/sw/detail-button-qa/baseline.json`도 이 class를 기준으로 삼습니다.
+- 소비 코드는 이 class로 인쇄 버튼을 찾거나 덮지 않습니다(§10-6). 공통 pill 외형 class와 인쇄 전용 class의 분리는 class·선택자·테스트 baseline이 함께 바뀌는 별도 구현 과제입니다.
+
+### 15.4 글꼴에 따른 실제 텍스트 폭
+
+- 로고 폭 원칙은 §1 "로고 확장 공통 원칙"을 따르며 여기서 반복하지 않습니다. 이 절은 글꼴 차이만 다룹니다.
+- 텍스트 로고·파일명·탭·필드 값처럼 폭이 내용에 따라 정해지는 영역은 실제 렌더링 글꼴에 따라 폭이 다릅니다. §3의 SW 기본 글꼴은 앱이 글꼴 파일을 로드할 때 기준이며, 소비 프로젝트가 Noto Sans KR을 로드하지 않았거나 다른 글꼴을 지정하면 대체 글꼴로 그려져 글자 폭·말줄임 시점·홈 폭이 문서 실측값과 달라질 수 있습니다.
+- 문서의 px 실측(예: §14·[COMPONENT_CATALOG.md](./COMPONENT_CATALOG.md)의 Process 로고 칸 값, HMDesign 저장소 Process 명세의 StrAna·Accessway 값)은 해당 글꼴·브라우저·당시 Commit 기준의 검증 사례이며 고정 규격이나 디자인 토큰이 아닙니다. 새 로고 이름이나 글꼴마다 고정 폭·예외를 추가하지 않고, 내용 폭을 따르는 기존 구조와 Header별 최소 폭으로 처리합니다.
+- 폭을 검증할 때는 글꼴이 실제로 로드됐는지 확인하고, 다른 글꼴 환경의 결과는 글꼴 이름을 함께 기록합니다.
+
+### 15.5 공통 규칙으로 강제하지 않는 사항
+
+- 단계 수·이름 길이에 따른 말줄임, 선택 단계 최소 폭, 권장 화면 폭, 단계 축소·More·스크롤은 `SWProcessHeader` 고유 검토 항목입니다(현재 동작은 [COMPONENT_CATALOG.md](./COMPONENT_CATALOG.md) 11절 반응형, 검토 기록은 HMDesign 저장소 `docs/sw/sw-process-header-design-spec.md` §12). 다른 Header에 같은 기준을 적용하지 않습니다.