HMDesign/packages/ui/ai/DESIGN_RULES.md

Web(@hm-design/ui) 디자인 규칙

출처: @hm-design/ui/theme.css(원본 src/theme/primitives.css·default.css·컴포넌트별 theme/*.css)에 실제 선언된 값. 이 문서와 그 CSS에 없는 값은 확정값이 아닙니다. 새 UI는 아래 변수를 var(--…)로 읽고 HEX·px 값을 새로 만들지 않습니다. 참고할 변수가 없을 때만 AI_USAGE.md §1-5 ③으로 구성하고 "AI 구성 값 — 디자인 확인 필요"로 보고합니다.

• 토큰 범위: :root, [data-hm-theme]. Runtime Theme(@hm-design/ui/theme)가 같은 변수를 바꿉니다.
• Light/Dark 분기 없음. 컴포넌트 CSS에 html·body·* 규칙을 추가하지 않습니다.
• 이름을 추측하지 않습니다. 특히 --hm-sem-text-*, --hm-sem-border-*, --hm-sem-stroke-divider는 선언되어 있지 않습니다(아래 표의 이름을 씀). 없는 토큰을 fallback 색으로 감추지 않습니다.
• Tailwind utility로는 shadcn 매핑 utility(bg-card, text-primary, text-muted-foreground 등)를 쓸 수 있습니다. HM 값과 다를 수 있는 임의 utility 색(bg-green-700 등)은 쓰지 않습니다.

1. 기본 팔레트 (primitives → --hm-sem-palette-*)

역할	값	변수
Green(주색)	#123328	--hm-sem-palette-green-default
Green 진한 글자	#0A221D	--hm-sem-palette-green-dark-1
Green Focus·Active	#266651	--hm-sem-palette-green-light-2
Green Tint(강조 면)	#BDDFD4	--hm-sem-palette-green-tint
Beige(콘텐츠 면)	#F5F0E5	--hm-sem-palette-beige-light
Warm neutral	dark #6E6759, mid #9A9284, pale #DEDBD2, muted #F4F1EA	--hm-sem-palette-warm-neutral-dark / -mid / -pale / -muted
Red	#D32F2F	--hm-sem-palette-red-danger
Gray placeholder	#999999	--hm-sem-palette-neutral-gray-500
White / Black	#FFFFFF / #000000	--hm-sem-palette-white / --hm-sem-palette-black

Brown·Orange 계열 팔레트(--hm-sem-palette-brown-*, --hm-sem-palette-orange-*)도 선언되어 있으며 Button secondary(Brown)·modify(Orange) 역할에 쓰입니다. 새 UI는 팔레트보다 §2의 Semantic 변수를 우선합니다.

2. Semantic 색·면 (새 UI가 읽는 변수)

역할	변수	기본
페이지·콘텐츠 배경	--hm-sem-bg-content	Beige
카드·팝업 표면	--hm-sem-bg-surface	White
보조 면	--hm-sem-bg-subtle	warm-neutral-muted
브랜드 배경(gradient)	--hm-sem-bg-brand, --hm-sem-bg-brown, --hm-sem-bg-orange	세로 gradient(GNB·Brand 버튼 면)
기본 글자	--hm-sem-fg-primary	green-dark-1
보조 글자	--hm-sem-fg-secondary	warm-neutral-dark
placeholder	--hm-sem-fg-placeholder	gray-500
일반 테두리	--hm-sem-stroke-default	warm-neutral-mid
입력 테두리	--hm-sem-stroke-input-default	warm-neutral-pale
Focus 테두리	--hm-sem-stroke-input-focus	green-light-2
주 액션 / 위 글자	--hm-sem-action-primary / --hm-sem-on-action-primary	Green / White
취소 액션	--hm-sem-action-cancel	warm-neutral-dark
위험 액션	--hm-sem-action-destructive	Red
오류 상태(잠정)	--hm-sem-status-error	#B3261E
강조 면 / 위 글자	--hm-sem-accent / --hm-sem-on-accent	green-tint / #123328
선택(Active) / 위 글자	--hm-sem-state-active / --hm-sem-on-state-active	green-light-2 / White
하이라이트	--hm-sem-surface-highlight	accent 45%
Floating(Popover·Menu·Tooltip 류)	--hm-sem-floating-background, -border-width(1px), -border-color, -radius, -shadow	White, 입력 테두리, 4px, 0 0 12px 검정 20%
Overlay(Dim)	--hm-sem-overlay-background	검정 10%

3. Typography

항목	값
글꼴	--hm-font-family-base: "Noto Sans KR", "Malgun Gothic", sans-serif (글꼴 파일 포함)
Weight	400 / 500 / 700만(600 없음). --hm-font-weight-medium(500), --hm-font-weight-bold(700). 카드·Dialog 제목 700
Card 제목	20 / 28px / 700 (--hm-card-title-*)
Dialog	제목 20 / 28 / 700, 설명 14 / 20, 본문 16 / 24 (--hm-dialog-*)
Button	sm 12/18, default 13/20, lg 15/22. Brand 700, Standard(solid·outline) 500
Input	small 12, medium 14, large 16 (weight 400)

4. 크기·간격·Radius

항목	값	변수
기본 control 높이	34px	--hm-control-height-md
Button 높이(min)	sm 28 · default 34 · lg 42, padding-x 10 · 14 · 18	—
Input 높이	small 28 · medium 34 · large 42(기본), padding-x 10 · 12 · 12	--hm-input-*
Select Trigger 높이	medium 34 · large 44(기본)	—
Control radius	4px	--hm-radius-control-md → --hm-radius-button, --hm-radius-input, --hm-radius-select, --hm-radius-container
Card	border 1px, padding 24px, radius 4px, 그림자 없음	--hm-card-*
Dialog	radius 8px, padding 24px, Header 아래 16px, Footer 위 16px, 버튼 간격 8px, 그림자 0 0 12px 검정 20%	--hm-dialog-*

5. 상태

상태	규칙(실제 CSS)
Button Hover·Pressed(brand·solid)	면 위 검정 20% inset overlay. transition·눌림 이동 없음
Button Hover(outline)	역할 색으로 채우고 흰 글자. Red outline은 Red 8% 면
Disabled	Button·Input·Select opacity: 0.6 + cursor: not-allowed, 기본 면 유지 (전역 Disabled 토큰 아님)
Input Focus	테두리만 1.5px --hm-sem-stroke-input-focus(그림자·glow 없음)
Invalid	aria-invalid="true" → 오류 테두리, 키보드 Focus 시 3px 50% ring
ReadOnly(Input)	상자 없이 글자만, 흐리지 않음
Focus(그 밖)	shadcn 기본 focus-visible ring 유지
선택	--hm-sem-state-active / --hm-sem-on-state-active

새 상호작용 UI는 이 표의 같은 상태 규칙을 따르고, 가능하면 상태를 가진 기존 컴포넌트(Button, Toggle, Input)를 안쪽에 써서 상태를 다시 만들지 않습니다.

6. 스크롤바

• 스크롤 영역이 필요하면 ScrollArea(Radix)를 씁니다. 막대는 Hover·스크롤 중에 표시됩니다.
• 값: 두께 10px(--hm-scroll-area-scrollbar-size), thumb --hm-sem-stroke-default, Hover --hm-sem-fg-secondary, radius 9999px.
• 브라우저 기본 스크롤바를 CSS(::-webkit-scrollbar)로 새로 꾸미지 않습니다.

7. Overlay·Panel 레이아웃

• 모달 = Dialog(Header · Body(스크롤) · Footer). 확인 = AlertDialog. 측면 상세 = Sheet. 하단 작업 = Drawer. 비모달 보조 = Popover.
• 새 Panel 모양이 필요하면 Card(White surface / Beige content)로 만듭니다. Floating 모양이 꼭 필요하면 --hm-sem-floating-*만 읽습니다.
• Dim은 --hm-sem-overlay-background.
• Scoped Theme([data-hm-theme])는 body Portal(SelectContent·PopoverContent·DatePicker 팝업)에 자동 전달되지 않습니다.

8. 아이콘

• lucide-react(패키지 의존성)의 아이콘을 씁니다. Button 안 아이콘 기본 크기는 16px(size-4, shadcn 기본).
• 아이콘 색은 글자색을 상속합니다. 아이콘 전용 색 토큰은 없습니다.

9. 새 컴포넌트 체크리스트

1. 같은 역할의 기존 컴포넌트·Pattern이 없는지 COMPONENT_CATALOG.md에서 확인했다.
2. 소비 프로젝트에 작성했고 패키지 파일·hm-*/data-slot 규칙을 덮어쓰지 않았다.
3. 면·글자·테두리·radius는 §2·§4 변수만 읽는다. HEX·임의 px 없음.
4. 버튼·입력·선택은 기존 컴포넌트를 안쪽에 썼다(상태 재구현 없음).
5. Font Weight 400/500/700, 글꼴은 상속(--hm-font-family-base).
6. Label·키보드·Focus 복귀·Disabled를 확인했다.