Figma 디자인 토큰 AI 변환 누락: 하드코딩 오류 완벽 대처법

 

디자인 토큰이 하드코딩된 색상 값으로 변환되어 당황하셨나요? AI를 활용한 Figma to React 퍼블리싱 과정에서 디자인 변수(Token)가 누락되는 원인을 알아보고, 프롬프트와 구조화를 통해 변수 매핑 오류를 해결하는 방법을 알아봅니다.

 

요즘 AI 도구를 사용해서 피그마(Figma) 시안을 React 코드로 뚝딱 변환하는 작업, 다들 한 번쯤 시도해 보셨을 텐데요. 디자인이 곧바로 컴포넌트로 바뀌는 걸 보면 정말 신세계가 따로 없죠. 하지만 막상 결과물을 프로젝트에 적용하려고 코드를 까보면 한숨이 나오는 경우가 종종 있어요.

분명히 피그마에서는 Primary/500 같은 디자인 토큰(Design Token)으로 예쁘게 묶어놨는데, AI가 뱉어낸 코드에는 color: #6a1b9a처럼 헥스(Hex) 코드가 생으로 하드코딩되어 있는 현상 말이에요. 다크모드 대응이나 테마 변경을 하려면 이걸 일일이 다 찾아 바꿔야 하니 완전 짜증나죠. 저도 실무에서 이 문제 때문에 AI가 짜준 코드를 통째로 갈아엎은 적이 있답니다. 왜 이런 일이 발생하는지, 그리고 어떻게 하면 AI가 우리 팀의 디자인 토큰을 똑똑하게 매핑하게 만들 수 있는지 차근차근 짚어보도록 할게요. 😊

 

왜 AI는 디자인 토큰을 무시할까요? 🤔

AI가 코드를 생성할 때 피그마 API나 플러그인을 통해 데이터를 읽어오는데요. 이때 피그마의 내부 구조상 레이어에 적용된 '최종 결과값(Raw Value)'과 '참조된 변수명(Variable/Style Name)'이 분리되어 전달됩니다.

우리가 AI에게 "이 화면을 React로 만들어줘"라고 단순하게 명령하면, AI는 눈에 보이는 시각적 일치도에 집중하느라 참조된 변수명 대신 즉시 렌더링 가능한 하드코딩 값을 우선적으로 선택해버리는 경향이 있어요. 즉, var(--primary-color)라는 개념을 알면서도, 확실하게 화면을 똑같이 그릴 수 있는 #6a1b9a를 안전한 선택지로 고르는 셈이죠.

💡 알아두세요!
Figma에서 'Variables' 기능을 사용했더라도, AI 모델이나 연결된 MCP 서버가 해당 변수 참조 정보를 제대로 파싱하지 못하는 경우도 꽤 많습니다. 이럴 땐 중간 다리 역할을 해줄 정보가 필요해요.

 

하드코딩 vs 토큰 매핑 비교 📊

이해를 돕기 위해, AI가 잘못 변환한 하드코딩 방식과 우리가 궁극적으로 원하는 토큰 매핑 방식의 차이를 표로 비교해 봤어요.

구분	AI의 하드코딩 결과 (Bad)	토큰 매핑 결과 (Good)
색상 (Color)	color: #1a1a1a;	color: var(--text-primary);
여백 (Spacing)	padding: 16px;	padding: theme.space.md;
폰트 크기 (Typography)	font-size: 24px;	className="text-2xl" (Tailwind)

⚠️ 주의하세요!
컴포넌트 내부에 하드코딩된 수치가 3개 이상 보인다면, 그 코드는 유지보수가 불가능한 '일회용 코드'일 확률이 높습니다. 바로 프로젝트에 병합(Merge)하지 마세요.

 

해결책 1: 디자인 토큰 사전 주입하기 💉

AI가 마음대로 헥스 코드를 쓰지 못하게 하려면, 코딩을 시작하기 전에 우리가 사용하는 토큰 사전(Dictionary)을 먼저 학습시켜야 합니다. 프롬프트에 React 프로젝트에서 사용 중인 CSS 변수나 Tailwind 설정 파일의 일부를 미리 던져주는 것이죠.

예를 들어, 프롬프트 상단에 이런 식으로 명시해 줍니다.

📝 프롬프트 예시

"너는 이제부터 우리 팀의 시니어 프론트엔드 개발자야. 피그마 디자인을 React로 변환할 때 절대 Hex Color나 하드코딩된 px 단위를 쓰지 마.

[우리 팀의 디자인 토큰 규칙]
- Primary Color (#6a1b9a) -> var(--color-primary)
- Background (#f3e5f5) -> var(--color-bg-sub)
- Spacing 16px -> gap-4 또는 p-4 (Tailwind 기준)

이 규칙에 매핑되지 않는 색상이나 간격이 피그마에 있다면, 가장 가까운 토큰 값으로 강제 치환해서 코드를 작성해 줘."

 

AI 생성 코드 하드코딩 검출기 🔍

AI가 짜준 CSS나 Styled Components 코드에 헥스 코드가 몰래 섞여 들어오진 않았는지 바로 확인할 수 있는 간단한 자가 진단기를 만들어 보았습니다. 아래에 AI가 생성한 코드를 붙여넣어 보세요!

코드 내 Hex 색상 검사기

 

실전 사례: 버튼 컴포넌트의 배신 📚

제 경험을 하나 말씀드릴게요. 피그마에서 정말 완벽하게 Variables를 연동해 둔 공통 버튼(Button) 컴포넌트를 Claude를 통해 React로 변환한 적이 있어요. 처음엔 눈으로 보기에 디자인이 완벽해서 "와, 진짜 잘 됐다" 싶었죠.

그런데 나중에 다크모드를 붙이려고 보니 버튼 색상이 죽어도 안 변하는 거예요. 코드를 열어보니 background-color: var(--button-primary)가 아니라 background-color: #6a1b9a로 고정되어 있었던 거죠. 피그마 상에서 버튼의 상태(Hover, Active) 변수까지 지정해 뒀는데, AI는 그저 정지된 화면의 특정 색상값만 '스포이드로 찍어내듯' 가져온 것이 원인이었습니다.

결국 해결책은 AI와 대화할 때 Figma의 JSON 토큰 파일(또는 CSS Variables 리스트)을 컨텍스트로 먼저 던져주고, "이 안에서만 골라서 써"라고 제한을 두는 것이었습니다. 제 생각엔 아직까지 AI가 피그마의 복잡한 로컬 변수(Local Variables) 참조 트리를 100% 자율적으로 해석하길 기대하는 건 무리인 것 같아요.

 

핵심 요약 노트 📝

글이 길어졌네요! 변수 매핑 오류를 방지하기 위해 실무에서 꼭 챙겨야 할 핵심을 카드 한 장으로 요약해 드릴게요.

💡

AI 토큰 매핑 성공 가이드

🔥 문제의 원인: AI는 참조 변수명보다 확실한 렌더링 값(Hex)을 선호합니다.

🧠 해결책 1 (프롬프트): 프로젝트에서 사용하는 토큰 리스트(CSS 변수명)를 AI에게 미리 주입하세요.

⚙️ 핵심 프롬프트 공식:

"모든 색상과 간격은 제공된 토큰 리스트 안에서만 가장 가까운 값으로 매핑할 것"

🔍 검증 습관: 코드를 병합하기 전 반드시 하드코딩된 값(#, px)이 남아있는지 검색해보세요.

조금만 가이드를 주면 AI도 훌륭한 시니어 퍼블리셔가 됩니다!

 

자주 묻는 질문 ❓

Q: Figma 플러그인을 쓰면 토큰 매핑이 알아서 되지 않나요?

A: 일부 플러그인(예: Anima, Builder.io 등)은 Figma Variables 연동을 지원하지만, ChatGPT나 Claude 등 범용 AI 모델에 화면을 넘길 때는 정보가 누락되는 경우가 많아 수동 가이드가 필요합니다.

Q: Tailwind를 사용할 때는 어떻게 매핑하나요?

A: 프롬프트에 `tailwind.config.js`의 theme 설정 일부를 복사해 주고, "인라인 스타일이나 커스텀 헥스 코드를 쓰지 말고 반드시 Tailwind 유틸리티 클래스(예: bg-primary-500)로 작성해"라고 명시해야 합니다.

Q: 폰트 스타일(Typography) 토큰도 맵핑이 잘 될까요?

A: 색상보다는 조금 더 까다롭습니다. 폰트는 크기, 굵기, 행간이 복합적으로 묶여 있기 때문에 "Heading 1은 text-2xl font-bold로 매핑해" 와 같이 복합 스타일 가이드를 명확히 주는 것이 좋습니다.

AI가 만들어주는 코드는 속도 면에서는 훌륭하지만, 결국 우리 프로젝트의 규칙(디자인 시스템)에 맞게 다듬는 건 아직 개발자의 몫인 것 같아요. 오늘 알려드린 프롬프트 가이드를 적용해보시면 유지보수하기 훨씬 편한 코드를 얻으실 수 있을 거예요! 실무에 적용해 보시다가 또 다른 문제가 생기거나 궁금한 점이 있다면 언제든 댓글로 물어봐주세요~ 😊