Claude Design + Claude Code로 Figma 없이 Next.js 컴포넌트 자동 생성하기 — 핸드오프 번들 실전 가이드

대상 독자: Next.js와 Tailwind CSS를 사용해본 경험이 있으며, 디자이너와 협업하는 프론트엔드 개발자

디자인과 개발 사이의 벽은 팀의 속도를 꾸준히 늦춰왔습니다. 디자이너가 Figma에서 완성한 화면을 개발자가 픽셀 단위로 재현하는 동안 요구사항은 바뀌고, QA에서 불일치가 발견되고, 수정 사이클이 반복됩니다. 기존 디자인-개발 QA 사이클은 평균 2~3일이 소요되는 경우가 흔합니다. 2026년 4월 17일, Anthropic이 발표한 Claude Design + Claude Code 핸드오프 번들은 이 구조적 마찰을 하나의 대화 흐름 안에서 해소하는 시도입니다.

이 워크플로우의 핵심 흐름은 세 단계로 요약됩니다: ① Claude Design에서 텍스트 프롬프트로 프로토타입 생성 → ② /handoff 명령으로 사양 번들 패키징 → ③ Claude Code가 현재 코드베이스를 읽고 Next.js 15 App Router 컴포넌트를 자동 생성. 이 글에서는 각 단계의 실제 예시, 현 시점의 한계, 그리고 실무에서 자주 마주치는 함정을 함께 살펴봅니다.

Claude Code를 처음 접하는 분이라면 예시 1~2만 먼저 읽으셔도 충분합니다. 예시 3(Agent Skills)은 반복 작업 자동화를 원하는 분을 위한 심화 내용입니다.

핵심 개념

Claude Design이란 무엇인가

Claude Design은 Claude Opus 4.7을 기반으로 하는 Anthropic Labs의 실험 제품으로, 텍스트 프롬프트만으로 시각적 프로토타입, 슬라이드, 원페이저를 생성합니다. Canva와의 파트너십으로 PDF, URL, PPTX, Canva 형식 내보내기가 가능하며, Claude Pro·Max·Team·Enterprise 구독에 추가 과금 없이 포함됩니다.

Claude Design의 핵심은 반복 대화를 통한 점진적 시각화입니다. "레이아웃을 3단 그리드로 바꿔줘", "헤더 배경색을 #0F172A로 조정해줘" 같은 자연어 피드백이 즉시 반영되면서 프로토타입을 다듬어 나갈 수 있습니다.

Claude Artifacts: claude.ai에서 별도 설정 없이 인터랙티브 React/HTML 컴포넌트를 생성하고 링크로 공유할 수 있는 기능입니다. Claude Design에 아직 접근이 안 된다면, Artifacts로 빠른 프로토타이핑을 먼저 경험해보시면 좋습니다.

핸드오프 번들의 구조

Claude Design 작업이 완료된 시점에 /handoff 명령을 실행하면 다음 세 가지 정보가 패키징된 번들이 생성됩니다.

번들 구성 요소	내용
측정값(Measurements)	여백, 폰트 크기, 컴포넌트 간격 등 수치 사양
인터랙션 사양(Interaction Spec)	호버, 클릭, 전환 애니메이션 등 동작 정의
QA 체크리스트	구현 후 검증해야 할 항목 목록

Claude Code는 이 번들을 입력으로 받아 현재 코드베이스의 디자인 시스템을 스캔하는 것으로 관찰됩니다. 기존 컴포넌트 재사용 여부를 판단한 뒤 프로덕션 코드를 생성하며, 새 컴포넌트를 처음부터 만드는 것이 아니라 팀이 이미 사용 중인 스타일과 패턴을 우선 적용합니다. 스크린샷을 직접 붙여넣는 기존 방식과 가장 크게 다른 부분이 바로 이 지점입니다.

선택 기능: Figma MCP와 Agent Skills

이 두 기능은 핵심 핸드오프 워크플로우를 확장하는 선택적 도구입니다. 기본 흐름(예시 1~2)에 익숙해진 뒤 도입을 고려해보시면 좋습니다.

Figma MCP — 양방향 코드↔디자인 흐름

2026년 2월부터 Claude Code에 Figma MCP(Model Context Protocol) 서버를 연결하면 코드→디자인 역방향 전환도 가능합니다. 브라우저에서 렌더링된 상태가 편집 가능한 Figma 레이어로 자동 변환되어 디자이너와 개발자가 동일한 소스를 공유하게 됩니다. 서버 설치는 Figma 공식 가이드를 참고하시면 됩니다. 설치 후 Claude Code 터미널에서 다음과 같이 연결을 확인할 수 있습니다.

bash

# MCP 서버 목록 확인
claude mcp list

MCP(Model Context Protocol): AI 모델이 외부 도구 및 데이터 소스와 표준화된 방식으로 통신하기 위한 Anthropic의 오픈 프로토콜입니다.

Agent Skills(.claude/skills/)

.claude/skills/ 디렉토리에 마크다운 파일을 배치하면 Claude Code가 해당 도메인 지식을 사전 로드합니다. Figma 디자인 토큰을 Tailwind CSS 변수로 자동 동기화하거나, 컴포넌트 생성 시 shadcn/ui를 우선 재사용하는 규칙을 정의할 수 있습니다. 구체적인 설정 방법은 예시 3에서 확인할 수 있습니다.

실전 적용

위에서 살펴본 개념들이 실제로 어떻게 연결되는지 세 가지 예시를 통해 확인해봅니다. 예시 1과 2는 독립적으로 시작할 수 있으며, 예시 3은 예시 1의 반복 작업을 자동화하는 심화 내용입니다.

예시 1: B2B SaaS 대시보드 랜딩 페이지 구현

가장 전형적인 핸드오프 시나리오입니다. Claude Design에서 프로토타입을 만들고 Next.js 15 App Router 컴포넌트로 전환하는 전체 흐름을 살펴봅니다.

1단계 — Claude Design에서 프로토타입 생성

프롬프트: "대시보드 랜딩 페이지, 다크 테마, B2B SaaS 느낌.
상단 네비게이션, 히어로 섹션(CTA 버튼 2개),
3열 피처 카드, 푸터 포함"

반복 대화로 레이아웃과 색상을 조정한 뒤 /handoff를 실행합니다.

2단계 — Claude Code에 번들 전달

[Claude Code 프롬프트]
이 핸드오프 번들로 Next.js 15 App Router 컴포넌트를 생성해줘.
기존 shadcn/ui 컴포넌트를 최대한 재사용하고,
Tailwind 디자인 토큰은 현재 tailwind.config.ts를 참조해줘.
설명 없이 코드만 출력해줘.

3단계 — 생성된 코드 예시

typescript

// src/app/(marketing)/page.tsx
import Link from "next/link";
import { HeroSection } from "@/components/marketing/hero-section";
import { FeatureGrid } from "@/components/marketing/feature-grid";
import { SiteHeader } from "@/components/layout/site-header";
import { SiteFooter } from "@/components/layout/site-footer";
 
interface Feature {
  title: string;
  description: string;
  icon: string;
}
 
const FEATURES: Feature[] = [
  { title: "실시간 분석", description: "데이터를 즉시 시각화합니다", icon: "chart" },
  { title: "팀 협업", description: "권한 기반 대시보드 공유", icon: "users" },
  { title: "API 연동", description: "주요 SaaS와 원클릭 연결", icon: "plug" },
];
 
export default function LandingPage() {
  return (
    <div className="min-h-screen bg-background">
      <SiteHeader />
      <main>
        <HeroSection
          headline="데이터를 인사이트로"
          subline="팀의 의사결정을 10배 빠르게 만드는 B2B 분석 플랫폼"
          primaryCta={{ label: "무료로 시작하기", href: "/signup" }}
          secondaryCta={{ label: "데모 보기", href: "/demo" }}
        />
        <FeatureGrid features={FEATURES} />
      </main>
      <SiteFooter />
    </div>
  );
}

typescript

// src/components/marketing/hero-section.tsx
import Link from "next/link";
import { Button } from "@/components/ui/button"; // shadcn/ui 재사용
 
interface HeroSectionProps {
  headline: string;
  subline: string;
  primaryCta: { label: string; href: string };
  secondaryCta: { label: string; href: string };
}
 
export function HeroSection({
  headline,
  subline,
  primaryCta,
  secondaryCta,
}: HeroSectionProps) {
  return (
    <section className="container mx-auto px-4 py-24 text-center">
      <h1 className="text-5xl font-bold tracking-tight text-foreground mb-6">
        {headline}
      </h1>
      <p className="text-xl text-muted-foreground mb-10 max-w-2xl mx-auto">
        {subline}
      </p>
      <div className="flex gap-4 justify-center">
        <Button size="lg" asChild>
          <Link href={primaryCta.href}>{primaryCta.label}</Link>
        </Button>
        <Button size="lg" variant="outline" asChild>
          <Link href={secondaryCta.href}>{secondaryCta.label}</Link>
        </Button>
      </div>
    </section>
  );
}

자동 생성 포인트	설명
`shadcn/ui Button` 재사용	코드베이스 스캔 후 기존 컴포넌트 우선 사용
Next.js `Link` 컴포넌트	`<a>` 태그 대신 App Router 클라이언트 사이드 내비게이션 적용
`text-foreground`, `text-muted-foreground`	하드코딩 대신 CSS 변수 토큰 참조
Server Component	App Router 기본값 유지, `'use client'` 불필요 시 미추가
Props 인터페이스	TypeScript strict mode 준수
`Feature` 인터페이스	`FEATURES` 배열 타입 명시로 복붙 즉시 사용 가능

예시 2: Figma MCP를 통한 코드→디자인 역전환

개발 중 완성된 컴포넌트를 Figma로 역전송해 디자이너가 수정한 뒤 다시 코드에 반영하는 시나리오입니다. Figma MCP 서버가 설치된 상태에서 진행합니다.

bash

# 터미널: MCP 서버 연결 상태 먼저 확인
claude mcp list

[Claude Code 프롬프트]
src/components/marketing/hero-section.tsx를 Figma로 보내줘

위 프롬프트를 실행하면 브라우저 렌더링 상태가 편집 가능한 Figma 레이어로 변환됩니다. 디자이너가 Figma에서 색상이나 간격을 수정한 뒤, 다음 프롬프트로 변경사항을 코드에 반영할 수 있습니다.

[Claude Code 프롬프트]
Figma에서 업데이트된 hero-section 변경사항을 코드에 반영해줘.
기존 컴포넌트 구조는 유지할 것.

핵심 인사이트: 이 양방향 흐름은 디자이너와 개발자가 각자의 도구(Figma / 코드 에디터)를 유지하면서도 동일한 소스를 공유하게 만듭니다. "Figma 파일이 최신인가, 코드가 최신인가"라는 질문이 사라집니다.

예시 3: Agent Skills로 디자인 토큰 동기화 자동화

디자인 토큰이 변경될 때마다 Tailwind 설정을 수동으로 업데이트하는 반복 작업을 자동화하는 예시입니다. 예시 1의 핸드오프 워크플로우를 반복하는 팀이라면, 이 설정으로 컨벤션을 자동 적용할 수 있습니다.

markdown

<!-- .claude/skills/design-system.md -->
# Design System Skill
 
## 컴포넌트 생성 규칙
- shadcn/ui 컴포넌트가 존재하면 새로 만들지 않고 재사용합니다
- 링크 요소는 반드시 Next.js `Link` 컴포넌트를 사용합니다
- 색상 값은 반드시 디자인 시스템 토큰을 통해 참조합니다
 
## 토큰 동기화 절차 (/handoff 번들에 토큰 변경이 포함된 경우)
1. 번들의 색상 토큰을 `tailwind.config.ts`의 `colors` 섹션에 반영
2. 타이포그래피 토큰을 `fontSize`, `fontFamily`에 반영
3. CSS 변수는 `src/app/globals.css`의 `:root`와 `.dark` 블록에 동기화
4. 기존 커스텀 값은 덮어쓰지 않고 병합합니다
 
## 파일 구조
- 신규 컴포넌트: `src/components/ui/`
- 페이지 전용 컴포넌트: `src/components/[페이지명]/`

핸드오프 번들에 새 브랜드 컬러(--brand-500)가 추가된 경우, 동기화 전후 tailwind.config.ts의 변화는 다음과 같습니다.

typescript

// tailwind.config.ts — 동기화 전 (shadcn/ui 기본 설정)
import type { Config } from "tailwindcss";
 
const config: Config = {
  content: ["./src/**/*.{ts,tsx}"],
  theme: {
    extend: {
      colors: {
        primary: "hsl(var(--primary))",
        "primary-foreground": "hsl(var(--primary-foreground))",
        background: "hsl(var(--background))",
        foreground: "hsl(var(--foreground))",
      },
    },
  },
};
 
export default config;

typescript

// tailwind.config.ts — 동기화 후 (핸드오프 번들 토큰 병합)
import type { Config } from "tailwindcss";
 
const config: Config = {
  content: ["./src/**/*.{ts,tsx}"],
  theme: {
    extend: {
      colors: {
        primary: "hsl(var(--primary))",
        "primary-foreground": "hsl(var(--primary-foreground))",
        background: "hsl(var(--background))",
        foreground: "hsl(var(--foreground))",
        muted: "hsl(var(--muted))",
        "muted-foreground": "hsl(var(--muted-foreground))",
        // 핸드오프 번들에서 추가된 커스텀 토큰 (기존 값은 덮어쓰지 않음)
        brand: {
          500: "hsl(var(--brand-500))",
          600: "hsl(var(--brand-600))",
        },
      },
    },
  },
};
 
export default config;

장단점 분석

장점

항목	내용
원스톱 워크플로우	아이디어→프로토타입→프로덕션 코드를 단일 대화 루프 안에서 완결
디자인 시스템 인식	코드베이스를 스캔해 팀 스타일 자동 적용, shadcn/ui 재사용
추가 비용 없음	기존 Claude Pro/Max/Team/Enterprise 구독 한도 내 사용
양방향 흐름	코드→Figma 역변환으로 디자이너-개발자 협업 주기 단축
전체 코드베이스 처리	파일을 나눠 여러 번 붙여넣을 필요 없이 프로젝트 전체를 한 번에 읽고 처리 가능 (플랜별 컨텍스트 창 크기 상이)
Canva 연동	PDF·PPTX·URL 내보내기로 이해관계자 공유 용이

단점 및 주의사항

항목	내용	대응 방안
실험적 단계	Research Preview로 기능 불안정·오류 가능성 존재	생성 코드를 코드 리뷰 후 머지하는 절차 유지
구독 한도 소진	Claude Design 사용이 기존 메시지 한도를 함께 소모	Artifacts로 빠른 검증 후 Design 사용
이미지 생성 불가	이미지 분석만 가능, 래스터 자산 직접 생성 미지원	Unsplash API, Cloudinary 등 외부 자산 소스와 병행
복잡한 인터랙션 한계	드래그·다중 스텝 애니메이션 등 고도 인터랙티브 UI는 수동 보완 필요	Framer Motion 등 별도 라이브러리와 조합
MCP 설정 허들	Figma MCP 연동에 별도 서버 설치 및 설정 필요	`.claude/mcp.json` 설정 파일을 Git에 포함해 팀 단위로 공유
장황한 코드 설명	생성 시 불필요하게 긴 설명이 붙는 경향	프롬프트에 "설명 없이 코드만 출력해줘" 명시

App Router: Next.js 13부터 도입된 라우팅 방식으로, app/ 디렉토리 기반의 Server Component, 레이아웃, 에러 바운더리를 지원합니다. Claude Code는 Pages Router가 아닌 App Router 구조로 컴포넌트를 자동 생성하는 것으로 관찰됩니다.

실무에서 가장 흔한 실수

핸드오프 번들 없이 Claude Code에 디자인 스크린샷을 직접 전달하는 것 — 번들에는 수치 사양과 QA 체크리스트가 포함되어 있어, 스크린샷만 전달했을 때보다 훨씬 정밀한 코드가 생성됩니다. /handoff 명령을 반드시 거치는 것을 권장합니다.
Agent Skills 파일 없이 프로젝트별 컨벤션을 매번 프롬프트에 설명하는 것 — .claude/skills/ 디렉토리에 팀 컨벤션을 한 번 정의해두면 이후 모든 작업에 자동 적용됩니다. 온보딩 비용도 함께 줄어듭니다.
생성된 컴포넌트를 타입 검사 없이 바로 배포하는 것 — Claude Code는 TypeScript strict mode를 준수하려 하지만, 복잡한 제네릭이나 외부 타입 의존성에서 오류가 발생할 수 있습니다. pnpm build 후 타입 에러를 반드시 확인하는 것을 권장합니다.

마치며

Claude Design의 /handoff 명령과 Claude Code의 코드베이스 인식 능력이 결합될 때, 디자인과 개발 사이의 번역 비용이 사라지고 팀의 이터레이션 속도가 근본적으로 달라집니다.

지금 바로 시작해볼 수 있는 3단계를 안내합니다.

Agent Skills 파일 작성 — 기존 프로젝트의 .claude/skills/design-system.md에 shadcn/ui 재사용 규칙, 파일 구조, Tailwind 토큰 참조 방식을 정의해두면, 다음 번 핸드오프 번들을 전달했을 때 팀 컨벤션이 자동 반영된 코드를 받을 수 있습니다.
Claude Design 또는 Artifacts로 첫 프로토타입 만들기 — claude.ai에 로그인한 뒤 좌측 사이드바에서 "Design" 메뉴가 보인다면 바로 시작할 수 있습니다. 아직 순차 공개 중이라 보이지 않는다면 Claude Artifacts로 먼저 인터랙티브 컴포넌트 프로토타이핑을 경험해보시면 좋습니다.
Figma MCP 서버 설치 — Figma 공식 가이드를 참고해 로컬 환경에 MCP 서버를 설치하고 .claude/mcp.json에 설정을 추가해볼 수 있습니다. 설정이 완료되면 Claude Code 터미널에서 "현재 페이지를 Figma로 보내줘" 한 줄로 코드↔디자인 양방향 흐름을 경험할 수 있습니다.

다음 글 발행 시 알림을 받고 싶으시다면 뉴스레터를 구독해두시면 좋습니다.

다음 글: Figma MCP 서버를 팀 환경에서 설정하고 Claude Code와 연동해 디자인 시스템 토큰을 지속적으로 동기화하는 CI/CD 파이프라인 구축 실전 가이드

참고 자료

Claude

Claude Design + Claude Code로 Figma 없이 Next.js 컴포넌트 자동 생성하기 — 핸드오프 번들 실전 가이드

대상 독자: Next.js와 Tailwind CSS를 사용해본 경험이 있으며, 디자이너와 협업하는 프론트엔드 개발자

Claude Code를 처음 접하는 분이라면 예시 1~2만 먼저 읽으셔도 충분합니다. 예시 3(Agent Skills)은 반복 작업 자동화를 원하는 분을 위한 심화 내용입니다.

핵심 개념

Claude Design이란 무엇인가

Claude Artifacts: claude.ai에서 별도 설정 없이 인터랙티브 React/HTML 컴포넌트를 생성하고 링크로 공유할 수 있는 기능입니다. Claude Design에 아직 접근이 안 된다면, Artifacts로 빠른 프로토타이핑을 먼저 경험해보시면 좋습니다.

핸드오프 번들의 구조

Claude Design 작업이 완료된 시점에 /handoff 명령을 실행하면 다음 세 가지 정보가 패키징된 번들이 생성됩니다.

번들 구성 요소	내용
측정값(Measurements)	여백, 폰트 크기, 컴포넌트 간격 등 수치 사양
인터랙션 사양(Interaction Spec)	호버, 클릭, 전환 애니메이션 등 동작 정의
QA 체크리스트	구현 후 검증해야 할 항목 목록

선택 기능: Figma MCP와 Agent Skills

이 두 기능은 핵심 핸드오프 워크플로우를 확장하는 선택적 도구입니다. 기본 흐름(예시 1~2)에 익숙해진 뒤 도입을 고려해보시면 좋습니다.

Figma MCP — 양방향 코드↔디자인 흐름

bash

# MCP 서버 목록 확인
claude mcp list

MCP(Model Context Protocol): AI 모델이 외부 도구 및 데이터 소스와 표준화된 방식으로 통신하기 위한 Anthropic의 오픈 프로토콜입니다.

Agent Skills(.claude/skills/)

실전 적용

예시 1: B2B SaaS 대시보드 랜딩 페이지 구현

가장 전형적인 핸드오프 시나리오입니다. Claude Design에서 프로토타입을 만들고 Next.js 15 App Router 컴포넌트로 전환하는 전체 흐름을 살펴봅니다.

1단계 — Claude Design에서 프로토타입 생성

프롬프트: "대시보드 랜딩 페이지, 다크 테마, B2B SaaS 느낌.
상단 네비게이션, 히어로 섹션(CTA 버튼 2개),
3열 피처 카드, 푸터 포함"

반복 대화로 레이아웃과 색상을 조정한 뒤 /handoff를 실행합니다.

2단계 — Claude Code에 번들 전달

[Claude Code 프롬프트]
이 핸드오프 번들로 Next.js 15 App Router 컴포넌트를 생성해줘.
기존 shadcn/ui 컴포넌트를 최대한 재사용하고,
Tailwind 디자인 토큰은 현재 tailwind.config.ts를 참조해줘.
설명 없이 코드만 출력해줘.

3단계 — 생성된 코드 예시

typescript

// src/app/(marketing)/page.tsx
import Link from "next/link";
import { HeroSection } from "@/components/marketing/hero-section";
import { FeatureGrid } from "@/components/marketing/feature-grid";
import { SiteHeader } from "@/components/layout/site-header";
import { SiteFooter } from "@/components/layout/site-footer";
 
interface Feature {
  title: string;
  description: string;
  icon: string;
}
 
const FEATURES: Feature[] = [
  { title: "실시간 분석", description: "데이터를 즉시 시각화합니다", icon: "chart" },
  { title: "팀 협업", description: "권한 기반 대시보드 공유", icon: "users" },
  { title: "API 연동", description: "주요 SaaS와 원클릭 연결", icon: "plug" },
];
 
export default function LandingPage() {
  return (
    <div className="min-h-screen bg-background">
      <SiteHeader />
      <main>
        <HeroSection
          headline="데이터를 인사이트로"
          subline="팀의 의사결정을 10배 빠르게 만드는 B2B 분석 플랫폼"
          primaryCta={{ label: "무료로 시작하기", href: "/signup" }}
          secondaryCta={{ label: "데모 보기", href: "/demo" }}
        />
        <FeatureGrid features={FEATURES} />
      </main>
      <SiteFooter />
    </div>
  );
}

typescript

// src/components/marketing/hero-section.tsx
import Link from "next/link";
import { Button } from "@/components/ui/button"; // shadcn/ui 재사용
 
interface HeroSectionProps {
  headline: string;
  subline: string;
  primaryCta: { label: string; href: string };
  secondaryCta: { label: string; href: string };
}
 
export function HeroSection({
  headline,
  subline,
  primaryCta,
  secondaryCta,
}: HeroSectionProps) {
  return (
    <section className="container mx-auto px-4 py-24 text-center">
      <h1 className="text-5xl font-bold tracking-tight text-foreground mb-6">
        {headline}
      </h1>
      <p className="text-xl text-muted-foreground mb-10 max-w-2xl mx-auto">
        {subline}
      </p>
      <div className="flex gap-4 justify-center">
        <Button size="lg" asChild>
          <Link href={primaryCta.href}>{primaryCta.label}</Link>
        </Button>
        <Button size="lg" variant="outline" asChild>
          <Link href={secondaryCta.href}>{secondaryCta.label}</Link>
        </Button>
      </div>
    </section>
  );
}

자동 생성 포인트	설명
`shadcn/ui Button` 재사용	코드베이스 스캔 후 기존 컴포넌트 우선 사용
Next.js `Link` 컴포넌트	`<a>` 태그 대신 App Router 클라이언트 사이드 내비게이션 적용
`text-foreground`, `text-muted-foreground`	하드코딩 대신 CSS 변수 토큰 참조
Server Component	App Router 기본값 유지, `'use client'` 불필요 시 미추가
Props 인터페이스	TypeScript strict mode 준수
`Feature` 인터페이스	`FEATURES` 배열 타입 명시로 복붙 즉시 사용 가능

예시 2: Figma MCP를 통한 코드→디자인 역전환

bash

# 터미널: MCP 서버 연결 상태 먼저 확인
claude mcp list

[Claude Code 프롬프트]
src/components/marketing/hero-section.tsx를 Figma로 보내줘

[Claude Code 프롬프트]
Figma에서 업데이트된 hero-section 변경사항을 코드에 반영해줘.
기존 컴포넌트 구조는 유지할 것.

핵심 인사이트: 이 양방향 흐름은 디자이너와 개발자가 각자의 도구(Figma / 코드 에디터)를 유지하면서도 동일한 소스를 공유하게 만듭니다. "Figma 파일이 최신인가, 코드가 최신인가"라는 질문이 사라집니다.

예시 3: Agent Skills로 디자인 토큰 동기화 자동화

markdown

<!-- .claude/skills/design-system.md -->
# Design System Skill
 
## 컴포넌트 생성 규칙
- shadcn/ui 컴포넌트가 존재하면 새로 만들지 않고 재사용합니다
- 링크 요소는 반드시 Next.js `Link` 컴포넌트를 사용합니다
- 색상 값은 반드시 디자인 시스템 토큰을 통해 참조합니다
 
## 토큰 동기화 절차 (/handoff 번들에 토큰 변경이 포함된 경우)
1. 번들의 색상 토큰을 `tailwind.config.ts`의 `colors` 섹션에 반영
2. 타이포그래피 토큰을 `fontSize`, `fontFamily`에 반영
3. CSS 변수는 `src/app/globals.css`의 `:root`와 `.dark` 블록에 동기화
4. 기존 커스텀 값은 덮어쓰지 않고 병합합니다
 
## 파일 구조
- 신규 컴포넌트: `src/components/ui/`
- 페이지 전용 컴포넌트: `src/components/[페이지명]/`

핸드오프 번들에 새 브랜드 컬러(--brand-500)가 추가된 경우, 동기화 전후 tailwind.config.ts의 변화는 다음과 같습니다.

typescript

// tailwind.config.ts — 동기화 전 (shadcn/ui 기본 설정)
import type { Config } from "tailwindcss";
 
const config: Config = {
  content: ["./src/**/*.{ts,tsx}"],
  theme: {
    extend: {
      colors: {
        primary: "hsl(var(--primary))",
        "primary-foreground": "hsl(var(--primary-foreground))",
        background: "hsl(var(--background))",
        foreground: "hsl(var(--foreground))",
      },
    },
  },
};
 
export default config;

typescript

// tailwind.config.ts — 동기화 후 (핸드오프 번들 토큰 병합)
import type { Config } from "tailwindcss";
 
const config: Config = {
  content: ["./src/**/*.{ts,tsx}"],
  theme: {
    extend: {
      colors: {
        primary: "hsl(var(--primary))",
        "primary-foreground": "hsl(var(--primary-foreground))",
        background: "hsl(var(--background))",
        foreground: "hsl(var(--foreground))",
        muted: "hsl(var(--muted))",
        "muted-foreground": "hsl(var(--muted-foreground))",
        // 핸드오프 번들에서 추가된 커스텀 토큰 (기존 값은 덮어쓰지 않음)
        brand: {
          500: "hsl(var(--brand-500))",
          600: "hsl(var(--brand-600))",
        },
      },
    },
  },
};
 
export default config;

장단점 분석

장점

항목	내용
원스톱 워크플로우	아이디어→프로토타입→프로덕션 코드를 단일 대화 루프 안에서 완결
디자인 시스템 인식	코드베이스를 스캔해 팀 스타일 자동 적용, shadcn/ui 재사용
추가 비용 없음	기존 Claude Pro/Max/Team/Enterprise 구독 한도 내 사용
양방향 흐름	코드→Figma 역변환으로 디자이너-개발자 협업 주기 단축
전체 코드베이스 처리	파일을 나눠 여러 번 붙여넣을 필요 없이 프로젝트 전체를 한 번에 읽고 처리 가능 (플랜별 컨텍스트 창 크기 상이)
Canva 연동	PDF·PPTX·URL 내보내기로 이해관계자 공유 용이

단점 및 주의사항

항목	내용	대응 방안
실험적 단계	Research Preview로 기능 불안정·오류 가능성 존재	생성 코드를 코드 리뷰 후 머지하는 절차 유지
구독 한도 소진	Claude Design 사용이 기존 메시지 한도를 함께 소모	Artifacts로 빠른 검증 후 Design 사용
이미지 생성 불가	이미지 분석만 가능, 래스터 자산 직접 생성 미지원	Unsplash API, Cloudinary 등 외부 자산 소스와 병행
복잡한 인터랙션 한계	드래그·다중 스텝 애니메이션 등 고도 인터랙티브 UI는 수동 보완 필요	Framer Motion 등 별도 라이브러리와 조합
MCP 설정 허들	Figma MCP 연동에 별도 서버 설치 및 설정 필요	`.claude/mcp.json` 설정 파일을 Git에 포함해 팀 단위로 공유
장황한 코드 설명	생성 시 불필요하게 긴 설명이 붙는 경향	프롬프트에 "설명 없이 코드만 출력해줘" 명시

App Router: Next.js 13부터 도입된 라우팅 방식으로, app/ 디렉토리 기반의 Server Component, 레이아웃, 에러 바운더리를 지원합니다. Claude Code는 Pages Router가 아닌 App Router 구조로 컴포넌트를 자동 생성하는 것으로 관찰됩니다.

실무에서 가장 흔한 실수

핸드오프 번들 없이 Claude Code에 디자인 스크린샷을 직접 전달하는 것 — 번들에는 수치 사양과 QA 체크리스트가 포함되어 있어, 스크린샷만 전달했을 때보다 훨씬 정밀한 코드가 생성됩니다. /handoff 명령을 반드시 거치는 것을 권장합니다.
Agent Skills 파일 없이 프로젝트별 컨벤션을 매번 프롬프트에 설명하는 것 — .claude/skills/ 디렉토리에 팀 컨벤션을 한 번 정의해두면 이후 모든 작업에 자동 적용됩니다. 온보딩 비용도 함께 줄어듭니다.
생성된 컴포넌트를 타입 검사 없이 바로 배포하는 것 — Claude Code는 TypeScript strict mode를 준수하려 하지만, 복잡한 제네릭이나 외부 타입 의존성에서 오류가 발생할 수 있습니다. pnpm build 후 타입 에러를 반드시 확인하는 것을 권장합니다.

마치며

지금 바로 시작해볼 수 있는 3단계를 안내합니다.

Agent Skills 파일 작성 — 기존 프로젝트의 .claude/skills/design-system.md에 shadcn/ui 재사용 규칙, 파일 구조, Tailwind 토큰 참조 방식을 정의해두면, 다음 번 핸드오프 번들을 전달했을 때 팀 컨벤션이 자동 반영된 코드를 받을 수 있습니다.
Claude Design 또는 Artifacts로 첫 프로토타입 만들기 — claude.ai에 로그인한 뒤 좌측 사이드바에서 "Design" 메뉴가 보인다면 바로 시작할 수 있습니다. 아직 순차 공개 중이라 보이지 않는다면 Claude Artifacts로 먼저 인터랙티브 컴포넌트 프로토타이핑을 경험해보시면 좋습니다.
Figma MCP 서버 설치 — Figma 공식 가이드를 참고해 로컬 환경에 MCP 서버를 설치하고 .claude/mcp.json에 설정을 추가해볼 수 있습니다. 설정이 완료되면 Claude Code 터미널에서 "현재 페이지를 Figma로 보내줘" 한 줄로 코드↔디자인 양방향 흐름을 경험할 수 있습니다.

다음 글 발행 시 알림을 받고 싶으시다면 뉴스레터를 구독해두시면 좋습니다.

다음 글: Figma MCP 서버를 팀 환경에서 설정하고 Claude Code와 연동해 디자인 시스템 토큰을 지속적으로 동기화하는 CI/CD 파이프라인 구축 실전 가이드