#개요와 빠른 참조

CONE-Watcher N 프론트엔드(heka-nhn-frontend)는 자체 디자인 시스템 패키지 @heka/theme를 사용합니다. 이 페이지는 개발자가 새 화면을 만들 때 가장 자주 찾는 토큰을 한 곳에 모은 빠른 참조입니다.

권위 있는 출처: 이 페이지는 요약입니다. 완전한 명세는 다음을 참조하세요.

• 상세 명세: spec/cone-watcher-frontend/design-system.md — 11개 섹션, 코드 인용 포함
• 시각 카탈로그: cone-watcher-frontend/docs/design-system/index.html — 정적 HTML 1파일, 브라우저로 직접 열기

#1. 디자인 시스템의 위치

@heka/theme 패키지가 dashboard·admin 두 앱의 시각 일관성을 단일 출처에서 보장합니다.

dashboard ─┐
admin ─────┴─→ @heka/theme (palette, typography, components 오버라이드)
                  ↓ overrideTheme({}, koKR)
                각 앱의 미세 조정

핵심 설계 의도 — 색 토큰 수를 적게 유지하고, 인터랙션은 알파 단계(33 → 66 → 99 → cc → e6)로 표현합니다. hover·active에서 새 색을 만들지 않습니다.

#2. 색 토큰 빠른 참조

#2.1 텍스트 (palette.text)

#2.2 의미 색 (palette top-level)

#2.3 상태 색 (오버라이드 안 직접 hex)

알파 표기: 1a=10%, 33=20%, 4d=30%, 66=40%, 80=50%, 99=60%, b3=70%, cc=80%, e6=90%

success/warning 토큰은 없습니다. 알림성 UI를 만들 때 임의 hex가 박히지 않도록, 새 토큰 추가가 필요하면 디자이너와 합의 후 palette 확장이 먼저입니다.

#3. 모양 토큰 (radius)

pill (999) ─ 검색·Tabs default·Radio thumb
strong (16) ─ Paper·Heka Tile
default (12) ─ Button·IconButton·PaginationItem
soft (8) ─ Chip·Heka Profile/Note/Contextual
subtle (4) ─ 입력·Menu paper·TableRow head
hairline (2) ─ Tooltip 전용

16 이상의 큰 둥글기는 의도적으로 사용 안 합니다. Material 3는 20·28·32·48 단계까지 있지만 우리에겐 불필요(운영자 도구 디자인).

#4. 타이포그래피

• 패밀리: Poppins (영문) + "Noto Sans KR" (한글)
• 폼 입력 계열(InputBase·InputLabel·FormHelperText): "Noto Sans KR" 우선
• 본문 16px / 라인 120% / letterSpacing: 0이 기본
• 본문 설명(Note·Contextual)만 150%로 풀어 가독성 확보
• wordBreak: 'keep-all' 전역: 한국어 어절 단위 줄바꿈

#5. 간격 (spacing)

코드 전반에서 4의 배수만 사용합니다 — 4·8·12·16·20·24·32. 임의 값(예: 13, 17, 22)은 도입하지 마세요. MUI의 기본 spacing 단위(8)와 호환됩니다.

#6. 그림자

거의 모든 컴포넌트가 boxShadow: 'none'입니다. 예외는 두 곳뿐:

새 컴포넌트에 임의 그림자를 추가하지 마세요. Material 3는 5단계 elevation을 가지지만 우리는 의도적으로 단일 평면입니다.

#7. 브레이크포인트

xs/sm/md/lg/xl   ─ MUI 표준 (호환용 유지)
zero (0) / tablet (1024) / desktop (1440) / full (1920)  ─ 우리 커스텀

레이아웃 작성 시 우리 커스텀(tablet/desktop/full)을 우선 사용합니다.

#8. 무엇을 어디서 import하나

// 1. MUI 표준 컴포넌트 — 자동으로 우리 오버라이드 적용됨
import { Button, TextField, Dialog } from '@mui/material';

// 2. Heka 커스텀 컴포넌트
import {
  Profile, Note, Tile, Contextual,  // 4종 — theme 슬롯 등록
  Link, MenuItem, Search, Select, Tabs,  // 5종 — styled export
} from '@heka/theme';

// 3. 테마 객체 (앱 루트의 ThemeProvider에 주입)
import { theme, overrideTheme } from '@heka/theme';

#9. 다음 단계

새 화면·컴포넌트를 만들기 전에 02. 새 컴포넌트 5규칙을 한 번 읽어보세요. 자주 어기면 디자인 일관성이 빠르게 무너지는 항목들입니다.