---
title: "🎨 26-05-30_달록_핸드오프 — 스튜디오(UI 편집 툴) 설계·구현"
notion_id: "36f22962086881faafcfd4ea5d18c2f0"
notion_url: "https://app.notion.com/p/36f22962086881faafcfd4ea5d18c2f0"
category: "handoff"
parent: "핸드오프 (Claude.ai 컨텍스트 공유용)"
updated: "2026-05-29"
priority: "Medium"
purpose: "마스터 전용 /studio UI 토큰 편집 툴 설계·구현 + 인라인→토큰/CSS 전면 마이그레이션(1,584곳) + 재사용 플레이북"
---

작성일 2026.05.30 · 최창용 · Claude Opus 4.8
매번 자잘한 UI 변경(색·폰트·톤앤매너)을 AI 프롬프트로 처리하던 비효율을, **마스터가 직접 만지고 미리보기로 확인 → 변경분만 내보내 AI 검수·반영**하는 흐름으로 바꾸기 위한 도구. 비개발자도 읽도록 평어 해설 병기.
> 📌 **[권고]** 퍼즈된 팩토핀 프로젝트의 재개, 그 외 기타 한스브릿지에서 진행하는 어플리케이션 개발 프로젝트의 시작 시 해당 툴의 작업을 최우선 미션으로 정할 것을 권장한다.
---
## 1. 한눈에 — 무엇을 만들었나
`/studio` 경로에 **마스터 전용** UI 토큰 편집 페이지를 신설. 색·글꼴·모서리·본문 글자 크기를 슬라이더·색상 피커로 직접 바꾸면, **다크/라이트 · 데스크탑/모바일** 미리보기가 실시간으로 반응하고, 바뀐 값만 모아 CSS로 내보낸다. 그 CSS를 AI(클로드)에게 붙여넣어 "바로 적용 vs 백엔드 동반"을 검수받고 반영한다.
쉽게 말해 — **색·폰트·톤앤매너를 사장님이 직접 운전하는 운전대.** 기존 "목업 catalog 우선" 워크플로우를 GUI로 옮긴 것.
## 2. 왜 이렇게 만들었나 (설계 근거)
| 결정 | 근거 |
| --- | --- |
| **토큰(CSS 변수) 기반** | 달록 톤앤매너가 이미 src/index.css의 CSS 변수 한 곳으로 흐름. 변수 값만 바꿔도 앱 전체가 즉시 반응(재빌드 불필요) |
| **버튼 위치는 범위 밖** | 위치는 토큰이 아니라 JSX 구조 + JS isMobile 분기(9개 파일). 토큰 툴로 못 풂. 빈도 쌓이면 별도 비주얼 에디터(Onlook 류) 검토 |
| **마스터 한정 + lazy 로드** | 일반 사용자에겐 메뉴·번들 모두 미노출. 빌드 확인: Studio 청크가 별도 분리됨 |
| **달록 안 숨김 라우트** | 실제 컴포넌트를 그대로 import → 미리보기 정확도 100% |
| **미리보기 = 내보내기** | 화면에 적용된 값과 내보내는 CSS가 동일 → 미리보기와 실제가 어긋남 사고 차단 |
### 트레이드오프 (의식적 선택)
- 토큰마다 모바일 분리 시 값이 2개 → UI·index.css가 그만큼 커짐. "한 번에 반응형까지" 결정에 따라 감수.
- 미리보기 모바일 프레임은 폭 390px로 토큰 값을 모바일 기준으로 보여주되, **실제 레이아웃 reflow(880px @media 발동)는 흉내 내지 않음**. 진짜 reflow 미리보기는 iframe 필요 — 향후 과제(§6).
## 3. 반응형 토큰 모델
토큰마다 **연결(🔗)/분리(⛓️‍💥)** 토글.
- **연결(기본)** — 데스크탑·모바일 같은 값. 색처럼 화면 무관한 건 거의 다 이 상태.
- **분리** — 모바일 전용 값을 따로. 글자 크기·모서리·간격 등 작은 화면에서 달라야 하는 것만.
내보내기는 분리 토큰만 `@media (max-width: 880px)` 블록으로 출력. 브레이크포인트는 달록 기존 경계(880px) 하나로 통일.
내부 상태는 토큰당 4슬롯(다크/라이트 × 데스크탑/모바일) + split 플래그. **상태를 구조화 데이터로 보관**하므로, 내보내기 포맷만 바꾸면 CSS 외 다른 타깃(앱화 대비 RN/JSON 등)도 추가 가능(§5).
## 4. 검수 게이트 (설계 — 일부 미구현)
커밋 직전 "이 변경 바로 적용해도 되나?"를 두 축으로 판별.
- **축 1 · 안전한가** — 백엔드·데이터·구조를 건드렸나
- **축 2 · 어디까지 봤나** — 데스크탑만? 모바일까지?
```javascript
🟢 index.css 의 :root / @media 토큰 라인만 → 바로 적용 (AI 호출 X)
🔴 supabase·.from(·rpc(·fetch·useEffect·RLS·props 변경 → 정지, 백엔드 동반
🟡 .tsx JSX 구조 변경인데 위 키워드 없음 → 이때만 AI 검수
```
반응형 보강:
- 모바일 전용 토큰(@media)이 바뀜 → 데스크탑만 보고 통과 불가, 모바일 확인 강제
- --text2/--text3 등 대비 민감 색이 바뀜 → 모바일 대비 확인 경고
> 현재 스튜디오는 내보내기 시 "AI 검수받으라" 안내까지만 구현. 자동 게이트(pre-commit 훅 스크립트)는 미구현 — 다음 작업 후보.
## 5. 앱화(구글플레이·iOS) 대응 — 중요
달록은 웹 기반이지만 향후 앱스토어 배포 예정. 이 툴이 거기까지 커버되는지는 **앱화 방식**에 달림.
| 앱화 경로 | 이 툴 커버 | 설명 |
| --- | --- | --- |
| **WebView 래퍼**(TWA·Capacitor·PWA) | ✅ **100%** | 앱이 곧 웹 빌드. index.css가 앱 안에서 그대로 돎 → 색·폰트·톤 변경이 안드로이드·iOS 앱에 자동 반영 |
| **React Native 재작성** | △ 부분 | CSS 변수 없음(스타일=JS 객체). 단 토큰을 진본으로 두는 규율은 그대로 이전되고, 내보내기 어댑터만 CSS→JS/JSON 으로 교체하면 됨 |

핵심 — **토큰 기반 설계는 멀티플랫폼 표준**(Style Dictionary 등이 토큰 1벌→웹·iOS·Android 동시 생성). 즉 지금 토큰으로 만드는 것이 앱 미래를 막기는커녕 **가장 유리한 토대**. 또한 §3대로 상태를 구조화 데이터로 보관해, RN 전환 시 새 내보내기 함수 하나만 추가하면 됨.
**커버 안 되는 영역(공통)** — 앱 아이콘·스플래시·상태바 색·푸시 알림 스타일 등 OS 네이티브 설정. 이건 "자잘한 잦은 변경"이 아니라 한 번 정하는 설정이라 툴 대상 아님.
## 6. 향후 과제
1. 검수 게이트 자동화 — pre-commit 훅 + 규칙 스크립트(🟢🔴 무료 판별, 🟡만 AI)
2. 진짜 모바일 reflow 미리보기 — iframe 기반(880px @media 실제 발동)
3. 간격(spacing) 스케일 토큰 신설 — 현재 여러 컴포넌트에 하드코딩. 도입 시 게이트 검수 필수(구조 변경)
4. 별도 앱처럼 접근(2단계) — 같은 코드, 서브도메인 studio.dallog.* 별도 빌드 엔트리 (욕구 쌓이면)
5. 내보내기 자동 반영 — 현재 수동(복사→AI). 익숙해지면 파일 직접 쓰기 검토
## 7. 변경 파일 (구현 범위)
- `src/index.css` — `--font-size-base: 14px` 토큰 추가 + html font-size를 변수로(fallback 14px, 하위호환)
- `src/pages/Studio.tsx` — 스튜디오 본체(토큰 패널·미리보기·내보내기)
- `src/pages/studio.css` — 스튜디오 스타일
- `src/App.tsx` — `/studio` lazy 라우트 추가
- `src/components/Layout.tsx` — 마스터 전용 사이드바 진입(StudioIcon)
확인 — `tsc --noEmit` 통과, `npm run build` 성공(Studio 청크 분리). 초기 빈 화면 버그(훅 순서 위반)는 가드를 모든 훅 뒤로 이동해 수정.
## 8. 보는 법
```javascript
npm run dev
```
마스터(mster)로 로그인 → 데스크탑 사이드바 '스튜디오' 클릭(또는 /studio 직접 접속). 값을 바꾸고 다크/라이트·데스크탑/모바일 토글로 확인 → "변경 CSS 복사" → AI에게 붙여넣어 검수·반영.
---
## 🔥 추가 진행 (2026.05.31) — 인라인 스타일 전면 마이그레이션 + 스튜디오 고도화
> 🧰 이 문서 최초 업로드(2026.05.30) **이후** 진행분. 오늘의 핵심 — 스튜디오를 만들다 드러난 "디자인 값(폰트·색·간격)이 컴포넌트 코드에 직접 박혀 있던 기술부채"를 **토큰·CSS 클래스 기반으로 전면 정리**했다. 이건 달록만의 일이 아니라 **타 한스브릿지 프로젝트에 그대로 적용하는 방법(플레이북)** 이라 §3에 따로 정리했다.
### 1. 인라인 → 디자인 토큰/CSS 전면 마이그레이션 (PR #11 · main 머지)
**배경(쉽게):** 버튼 색·글자 크기 같은 "디자인 값"이 화면 코드 곳곳에 숫자로 직접 적혀 있었다(약 1,584곳, 전체 코드의 10%, 34개 파일). 이러면 스튜디오에서 값을 바꿔도 앱 전체에 안 퍼진다. 그래서 이 값들을 한 곳(디자인 토큰)에서 관리하도록 전부 옮겼다.
| 항목 | 시작 | 완료 |
| --- | --- | --- |
| 인라인 글자크기(fontSize) | 613곳 | **0** |
| 인라인 style 전체 | 약 1,584곳 | **78** (전부 런타임 계산값) |

남은 78개는 데이터로 정해지는 값(달력 셀 색·동적 너비/높이·아바타 이미지 주소·증감 색)이라 코드에 두는 게 정상인 예외다.
**무엇이 생겼나:** 타입 스케일(`--fs-2xs`~`--fs-2xl`), 간격 스케일(`--space-1`~`--space-7`), 유틸리티·컴포넌트 클래스 100여 종(`.stat-tile`·`.pill`·`.panel`·`.modal-*`·`.section-head` 등). 이게 [[달록 디자인 시스템]]의 실질 진본이 됐다.
**방법:** 수동(토대·스튜디오·공통·대시보드) → **멀티에이전트 워크플로우**로 잔여 23개 파일을 병렬 변환(에이전트 23개·14분) → 반환된 CSS를 중앙에서 한 파일에 병합 → 타입체크·빌드·실제 화면 검증.
### 2. 스튜디오 고도화 (PR #12 · main 머지)
- **미리보기 고정(sticky):** 토큰 패널을 길게 스크롤해도 가운데 미리보기가 화면에 붙어 따라온다(좁은 화면 1열에선 자동 해제).
- **"직접 적용 & 커밋·푸시" 버튼:** 브라우저는 git을 직접 못 돌리므로, **개발 서버에만 붙는 전용 통로**(Vite 플러그인 `/__studio/apply`)를 만들었다. 스튜디오에서 값 바꾸고 버튼을 누르면 → 변경 토큰이 `studio-overrides.css`(앱 스타일 맨 뒤에 로드되어 덮어씀)에 기록되고 → 자동으로 git 커밋·푸시 → CF Pages 자동 배포. 배포본에는 이 통로·버튼이 포함되지 않는다(보안).
- 사용 전 `npm run dev` **재시작 1회** 필요(플러그인은 서버 시작 시 로드).
### 3. 🧰 재사용 플레이북 — 타 프로젝트 적용 순서
> 📌 새 한스브릿지 앱/팩토핀 재개 시, 디자인 정리를 이 순서로 하면 된다. (문서 상단 [권고] 참조)
1. **감사** — 인라인 `fontSize`/`color`/`padding`·`gap` 분포를 수치화하고 자주 쓰는 값의 군집을 찾는다(스케일 설계 근거).
2. **토대** — 타입 스케일(`--fs-*`) + 간격 스케일(`--space-*`) + 색 토큰 + 유틸리티 클래스를 먼저 깐다.
3. **편집 툴(스튜디오)** — 토큰을 GUI로 만지고 다크/라이트·데스크탑/모바일 미리보기 + 내보내기/직접적용. 마스터 전용·lazy 로드.
4. **마이그레이션** — 영역별로, 파일이 많으면 **멀티에이전트 워크플로우 병렬**(파일은 서로 독립이라 충돌 없음, 공유 CSS만 중앙 병합).
5. **예외 규칙** — 런타임 계산값(동적 색·데이터 기반 너비/높이·이미지 URL)만 인라인 허용. 나머지는 전부 토큰/클래스.
6. **검증** — `tsc`·빌드·실제 화면 스팟체크, 영역별 리뷰 가능한 커밋.
**핵심 원칙 한 줄:** 디자인 값은 반드시 토큰을 거친다 · 반복 패턴은 공통 클래스 · 일회성/동적만 인라인.
### 변경 산출물(레포)
- `src/index.css` — 디자인 시스템 진본(스케일·유틸리티·컴포넌트 클래스)
- `src/pages/Studio.tsx` · `studio.css` — 스튜디오 본체
- `src/studio-overrides.css` — 직접 적용 결과 기록(자동 생성)
- `vite.config.ts` — `studio-apply` 개발 전용 엔드포인트
- PR #11(전면 마이그레이션) · PR #12(스튜디오 고도화) — 모두 main 머지 완료