# Storybook UI 중심 간소화 (2026-10-22)

기준: `main` `aa8b7f8`. Storybook 전용 파일만 수정했습니다. 패키지 컴포넌트·공개 API·Theme Token·Story ID·export는 변경하지 않았습니다.

## 범위

- 조사: Story 파일 80개, Story 359개(사이드바 표시 83개, `verification`/`internal` 숨김 276개)
- 적용: 사이드바 표시 Story 83개
- 숨김 Story 276개는 테스트 기준 화면이므로 그대로 둡니다. 숨김 Story와 공유하는 State note(Input Readonly, Textarea Hover/Readonly, Progress, Table 등)도 유지합니다.

## 기준

| 유형 | 처리 |
|---|---|
| 상단 분류 라벨 `HM DESIGN SYSTEM / …` | 표시 Story에서 제거. `StoryPageHeader`의 `kicker`는 선택 Prop이 되었고 숨김 Story는 계속 전달합니다. |
| 섹션 제목을 반복하는 설명(`기본 Tooltip입니다.`, `side: …`, `className 확장입니다.`) | 제거 |
| 당연한 조작 안내(`버튼을 눌러 엽니다`, `포인터를 올려 확인합니다`) | 제거 |
| 긴 페이지·섹션 설명 | 핵심만 한 줄로 축약 |
| 내부 기술 설명(Figma 노드, 날짜, 내부 토큰명, CSS 파일명) | 화면에서 제거. 동작 상세는 `packages/sw/ai/COMPONENT_CATALOG.md`, `DESIGN_RULES.md`, `docs/components/*.md`에 이미 있습니다. |
| CENTER 반복 경계 안내(`CENTER_BOUNDARY`) | 한 줄로 축약하고 유지 |
| 필수 규격·제한(px 크기, 허용 조합, Hover 없음, 가상 데이터, 실제 인원 아님, 테스트 로고, 미확정 TBD/Candidate/Q3, 고정 날짜, GNB_ONLY Sidebar 금지) | 유지 |
| OrgChart 설명 | 제거하지 않고 축약만 합니다(verify-p8/p9가 `.sb-page-description`, `.sb-page-section-description` 스타일을 읽음). |
| SW 페이지 설명 | 기존 CSS가 이미 화면에서 숨기므로 표시 변화는 분류 라벨 제거뿐입니다. Home Menu만 소스 문구를 함께 축약했습니다. |

## 결과 (1440 × 900, 첫 UI 영역 상단 위치)

- 표시 설명 글자 수: 15,240 → 7,431
- 첫 UI 위치: 평균 28px 위로 이동(최소 24, 최대 81). Button 290 → 266, Dialog 290 → 234, Resizable 266 → 210, CENTER Overview 317 → 236, SW 페이지 234 → 210
- Story ID 359개는 변경 전후 동일합니다.

## 검증

- `tsc -p tsconfig.app.json --noEmit` PASS, `npm run test:guard` 94/94, `npm run check:ai-docs` PASS
- `build-storybook` 성공. Story 359개를 직접 URL로 렌더했을 때 오류 화면은 없었습니다. Avatar `all`·`fallback-error`의 404는 의도된 이미지 실패 예시이며 변경 전에도 같습니다.
- `packages/sw/tests/storybook-simplification.browser.mjs` 9/9 PASS
- `examples/org-chart/verify-p9.mjs`: 변경 전 빌드로 만든 로컬 기준에 대해 변경 후 67 PASS / 17 FAIL입니다. 변경 전 빌드도 같은 17건이 FAIL이므로 기존 이슈입니다.
- `packages/sw/tests/integrated-visual.browser.mjs` capture/compare: 숨김 검증 Story 6종(detail-buttons 등)은 동일합니다. 표시 Story(overview, logo-slot, responsive-more, property-panel-compare)의 차이는 모두 분류 라벨 제거에 따른 세로 이동(24px, Overview는 12px)이며 그 외 픽셀 차이는 없습니다. 시각 기준 이미지는 갱신하지 않았습니다.

## 추가 간소화 (da0e647 이후)

- **Expanded OrgChart (Preview first)**: 조직도 미리보기를 제목 바로 아래로 옮겼습니다. 1440 × 900에서 미리보기 시작 위치가 1103 → 177px입니다. 데이터·레이아웃·인터랙션 설정은 미리보기 아래에 그대로 둡니다. 설정 안내 문구(회사 숨김 동작, Hybrid/TB 조건, Compact 미지원, Pan·클릭 안내)와 섹션 설명은 제거했습니다. Pan·Alt+M 안내는 조직도 툴바가 이미 표시합니다. `OrgChartExampleCounts` 집계 문구는 화면에서 제거하고, OrgChart 브라우저 검증(P8, P9-2/3/4)이 읽는 `hidden` 데이터 hook으로만 남겼습니다. 숨김 legend 3개(데이터·레이아웃·기능 설정)와 Drag & Drop ON/OFF 글자도 제거했습니다. 적용 예정 상태는 직원 수를 바꾼 동안에만 표시합니다. 초기 보기는 기존 100% center를 유지하며 Fit to View로 전체를 볼 수 있습니다.
- **Tabs → Do / Don't**: UI 예시 없이 문단만 있던 섹션을 제거했습니다. 규칙은 [Tabs §16](../components/tabs.md)에 있습니다.
- **Button → States**: 대표 화면에서만 Brand / Standard 상태 설명 문단을 숨깁니다(Story 전용 `showNote`). 숨김 Story `States`·`StandardStates`는 문단을 유지하고, 규칙은 [Button](../components/button.md)과 UI AI 가이드에 있습니다. 모든 상태 버튼과 `Activated` 출력은 유지합니다.
- 검증: tsc PASS, `test:guard` 94/94, `check:ai-docs` PASS, Story 359개 렌더·ID 동일, SW simplification 9/9. Expanded 설정 조작(직원 수·데이터 적용·LR 전환·Drag & Drop·초기화) 9/9. OrgChart P9(67/17)와 P9-2(2/4)는 da0e647 빌드와 같은 FAIL 목록이므로 기존 이슈입니다.

## 추가 간소화 2 (2026-10-22~23)

대표 Story의 페이지·섹션 설명과 예시 캡션을 더 줄였습니다. 위 `기준` 표와 `추가 간소화`의 "유지" 항목 중 아래는 이번 변경으로 바뀌었습니다(위 기록은 당시 결과로 보존).

- 컴포넌트 44개·Pattern 대표 Story: `StoryPageHeader`·`StorySection` 설명과 State note를 제거했습니다. 값 표시(`value = …`, `slide n / 5`, `Activated: n`, 선택 경로)·캡션·규격 목록은 Story 전용 `showValue`/`showNote`/`showSpec`/`showCaption`으로 대표 화면에서만 숨기고 숨김 verification Story는 유지합니다. 변경 내용은 각 `docs/components/*.md`·`docs/patterns/*.md`의 Storybook 절에 반영했습니다.
- 숨김으로 옮긴 구역: Tabs `Default API` → `DefaultApi`, Filter Bar 입력/적용 조건 수 → `DraftApplied`(`scripts/verify-quality-reference.mjs`가 이 ID를 검사), Select 열린 목록 → 기존 숨김 `Open`. Toggle의 Controlled·className 확장 예시와 Filter Bar Usage / Do & Don't 문단은 제거했고 규칙은 각 문서에 있습니다.
- Checkbox·Switch·Radio Group Hover는 Storybook 전용 `data-sb-hover`로 고정해 보여 줍니다(컴포넌트 API 아님).
- Data Table 목록 검색 구역: 목록 제목을 Card 밖 PageHeader에서 같은 Card의 CardTitle로 옮겼습니다.
- CENTER: 반복 경계 안내(`CENTER_BOUNDARY`)와 페이지 설명을 화면에서 제거했고 `Overview`는 숨김(직접 URL 유지)으로 바꿨습니다.
- OrgChart: Overview·Full Composition·Expanded의 페이지·섹션 설명(가상 데이터 안내 포함)을 제거했습니다. Expanded는 Core 툴바 안내 문구를 Story 전용 stylesheet로 숨기며 기능은 그대로입니다([Expanded 사용법](../org-chart/expanded-usage.md)). `examples/org-chart/verify-p8.mjs`·`verify-p9.mjs`의 공통 스타일 비교에서 `.sb-page-description`은 기준 Pattern 화면과 OrgChart 화면 모두에 없습니다(양쪽 null). P8 `styles`의 Expanded 비교는 f4ddd5a 이후 Preview-only 구조(StorySection 없음)를 반영해 `.sb-page-section`·`-header`·`-title`이 **없어야** 하고 나머지 선택자는 Pattern 화면과 같아야 하도록 고쳤습니다. 2026-10-23 실행(6024 Storybook): P8 `styles` 8/8, `full-repair` 5/5(Expanded 수정 전 실행, 영향 없음), P9 `overview`·`department` 40/40 PASS, Console 오류 0.
- Story ID는 바뀌지 않았고 `DefaultApi`·`DraftApplied` 두 숨김 Story가 추가되었습니다.