この記事の要点（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 スキルとは何か
/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 に組んでもらう」という使い方が主なユースケースになる。
操作の全体フロー
今回の作業は以下の順序で進めた。
1. プロジェクト作成（create_project）
2. HTML コンポーネントの準備（@dsCard マーカー付きファイルを4本作成）
3. アップロード：finalize_plan → write_files → register_assets
4. claude.ai/design でデザインシステムを確認
5. UI 生成チャットでコンポーネントを活用したページを作成
1番のプロジェクト作成は以下のように呼ぶ。
DesignSync(method: "create_project",
name: "UI Sandbox")
→ projectId: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" が返る
手順は一見シンプルだが、3番のアップロードに3ステップが必要な点と、著者の実機試行では register_assets を省略するとカードが表示されなかった点が落とし穴になる。詳しくは後述する。
コンポーネント HTML の作り方
コンポーネントファイルは通常の HTML で書く。ただし先頭行に @dsCard マーカーコメントを入れる必要がある。
<!-- @dsCard group="Components" -->
<!DOCTYPE html>
<html lang="ja">
<head>
<meta charset="UTF-8">
<title>Button</title>
</head>
<body>
<button class="btn-primary">Primary</button>
<button class="btn-secondary">Secondary</button>
</body>
</html>
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
tmp/ds-sandbox/components/badge/index.html
各ファイルの先頭行に <!-- @dsCard group="Components" --> を入れた。
アップロード3ステップの解説
HTML ファイルを用意したら、次はアップロードだ。ここが最も重要なポイントで、3つの MCP メソッドを順番に呼ぶ必要がある。
ステップ1: finalize_plan
DesignSync(method: "finalize_plan",
writes: ["button/index.html", "card/index.html",
"input/index.html", "badge/index.html"],
deletes: [],
localDir: "tmp/ds-sandbox/components")
→ planId: "plan-xxxxxxxx" が返る
このメソッドは「これからこのファイルを書き込む」という宣言をサービス側に送り、planId を取得する。localDir にはコンポーネントファイルが入っているローカルディレクトリを指定する。
ステップ2: write_files
DesignSync(method: "write_files",
planId: "plan-xxxxxxxx",
files: [
{path: "button/index.html", content: "<!-- @dsCard ... -->..."},
...
])
finalize_plan で取得した planId を使い、実際にファイルの内容をアップロードする。
ステップ3: register_assets
DesignSync(method: "register_assets",
planId: "plan-xxxxxxxx")
アップロードしたファイルをデザインシステムパネルに「カード」として明示的に登録する。著者の実機試行では、このステップを踏まないとファイルはサーバーに存在するもののパネル上に表示されなかった。
ハマりポイント：register_assets が必要だった理由
今回最も時間を取られたのがこの点だ。
@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 といったバリエーションが自動でプレビュー表示されていた。HTML 内の CSS クラス構造やセクションラベルをパースして各状態を検出しているものと推測される（詳細な仕組みは非公開）。
「Brand」セクションでは4コンポーネントすべてが一覧表示された。ここまで来れば、次の UI 生成で素材として使える状態だ。
Claude Design での UI 生成デモ
デザインシステムが登録できたら、いよいよ UI 生成を試す。「New design」ボタンで新規デザインを開くと、チャット欄の下に「UI Sandbox ×」というコンテキストバッジが自動で付いていた。プロジェクト名が自動的にコンテキストとして添付される仕様だ。
以下のプロンプトを入力した。
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 がそこから言語を判断したと推測される（確認はしていない）。
/design-sync で確認できたこと・できなかったこと
CLI からデザインシステムを操作して分かったことを整理する。
動いたこと:
- プロジェクト作成・コンポーネントアップロード・カード登録まで MCP 経由で完結できた
- 登録したコンポーネントを Claude Design の UI 生成チャットが自動で参照した
- 4コンポーネントを組み合わせたページが1プロンプトで生成された
ハマったこと / 注意点:
-
@dsCardマーカーだけではカードが表示されない。register_assetsの明示的な呼び出しが必要だった - アップロードは
finalize_plan → write_files → register_assetsの3ステップ必須。どれか1つを省くと機能しない
未確認・試していないこと:
-
register_assetsが「レガシー」とされている背景（将来廃止の予定があるかどうか） - Web UI からのアップロードで
@dsCard自動認識が機能するかどうか - コンポーネントの更新（既存カードへの上書き）の挙動
「コンポーネントを事前に登録 → Claude が素材として使う」という流れは、デザインの一貫性を保ちながら AI に新しいページを作らせる用途に向いている。ただし現時点では @dsCard 自動認識と register_assets の関係など、仕様と実機挙動に乖離が見られる部分があるため、試す際は本記事のハマりポイントを参考にしてほしい。
DesignSync のように「ローカルファイル → AI サービスのコンテキスト」という連携を MCP で組み上げると、次の問いが出てくる——自分のプロジェクト全体で、どの情報をどのエージェントに渡すか、どう設計すればいいか。
そうした「エージェントチームに情報を渡す設計」を体系化したのが Zenn Books シリーズだ。Vol.1「作るまで」では Claude Code でエージェントを動かし始める最初のステップを、Vol.4「仕組みを渡すまで」では権限管理・情報設計・ガバナンスの組み方を扱っている。
この記事は はてなブログ からのクロスポストです。