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

날짜: 2026-07-08
상태: 첫 슬라이스 구현 완료(2026-07-08) — 128/128 테스트 통과, design-system/ 실제 빌드+렌더 검증(preview_ui.py)
관련: design-craft-upgrade, 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 없이 컴포넌트 생성 금지.

검증

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

비목표 (YAGNI)

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

첫 슬라이스 범위

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

5.0 KiB Raw Permalink Blame History