Private

Public Access

0 Fork 0

Files

T

shkim4 dc9258599c feat(chart): add @hm-design/chart package with Bar, Line, Donut, Pie, Radar, Area and Radial charts

- new workspace package packages/chart (shadcn/ui Chart + Recharts, HM Theme tokens), examples entry with sample data
- Storybook Chart group (src/chart), consumer example (examples/chart), build:chart / build:chart-example scripts
- README rewritten as the AI usage guide (install, CSS wiring, chart selection, data rules, verification)
- docs: package count/list, Submodule guide (chart workspace, React dedupe), shared AI_GUIDE row, MAINTAINING, story inventory

2026-11-06 15:52:47 +09:00

5.3 KiB

Raw Permalink Blame History

HMDesign 패키지 AI 지침 유지보수

이 문서는 HMDesign 저장소 유지보수자용이며 패키지에 포함되지 않습니다. 패키지에 포함되는 AI 지침은 소비 프로젝트의 AI 코딩 도구가 읽는 실행 규칙이므로, 코드와 다른 내용이 남지 않게 아래 절차로 함께 갱신합니다.

1. 구조

위치	역할	패키지 포함
`docs/ai/AI_GUIDE.md`	공통 진입점 원본(사용 유형 Web / SW 일반·뷰어 / OrgChart / 혼합 선택, 없는 컴포넌트 처리 3단계, 1~~7단계, 패키지·SW 모드 분리, 예시 A~~D, 소비 프로젝트 설정)	사본으로 포함
`docs/ai/AGENTS_SNIPPET.md`	소비 프로젝트 루트 `AGENTS.md`에 붙일 연결 문구 원본	사본으로 포함
`docs/ai/MAINTAINING.md`	이 문서	미포함
`packages/ui/ai/`	Web: `AI_USAGE`, `COMPONENT_CATALOG`, `DESIGN_RULES`, `COMPOSITION_PATTERNS`	포함(`files`)
`packages/sw/ai/`	SW: 위 4종(`AI_USAGE.md` §0 = SW 일반/뷰어 모드 선택) + 뷰어 모드 전용 `VIEWER.md` + 일반 모드 하단 막대 `FOOTER.md`(공유 사본 포함 Markdown 8개) + `examples/` 10개(A~G·I 일반 모드 — G 로고 클릭 메뉴, I Footer / H 뷰어 모드 / J 테마 설정)와 예제 보조 파일(`SWSearchControl.tsx`, `sample-data.ts`, `example-layout.css`, `sw-search-control.css`)	포함
`packages/org-chart/ai/`	OrgChart(Core + React 어댑터 API): 위 4종	포함
`packages/org-chart-react/ai/`	`AI_USAGE`(Core `ai/` 안내)	포함
`scripts/ai-docs.mjs`	동기화(`--sync`)·검사(`--check`)	—

@hm-design/center-graphic과 @hm-design/chart에는 ai/ 폴더가 없습니다(공통 가이드에 "README만"으로 안내). @hm-design/chart는 packages/chart/README.md가 설치·CSS 연결·차트 선택·Props·검증 지침을 겸하므로 차트 공개 Export·Props·기본값이 바뀌면 같은 Commit에서 README를 고칩니다(check:ai-docs는 chart README를 검사하지 않음). 추가하려면 같은 4종 구조로 만들고 scripts/ai-docs.mjs의 packages에 등록합니다.

저장소 루트 AGENTS.md·CLAUDE.md는 이 저장소를 개발하는 AI용 규칙이고, packages/*/ai/는 패키지를 설치해 쓰는 소비 프로젝트의 AI용 규칙입니다. 내용이 겹쳐도 서로를 대신하지 않습니다. 패키지 ai/ 문서는 패키지 밖(../../docs/…)을 링크하지 않습니다(설치 후 존재하지 않음).

2. 컴포넌트를 추가·수정할 때

같은 변경(같은 Commit)에서 처리합니다.

공개 Export가 바뀌면 해당 패키지 ai/COMPONENT_CATALOG.md에 이름·용도·HM Props(기본값)를 추가·수정·삭제합니다. 내부 전용 이름은 "공개하지 않은 것" 절에만 적습니다.
Props·Variant 기본값·허용 조합이 바뀌면 카탈로그 표와 COMPOSITION_PATTERNS.md의 예시 코드를 함께 고칩니다.
토큰·CSS 값이 바뀌면 DESIGN_RULES.md의 표를 실제 CSS 선언과 맞춥니다(값은 CSS에서 복사, 추측 금지).
새 화면 유형·조합 규칙이 생기면 COMPOSITION_PATTERNS.md §0 표에 행을 추가합니다. SW 뷰어 모드 컴포넌트(SWViewer*)를 바꾸면 VIEWER.md와 카탈로그의 뷰어 절을 함께 고치고, 일반/뷰어 모드 구분이 바뀌면 packages/sw/ai/AI_USAGE.md §0과 공통 AI_GUIDE.md 1단계·5단계를 같이 맞춥니다.
공통 규칙(유형·SW 모드 선택·혼합·보고 형식)이 바뀌면 docs/ai/AI_GUIDE.md만 고치고 npm run sync:ai-docs로 사본을 갱신합니다. 패키지 사본을 직접 고치지 않습니다.
npm run check:ai-docs를 실행해 PASS를 확인합니다.
버전을 올리면 카탈로그 첫 줄의 기준 버전을 같이 바꿉니다.

3. `npm run check:ai-docs`가 검사하는 것

docs/ai의 공유 파일과 각 패키지 사본이 같은지(줄바꿈 CRLF/LF 차이는 무시 — core.autocrlf=true에서 packages/sw만 .gitattributes로 LF checkout)
각 패키지 package.json의 files에 ai가 있는지
공개 진입점(src/index.ts 등, export * 재귀 포함)의 모든 Export 이름이 카탈로그에 나오는지
카탈로그에 Export처럼 보이지만(기존 Export 이름으로 시작) 실제로는 없는 이름이 없는지 — 예: DialogFancyPanel. "공개하지 않은 것"·"없는 것"·"지원하지 않는" 절은 제외
ai/ 문서의 상대 링크가 존재하고 패키지 밖(저장소 전용 문서)을 가리키지 않는지

검사하지 않는 것: Props 이름·기본값·토큰 값의 정확성, 예시 코드의 컴파일. 이 부분은 리뷰와 소비 프로젝트 검증(§4)으로 확인합니다.

4. 소비 프로젝트 검증 (배포 전 권장)

npm run build:packages 후 npm pack -w <패키지> --ignore-scripts --pack-destination <임시 폴더>
임시 소비 프로젝트(React 19 + Vite + Tailwind CSS 4)에 tarball 설치
node_modules/@hm-design/*/ai/AI_GUIDE.md가 있는지, 링크가 설치 위치에서 열리는지 확인
COMPOSITION_PATTERNS.md의 예시를 옮겨 tsc --noEmit·vite build·브라우저 렌더링 확인
결과와 NOT VERIFIED를 기록

npm pack의 prepack은 build를 다시 실행합니다. 공유 dist를 쓰는 build를 동시에 돌리지 않습니다.

5.3 KiB Raw Permalink Blame History