Private

Public Access

0 Fork 0

Files

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

4.7 KiB

Raw Blame History

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

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

문서	내용
COMPONENT_CATALOG.md	공식 공개 컴포넌트·Props·Callback·크기·CSS 의존성
DESIGN_RULES.md	SW 전용 토큰·Typography·간격·Hover/Focus/Selected·Overlay·Motion·반응형
COMPOSITION_PATTERNS.md	완성형·간소화·기능 중심·확장 Header 조합 방법
examples/	공개 API만 쓰는 예제 A~D(독립 소비 프로젝트에서 Typecheck·Build·브라우저 검증)

1. 작업 순서 (필수)

먼저 검색한다. 요청 기능을 COMPONENT_CATALOG.md의 공개 컴포넌트에서 찾는다.
있으면 재사용한다(1순위). 완성형 Header가 필요하면 SWHeader 하나만 쓴다. 기존 Props(hiddenControls, menuOrder, controls, 각 데이터 배열·Callback)로 해결되는지 먼저 본다.
없으면 조합한다(2순위). 개별 공개 컴포넌트(SWHeaderHome, SWHeaderDocumentTitle, SWHeaderLayerMenu …)를 <SWTheme> 안에 배치한다. 배치용 CSS만 소비 프로젝트에 작성한다(COMPOSITION_PATTERNS.md).
조합으로도 안 될 때만 새로 만든다(3순위). 새 컴포넌트는 소비 프로젝트에 작성하고, 공개 컴포넌트(예: SWHeaderInput)를 내부에 재사용하며, 외형은 공개 토큰 --hm-sw-header-*만 읽는다(DESIGN_RULES.md, 예제 D).
새 디자인 값을 만들지 않는다. 크기·색·간격은 토큰과 DESIGN_RULES의 확인값만 쓴다. 값이 없으면 추측하지 말고 사용자에게 확인한다.
존재하지 않는 API를 추측하지 않는다. 카탈로그와 dist/index.d.ts에 없는 Export·Props는 없는 것이다.
패키지 코드를 복사하지 않는다. node_modules/@hm-design/sw/dist의 구현이나 hm-sw-* CSS 블록을 복사해 같은 컴포넌트를 다시 만들지 않는다.
실제로 검증한다. 소비 프로젝트에서 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 패키지 공식 컴포넌트로 승격할지는 별도 검토 대상이다. 임의로 패키지에 추가하지 않는다.

4.7 KiB Raw Blame History