shkim4/HMDesign
Private
Public Access
1
0 Fork 0
Code Activity
Files
5faa1f1ffe89eb7aeb4aaec81ac5bb2d0f4fced9
HMDesign/packages/sw/README.md
T
shkim4andClaude Opus 5.5 e27385e0f0 feat(sw): prepare reusable AI-friendly component package 
- Ship an AI guide in the package (ai/: usage rules, component catalog,
  design rules, composition patterns) via package.json files.
- Add examples A-D that import only public exports: default header,
  viewer header, feature header, and a consumer-side search extension
  that reuses SWHeaderInput and the public SW tokens.
- Add SW-only checks: docs/API consistency, tarball consumer project
  (React 19 + TS + Vite typecheck/build) and a browser check (27/27).
- No runtime source or public API change; README gains a pointer section.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-19 11:22:07 +09:00

94 lines
15 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# @hm-design/sw
> **현재 기준 색인(2026-10-19 1차 정리):** 아래 날짜별 안내는 작성 당시 기록입니다. 현재 기준은 [사용 가이드](../../docs/sw/sw-header-usage.md), [디자인 명세](../../docs/sw/sw-header-design-spec.md) 상단 색인, 속성 필드 13개 [검증 기록](../../docs/sw/sw-property-fields-verification-2026-10-19.md), 게이지·속성Bar [후속 4건 기록](../../docs/sw/sw-header-followup-four-design-fixes-verification-2026-10-19.md)·[Firefox 게이지 기록](../../docs/sw/sw-header-firefox-range-close-verification-2026-10-19.md)입니다. Storybook은 `SW / Header` 33개 Story이며 전체 목록과 2차 검토 대상은 [1차 정리 보고](../../docs/sw/sw-first-pass-cleanup-review-2026-10-19.md)에 있습니다.
> **3차 구현(2026-10-16):** `hiddenControls`(로고 외 모든 구성요소 개별 제거, 로고 필수), `menuOrder`(레이어·색상·선/문자/치수스타일 순서), 속성창 `shapeContent` Slot, 속성창 4상태 개별·비교 Story를 추가했습니다. 미지정 시 기존 디자인과 같습니다. [사용법](../../docs/sw/sw-header-usage.md#구성요소-표시메뉴-순서속성창-4상태형상-slot-2026-10-16-3차), [3차 검증 기록](../../docs/sw/sw-header-composition-shape-verification-2026-10-16.md).
> **후속 구현(2026-10-16):** 속성Bar(`SWHeaderPropertyBar`), 메뉴 단위 `controls` allowlist, Colorize 원본 Default/Hover를 추가했습니다. 상세 pill의 미사용 Stroke 선언·변수는 원본에서 제거했습니다. [사용법](../../docs/sw/sw-header-usage.md#후속-5개-요구사항-연결-2026-10-16), [새 검증 기록](../../docs/sw/sw-header-followup-five-verification-2026-10-16.md)을 따릅니다. 이전 설명과 PASS 로그는 보존합니다.
> **최신 추가 구현(2026-10-16):** 상세 5개 Hover·색상 기준 필수 선택·목록 Hover/Selected 통일·데이터 기반 속성창·K 가이드 반복을 제공합니다. 아래 추가 연결과 [현재 검증 보고](../../docs/sw/sw-header-additional-verification-2026-10-16.md)를 따릅니다. 아래의 이전 Hover 없음·일반 자기 색 Stroke 설명은 추가 기준으로 대체됩니다.
HM Design System의 SW(설치형·도면 SW) 전용 React 컴포넌트 패키지입니다. `@hm-design/ui`와 독립적으로 빌드·배포·사용하며 서로 의존하지 않습니다.
현재 포함: **SW Header** (Figma `rj6wpsfk24lOWvWiVRAANP` node `26:8944` `header_green`), `SWTheme`.
```tsx
import { SWHeader } from "@hm-design/sw"
import "@hm-design/sw/styles.css"
<SWHeader documentTitle="C0020101-006-평면및종단면도(06)" logoSrc={productLogo} logoAlt="제품명" onClose={closeWindow} />
```
- 로고는 확정 디자인이 아닙니다. 로고 영역 배치는 공통이고 로고 이미지는 각 SW 프로그램이 `logoSrc` 또는 `logo`로 전달합니다. 패키지에는 로고가 없으며, 전달하지 않으면 로고 없이 표시됩니다.
- 파일명을 클릭하면 문서 Dropdown(Figma 26:10662)이 열립니다. 목록은 `documents`, 선택·New·Open은 Callback으로 각 프로그램이 연결합니다(`documents` 미전달 시 Dropdown 없음).
- 레이어 필드를 클릭하면 레이어 Dropdown(Figma 26:10940, 갈색 목록·주황 행 Hover)이 열립니다. 목록은 `layers`(`id`, `name`, `color`, `visible`, `frozen`, `locked`, `disabled`), 현재 레이어는 `activeLayerId`이며 선택은 `onLayerSelect`, 전구·눈꽃·자물쇠는 `onLayerVisibilityChange` / `onLayerFreezeChange` / `onLayerLockChange`, 하단 버튼은 `onLayerDetail`로 각 프로그램이 연결합니다. 아이콘은 데이터만 반영하며 실제 표시·동결·잠금은 호스트가 처리합니다(`layers` 미전달 시 기존 필드 버튼). 확정 매핑: 전구 컬러 `visible=true`·회색 `false`, 눈꽃 컬러 `frozen=false`·회색 `true`, 자물쇠 컬러 `locked=false`·회색 `true`이며 클릭 시 각 boolean의 반전값을 전달합니다([명세 §5.2](../../docs/sw/sw-header-design-spec.md#52-레이어-dropdown-figma-headermenu레이어-2610940-2026-10-16), [검증 기록](../../docs/sw/sw-header-layer-dropdown-verification-2026-10-16.md)).
- Hover는 Figma 홈 버튼의 노란 gradient 1px 테두리를 SW Header의 테두리 있는 버튼에 공통 적용합니다(디자인 명세 §11.1).
- 창 이동 Hover Motion은 GIF의 경로를 유지하고 후속 사용자 요청으로 1.64 → **1.4초**로 단축했습니다. 커서 상승 → 약 444ms 문구 등장 → 오른쪽 위로 이동 → 약 888ms부터 512ms 유지 → 반복입니다. 기존 SVG·줄무늬·Tooltip·`onWindowMoveStart`·Drag 중 정지·Reduced Motion·88px/24px/숨김 정책은 유지합니다. 실제 창 이동은 호스트 책임이며 [사용 가이드 §10.2](../../docs/sw/sw-header-usage.md#102-창-이동-hover-motion), [현재 검증 기록](../../docs/sw/sw-header-speed-composed-hover-verification-2026-10-16.md)을 따릅니다.
- 그룹 필드 Hover는 텍스트와 선/폰트/치수 미리보기를 `#FFC600`으로 표시합니다. 기존 Gradient Border·검정 외곽선·색상 견본·레이어 상태·Disabled/Selected 정책을 유지하며 상세보기는 기존 텍스트 전용 Hover 그대로입니다([명세 §11.5](../../docs/sw/sw-header-design-spec.md#115-현재-추가-기준--1400ms-및-그룹-필드-hover-2026-10-16)).
- 색상·선스타일·문자스타일·치수스타일 Dropdown(2026-10-16, Figma 26:10986 / 26:11036 / 26:12666 / 26:12659 / 26:11104 / 26:10702 / 26:11181 / 26:11215): `colors`·`userColors`·`colorMode`, `lineTypes`·`lineWeights`, `textStyles`, `dimensionStyles`를 주면 각 필드가 Dropdown이 됩니다(주지 않으면 기존 버튼). 모든 항목은 `id` 기반 배열 Props이며 추가·삭제·이름/값 변경·재정렬에 소스 수정이 필요 없습니다. 선택·입력은 `onColorSelect` / `onColorModeChange` / `onColorInput` / `onColorPick`, `onLineTypeSelect` / `onLineWeightSelect` / `onLineWeightValueChange` / `onLineScaleChange`, `onTextStyleSelect`, `onDimensionStyleSelect`, 하단 `… 상세`는 `on*Detail`로 각 프로그램이 연결합니다(상세 팝업은 미제공). Dropdown 안 독립 버튼은 Hover 효과가 없고 목록 행·Input은 Figma Hover를 유지합니다(이후 2026-10-16 추가 수정: ByLayer/ByBlock·`… 상세` 버튼은 Figma Hover 적용, 색상 추출은 Colorize Hover, 색상 칩은 Hover 없음)([명세 §5.3](../../docs/sw/sw-header-design-spec.md#53-색상--선스타일--문자스타일--치수스타일-dropdown-2026-10-16), [사용 가이드 §7](../../docs/sw/sw-header-usage.md#색상--선문자치수스타일-dropdown-예-2026-10-16)).
```tsx
<SWHeader
documentTitle={fileName}
color={color} colors={palette} userColors={userColors} colorMode={colorMode}
onColorSelect={option => applyColor(option)} onColorModeChange={setColorMode} onColorInput={({ hex }) => applyHex(hex)}
lineStyle={lineStyle} lineTypes={lineTypes} lineWeights={lineWeights}
onLineTypeSelect={type => setLineStyle(s => ({ ...s, name: type.name }))}
textStyle={textStyle} textStyles={textStyles} onTextStyleSelect={style => setTextStyle(style)}
dimensionStyle={dimensionStyle} dimensionStyles={dimensionStyles} onDimensionStyleSelect={style => setDimensionStyle(style)}
/>
```
- 반응형 More: 좁은 헤더에서 더보기의 필드를 고르면 그 필드가 첫 칸(레이어 자리)에 표시되고 Dropdown이 바로 아래 열립니다. 레이어는 더보기에서 다시 고를 수 있으며, 전환은 UI 상태라 데이터 Callback을 호출하지 않습니다([명세 §5.4](../../docs/sw/sw-header-design-spec.md#54-반응형-more--대표-필드-전환-2026-10-16)).
- Text Stroke: Figma에 Stroke가 있는 텍스트만 검정 외곽선(14·16px 1.3px, 12px 1px)을 표시합니다. 자기 색 0.3px Stroke는 2026-10-16 추가 수정으로 제거했습니다. 더보기·Tooltip·`+ New`/`Open`은 제외([명세 §6.1](../../docs/sw/sw-header-design-spec.md#61-text-stroke-2026-10-16)).
- `SWHeaderInput`: 레이어 상세 등 상세 영역에서 쓰는 수정 가능 Input(Figma 26:11656, Default / Hover / 편집, caret `#E60403`). `value`(확정값) · `onValueChange`(임시값) · `onCommit`(Enter·Focus 이동, 유효 + 변경 시) · `onCancel`(Escape) · `valueType`(`text` / `number`) · `parse` · `readOnly` · `disabled`([명세 §5.5](../../docs/sw/sw-header-design-spec.md#55-레이어-상세-버튼--수정-가능한-input-2026-10-16)).
- Peer: `react`, `react-dom` `^19.0.0`. 런타임 dependency는 없습니다.
- 출력: `dist/index.js`(ESM, Figma SVG asset은 data URI로 포함, 임시 Figma URL 없음), `dist/*.d.ts`, `dist/styles.css`.
- CSS는 자동 import되지 않습니다. `@hm-design/sw/styles.css`를 한 번 import합니다.
- Registry에는 아직 게시하지 않았습니다. 설치·사용·Props는 [사용 가이드](../../docs/sw/sw-header-usage.md), 디자인 기준은 [디자인 명세](../../docs/sw/sw-header-design-spec.md)를 따릅니다.
```bash
npm run build -w @hm-design/sw
npm run typecheck -w @hm-design/sw
```
## 추가 연결: 속성창·K 가이드 (2026-10-16)
- `SWHeaderPropertyPanel` 및 property/group/selection 타입을 공개합니다. `SWHeader.propertyPanel`에 외부 데이터를 전달하면 기존 속성창 버튼·More와 연결됩니다.
- `propertyPanelOpen/onPropertyPanelOpenChange`로 Controlled 열림을 지원하며, 생략하면 내부 열림 상태를 사용합니다. 기존 `onPropertyPanelToggle`을 보존합니다.
- Text/Number/Select/Color/Slider/Computed, id 기반 동적 항목, 검증·확정·취소·외부 변경·ReadOnly/Disabled·그룹 펼침을 지원합니다. CAD 계산·선택·객체 변경은 호스트가 담당합니다.
- 상세 5개는 Figma 고정 크기와 Hover를 적용합니다. ByLayer/ByBlock은 정확히 하나가 표시되며, 기존 null 직접 색상 의미는 보존합니다. 레이어/선/문자/치수 목록은 Hover와 Selected 디자인이 같습니다.
- K는 기존 버튼을 재사용하고 원본 이미지 Pan/Zoom을 반복합니다. 640px 미만에서는 기존 More 항목에서도 같은 가이드를 표시합니다. Reduced Motion은 정적 이미지이며 기존 창 이동 1400ms는 유지합니다.
- 지정된 일반 text-stroke-width 선언·변수는 제거했고 검정 text-shadow와 상세 pill의 별도 Stroke는 보존했습니다(상세 pill Stroke도 아래 후속 5개 요구사항에서 제거됨).
- 사용 예시와 API는 [가이드 추가 절](../../docs/sw/sw-header-usage.md#속성창k-가이드-추가-연결-2026-10-16), 디자인 값은 [명세 추가 절](../../docs/sw/sw-header-design-spec.md#추가-수정-기준--속성창k-가이드-2026-10-16)을 확인하세요.
- 검증: 기존 17 + 신규 4 Story, [현재 실행 결과 및 NOT VERIFIED](../../docs/sw/sw-header-additional-verification-2026-10-16.md). 과거 로그는 보존합니다.
## 후속 5개 요구사항 API (2026-10-16)
- `SWHeaderPropertyBar` / `SWHeaderPropertyBarProps`를 공개합니다. `propertyBar`로 selection/properties/onPropertyChange와 readOnly/disabled를 전달합니다. 속성창과 SWHeaderProperty/Selection 데이터를 공유하며, `propertyBarOpen/defaultPropertyBarOpen/onPropertyBarOpenChange`는 별도의 표시 상태입니다. 최대 폭 1222·높이 28px이고 Header 49px 아래에 표시됩니다.
- `SWHeaderControlId` / `SWHeaderControlConfig` / `SWHeader.controls`는 메뉴 자체의 전체 allowlist입니다. undefined는 기존 기본 구성, []는 선택적 컨트롤 없음입니다. id/visible/label과 배열 순서로 제거·복원·변경·재배치하며 More도 동일 구성을 따릅니다. 내부 옵션 배열·선택값 Props는 그대로입니다.
- Text Stroke Story의 지정 원본 이미지 블록·전용 import를 제거했습니다. 원본 PNG와 다른 비교 Story는 보존합니다.
- 상세 span의 `-webkit-text-stroke-width`와 미사용 `--hm-sw-header-solid-stroke-width`를 src/theme/sw.css에서 제거했습니다. build는 이 원본에서 dist/styles.css를 만드므로 dist만 편집하지 않습니다. 검정 text-shadow·SVG Stroke·상세 Hover는 보존합니다.
- 색상 추출 버튼은 로컬 Figma Default/Hover SVG를 사용합니다(24px/18px). 기존 `onColorPick`은 그대로이며 Hover는 Callback을 실행하지 않습니다. `26:11338` 돋보기 Overlay는 호스트 연동 대상입니다.
- Storybook은 기존 21개와 신규 Property Bar / Dynamic Controls / Colorize, 총 24개입니다. [최신 검증 기록](../../docs/sw/sw-header-followup-five-verification-2026-10-16.md)을 참조하세요.
## 3차 API (2026-10-16)
- `SWHeader.hiddenControls?: readonly SWHeaderHideableControlId[]` — `SWHeaderControlId` + `SWHeaderFrameControlId`(`home` / `windowMove` / `minimize` / `close`). 로고는 항상 표시하며 `home` 제거 시 정적 로고입니다. 제거한 요소는 공간·Popup·Callback이 없습니다.
- `SWHeader.menuOrder?: readonly SWHeaderMenuId[]` — 5개 유사 메뉴끼리만 순서 변경. 지정 id 우선, 누락 id는 기본 순서로 뒤에, 중복·알 수 없는 id 무시. More 목록도 같은 순서입니다.
- `SWHeaderPropertyPanelProps.shapeContent?: SWHeaderPropertyShapeContent` — `undefined` Figma 원형, `null`/`false` 빈 208×208 영역, ReactNode 또는 `(context: SWHeaderPropertyShapeContext) => ReactNode`. `SWHeader.propertyPanel`로도 전달됩니다.
- 하위 공개 컴포넌트에 선택적 표시 Props 추가(기본 true): `SWHeaderHome.interactive`, `SWHeaderProperties.showCaption/showBar/showPanel`, `SWHeaderActions.showPrint/showPopupGuide`, `SWHeaderWindowControls.showWindowMove/showMinimize/showClose`.
- Storybook: 기존 24개 + Composition, Property Panel 개별 4개, 4개 비교, 형상 Slot = 31개.
## 속성 필드·게이지 (2026-10-19)
- 속성창 공통 행은 Figma 26:12388 ~ 26:12649의 Default / Hover / On을 따릅니다. 숫자는 편집 On(`#0F0D0A`), 레이어·선스타일·색상은 Dropdown On(`#211D13`)이며 하이퍼링크·재료는 Default·Hover만 있습니다.
- 추가 API(모두 선택): `SWHeaderProperty.picker`(`"layer" | "lineStyle" | "color" | false`), `SWHeaderProperty.decimals`, `SWHeaderPropertyPanelProps.menus`(`SWHeaderPropertyMenus`). 필드 Dropdown은 Header Dropdown과 같은 목록 컴포넌트를 씁니다. [사용법](../../docs/sw/sw-header-usage.md#속성창k-가이드-추가-연결-2026-10-16), [검증 기록](../../docs/sw/sw-property-fields-verification-2026-10-19.md).
- 투명도 게이지는 빨강 채움 + 베이지 Track이며 Chrome·Firefox가 같은 그림을 씁니다([Firefox 게이지 기록](../../docs/sw/sw-header-firefox-range-close-verification-2026-10-19.md)).
## AI 코딩 도구용 가이드 (2026-10-19)
다른 프로젝트에서 AI 코딩 도구가 이 패키지를 재사용·조합·확장할 때는 설치된 패키지의 `ai/` 폴더를 먼저 읽습니다: [AI_USAGE.md](./ai/AI_USAGE.md)(작업 순서·Import 규칙) → [COMPONENT_CATALOG.md](./ai/COMPONENT_CATALOG.md)(공개 API) → [DESIGN_RULES.md](./ai/DESIGN_RULES.md)(토큰·상태·Motion) → [COMPOSITION_PATTERNS.md](./ai/COMPOSITION_PATTERNS.md)(조합 방법) → [examples/](./ai/examples)(공개 API만 쓰는 예제 A~D). `ai/`는 npm 패키지(`files`)에 포함됩니다. 런타임 API는 바뀌지 않았습니다.
View Git Blame Copy Permalink