shkim4/HMDesign
Private
Public Access
1
0 Fork 0
Code Activity
Files
c7f29b01420491c461a558e35a7ca3d09b052dfe
HMDesign/packages/ui/ai/AI_USAGE.md
T
shkim4 7621934f69 docs(ai): split SW usage into general / viewer mode in packaged AI guides 
- Usage types are now Web / SW (general mode, viewer mode) / OrgChart / mixed.
  Shared AI_GUIDE step 1 asks for the SW mode only when the request or the
  project setting (HMDesign 사용 유형: SW 일반 | SW 뷰어) leaves it open;
  examples B0/B1/B2 cover "HMDesign SW로 화면을 만들어 주세요", general and viewer.
- Missing-component handling in three steps (reuse in the chosen type/mode ->
  build with that mode's tokens -> HMDesign-consistent style, reported as
  "AI 구성 값 — 디자인 확인 필요"), plus SW general/viewer separation rules.
- sw/ai: AI_USAGE §0 mode selection, catalog §8 lists all 33 SWViewer* exports,
  DESIGN_RULES §11 viewer tokens, PATTERNS 7 viewer composition; examples B/F
  marked as general mode. ui/ai and org-chart/ai aligned with the new types.
- AGENTS_SNIPPET, AGENTS.md and MAINTAINING updated; copies synced.
- scripts/ai-docs.mjs: shared-copy check ignores CRLF/LF (core.autocrlf=true
  checks out packages/sw as LF and the rest as CRLF).
- Verification record updated (code samples typechecked, built and rendered).
2026-10-19 17:34:15 +09:00

7.0 KiB
Raw Blame History

@hm-design/ui — AI 코딩 도구 사용 안내 (Web UI)

먼저 AI_GUIDE.md(공통 1~7단계, 사용 유형 정의)를 읽습니다. 사용 유형은 1 Web / 2 SW(SW 일반 모드 · SW 뷰어 모드) / 3 OrgChart / 4 혼합이고, 소비 프로젝트 설정 값은 HMDesign 사용 유형: Web | SW 일반 | SW 뷰어 | OrgChart | 혼합(영역별)입니다. 이 폴더는 유형이 Web이거나 혼합의 Web 영역일 때만 씁니다. 이 폴더(node_modules/@hm-design/ui/ai/)의 내용은 @hm-design/ui 0.1.0의 공개 Export(src/index.ts → dist/index.d.ts)와 theme.css에서 확인한 값만 적습니다.

  • 요청에 SW(일반/뷰어) 화면이 섞이면 그 영역은 SW 안내, OrgChart가 섞이면 OrgChart 안내로 넘기고, 영역·모드 사이에 컴포넌트·토큰을 임의로 섞지 않습니다. 유형이 정해지지 않았으면 AI_GUIDE의 확인 질문을 먼저 합니다.
  • Web 컴포넌트(Button, DropdownMenu, Dialog 등)를 SW 화면의 Header·뷰어 메뉴·툴바 대용으로 쓰지 않습니다. SW 화면 안에서 Web 컴포넌트는 SW 문서가 허용한 지점에만 둡니다: 일반 모드는 SWPopup의 children 안(예: Popup 하단 Button), 뷰어 모드는 SWViewerPanel의 children 안이며 SWViewer* 컨트롤로 안 될 때만입니다.
문서 내용
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. 작업 순서 (필수)

  1. Pattern을 먼저 본다. 화면 단위 요구(목록 검색, 상단/좌측 메뉴, Dashboard, 페이지 제목, 로딩)는 COMPOSITION_PATTERNS.md §0 표에서 Pattern을 고른다.
  2. 컴포넌트를 찾는다. COMPONENT_CATALOG.md에서 요청 항목과 같은 역할을 찾는다. 같은 역할이 있으면 새로 만들지 않는다.
  3. Variant·Props로 맞춘다. Button의 variant × appearance, Input/Select/DatePicker/Combobox의 size, Card·Tabs의 surface 등 기존 Props로 해결한다. <Button>처럼 기본 API만으로 HM 외형이 적용된다. hm-* class를 붙이거나 Story 전용 class로 외형을 보정하지 않는다.
  4. 조합한다. 여러 컴포넌트를 배치하고 배치용 레이아웃(flex/grid, 간격)만 소비 프로젝트에 작성한다.
  5. 없을 때만 새로 만든다 (3단계).
    • ① 기존 Pattern·컴포넌트·Variant·Props·조합으로 되는지 먼저 확인한다(위 1~4).
    • ② 없으면 소비 프로젝트에 새로 작성한다. 색·간격·radius·글꼴은 DESIGN_RULES.md의 Web 토큰(--hm-sem-*, --hm-color-*, --hm-radius-*)을 var(--…)로 읽고, hover·focus·disabled·invalid 등 상태 표현도 같은 문서를 따른다. 안쪽에는 기존 컴포넌트(Card, Button, Label …)를 재사용한다. 쓸 수 있는 토큰이 있으면 반드시 토큰을 쓴다.
    • ③ 참고할 토큰·스타일이 없을 때만 HMDesign 공통 규칙(Font Weight 400/500/700만, Light/Dark 없음, 전역 CSS 금지)과 조화되게 구성한다. 이때 토큰에 없는 값은 결과 보고에 "AI 구성 값 — 디자인 확인 필요" 로 적는다.
  6. 추측하지 않는다. 카탈로그·dist/index.d.ts에 없는 Export·Props·토큰은 없다. 기본 HTML·임의 CSS·data-slot 흉내로 HM 컴포넌트를 모방하지 않는다(레이아웃·콘텐츠용 HTML은 허용).
  7. 실제로 검증한다. 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와 control id를 연결한다(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가 기준이다.
View Git Blame Copy Permalink