Claude Code의 /design-sync를 사용하여 claude.ai/design 디자인 시스템을 CLI에서 조작해 보았다

이 기사의 요점 (2026년 6월): Anthropic 공식 Claude Code 스킬 /design-sync를 사용하여, 로컬의 HTML 컴포넌트 4개(Button·Card·Input·Badge)를 claude.ai/design 디자인 시스템 프로젝트로 업로드했다. 업로드는 「finalize_plan → write_files → register_assets」의 3단계로 진행하며, @dsCard 마커를 HTML에 삽입하는 것만으로는 카드가 표시되지 않는 주의할 점이 있었다. 최종적으로는 Claude Design의 UI 생성 채팅이 디자인 시스템 파일을 자동으로 읽어 들여, 컴포넌트를 조합한 일본어 기사 목록 페이지를 생성하는 것까지 확인할 수 있었다.

/design-sync는 Anthropic이 제공하는 Claude Code의 공식 스킬(슬래시 명령어)로, 내부에서는 DesignSync라는 MCP 도구가 작동하고 있다. claude.ai/design(Claude의 디자인 생성 서비스)의 디자인 시스템 프로젝트와 로컬의 HTML 컴포넌트 파일을 동기화하는 기능을 제공한다. Claude Code가 설치되어 있다면 추가 설정 없이 이용할 수 있다(Pro·Max·Team·Enterprise 플랜 필요).

Claude Design에서는 보통 채팅창에 "버튼을 만들어줘"라고 입력하면 Claude가 처음부터 UI를 생성한다. 하지만 /design-sync를 사용하면, 미리 자신이 정의한 컴포넌트(스타일이나 구조가 결정된 HTML)를 디자인 시스템으로 등록해 두고, 이후의 UI 생성 시 그것들을 소재로 사용하게 할 수 있다.

"기존 컴포넌트를 유지하면서 페이지 전체를 Claude가 구성하도록 하는 것"이 주요 유스케이스(Use Case)가 된다.

이번 작업은 다음과 같은 순서로 진행했다.

1. 프로젝트 생성 (create_project)
2. HTML 컴포넌트 준비 (@dsCard 마커가 포함된 파일 4개 작성)
3. 업로드: finalize_plan → write_files → register_assets
...

1번 프로젝트 생성은 다음과 같이 호출한다.

DesignSync(method: "create_project",
name: "UI Sandbox")
→ projectId: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"가 반환됨

절차는 얼핏 간단해 보이지만, 3번 업로드에 3단계가 필요하다는 점과 저자의 실제 기기 시험에서는 register_assets를 생략하면 카드가 표시되지 않았던 점이 함정이 된다. 자세한 내용은 후술한다.

컴포넌트 파일은 일반적인 HTML로 작성한다. 단, 첫 번째 줄에 @dsCard 마커 주석을 넣어야 한다.

<!-- @dsCard group="Components" -->
<!DOCTYPE html>
<html lang="ja">
...

group="Components" 부분은 디자인 시스템 패널에서의 그룹 분류에 사용된다. 이번에는 Button·Card·Input·Badge 4개 파일을 tmp/ds-sandbox/components/ 아래에 생성했다.

tmp/ds-sandbox/components/button/index.html
tmp/ds-sandbox/components/card/index.html
tmp/ds-sandbox/components/input/index.html
...

각 파일의 첫 번째 줄에 를 넣었다.

HTML 파일을 준비했다면 다음은 업로드다. 이 부분이 가장 중요한 포인트로, 3개의 MCP 메서드를 순서대로 호출해야 한다.

DesignSync(method: "finalize_plan",
writes: ["button/index.html", "card/index.html",
"input/index.html", "badge/index.html"],
...

이 메서드는 "앞으로 이 파일들을 작성하겠다"라는 선언을 서비스 측에 보내고, planId를 획득한다. localDir에는 컴포넌트 파일이 들어 있는 로컬 디렉터리를 지정한다.

DesignSync(method: "write_files",
planId: "plan-xxxxxxxx",
files: [
...

finalize_plan에서 획득한 planId를 사용하여, 실제로 파일 내용을 업로드한다.

DesignSync(method: "register_assets",
planId: "plan-xxxxxxxx")

업로드한 파일을 디자인 시스템 패널에 "카드 (card)"로서 명시적으로 등록한다. 저자의 실제 기기 테스트에서는 이 단계를 거치지 않으면 파일은 서버에 존재하지만 패널 상에는 표시되지 않았다.

이번에 가장 시간을 많이 잡아먹은 부분이 바로 이 점이다.

@dsCard 마커를 파일에 넣고 업로드한 후, claude.ai/design의 디자인 시스템 화면을 확인했을 때 카드가 전혀 표시되지 않았다. DesignSync의 사양 설명에는 "HTML 첫 번째 줄의 @dsCard 주석으로부터 카드 인덱스를 자동으로 구축한다"라고 되어 있지만, 저자의 실제 기기 테스트에서는 자동 인식이 작동하지 않았다.

register_assets 메서드를 호출함으로써, 업로드된 파일을 명시적으로 카드로 등록할 수 있었다. 이 메서드는 사양상 "레거시 (legacy): register preview cards explicitly"로 위치하고 있으며, @dsCard를 통한 자동 인식이 정식 방법인 것으로 보인다. 다만 저자의 환경에서는 자동 인식이 동작하지 않아 register_assets의 명시적인 호출이 필요했다.

사양 기재와 실제 동작이 일치하지 않았던 케이스로 기록해 둔다. 유사한 현상이 발생할 경우 register_assets를 시도해 보길 권한다. @dsCard 자동 인식이 어떤 조건에서 기능하는지는 현 시점에서 확인되지 않았다.

register_assets 완료 후 claude.ai/design/p/{projectId}를 열면, "Review draft design system" 화면에 4개의 카드가 나열되어 있었다.

Badge 컴포넌트 카드를 열면 Semantic, Solid, With Dot, Sizes와 같은 변형(variation)들이 자동으로 프리뷰 표시되어 있었다. HTML 내의 CSS 클래스 구조나 섹션 라벨을 파싱하여 각 상태를 검출하는 것으로 추측된다 (상세한 메커니즘은 비공개).

"Brand" 섹션에서는 4개의 컴포넌트 모두가 목록으로 표시되었다. 여기까지 오면 다음 UI 생성 시 소재로 사용할 수 있는 상태가 된다.

디자인 시스템이 등록되었다면, 드디어 UI 생성을 시도한다. "New design" 버튼으로 신규 디자인을 열면, 채팅창 아래에 "UI Sandbox ×"라는 컨텍스트 배지(context badge)가 자동으로 붙어 있었다. 프로젝트 이름이 자동으로 컨텍스트로서 첨부되는 사양이다.

다음 프롬프트를 입력했다.

Article list page using Card, Badge, Button, and Input (search)
from the UI Sandbox design system.

Claude는 응답하기 전에 디자인 시스템 파일을 읽어오는 처리를 수행했다 ("Listing files ×2, Reading ×4"라는 툴 호출이 화면에 표시되었다). 그 후:

Got everything I need. Building an article list page that combines all four components with working search/filter.

라고 응답하며 생성이 시작되었다.

생성된 페이지는 일본어 기사 목록 페이지였다. "記事一覧 (기사 목록)" 타이틀, 검색 바 (Input 컴포넌트), 카테고리 필터의 Badge, 기사 카드 (Card 컴포넌트) 9개, 우측 상단의 "+ 新しい記事 (새 기사)" Primary Button. 등록한 4개의 컴포넌트가 조합된 레이아웃이 출력되었다.

프롬프트는 영어로 작성했지만, 생성물은 레이블이나 샘플 데이터가 일본어로 되어 있다는 점이 흥미롭다. 등록한 컴포넌트 HTML에 일본어 샘플 텍스트가 포함되어 있어, Claude가 이를 통해 언어를 판단한 것으로 추측된다 (확인은 하지 않았다).

CLI에서 디자인 시스템을 조작하며 알게 된 점을 정리한다.

성공한 것:

프로젝트 생성 · 컴포넌트 업로드 · 카드 등록까지 MCP를 통해 완결할 수 있었다
등록한 컴포넌트를 Claude Design의 UI 생성 채팅이 자동으로 참조했다
4개의 컴포넌트를 조합한 페이지가 1개의 프롬프트로 생성되었다

어려웠던 점 / 주의사항:

@dsCard 마커만으로는 카드가 표시되지 않는다. register_assets의 명시적인 호출이 필요했다. 업로드는 finalize_plan → write_files → register_assets의 3단계가 필수적이다. 이 중 하나라도 생략하면 작동하지 않는다.

미확인 · 시도하지 않은 것:

register_assets가 '레거시(Legacy)'로 취급되는 배경 (향후 폐지 예정이 있는지 여부)
Web UI를 통한 업로드 시 @dsCard 자동 인식이 작동하는지 여부
컴포넌트 업데이트 (기존 카드 덮어쓰기)의 동작

'컴포넌트를 사전에 등록 → Claude가 소재로 사용한다'는 흐름은, 디자인의 일관성을 유지하면서 AI에게 새로운 페이지를 만들게 하는 용도에 적합하다. 다만 현시점에서는 @dsCard 자동 인식과 register_assets의 관계 등, 사양과 실제 기기 동작 사이에 괴리가 보이는 부분이 있으므로, 테스트할 때는 본 기사의 주의사항을 참고해 주길 바란다.

DesignSync처럼 '로컬 파일 → AI 서비스의 컨텍스트'라는 연계를 MCP로 구축하면, 다음 질문이 떠오른다——내 프로젝트 전체에서 어떤 정보를 어떤 에이전트에게 전달할 것인가, 어떻게 설계해야 하는가.

그러한 '에이전트 팀에게 정보를 전달하는 설계'를 체계화한 것이 Zenn Books 시리즈다. Vol.1 「만들기까지」에서는 Claude Code로 에이전트를 움직이기 시작하는 첫 단계를, Vol.4 「구조를 넘기기까지」에서는 권한 관리 · 정보 설계 · 거버넌스 구축 방법을 다루고 있다.

Claude Code를 능숙하게 다루는 에이전트 팀 만들기 Vol.1 「만들기까지」 (서장 · 제1부 무료)
Vol.4 「구조를 넘기기까지」 (서장 무료)

이 기사는 はてなブログ (Hatena Blog) 에서의 크로스 포스트입니다.

Claude Code의 /design-sync를 사용하여 claude.ai/design 디자인 시스템을 CLI에서 조작해 보았다

요약

핵심 포인트

댓글