AI를 활용한 Figma에서 프로덕션 React로의 전환

새로운 디자인-투-코드 (design-to-code) 워크플로우의 네 가지 요소: 프로젝트 내의 shadcncraft, shadcncraft Figma 키트, Figma MCP, 그리고 shadcn MCP입니다. 이를 어떻게 설정하는지, 실제 작업에서 루프가 실제로 어떻게 작동하는지, 그리고 기존 프로젝트에 어떻게 도입하는지에 대해 알아봅니다.

디자이너들은 수년 동안 "디자인-투-코드"를 약속받아 왔습니다. 하지만 실제로 전달된 것은 아무도 배포하고 싶어 하지 않는 div soup(div 덩어리)를 내보내는 버튼뿐이었습니다. 그 약속은 조용히 정체되었습니다. 지난 12개월 동안 무언가 변화가 일어났으며, 그 결과로 나온 워크플로우는 마침내 실제 팀이 사용할 수 있는 수준에 도달했습니다.

이 포스트는 벽 너머로 레드라인 (redlines)을 던지는 것을 그만두고 싶은 디자이너와, Figma 레이어를 수동으로 JSX로 변환하는 일을 멈추고 싶은 개발자를 위한 것입니다. 이것은 단 하나의 루프에 관한 것입니다: 당신의 React 컴포넌트와 일대일로 일치하는 키트를 사용하여 Figma에서 디자인한 다음, AI 도구가 Figma 파일을 읽어 당신의 코드베이스와 이미 동일한 언어로 말하는 코드를 생성하도록 하는 것입니다. 팀의 양측 모두 각자의 네이티브 도구에서 작업합니다. AI는 과거에 모두에게 세금처럼 여겨졌던 번역 단계를 수행합니다.

아래는 이 루프가 어떻게 작동하는지, 기존 프로젝트에 어떻게 설정하는지, 그리고 어디에서 사용자가 직접 제어권을 유지해야 하는지에 대한 내용입니다.

왜 이 루프가 지금은 다른가

세 가지 조건이 동시에 충족되어야 했으며, 마침내 그것이 가능해졌습니다.

첫째, 디자인 파일이 프로덕션 코드와 동일한 빌딩 블록 (building blocks)을 사용해야 합니다. "버튼의 Figma 버전"이 아닙니다. 동일한 이름, 동일한 변형 (variants), 동일한 프롭 인터페이스 (prop surface)를 가진 동일한 버튼이 당신의 Figma 라이브러리와 /components/ui/ 폴더에 모두 존재해야 합니다. shadcncraft는 이 제약 조건을 중심으로 구축되었습니다. Figma 키트와 React 레지스트리 (registry)는 컴포넌트 단위로, 슬롯 (slot) 단위로 서로를 거울처럼 반영합니다.

둘째, AI가 디자인을 볼 수 있어야 합니다. Figma MCP 서버는 파일 시스템이 코드 에디터에 노출되는 것과 동일한 방식으로 디자인 파일을 AI 도구에 노출합니다. 이제 Claude, Cursor, Codex 및 관련 도구들은 프레임 (frame)을 읽고, 그 구조를 이해하며, 사용된 변수 (variables)를 확인하고, 이에 대해 추론할 수 있습니다. 이것이 워크플로우를 뒤바꾼 핵심입니다. 작년까지만 해도 AI 도구들은 스크린샷만을 볼 수 있었습니다. 하지만 이제는 레이어 (layers)를 읽을 수 있습니다.

셋째, AI가 컴포넌트 (components)를 인식해야 합니다. shadcn MCP 서버와 shadcncraft의 네임스페이스가 지정된 레지스트리 (namespaced registry) 덕분에, AI는 매번 React를 처음부터 새로 생성하지 않습니다. 대신 설치된 키트에서 적절한 컴포넌트를 가져와 이를 조합할 수 있습니다. 생성된 코드는 마치 당신의 컨벤션 (conventions)을 이미 알고 있는 사람이 작성한 것처럼 보이는데, 실제로 그렇기 때문입니다.

이 세 가지 요소가 연결되면 다음과 같은 루프가 실행됩니다: 화면을 디자인하고, AI에게 구현을 요청하며, 실제 컴포넌트를 사용한 초안을 받은 뒤, 에디터에서 다듬습니다. 과거에 오후 내내 걸렸던 번역 단계가 이제는 몇 분 만에 끝납니다. 양 끝단이 동일한 키트에 고정되어 있기 때문에 디자인과 코드 사이의 괴리 (drift)도 줄어듭니다.

엔드 투 엔드 (end to end) 설정

연결해야 할 네 가지 요소가 있습니다. 일단 설정이 완료되면 이 부분은 다시 건드릴 필요가 없습니다.

1. React 프로젝트에 shadcncraft 설치

프로젝트에서 이미 shadcn/ui를 사용하고 있다면, 이미 거의 다 온 것이나 다름없습니다. components.json에 shadcncraft 레지스트리를 추가하고, .env에 라이선스 키를 설정하면, 표준 shadcn CLI를 통해 어떤 블록 (block)이나 컴포넌트도 설치할 수 있습니다:

pnpm dlx shadcn@latest add @shadcncraft/header-1

스타일 프리셋 (style presets)을 전환하는 방법과 팀 라이선스를 구성하는 방법을 포함한 전체 설정 방법은 설치 문서 (Installation docs)에 나와 있습니다.

2. Figma에서 연 shadcncraft Figma 키트

Figma에서 키트를 엽니다. 이것이 여러분의 디자인 라이브러리 (design library)가 됩니다. 코드에서 설치할 수 있는 모든 블록과 컴포넌트는 이곳에 동일한 이름과 동일한 변형 (variants)을 가진 대응 항목으로 존재합니다. 테마는 shadcncraft Figma 플러그인을 사용하여 파일 내부에서 관리되며, 이 플러그인은 Figma 파일에서 shadcn 호환 CSS 변수 (CSS variables)를 코드베이스로 직접 내보낼 수 있습니다. 이제 디자인 토큰 (design tokens)과 코드 토큰 (code tokens)은 더 이상 별도로 관리해야 하는 두 가지 요소가 아닙니다.

3. AI 도구에 연결된 Figma MCP 서버

Figma 설정에서 Figma MCP 서버를 활성화한 다음, 여러분의 AI 도구가 이를 가리키도록 설정하세요. Cursor, Claude Code, VS Code, 그리고 Codex는 모두 MCP 서버를 지원합니다. 연결되면 AI는 shadcncraft 키트와 그 위에 설계 중인 화면을 포함하여 여러분이 열어둔 모든 Figma 파일을 읽을 수 있습니다.

4. 함께 연결된 shadcn MCP 서버

shadcncraft 레지스트리 (registry)는 shadcn MCP 서버와 즉시 연동됩니다. 프로젝트 루트에서 선택한 에디터에 맞는 초기화 (init) 명령어를 실행하세요:

pnpm dlx shadcn@latest mcp init --client cursor
pnpm dlx shadcn@latest mcp init --client claude
pnpm dlx shadcn@latest mcp init --client vscode

두 MCP 서버가 모두 연결되면, 여러분의 AI 도구는 Figma 파일(Figma MCP를 통해)을 읽는 동시에 키트에서 적절한 컴포넌트를 설치(shadcn MCP를 통해)할 수 있습니다. 이것이 바로 가교 (bridge) 역할을 합니다.

네 가지 요소 중 하나라도 누락되면 루프 (loop)는 기능이 저하된 형태로 작동합니다. AI 없이 수동으로 빌드하거나, Figma MCP 없이 AI를 사용하여 디자인 컨텍스트 (design context)를 놓칠 수 있습니다. 하지만 이 네 가지가 모두 함께 있을 때, 이것은 계속해서 탭을 전환해야 하는 네 개의 별개 도구가 아니라 하나의 통합된 워크플로 (workflow)처럼 느껴지게 됩니다.

실제 사례에서의 루프

실제 작업에서 루프가 어떻게 작동하는지 살펴보겠습니다. 이미 shadcn/ui로 구축된 기존 SaaS 앱이 있고, 여기에 결제 설정 (billing settings) 페이지를 추가해야 한다고 가정해 봅시다.

Figma 파일을 엽니다. shadcncraft 블록들을 사용하여 화면을 구성합니다: 페이지 헤더 (page header), 설정 네비게이션 (settings nav), 플랜 요약 카드 (plan summary card), 인보이스 테이블 (invoices table), 결제 수단 블록 (payment method block). 이것들은 키트(kit)에서 가져온 실제 컴포넌트들이기 때문에, 이미 적절한 토큰 (tokens), 적절한 간격 (spacing), 그리고 적절한 빈 상태 (empty states) 및 에러 상태 (error states)를 갖추고 있습니다. 문구를 수정하고, 플랜 등급 (plan tier)을 교체하며, 테이블이 실제 데이터 구조 (data shape)를 가리키도록 설정합니다. 디자인에는 약 20분 정도가 소요됩니다.

그런 다음 에디터로 전환하여 Claude에게 다음과 같이 요청합니다:

"Figma에서 선택한 프레임(frame)을 바탕으로 결제 설정 (billing settings) 페이지를 구축해줘. 이 프로젝트에 이미 존재하는 shadcncraft 컴포넌트들을 사용해. 사용자 설정 (user settings) 페이지의 기존 라우트 컨벤션 (route conventions)과 데이터 페칭 (data fetching) 패턴을 유지해줘."

Claude는 Figma MCP를 통해 Figma 프레임을 읽습니다. Claude는 shadcncraft의 레이어 이름 (layer names)을 확인합니다. shadcncraft의 컨벤션은 레이어 이름이 React 컴포넌트의 data-slot 값과 일치하도록 하는 것이므로, Claude는 card-header가 <CardHeader>가 되고, tabs-trigger가 <TabsTrigger>가 되는 식의 규칙을 이해합니다. 프로젝트에 아직 없는 것이 있다면 레지스트리 (registry)에서 설치하고, 기존의 데이터 페칭 패턴을 참조하여 페이지를 출력합니다.

첫 번째 결과물(first pass)만으로도 목표의 대부분에 도달할 수 있습니다. 변경 사항 (diff)을 검토합니다. 비즈니스 규칙 (business rules), 실제 데이터 구조 (data shape), 디자인에서 명시하지 않은 문구 (copy), AI가 고려하지 못한 예외 케이스 (edge cases) 등 오직 당신만이 수정할 수 있는 부분들을 바로잡습니다. 그리고 커밋 (commit)합니다.

이것이 바로 이전 세대의 디자인-투-코드 (design-to-code) 도구들이 결코 제공하지 못했던 부분입니다. 생성된 코드는 당신이 직접 작성할 리 없는 'div-soup' (div 태그가 난무하는 코드)가 아닙니다. 당신이 직접 선택했을 것과 동일한 컴포넌트를, 동일한 프롭스 (props)를 사용하여, 동일한 구성 (composition)으로 사용합니다. AI가 스크린샷으로부터 컴포넌트를 임의로 만들어낸 것이 아니라, 당신이 설치한 키트로부터 컴포넌트를 구성했기 때문입니다.

루프가 깨지는 지점, 그리고 그에 대한 대처법

솔직한 답변을 드리자면: 이 루프는 마법의 버튼이 아닙니다. 양 끝단(design과 code)이 모두 절제되어 있을 때 잘 작동합니다. 주의해야 할 사항은 다음과 같습니다.

Figma 파일은 shadcncraft 컴포넌트와 비슷해 보이는 커스텀 도형이 아니라, 반드시 shadcncraft 컴포넌트로 구축되어 있어야 합니다. 만약 디자이너가 일회성 수정을 위해 인스턴스(instance)를 분리(detach)했다면, AI는 더 이상 그 밑단의 컴포넌트를 인식할 수 없습니다. AI는 그저 사각형들이 들어있는 프레임(frame)으로만 인식할 뿐입니다. 이 경우 출력물은 여러분의 키트(kit)가 아닌 일반적인 JSX가 될 것입니다. 해결 방법은 기계적입니다. 인스턴스를 온전하게 유지하고, 분리(detach)하는 대신 슬롯(slots)과 변형 속성(variant properties)을 사용하여 변경 사항을 적용하십시오.

AI의 출력물은 시작점이지 최종 커밋(final commit)이 아닙니다. 빠르지만 숙련되지 않은 기여자가 보낸 풀 리퀘스트(pull request)처럼 취급하십시오. 코드를 읽고, 실행하고, 여러분의 코드베이스 컨벤션(conventions)에 맞지 않는 것은 리팩터링(refactor)하십시오. 이 방식의 장점은 리뷰(review) 과정을 없애는 것이 아니라, 첫 번째 패스(first pass)의 속도를 높이는 데 있습니다.

드리프트(Drift, 괴리)는 실제로 존재하지만, 이제는 측정 가능합니다. 오늘 화면을 생성했는데 다음 달에 키트가 업데이트된다면, 여러분의 화면은 자동으로 업데이트되지 않습니다. 이는 임포트(import) 방식이 아닌 설치(install) 방식의 모든 레지스트리(registry)가 가진 동일한 문제이며, shadcncraft는 shadcn과 동일한 방식인 문서의 업데이트 전략을 통해 이를 처리합니다. 핵심은 드리프트가 영구적인 기본 상태가 아니라, 이제는 가시화되고 해결 가능한 문제가 되었다는 점입니다.

AI가 잘못된 컴포넌트를 선택할 때, 해결책은 대개 더 명확한 이름입니다. 만약 동일한 프롬프트(prompt)를 사용했는데 Sheet를 원했음에도 계속 Dialog가 생성된다면, 그것은 AI의 문제가 아니라 여러분의 명명(naming)에 대한 피드백입니다. shadcncraft 컴포넌트 이름은 공개된 인터페이스(public surface)이며, 도구나 사람이 지속적으로 혼동을 일으킬 경우 저희는 이름을 업데이트합니다.

이것이 이전의 시도들보다 나은 이유

두 가지 이유가 있으며, 둘 다 구조적인 문제입니다.

1세대 디자인-투-코드(design-to-code) 도구들은 스크린샷을 활용해 영리하게 동작하려 했습니다. 픽셀을 읽고 구조를 추론(infer)하려고 시도했습니다. 이는 정적인 사각형에는 작동하지만, 상태(stateful)가 있거나, 반응형(responsive)이거나, 실제 프리미티브(primitives)로 구성된 모든 것에서는 무너집니다. 반면, 이 루프(loop)는 실제 Figma 레이어 트리(layer tree)를 읽고 이를 실제 React 컴포넌트와 매칭합니다. 틀릴 수 있는 추론 계층(inference layer)이 존재하지 않습니다.

둘째는 디자인 파일과 프로덕션 코드 (production code)가 동일한 소스에 고정되어 있다는 점입니다. 양측 모두 동일한 키트 (kit), 동일한 이름, 동일한 변형 (variants), 동일한 토큰 (tokens)을 사용합니다. AI는 두 언어 사이를 번역할 필요 없이, 그저 조립하기만 하면 됩니다. 이것이 현재 AI 도구들이 잘하는 부분입니다.

기존 프로젝트에 도입하기

처음부터 다시 시작할 필요는 없습니다. 아마 그래서도 안 될 것입니다.

만약 프로젝트에서 이미 shadcn/ui를 사용하고 있다면, 기존의 어떤 것도 제거하지 않고 그 위에 shadcncraft를 계층적으로 쌓을 수 있습니다. 컴포넌트 (components)는 기존 컴포넌트와 나란히 설치됩니다. 토큰 (tokens)도 일치합니다. 로드맵에서 화면 하나를 선택하세요. 가급적이면 그린필드 (greenfield, 신규 구축) 프로젝트이거나 리프레시가 필요한 화면이 좋습니다. 그리고 그 단일 화면에 대해 루프 (loop)를 처음부터 끝까지 시도해 보세요. 설정 페이지, 새로운 온보딩 플로우 (onboarding flow), 결제 카드 등 무엇이든 좋습니다. 전후를 솔직하게 비교할 수 있을 만큼 충분히 독립적인 것이라면 무엇이든 괜찮습니다.

첫 번째 화면에서 확인해야 할 것은 생산성 수치가 아닙니다. 여러분이 확인해야 할 것은 이 루프가 하나의 워크플로우 (workflow)처럼 느껴지는지, 아니면 네 개의 워크플로우처럼 느껴지는지입니다. 만약 하나처럼 느껴진다면, 거기서부터 확장해 나가십시오. 만약 네 개처럼 느껴진다면, 가장 흔한 원인은 네 가지 요소 중 하나가 실제로 연결되어 있지 않기 때문이며, 대개는 Figma MCP가 원인입니다. 10분 정도 시간을 내어 확인해 볼 가치가 있습니다.

시작할 곳을 찾고 있다면, 설치 문서 (Installation docs)에서 프로젝트 측 설정과 shadcn MCP 설정을 다루고 있습니다. Figma 키트 (kit)와 Figma MCP 설정은 Figma 내부에 있습니다. 화면 하나를 정하고, 오후 시간을 할애하여 결과물이 어떻게 나오는지 확인해 보세요.

디자이너와 개발자가 동일한 소스로 제품을 출시할 수 있다는 약속은 아주 오래전부터 존재해 왔습니다. 이것이 그 약속이 실제로 실현된 첫 번째 사례입니다.