# 코드 기반 디자인 시스템 파이프라인 — 설계

- 날짜: 2026-07-08
- 상태: 첫 슬라이스 구현 완료(2026-07-08) — 128/128 테스트 통과, design-system/ 실제 빌드+렌더 검증(preview_ui.py)
- 관련: [design-craft-upgrade](2026-07-08-design-craft-upgrade-design.md), [[figma-mcp-account-separation]]

## 배경 / 결정

Figma MCP 실험에서 확인: 무료(Starter) 계정은 읽기 도구 **월 6회** 제한이라 품질 반복(build→screenshot→fix) 루프가 막히고, 디자인 시스템(재사용 컴포넌트)이 없으면 맨바닥 조립이라 제품 품질이 안 나온다. 결론 — **실제 UI는 프론트엔드 코드로, 디자인 시스템도 코드로 굳힌다.**

이건 design-craft(DESIGN.md·skill)의 *대체가 아니라 완성*이다. 층 관계:
- **design-brief / DESIGN.md** = 제약(무엇을)
- **skill(design-craft)** = 방법(어떻게)
- **디자인 시스템** = 재사용 실체 = 코드로 굳힌 tokens + 컴포넌트  ← 이번에 신설
- **프론트엔드 코드** = 매체(실제로 보이는 결과)  ← 이번에 신설

## 스택 결정 (근거)

**React + CSS 변수 (Vite)**. 
- 순수 HTML/CSS 탈락: 재사용 *컴포넌트*가 없어 디자인 시스템의 핵심에서 무너짐.
- Tailwind-first 후순위: 토큰이 tailwind.config에 갇힘 → design-brief 토큰 SoT가 흐려짐. (나중에 편의 레이어로 얹기 가능)
- CSS 변수 = design-brief 토큰과 1:1, 프레임워크 무관·이식성. React = 재사용 컴포넌트 1급.
- **디리스크 완료**: 이 환경에서 `npm install(4s) → vite build(425ms) → 로컬서버 → headless chrome 스크린샷` 전 구간 실증(React SPA 실제 렌더 확인).

## 파이프라인 (하네스 배선)

```
/design-system  (신규 커맨드)
  0. design-brief 세우기            (design-craft skill · design-brief-spec)
  1. DES-PLATFORM → tokens.css + 코어 컴포넌트(React)     ← 디자인 시스템
  2. ENG-FE       → screens/ 조립                         ← 화면
  3. preview_ui.py → vite build → 로컬서버 → chrome PNG    ← 실제 UI 확인(rate-limit 없음)
```
기존 직무 재사용: **DES-PLATFORM**(토큰·컴포넌트)·**ENG-FE**(화면)·**design-craft**(방법)·**design-brief**(제약).

## 산출 구조 (생성물)

```
design-system/                     # 실제 빌드되는 React+Vite 패키지 (예제/레퍼런스 슬라이스)
  design-brief.yaml                # 제약층(SoT) — 이 시스템의 brief/references/tokens/decisions/donts
  package.json / vite.config.js / index.html
  src/
    tokens.css                     # design-brief tokens를 CSS 변수로 (DES-PLATFORM)
    components/{Button,Card,Input}.jsx  # 토큰만 소비하는 재사용 컴포넌트 (DES-PLATFORM)
    screens/StartScreen.jsx        # 컴포넌트 조립 화면 (ENG-FE)
    preview.jsx                    # 컴포넌트 갤러리 + 화면 미리보기 엔트리
  README.md                        # 빌드·미리보기 방법
```
node_modules는 로컬(미추적). git 미관리 유지.

## preview 훅 — `.claude/hooks/preview_ui.py`

D2 렌더러(render_consult)의 형제. 계약:
- 입력: 프로젝트 디렉터리(package.json 존재).
- 동작: (필요시) `npm install` → `vite build` → 임시 포트로 `http.server`(dist) → `google-chrome --headless=new --virtual-time-budget`로 스크린샷 → 서버 종료.
- sleep 금지 제약: curl/urllib 재시도로 서버 준비 대기(폴링).
- 출력: PNG 경로(들). `--url-path`로 특정 라우트(#/screen) 지정 가능.
- 폴백: chrome/npm 미가용 시 명확한 에러(파이프라인은 계속).

## /design-system 커맨드

- 인자: 대상 주제/제품 + 대상 디렉터리(기본 `design-system/`).
- 절차: ①design-brief(design-craft) → ②DES-PLATFORM 토큰+컴포넌트 → ③ENG-FE 화면 → ④preview_ui.py 스크린샷 → ⑤report-header(BLUF) 보고 + 산출 경로.
- 불변식 준수: report-header, evidence, 권한(외부 side-effect 기본 금지 — npm/chrome은 로컬 빌드라 허용 범위), design-brief 없이 컴포넌트 생성 금지.

## 검증

1. (완료) 미리보기 루프 디리스크 — React SPA 실제 렌더 스크린샷.
2. 첫 슬라이스: design-system/ 빌드 성공 + preview_ui.py로 화면 스크린샷 산출.
3. test_enforcement: preview_ui.py 존재/임포트, design-brief.yaml 유효(앵커 5종), design-system 필수 파일 존재.
4. 컴포넌트가 하드코딩 색이 아니라 **토큰(var(--*))만 소비**하는지 린트성 체크(간이).

## 비목표 (YAGNI)

- Storybook·CI 배포·비주얼 회귀 테스트는 후속. 우선 build→screenshot 루프.
- 다중 테마/다크모드·접근성 자동감사는 후속(토큰 구조는 확장 가능하게).
- 실제 제품(ca-tmpl 등) 타깃 적용은 파이프라인 검증 후.

## 첫 슬라이스 범위

tokens.css + **Button·Card·Input** 3 컴포넌트 + **StartScreen** 1개 + preview 갤러리 → preview_ui.py로 스크린샷 2장(갤러리/화면). 파이프라인이 실제로 도는 걸 증명하고 확장.