init-design

name	init-design
description	기존 프로젝트 코드베이스에서 디자인 시스템을 역추출해 docs/design/ Ground Truth 파일(DESIGN-TOKENS.md·UX-BRIEF.md)을 생성한다. UI 프리비전이나 리디자인 파이프라인을 거치지 않고 개발된 프로젝트에서 디자인 기준 파일을 수립할 때 사용. '/init-design', '디자인 역추출', '디자인 토큰 추출', 'DESIGN-TOKENS 만들어줘', 'UX-BRIEF 생성해줘', '디자인 기준 파일 없어', 'Ground Truth 만들어줘', '디자인 파일 없는데 만들어줘' 등 언급 시 호출.
argument-hint	[대상 경로] [--deep] [--dry-run] [--skip-ux-brief]

INIT-DESIGN — 디자인 시스템 역추출 파이프라인

$ARGUMENTS 에 대해 아래 파이프라인을 실행한다.

SCAN → EXTRACT → NORMALIZE → GENERATE → [DEEP: CLEANUP] → REPORT

존재 이유: 이미 개발된 프로젝트에서 기존 코드를 Ground Truth로 확정하고 docs/design/ 기준 파일을 역추출로 생성하는 전용 스킬이다. 디자인 토큰이 코드 곳곳에 흩어져 있어 문서화된 단일 기준이 없는 프로젝트에서, 이후 UI 작업의 최우선 참조 기준을 수립한다.

리디자인과의 경계

이 스킬은 기존 디자인을 문서화할 뿐, 교체하지 않는다.

	디자인 교체(리디자인)	/init-design
목적	디자인 교체	현재 디자인 문서화
코드 변경	스타일 전면 교체	기본 없음 (--deep 시 한정적)
기준	타겟 새 디자인	기존 코드 그대로
출력	새 DESIGN-TOKENS.md	역추출 DESIGN-TOKENS.md

---

Phase 0: PARSE — 인자 파싱

인자	기본값	설명
대상 경로	src/	스캔할 소스 루트
--deep	OFF	하드코딩 교체 + 유틸 클래스 추출 + 컴포넌트 정리
--dry-run	OFF	GENERATE 직전까지만 — 토큰 미리보기 출력, 파일 생성 없음
--skip-ux-brief	OFF	UX-BRIEF.md 생성 생략

---

Phase 1: SCAN — 현재 디자인 자산 스캔

1-1. 사전 확인

docs/design/ 존재 여부를 Glob으로 확인한다:

상황	동작
docs/design/DESIGN-TOKENS.md 없음	정상 진행
docs/design/DESIGN-TOKENS.md 존재	사용자에게 경고: "이미 파일이 존재합니다. 덮어쓰면 기존 파일은 archive로 이동됩니다. 계속할까요?" → 승인 시 계속, 거절 시 종료

1-2. 디자인 자산 병렬 수집

아래를 병렬로 Read·Glob한다:

수집 대상	경로 패턴	추출 내용
CSS 전역 파일	**/globals.css, **/index.css, **/*.module.css	CSS 커스텀 프로퍼티 (:root, [data-theme])
Tailwind 설정	tailwind.config.*	theme.extend.* 값 전체
레이아웃 컴포넌트	**/layout/**, **/Header.*, **/Footer.*, **/Sidebar.*	레이아웃 구조·영역 분류
페이지 파일	**/page.tsx, **/page.jsx, **/page.vue	라우트 목록 (화면 맵용)
프로젝트 문서	프로젝트 루트 (CLAUDE.md, README.md, package.json)	기술 스택, 구조 원칙

1-3. 인벤토리 요약 출력

📋 스캔 결과
CSS 변수:    {N}개 (`:root` / `[data-theme]`)
Tailwind 확장: {M}개
커스텀 유틸 클래스: {K}개 (globals.css)
인라인 스타일 하드코딩: {W}개 (대략)
페이지(라우트): {P}개

---

Phase 2: EXTRACT — 토큰 추출

스캔 결과에서 아래 6개 카테고리로 토큰을 추출한다.

2-1. 추출 소스 우선순위

우선순위	소스	신뢰도
1	CSS :root / [data-theme] 커스텀 프로퍼티	높음 — 이미 토큰화된 값
2	Tailwind theme.extend.*	높음 — 구조적 확장
3	globals.css 커스텀 유틸 클래스 (.btn, .sv-label 등)	중간 — 프로젝트 전용 클래스
4	컴포넌트 className 반복 패턴	중간 — 암묵적 토큰
5	style={{...}} 인라인 하드코딩	낮음 — 정규화 필요

2-2. 추출 카테고리

Color: 배경(bg), 전경(fg), 강조(accent), 테두리(border), 음소거(muted), 코드 배경 등. 다크/라이트 모드 분리.

Typography: 폰트 패밀리(display/body/mono), 사이즈 스케일, 웨이트, 줄 간격.

Spacing: 마진·패딩·간격 값. 4px 기반 스케일 식별.

Border Radius / Shadow: 둥글기 값, 그림자 레이어.

Motion / Animation: 트랜지션 duration·easing, @keyframes.

커스텀 유틸 클래스: 프로젝트 전용 클래스 (예: .sv-label, .h-1, .btn-primary, .metallic). 역할과 적용 컨텍스트를 함께 기록.

---

Phase 3: NORMALIZE — 정규화

추출한 원시 값을 정제한다.

정규화 대상	규칙
유사 컬러	HSL 거리 ≤ 5 → 대표값 하나로 통합, 나머지는 별칭 표기
스페이싱	4·8·12·16·24·32·48·64·96·128px 표준 스케일에 스냅 (±2px 허용)
중복 폰트	동일 계열 폰트 통합 (Inter / Pretendard / JetBrains Mono 등)
시맨틱 역할 분류	값 → 역할 이름 매핑 (--bg-base, --fg-primary, --accent, --border-default 등)
하드코딩 값	기존 CSS 변수와 매핑 가능하면 "→ {변수명}" 표기, 신규면 "신규 토큰 필요" 표기

정규화 결과를 간략히 출력한다:

🔧 정규화 결과
통합된 유사 컬러: {N}쌍
스케일 스냅: {M}건
시맨틱 분류: {K}개
신규 토큰 필요: {W}건

---

Phase 4: GENERATE — Ground Truth 파일 생성

--dry-run 시 이 단계에서 미리보기만 출력하고 종료한다.

4-1. 디렉토리 준비

mkdir -p docs/design/archive

기존 DESIGN-TOKENS.md / UX-BRIEF.md 존재 시 → docs/design/archive/{YYYY-MM-DD}/로 이동 후 생성.

4-2. DESIGN-TOKENS.md 생성

경로: docs/design/DESIGN-TOKENS.md

# Design Tokens

> 생성일: {날짜}
> 출처: /init-design 역추출 — {대상 경로}
> 프로젝트: {CLAUDE.md 또는 package.json에서 추출}
> 갱신 방법: /init-design --dry-run (재확인)

---

## Color

| 토큰명 | 다크 | 라이트 | 역할 |
|---|---|---|---|
| `--bg` | `#0D0D0D` | `#FAFAF8` | 페이지 배경 |
| ... | ... | ... | ... |

## Typography

| 토큰명 / 클래스 | 값 | 용도 |
|---|---|---|
| `--font-display` | `Pretendard` | 헤딩 |
| `.h-1` | `font-size: clamp(...)` | 페이지 주제목 |
| ... | ... | ... |

## Spacing

| 스케일 | 값 | 주 사용처 |
|---|---|---|
| `--space-4` | `4px` | 인라인 간격 |
| ... | ... | ... |

## Border Radius / Shadow

(추출된 값)

## Motion / Animation

(추출된 값)

## 커스텀 유틸 클래스

> 이 프로젝트 전용 클래스. 신규 구현 시 이 클래스를 우선 사용한다.

| 클래스 | 역할 | 대표 적용처 |
|---|---|---|
| `.sv-label` | 섹션 레이블 (대문자 모노) | 사이드바 제목 |
| `.h-1` ~ `.h-4` | 제목 위계 | 페이지·섹션 제목 |
| `.btn`, `.btn-primary` | 버튼 | CTA |
| ... | ... | ... |

---

> 이 파일은 UI 작업 시 최우선 참조 기준입니다.
> 신규 토큰 추가는 이 파일에 먼저 등록 후 사용하세요.

4-3. UX-BRIEF.md 생성 (--skip-ux-brief 시 생략)

경로: docs/design/UX-BRIEF.md

페이지 파일(page.tsx)과 레이아웃 컴포넌트에서 역추출:

# UX Brief — {프로젝트명}

> 생성일: {날짜}
> 출처: /init-design 역추출 (기존 코드 기반)
> 주의: 신규 프로젝트 설계 브리프가 아닌 현행 구현 문서화

---

## 1. 화면 맵 (라우트 구조)

(page.tsx 파일에서 역추출한 라우트 목록)

/ (홈) ├── /about ├── /projects ├── /blog │ └── /blog/[slug] ├── /contact └── /login

## 2. 레이아웃 구조

(Header/Footer/Layout 컴포넌트에서 역추출)

- **글로벌 헤더**: {설명}
- **푸터**: {설명}
- **공통 레이아웃**: {설명}

## 3. 구현 시 준수 원칙

- DESIGN-TOKENS.md의 토큰 값을 Ground Truth로 사용
- 임의 컬러·스페이싱 추가 금지 (필요 시 DESIGN-TOKENS.md에 먼저 등록)
- 커스텀 유틸 클래스 우선 사용 (신규 인라인 스타일 최소화)
- 프로젝트 기술 스택 고정값 준수

---

Phase 5 (--deep): CLEANUP — 디자인 코드 정리

--deep 미지정 시 이 단계를 완전히 건너뛴다.

--deep은 GENERATE 완료 후 실행된다. 코드 변경이 수반되므로 각 단계 전 사용자 승인을 받는다.

5-1. 하드코딩 → CSS 변수 교체

Phase 2에서 추출한 인라인 하드코딩 값 중 DESIGN-TOKENS.md의 토큰과 매핑 가능한 항목을 치환한다.

🔄 하드코딩 교체 후보
  파일: src/components/blog/TableOfContents.tsx
  - style={{ color: '#64748B' }}  →  style={{ color: 'var(--accent)' }}
  파일: src/app/page.tsx
  - style={{ background: '#0D0D0D' }}  →  style={{ background: 'var(--bg)' }}
  ...
  총 {N}건 — 자동 치환합니까? (y/N)

승인 후 replace_all로 일괄 처리. 이후 프로젝트 검증(아래 5-3 참조) — FAIL 시 해당 파일만 롤백.

5-2. 반복 Tailwind 패턴 → 유틸 클래스 등록

3개 이상 컴포넌트에서 동일한 Tailwind 클래스 조합이 반복되는 경우 globals.css에 커스텀 유틸 클래스로 추출을 제안한다.

📦 유틸 클래스 추출 후보
  패턴: "text-xs font-mono uppercase tracking-widest text-[var(--fg-muted)]"
  사용처: TableOfContents.tsx, PostNavigation.tsx, BlogList.tsx (3곳)
  제안: .sv-label { ... } (이미 존재하면 스킵)

  패턴: "border border-[var(--border)] rounded-sm px-2 py-0.5 text-xs"
  사용처: BlogList.tsx, PostNavigation.tsx, page.tsx (3곳)
  제안: .tag { ... }
  ...
  총 {N}패턴 — 추출하겠습니까? (y/N)

승인 후:

1. globals.css에 @layer utilities { .클래스명 { ... } } 추가
2. 해당 컴포넌트의 className 값 교체
3. DESIGN-TOKENS.md 커스텀 유틸 클래스 섹션 갱신
4. 프로젝트 검증 실행 (아래 5-3 참조)

5-3. 검증

모든 --deep 정리 완료 후 최종 검증한다. 프로젝트에 검증 스크립트가 있으면 실행한다 (verify.sh, npm test, npm run build, npm run lint 등 프로젝트에 맞는 것):

# 예: 프로젝트에 verify.sh가 있으면
bash verify.sh
# 또는 빌드/타입체크
npm run build

• PASS → Phase 6 진행
• FAIL → 실패한 파일만 롤백 + 사용자 보고
• 검증 스크립트 없음 → 사용자에게 수동 검증 권고 후 진행

---

Phase 6: REPORT

🎨 init-design 완료
══════════════════════════════════════════
프로젝트:  {이름}
출처:      역추출 ({대상 경로})
══════════════════════════════════════════
[토큰]
  컬러:          {N}개 (다크/라이트)
  타이포:        {M}개
  간격:          {K}개
  유틸 클래스:   {J}개

[생성 파일]
  ✅ docs/design/DESIGN-TOKENS.md
  ✅ docs/design/UX-BRIEF.md        (또는 ⏭ --skip-ux-brief)
  📁 기존 파일 백업: docs/design/archive/{날짜}/  (해당 시)
──────────────────────────────────────────
[--deep 결과]  (해당 시)
  하드코딩 교체: {X}건
  유틸 클래스 추가: {Y}개
  검증: ✅ PASS / ❌ FAIL (롤백됨)
══════════════════════════════════════════
→ 생성된 DESIGN-TOKENS.md는 이후 모든 UI 작업의 최우선 참조 기준이다.
→ 후속 UI 구현·리디자인 워크플로우가 있으면 이 파일을 baseline으로 연결한다.

---

주의사항

• 기본 모드는 읽기 전용: Phase 1~4는 파일 생성만 하며 기존 소스 코드를 수정하지 않는다.
• --deep은 코드 변경 수반: 각 단계 전 사용자 승인 필수. 승인 없이 자동 치환하지 않는다.
• 검증 기반 롤백: --deep 실행 중 프로젝트 검증(verify.sh·npm run build 등) FAIL 시 해당 배치만 롤백하고 계속 진행한다.
• DESIGN-TOKENS.md 는 값만 정의: 스택별 주입 구문(tailwind.config.ts 반영 등)은 이 스킬의 범위 밖이다.
• UX-BRIEF.md 는 현행 구현 문서화: 신규 기획 브리프가 아님. 라우트·레이아웃을 있는 그대로 기록.