디자인 톤 입히기

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”을 누르면 위 형태로 복사됩니다. node-id가 없는 파일 전체 URL도 받지만, 프레임 단위로 지정할 때 색상 매핑이 더 정확합니다.

붙여 넣고 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 의 빌드와 캐시 항목을 먼저 봅니다.