@seyeonpark/design-system

BuilderHub 디자인 시스템 토큰 라이브러리입니다.

Figma에서 추출한 tokens.json을 대시보드에 업로드하면 colors.ts가 생성되고, dist/로 패키지 빌드됩니다.

설치

npm install @seyeonpark/design-system
# 또는
pnpm add @seyeonpark/design-system

로컬/GitHub에서 바로 쓰려면:

npm install github:ryeon18/design-system

사용법

import { Colors, Primitive } from '@seyeonpark/design-system';

Colors.Brand.Brand4;       // '#1A4BD1'
Colors.Text.Text6;         // '#262338'
Primitive.GrayScale.Gray_950;

개발

npm install
npm run dev          # http://localhost:9000 — 업로드 / 싱크 / 릴리스
npm run build        # colors.ts 생성 후 dist/ 라이브러리 빌드 (tsup)
npm run build:app    # 대시보드 웹앱 빌드

워크플로우

1. 디자이너가 Figma 플러그인으로 tokens.json 추출
2. 대시보드에서 tokens.json 업로드
3. src/styles/tokens/colors.ts 자동 생성
4. Color Preview에서 토큰 확인
5. 싱크로 커밋 후 GitHub에 push
6. 릴리스에서 patch/minor/major 선택 → Actions가 버전·CHANGELOG·태그·GitHub Release·npm publish 자동 처리

버전 관리

Semantic Versioning을 따릅니다.

| 버전 | 예시 | | --- | --- | | Patch | 토큰 값 보정, 버그 수정 | | Minor | 하위 호환 토큰·기능 추가 | | Major | Breaking Change |

권장: 대시보드 릴리스 버튼 사용 (Actions 자동화)

CLI 대안:

npm run release:patch
npm run release:push
# 또는
npm run release:full

릴리스 버튼 인증

로컬에서 릴리스를 실행하려면 GitHub 인증이 필요합니다 (repo, workflow).

1. .env에 GITHUB_TOKEN=ghp_...
2. 또는 gh auth login

npm 배포

npm은 Trusted Publishing을 권장합니다. Bypass 2FA가 붙은 Granular 토큰은 보안 경고가 뜹니다.

지금 바로 (간단): Classic Automation 토큰

Granular가 아니라 Classic 토큰을 만드세요.

1. https://www.npmjs.com/settings/~/tokens
2. Generate New Token → Classic Token
3. 타입: Automation
4. 생성된 값을 GitHub Secret NPM_TOKEN에 저장

Bypass two-factor authentication 체크는 Granular용입니다. Classic Automation이면 그 체크가 필요 없습니다.

권장 (장기): Trusted Publishing (토큰 없이 CI publish)

패키지가 npm에 한 번 올라간 뒤에만 설정할 수 있습니다.

1. 최초 1회 로컬에서 publish (아래 “최초 publish”)
2. npmjs.com → @seyeonpark/design-system → Settings → Trusted Publisher
3. GitHub Actions 선택 후:
   • Organization or user: ryeon18
   • Repository: design-system
   • Workflow filename: release.yml (파일명만)
4. 이후 릴리스는 NPM_TOKEN 없이도 Actions가 자동 publish

최초 publish (로컬 1회)

cd design-system
git pull
npm login          # ryeon18 + OTP
npm run build
npm publish --access public

그다음부터는 대시보드 릴리스(patch) 로 1.0.2 등 올리면 됩니다.

npm install @seyeonpark/design-system

import { Colors, Primitive } from '@seyeonpark/design-system';

스크립트

| 명령어 | 설명 | | --- | --- | | npm run dev | 토큰 대시보드 | | npm run build | 라이브러리 빌드 (dist/) | | npm run build:app | 대시보드 앱 빌드 | | npm run release:patch | 패치 버전 bump | | npm run release:minor | 마이너 버전 bump | | npm run release:major | 메이저 버전 bump | | npm run release:push | 태그 포함 push |

관련 문서

• 버전 관리 가이드
• 변경 이력