한화생명 디자인 시스템

Hanwha Life Design System — Foundation 토큰 + 27개 컴포넌트 + 라이브 카탈로그.

CSS 커스텀 프로퍼티 기반 토큰, React 19 + TypeScript 컴포넌트, 34개 가이드 페이지로 구성된 디자인 시스템 + 문서 사이트.

빠른 시작

npm install
npm run dev          # http://localhost:5173 — 라이브 카탈로그
npm run build        # 타입체크 + 프로덕션 docs 빌드
npm run build:lib    # 라이브러리 패키지 빌드 (dist-lib/)
npm run storybook    # http://localhost:6006 — Storybook
npm run lint

환경변수

| 키 | 용도 | 기본값 | |---|---|---| | VITE_STORYBOOK_URL | 사이드바 Storybook 링크 URL | dev: http://localhost:6006 / prod: 비노출 |

.env.production 또는 호스팅 플랫폼 환경변수에 설정. 미설정 시 프로덕션에서는 Storybook 메뉴 자체가 숨겨진다.

라이브러리로 사용

npm i hanwha-life-ds react react-dom

import { Button, Modal, TextField } from 'hanwha-life-ds'
import 'hanwha-life-ds/styles'   // 컴포넌트 스타일
import 'hanwha-life-ds/tokens'   // 디자인 토큰 (CSS 변수)

export default function App() {
  return <Button color="primary">청약 제출</Button>
}

peerDependencies: React 18+ 또는 19. ESM/CJS 듀얼 패키지, .d.ts 포함.

배포

| 플랫폼 | 설정 파일 | 빌드 명령 | 출력 | |---|---|---|---| | Vercel | vercel.json | npm run build | dist/ | | Netlify | netlify.toml | npm run build | dist/ |

두 설정 모두 다음 보안 헤더가 포함됨:

• Content-Security-Policy (script self만, inline 차단)
• Strict-Transport-Security (HSTS, 2년)
• X-Content-Type-Options: nosniff
• X-Frame-Options: SAMEORIGIN
• Referrer-Policy: strict-origin-when-cross-origin
• Permissions-Policy (camera/mic/geolocation/FLoC 차단)

자산은 1년 immutable 캐시.

라이브러리 패키지 배포 (npm publish)

소비 프로젝트 설정

다른 프로젝트에서 이 DS를 설치하려면 먼저 .npmrc에 레지스트리를 등록합니다.

@lettealo:registry=https://npm.pkg.github.com

그 다음 설치합니다.

npm install @lettealo/hanwha-life-ds

코드에서 사용합니다.

import { Button, TextField, Badge } from '@lettealo/hanwha-life-ds'
import '@lettealo/hanwha-life-ds/styles'

새 버전 게시 절차

v* 태그를 push하면 CI가 자동으로 GitHub Packages에 게시합니다. 태그 버전과 package.json 버전이 다르면 CI가 실패합니다 — 반드시 순서대로 진행하세요.

# 1. package.json 버전 올리기
npm version minor   # 또는 patch / major

# 2. 태그와 함께 push
git push origin main --follow-tags

npm version 명령이 package.json 수정 + 커밋 + 태그를 한 번에 처리합니다.

| 변경 유형 | 명령 | 예시 | |----------|------|------| | 버그 수정 | npm version patch | 3.0.0 → 3.0.1 | | 기능 추가 (하위 호환) | npm version minor | 3.0.0 → 3.1.0 | | 브레이킹 체인지 | npm version major | 3.0.0 → 4.0.0 |

필요한 GitHub Secrets

| Secret | 설명 | |--------|------| | GITHUB_TOKEN | GitHub 자동 제공, 별도 설정 불필요 | | VERCEL_TOKEN | 카탈로그/스토리북 배포용 | | VERCEL_ORG_ID | Vercel 조직 ID | | VERCEL_PROJECT_ID | 카탈로그 Vercel 프로젝트 ID | | VERCEL_PROJECT_ID_STORYBOOK | 스토리북 Vercel 프로젝트 ID |

CI

GitHub Actions가 다음 이벤트마다 실행됩니다 (.github/workflows/ci.yml).

| 이벤트 | 실행 job | |--------|---------| | main push / PR | lint + tsc + build (docs/lib) + npm audit | | main push | 위 + 카탈로그 Vercel 배포 + 스토리북 Vercel 배포 | | v* 태그 push | 위 전체 + npm publish → GitHub Packages |

구성

Foundation

| 토큰 | 위치 | 내용 | |---|---|---| | Color | src/styles/tokens.css | 8개 컬러 스케일 × 9단계 | | Typography | src/styles/tokens.css | 한화고딕/Noto Sans, 반응형 토큰 | | Shape | src/styles/tokens.css | radius 4 / 8 / 12 / 16 / full | | Elevation | src/styles/tokens.css | shadow small / medium / large | | Spacing | src/styles/tokens.css | 2px 기반 (2~48) |

Components (27)

Accordion, AssetIcon, BottomSheet, Button, Card, Checkbox, CheckboxButton, Chip, DatePicker, Dropdown, EmptyState, Graphic, Icon, IconButton, List, Modal, Notification, Radio, Stepper, Table, Tabs, TextButton, TextField, Toast, Toggle, Tooltip

각 컴포넌트는 src/components/<Name>/에 모듈로 분리. CSS Module + TypeScript Props.

디렉토리

hanwha-life-ds/
├── src/
│   ├── App.tsx                  # 카탈로그 라우팅
│   ├── main.tsx                 # ErrorBoundary + StrictMode
│   ├── index.ts                 # 라이브러리 entry
│   ├── components/              # 27개 컴포넌트
│   ├── pages/                   # 34개 가이드 페이지 (lazy)
│   ├── foundations/             # Storybook 스토리
│   ├── styles/tokens.css        # 디자인 토큰
│   ├── lib/cn.ts                # className 유틸
│   └── lib/assets.ts            # 자산 매핑
├── vite.config.ts               # 카탈로그 빌드
├── vite.lib.config.ts           # 라이브러리 빌드
├── tsconfig.lib.json            # .d.ts 생성
├── vercel.json / netlify.toml   # 배포 + 보안 헤더
└── .github/workflows/ci.yml     # CI 파이프라인

보안 / 프로덕션 체크

• npm audit: 0건 ✅
• XSS 패턴 (dangerouslySetInnerHTML/eval/innerHTML): 사용 없음 ✅
• 콘솔 로그: ErrorBoundary의 dev-only console.error만 ✅
• ErrorBoundary로 전체 트리 보호 ✅
• Hash 라우팅 decodeURIComponent 예외 안전처리 ✅
• TypeScript strict: true ✅

Breakpoint

| 구분 | 폭 | |---|---| | PC-Wide | ≥ 1441px | | PC | 1281–1440px | | Tablet | 768–1280px | | Mobile | ≤ 767px |

알려진 제약

• lib 번들 크기 (768KB): AssetIcon/Graphic이 import.meta.glob({ eager: true })로 모든 PNG를 base64 inline. 추후 src prop 기반 API로 전환하면 경량화 가능.
• 테스트: 인프라(vitest + playwright)는 구축됐으나 .test.tsx 파일 0개. Button stories의 play 함수 확장 필요.