디자인 톤 입히기

03-first-run.md으로 console-log 모드까지 한 바퀴를 돌고 나면, 사이드패널과 옵션 페이지가 base 기본 톤(중성 회색 + 파랑 강조)으로 떠 있습니다. 이 페이지의 끝에는 그 자리가 본인 디자인 톤으로 갈아 끼워져 있어야 합니다.

가는 길은 둘입니다. Figma 파일에서 색상을 자동으로 빼오거나, 색상 톤을 한 단어로 알려주고 AI가 추천 셋을 짜게 합니다. 둘 다 04-real-backend.md와 마찬가지로 선택 단계입니다. 디자인 톤이 아직 안 정해졌으면 이 페이지를 건너뛰고 베이스 기본 톤으로 계속 가도 됩니다.

언제 이 페이지를 보나

상황	어디로
톤이 아직 모르겠다	베이스 기본 그대로 두기. 정해지면 나중에 다시 이 페이지
Figma에 디자인이 있다	아래 “Figma URL로 자동 동기”
톤만 머리에 있다 (“따뜻한 베이지” 같은)	아래 “한 단어 톤으로 추천”
컴포넌트 모양까지 손보고 싶다	아래 “어디까지 손볼지 결정”

트리거

Claude Code 프롬프트에 한 줄 입력합니다.

디자인 톤 갈아끼우기

또는 프로젝트 커스텀, 영어로 customize design tokens. 어느 쪽이든 5-customize-extension 스킬의 5-b 자리(UI 테마)로 들어갑니다.

이미 한 번 실행한 자리라면 AI가 먼저 묻습니다.

이미 톤이 박혀 있어요. 다시 잡을까요? — 5-a 브랜딩 / 5-b UI 테마 / 5-c 도메인 권한

여기서는 5-b UI 테마만 고릅니다.

Figma URL로 자동 동기

Figma MCP가 등록되어 있을 때만 첫 질문이 두 갈래로 떨어집니다.

디자인 토큰을 어디서 가져올까요?

• Figma 디자인에서 자동 추출 — 추천
• 단어로 알려주시는 톤으로 진행

Figma MCP 등록은 01-prerequisites.md의 MCP 항목에서 다뤘습니다. 등록을 안 했다면 이 두 갈래 질문 자체가 안 뜨고 톤 단어 흐름으로 곧장 갑니다. 이 페이지에서 등록부터 시작해도 되지만, 한 번에 하나씩 끊어 두는 편이 안전합니다.

자동 추출을 고르면 URL을 한 번 더 묻습니다.

figma.com/design/<fileKey>/<파일이름>?node-id=<nodeId>

이 형태 그대로 복사해서 붙입니다. Figma에서 디자인 시안 프레임 하나를 우클릭해 “Copy link to selection”을 누르면 위 형태로 복사됩니다. 파일 전체 URL(node-id가 없는)도 받지만, 프레임 단위가 색상 매핑이 더 깔끔합니다.

붙이고 Enter를 누르면 다음 줄들이 흐릅니다.

✓ Figma 변수 7개 가져옴 (text/bg/primary/secondary/border)
✓ src/shared/ui/tokens.css 갱신
✓ brand.json에 figma_file_key, figma_node_id, synced_at 기록

정상 화면: src/shared/ui/tokens.css 를 열면 --color-primary, --color-secondary 같은 CSS 변수 값이 Figma의 색상 hex 코드로 바뀌어 있습니다.

막힌 화면:

• Figma URL을 파싱할 수 없습니다 → URL에 node-id= 가 빠진 경우. Figma에서 프레임을 직접 우클릭해 다시 복사
• 색상 변수를 찾을 수 없습니다 → 시안에 디자인 변수(Figma의 Variables 패널)가 정의돼 있지 않은 상태. AI가 보조 컨텍스트와 스크린샷으로 색상을 추정해서 채워 주기는 하지만, 정확도가 떨어집니다. 가능하면 Figma에서 변수를 먼저 잡고 다시 시도
• 변수 일부만 가져온 경우 (예: primary는 있는데 secondary 없음) → AI가 같은 톤 안에서 보조 색을 추천합니다. 결과 요약에 “secondary 추천 색 적용” 줄이 따로 붙습니다

한 단어 톤으로 추천

Figma가 없거나 톤 단어 흐름을 골랐으면 단일 질문이 옵니다.

어울리는 색상 톤을 한 단어로 알려주세요. (예: “professional blue”, “warm beige”, “tech green”)

비워 두면 베이스 기본 톤이 유지되고 5-b 단계 자체를 건너뜁니다. 한 단어를 적으면 AI가 그 톤에 맞는 primary / secondary / 배경 / 글자 색을 한 셋 추천해서 tokens.css 에 박습니다.

추천 결과가 마음에 안 들면 다시 이 흐름을 호출하면서 톤 단어를 다르게 줍니다 ("darker blue", "more saturated" 식). 매번 새로 추천이 떨어집니다.

어디까지 손볼지 결정

색상이 박힌 다음 한 번 더 묻습니다.

화면 테마를 어디까지 손볼까요?

• 색상만 바꾸기 — 추천
• 색상 + 폰트 바꾸기
• 전체 테마 손보기

처음에는 색상만 이 안전합니다. 버튼과 입력창 모양은 base 기본 그대로 두고 색상 변수만 갱신합니다. 폰트나 컴포넌트 모양은 나중에 다시 부르면서 한 단계씩 늘리면 됩니다.

전체 테마 손보기 는 작업이 큽니다. 사이드패널, 옵션 페이지, popup 안의 버튼, 입력창, 카드 컴포넌트 단위로 톤에 맞게 다 다시 잡습니다. 한 번 결정해 두면 후속 /implement-popup-ui, /implement-options-ui 가 그 톤을 그대로 따라옵니다.

적용 확인

작업이 끝나면 빌드와 Chrome 새로고침 한 번이 필요합니다.

pnpm run build

그리고 chrome://extensions 에서 확장 카드의 새로고침 아이콘을 눌러 dist를 다시 읽힙니다. 사이드패널을 다시 열면 색상이 바뀌어 있어야 합니다.

색상이 그대로면 보통 둘 중 하나입니다.

• 빌드를 안 했다 → pnpm run build 다시
• Chrome이 옛 dist를 캐시한 상태 → 카드 새로고침 후 사이드패널을 닫았다가 다시 엽니다

두 번째 갱신 — Figma 파일을 고친 다음

Figma 시안을 고친 뒤 다시 디자인 톤 갈아끼우기 를 부르면 동일한 fileKey가 brand.json 에 박혀 있어서 URL을 다시 묻지 않습니다. 변경된 변수만 sync 합니다.

이때 tokens.css 에서 직접 손본 값(예: AI 추천 secondary를 본인이 한 단계 어둡게 바꿔 둔 자리) 은 보존됩니다. brand.json 의 manual_overrides 키에 그 변수 이름이 박혀 있어서 자동 sync가 그 자리는 건너뜁니다.

수동 손본 값까지 Figma 기준으로 덮어쓰고 싶으면 한 번 더 물어보고 명시적으로 결정합니다.

manual_overrides에 secondary, accent 두 개가 박혀 있어요. Figma 값으로 덮어쓸까요?

다음

디자인 톤이 박혔다면 04-real-backend.md로 가서 외부 백엔드(Supabase 또는 자체 서버)를 연결하거나, 첫 실행 그대로 console-log 모드를 유지한 채 09-distribution.md로 바로 넘어가도 됩니다. 디자인은 배포 전에 안 잡혀도 되고, 잡혀 있어도 됩니다.

빌드나 새로고침 어디선가 막히면 06-troubleshooting.md 의 빌드와 캐시 항목을 먼저 봅니다.