82 lines
5.0 KiB
Markdown
82 lines
5.0 KiB
Markdown
# 코드 기반 디자인 시스템 파이프라인 — 설계
|
|
|
|
- 날짜: 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장(갤러리/화면). 파이프라인이 실제로 도는 걸 증명하고 확장.
|