Claude Code에 CLAUDE.md 하나 쥐여줬더니 디자인 일관성이 달라졌다

AI한테 "버튼 만들어줘"라고 하면 만들어주긴 해요. 근데 색이 다르고, 간격이 다르고, 폰트도 제멋대로거든요. 잘 만들어둔 디자인시스템이 있는데도 AI는 그걸 못 읽어요. Figma 파일을 열어봐야 프레임이랑 사각형 덩어리일 뿐이니까.

그래서 이번 글은 이미 존재하는 디자인시스템을 AI가 이해할 수 있는 형태로 바꾸는 이야기예요. "AI로 디자인시스템을 처음부터 새로 만드는 것"과는 다른 방향이에요. 이전 포스팅이 그쪽이었다면, 이번엔 이미 잘 굴러가고 있는 시스템을 JSON 토큰으로 변환하고, CLAUDE.md라는 일종의 헌법을 작성해서 Claude Code가 그 테두리 안에서만 움직이게 만드는 거죠. 다음 글에서는 이걸 실제로 활용해서 일관된 디자인을 뽑아내는 결과를 보여준다고 하고요.

핵심 흐름을 먼저 정리하면 이렇게 돼요. Figma 이미지 파일에서 출발해서 기본 token(컬러, 폰트 등)들을 만들고, component(버튼, 카드 등)에 대한 정의를 하고, pattern(리스트, 상세 화면 등)에 대한 정의를 한 다음, CLAUDE.md를 통해 각각의 시스템 단위 내용들을 통제하면서 Claude Code를 굴리는 순서예요. 도식화하면 이래요.

Figma → tokens / raw export → components 정의 → patterns 정의 → CLAUDE.md로 통제 → Claude Code 사용

이 순서를 뒤집거나 중간 단계를 건너뛰면 일관성이 깨져요. token 없이 component를 정의하면 AI가 색상값을 지어내고, pattern 없이 화면을 만들면 레이아웃이 매번 달라지거든요.

Figma에서 JSON까지 — Material Design 3로 해보는 실습

실습 기준은 Google Material Design 3 디자인시스템이에요. Figma Community에 공개된 파일(figma.com/community/file/1035203688168086460)을 열어보면 좌측 페이지 안에 Style과 Component 두 축으로 구성되어 있어요.

Style 쪽에는 Color, Typography만 있는 게 아니에요. 터치 시 변경되는 Elevation, 기본 Shape 같은 것들도 다양하게 정리되어 있더라고요. Component 쪽은 상단 앱바, 하단 탭바, 버튼, 카드 등 모바일 UI의 기본 세트가 갖춰져 있고요. (Material Design이니까 당연한 건데, 이 구조가 꼼꼼할수록 뒤에서 AI가 해석하기 편해져요. 반대로 말하면, 여기서 빠진 건 나중에 AI도 모른다는 뜻이에요.)

그리고 이걸 코드로 옮기기 위한 폴더 구조는 이렇게 잡아요.

``` /design-system CLAUDE.md /tokens color.json typography.json ... /components button.json card.json ... /patterns list.json form.json ... /icons icons.json /svg ic_arrow_right_24.svg ... ```

tokens, components, patterns, icons. 네 개 폴더가 전부예요. CLAUDE.md가 루트에 딱 하나 있고, 나머지는 각 폴더에 JSON 파일들이 들어가는 구조. 복잡하지 않죠. 근데 이 네 개를 채우는 과정이 꽤 다른데, 그건 아래에서 이야기할게요.

Next.js 16 + TypeScript + Tailwind CSS v4가 필요한 진짜 이유

디자인 시스템을 코드화하려면 먼저 프로젝트 뼈대가 필요해요. Claude한테 이렇게 시켜요. "Next.js 16, TypeScript, Tailwind CSS v4 기준으로 프로젝트 초기 세팅해주고, 디자인시스템을 위한 tokens, components, pattern, icons 폴더를 만들어줘." 한 번에 다 만들어달라고 하면 돼요.

"왜 이 3종 세트냐"고 물으면, 각각이 AI한테 서로 다른 종류의 가드레일을 씌워주기 때문이에요. 하나씩 뜯어볼게요.

Next.js — 디자인 시스템은 공통 컴포넌트가 생명이잖아요. Next.js의 파일 기반 라우팅은 Claude한테 "버튼은 여기 있고, 레이아웃은 저기 있다"는 지도를 제공해요. 어디에 뭐가 있는지를 파악하는 데 이게 결정적이더라고요. App Router 구조는 Storybook 같은 역할, 그러니까 디자인 시스템 문서화를 프로젝트 내부에 그냥 만들어버릴 수 있어서 특히 유리하고요.

TypeScript — 여기서 중요한 건 Interface예요. Button에 size 속성이 sm, md, lg 세 가지만 있다는 걸 코드로 명시해두면, Claude가 엉뚱한 값을 집어넣는 실수를 원천 봉쇄할 수 있어요. "이 가이드라인 밖으로는 나가지 마"라고 제약 사항을 주는 것과 같은 효과예요. 일반 자바스크립트였으면 이게 안 돼요. 타입이 없으면 AI한테 명확한 가이드를 줄 방법이 없거든요. 타입이 곧 울타리인 셈이죠.

Tailwind CSS v4 — 여기가 AI-Native 디자인 시스템의 핵심이에요. Claude는 복잡한 JSON 객체보다 표준 CSS 변수 구조를 훨씬 더 정확하게 이해하고 추론한다고 해요. 피그마의 디자인 토큰을 CSS 변수로 변환해두면, 별도의 학습 없이도 완벽하게 일치하는 코드를 뱉어낼 수 있다는 거예요. 근데 이게 좀 놀라운 게, JSON으로 토큰을 넘기면 파싱 에러가 종종 나는데 CSS 변수로 주면 거의 안 틀린다는 거거든요.

정리하면 리액트로 컴포넌트를 만들고, Next.js라는 튼튼한 뼈대 위에서 돌아가며, Tailwind CSS v4라는 최신 기술로 색칠을 하는 구조. 이렇게 세팅해두면 디자인 시스템을 위한 완벽한 초기 세팅이 되는 거예요. AI가 가장 잘 읽을 수 있는 스택을 의도적으로 고른 것이죠.

Variables가 깔끔하면 플러그인 한 방, 아니면 Devmode에서 한땀한땀

디자인 시스템을 토큰으로 바꾸는 건 상황에 따라 두 갈래로 나뉘어요. Figma 파일의 상태에 따라 난이도가 완전히 달라지거든요.

케이스 1: Figma Variables가 체계적으로 잘 정리된 경우

이 경우엔 많이 편해요. Figma Plugin 중에 Variables를 Token으로 바꿔주는 게 있거든요. Figma의 Action 메뉴에서 variables2json이라는 플러그인을 찾아서 다운로드하면 돼요.

플러그인이 Variables를 JSON으로 쭉 뽑아줘요. 그리고 만들어진 JSON 파일을 Claude에 넣고 한 방에 요청하는 게 포인트예요. 이런 식으로요. "첨부한 material3_variables.json을 분석해서 디자인 시스템을 만들어줘. Tokens는 JSON의 Schemes와 Palettes를 참조해서 Tailwind v4 전용 CSS 변수 파일을 만들어줘. Components는 JSON에 있는 M3/Button, M3/Sys 등의 토큰 값을 사용하는 React 컴포넌트들을 만들어줘 — 파일에 없는 구조는 표준 M3 스펙을 따라줘. Icons는 /icons/svg 폴더는 일단 비워두되 아이콘을 쉽게 불러올 수 있는 Icon.tsx 컴포넌트 구조만 잡아줘. 그리고 이 시스템을 Claude 너 스스로가 앞으로 어떻게 참조해야 할지 CLAUDE.md에 규칙을 정의해줘."

프롬프트가 좀 길죠. 근데 이걸 쪼개서 하나씩 요청하면 앞에서 만든 결과와 뒤에서 만든 결과가 안 맞는 일이 생겨요. 한 번에 전체 맥락을 주는 게 일관성 면에서 낫다는 거예요.

케이스 2: Variables가 존재하지 않거나 엉망인 경우

솔직히 현실에서는 이 케이스가 더 많죠. Variables를 다운로드받아 활용하기 어려울 때는 Figma devmode로 직접 들어가야 해요. 노가다의 시작이에요.

Material Design 3를 예로 들면, 만들어진 디자인시스템의 페이지로 들어가서 typography section을 선택해요. 그다음 Devmode로 전환하면 오른쪽 패널에 MCP > [Copy example prompt]라는 버튼이 보여요. 이 버튼으로 해당 섹션의 프롬프트를 복사하고, Claude한테 "tokens 폴더 안에 지금 넣은 내용 기반으로 json 파일을 만들어줘"라고 던져요.

Claude Code가 각각의 디자인시스템 파일을 알아서 만들어줘요. 잘 되긴 해요. 근데 문제는 이걸 모든 섹션에 대해 반복해야 한다는 거예요. typography 하고, color 하고, spacing 하고, elevation 하고... tokens만 끝나면 components도 같은 방식으로 해야 하고, patterns까지. 체계적인 Variables가 있는 케이스 1이랑 비교하면 품이 서너 배는 들어요.

아이콘은 또 별개 작업이에요. SVG 파일들을 /icons/svg 폴더에 넣어두고, json 파일로 규칙을 설정해둬야 하는데 — 이건 아래에서 좀 더 자세히 다룰게요.

CLAUDE.md — AI한테 "이 밖으로 나가면 절대 안 돼"라고 써주는 문서

재료를 다 모았으면 이제 가장 중요한 단계예요. AI가 디자인시스템을 마음대로 해석하지 못하도록 통제하는 가이드. CLAUDE.md를 작성하는 거예요.

이 문서는 다소 상세하게 만들어야 해요. 상황에 따라 단순화해서 써도 된다고는 하지만, 빡빡할수록 결과가 좋아지거든요. 구조를 뜯어보면 크게 네 덩어리로 나뉘어요.

첫 번째, Role과 Core Rules. Claude Code한테 역할을 부여해요. "너는 design system-driven UI generator야. 일관성을 창의성보다 우선시해." 그리고 절대 규칙 세 가지. 임의 UI 생성 금지. 새 컴포넌트나 스타일, 아이콘 발명 금지. 제공된 디자인 시스템 파일만 사용할 것. 이걸 NON-NEGOTIABLE이라고 대문자로 박아두더라고요. (이 정도까지 해야 하나 싶겠지만, 안 하면 진짜 AI가 창작을 해버려요.)

두 번째, Mandatory Workflow. UI를 생성할 때 반드시 따라야 하는 5단계 순서예요.

1. /patterns에서 적절한 패턴 선택 2. /components에서 필요한 컴포넌트 식별 3. 올바른 variant와 slot 적용 4. typography와 spacing 적용 5. icons 적용

단계를 건너뛰면 안 되고, 패턴 없이 레이아웃을 생성하면 안 돼요. 적합한 패턴이 없으면? 자유롭게 UI를 만드는 게 아니라 새 패턴을 제안하도록 되어 있어요. (이 부분이 좀 깐깐해 보이는데, 깐깐하지 않으면 AI가 매번 다른 레이아웃을 뱉어요. 일관성의 적이죠.)

세 번째, Component · Style · Icon Rules. 컴포넌트는 정의된 것만 사용하고, 허용된 variant만 적용해요. primary action 남용 금지, 불필요한 컴포넌트 조합 금지. 스타일 쪽은 body-sm, heading-lg 같은 semantic typography만 허용하고 raw font 값 직접 할당은 막아요. spacing.16 같은 spacing token만 쓸 수 있고 임의 간격은 금지. 일관된 레이아웃 리듬을 유지하라고 명시되어 있어요. 아이콘도 icons.json에 정의된 것만 사용 가능하고, 아이콘 사용 맥락(usage context)을 따라야 하며, 아이콘을 AI가 생성하거나 대체하는 건 금지예요.

네 번째, State Handling과 Output Format. 모든 UI는 loading state, empty state, error state 세 가지를 반드시 고려해야 해요. 이건 디자이너들 사이에서도 자주 빠뜨리는 부분인데, CLAUDE.md에 명시해두면 AI가 알아서 챙겨요. 결과물 포맷도 정해져 있어요. 선택한 패턴이 뭔지, 레이아웃 구조가 어떤지, 어떤 컴포넌트를 사용했는지, variant 선택은 뭔지, 적용된 토큰은 뭔지, 사용한 아이콘은 뭔지 — 여섯 가지를 구조화된 형태로 뱉어야 해요. 애매한 설명은 안 돼요.

요구사항이 불명확할 때는 AI가 추측하거나 발명하지 말고, 명확히 물어보거나 가장 가까운 패턴을 사용하도록 되어 있어요. 과도한 디자인, 시각적 노이즈, 불필요한 변형은 피하라고도 명시되어 있고요.

디자인 시스템 구조가 꼼꼼하게 만들어져 있지 않으면 이 workflow의 mandatory 항목들을 따라가기 어려울 수도 있다고 해요. 맞는 말이에요. tokens 폴더에 color.json이 없는데 "토큰을 참조해"라고 하면 AI가 뭘 참조하겠어요. CLAUDE.md의 품질은 결국 그 앞 단계에서 토큰과 컴포넌트를 얼마나 체계적으로 정리했느냐가 결정해요.

icons.json이 하는 일 — SVG 폴더만으로는 AI가 못 읽는다

아이콘 이야기를 좀 더 해볼게요. SVG 파일을 폴더에 넣어두는 것만으로는 AI가 아이콘을 제대로 활용하지 못해요. 파일명이 ic_arrow_right_24.svg라고 해서 AI가 "아, 이건 오른쪽 화살표고 네비게이션에 쓰는 거구나"라고 알아서 추론하길 기대하기엔 좀 무리가 있거든요.

icons.json은 아이콘 사용 시 AI한테 가이드를 해주는 역할이에요. 각 아이콘의 이름(name), 파일 경로(file), 사용 맥락(usage)을 정의해요. `"name": "arrow_right"`, `"file": "ic_arrow_right_24.svg"`, `"usage": ["navigation"]` — 이런 형식이죠. Claude한테 SVG 파일들을 인식시키고 "이 구조로 매핑해줘"라고 요청하면 알아서 svg 아이콘들을 인식하고 json으로 매핑해줘요.

usage 필드가 왜 중요하냐면요. AI가 navigation 용도의 아이콘이 필요한 상황에서 arrow_right를 자동으로 골라낼 수 있기 때문이에요. 파일명만 보고 추측하는 게 아니라 명시적인 맥락 정보가 붙어 있으니까요. 사소해 보이지만 이런 메타데이터 하나하나가 일관성을 만들어요. AI가 매번 다른 아이콘을 쓰는 문제도 이 파일 하나로 잡을 수 있고요.

여기까지가 디자인시스템을 AI가 읽을 수 있는 형태로 변환하는 전체 과정이에요. Figma에서 출발해서 tokens, components, patterns, icons를 JSON으로 만들고, CLAUDE.md 가이드를 작성하고, Claude Code를 돌리는 흐름이에요.

아직 이 파이프라인으로 최종 UI를 뽑아보지는 못했다고 해요. 클로드 토큰이 모자라서 짬짬이 테스트하는 중이라고. 근데 구조 자체는 꽤 설득력 있어요. 디자인시스템이 체계적일수록, CLAUDE.md가 빡빡할수록, AI가 뱉는 결과물의 일관성이 올라갈 수밖에 없으니까요. 이건 논리적으로 당연한 거예요.

다음 글에서 이 시스템 기반으로 실제 일관된 UI를 뽑아내는 결과가 나온다고 하니까, 그때가 진짜 판단의 순간이에요. 구조는 갖춰졌고, 남은 건 증명뿐이에요.