shkim4
fb74cd756f
- Shared entry point docs/ai/AI_GUIDE.md (type selection Web / SW / OrgChart / mixed, steps 1-7, package style separation, report format, examples A-D) and AGENTS_SNIPPET.md, copied into every package ai/ folder - New ai/ docs for @hm-design/ui and @hm-design/org-chart (+ org-chart-react pointer): AI_USAGE, COMPONENT_CATALOG, DESIGN_RULES, COMPOSITION_PATTERNS - SW ai/ linked to the shared guide; catalog lists every Props type explicitly - "ai" added to package files of ui, org-chart, org-chart-react - scripts/ai-docs.mjs: sync:ai-docs / check:ai-docs (copies, files, catalog <-> exports, links) - Maintenance guide and verification record under docs/ai
5.3 KiB
5.3 KiB
@hm-design/ui — AI 코딩 도구 사용 안내 (Web UI)
먼저 AI_GUIDE.md(공통 1~7단계)를 읽고 사용 유형이 Web 또는 Web이 포함된 혼합일 때 이 폴더를 씁니다. 이 폴더(node_modules/@hm-design/ui/ai/)의 내용은 @hm-design/ui 0.1.0의 공개 Export(src/index.ts → dist/index.d.ts)와 theme.css에서 확인한 값만 적습니다.
| 문서 | 내용 |
|---|---|
| COMPONENT_CATALOG.md | 공개 컴포넌트 44종·Pattern 8종·Theme API, HM 전용 Props·Variant |
| DESIGN_RULES.md | 실제 토큰(--hm-sem-* 등), 색·Typography·크기·상태·스크롤바·Overlay 규칙 |
| COMPOSITION_PATTERNS.md | 화면 유형별 조합(목록·Form·Dashboard·확인창·측면 상세)과 Navigation 단일 모드 |
1. 작업 순서 (필수)
- Pattern을 먼저 본다. 화면 단위 요구(목록 검색, 상단/좌측 메뉴, Dashboard, 페이지 제목, 로딩)는 COMPOSITION_PATTERNS.md §0 표에서 Pattern을 고른다.
- 컴포넌트를 찾는다. COMPONENT_CATALOG.md에서 요청 항목과 같은 역할을 찾는다. 같은 역할이 있으면 새로 만들지 않는다.
- Variant·Props로 맞춘다.
Button의variant×appearance,Input/Select/DatePicker/Combobox의size,Card·Tabs의surface등 기존 Props로 해결한다.<Button>처럼 기본 API만으로 HM 외형이 적용된다.hm-*class를 붙이거나 Story 전용 class로 외형을 보정하지 않는다. - 조합한다. 여러 컴포넌트를 배치하고 배치용 레이아웃(flex/grid, 간격)만 소비 프로젝트에 작성한다.
- 없을 때만 새로 만든다. 소비 프로젝트에 작성하고, 외형은 DESIGN_RULES.md의 토큰만
var(--…)로 읽으며, 안쪽에는 기존 컴포넌트(Card,Button,Label…)를 재사용한다. - 추측하지 않는다. 카탈로그·
dist/index.d.ts에 없는 Export·Props·토큰은 없다. 기본 HTML·임의 CSS·data-slot흉내로 HM 컴포넌트를 모방하지 않는다(레이아웃·콘텐츠용 HTML은 허용). - 실제로 검증한다. AI_GUIDE.md 6단계.
2. 설치·Import
import { Button, Card, Dialog, DataTable, useDataTable } from "@hm-design/ui"
import { applyRuntimeTheme, resetRuntimeTheme, loadRuntimeTheme } from "@hm-design/ui/theme"
앱 CSS 진입점(Tailwind CSS 4 통합이 처리하는 파일)에 이 순서로 넣는다.
@import "tailwindcss";
@import "@hm-design/ui/tailwind.css";
@import "@hm-design/ui/theme.css";
/* Dashboard 업무 상태 색이 필요할 때만 */
@import "@hm-design/ui/dashboard-status.css";
- 공개 진입점은
.,./theme,./theme.css,./tailwind.css,./dashboard-status.css뿐이다.@hm-design/ui/dist/components/...같은 내부 경로를 import하지 않는다. - Peer:
react,react-dom^19.0.0,tailwindcss^4.0.0. Tailwind CSS 4가 없는 프로젝트에서는 HM 외형이 적용되지 않는다(설치가 필요하다고 보고). tailwind.css가 패키지의 compiled class를@source로 등록하므로 shadcn CLI 설치나components.json이 필요 없다.- Noto Sans KR 글꼴과 OFL 라이선스는
theme.css에 포함된다(dist/fonts/). - 아이콘은 패키지 의존성인
lucide-react를 쓴다.
3. 스타일 규칙
- HM이 값을 정한 속성은 Theme Token으로 적용되어 있고, 정하지 않은 속성은 shadcn 기본 그대로다. 새 화면에서도 같은 구분을 지킨다.
className은 배치 확장용이다. HM 컴포넌트에 HEX·RGB·임의 px Spacing/Radius를 덮어쓰지 않는다.- Light/Dark 분기 없음.
dark:분기·Dark Token을 추가하지 않는다. - 테마 변경은 Runtime Theme(
applyRuntimeTheme(root, theme),loadRuntimeTheme(root, url))만 쓴다.theme은{ schemaVersion: 1, tokens: { "color.bg.content": "#…" } }형식이며 키는runtimeThemeContract에 있는 것만 유효하다. - 한 페이지의 Navigation은 GNB / LNB / DASHBOARD 중 하나다(COMPOSITION_PATTERNS.md §1).
4. 접근성 기본
- 입력 항목명은
Label htmlFor와 controlid를 연결한다(useId). placeholder는 항목명이 아니다.SelectTrigger·Combobox도id또는aria-labelledby를 연결한다. - Dialog·AlertDialog·Sheet·Drawer는 Title(필요 시 Description)을 넣는다. Escape와 Trigger Focus 복귀는 Radix 동작을 그대로 쓴다.
- 기존 컴포넌트의
aria-*연결 속성을 임의로 덮어쓰지 않는다.
5. 이 패키지에 없는 것
- 공개 Form Pattern, Empty·Error 전용 컴포넌트, Stepper, Tree, Chart(그래프) 컴포넌트는 없다. Form은
Label+Input/Textarea/Select/Checkbox/RadioGroup/Switch를Card안에 조합하고, 빈 목록은DataTable의emptyMessage, 오류 안내는Alert로 만든다. - Badge에 success / warning / information variant는 없다(HM Theme에 상태 팔레트가 아직 없음). 새 상태색을 만들지 않는다.
- 상세 컴포넌트 문서·Storybook은 HMDesign 저장소(
docs/components/<name>.md,docs/patterns/)에 있고 패키지에는 포함되지 않는다. 패키지만 있을 때는 이 폴더와.d.ts가 기준이다.