Claude Media
Claude Codeのdesign-handoffスキルで開発者向け仕様書を作る
Claude CodeClaude連携チュートリアル

Claude Codeのdesign-handoffスキルで開発者向け仕様書を作る

designプラグインのdesign-handoffは、画面のデザインからトークン・状態・ブレークポイント・エッジケースまで並べた仕様書を作るスキルです。導入、呼び出し方、出力の中身、渡し方の工夫を扱います。

読了目安 約11分

design-handoffは、デザインを実装担当に渡すときの仕様書を作るスキルです。Figmaのリンクか画面の説明を渡すと、余白・トークン・コンポーネントの状態・ブレークポイント・エッジケース・アニメーション・アクセシビリティを、決まった型の1本の文書にまとめます。

この記事では、スキルがどのプラグインに入っているか、Claude Codeでの呼び出し方、出力される仕様書の構造、そして渡し方で出来が変わる点を順に扱います。

design-handoffはどのプラグインに入っているか

提供元はAnthropicの knowledge-work-plugins リポジトリにある design プラグインです。README冒頭には、Coworkでの利用を主に想定して作られており、Claude Codeでも動くと書かれています。plugin.json のバージョンは1.2.0です。

design ディレクトリの直下にあるのは、.claude-plugin、skills、.mcp.json、CONNECTORS.md、README.md の5つです。commands ディレクトリはありません。skills の中は次の7つです。

スキル役割
design-handoff役割デザインから開発者向け仕様書を作る
design-critique役割使いやすさ・階層・一貫性のフィードバック
design-system役割デザインシステムの監査・文書化・拡張
accessibility-review役割WCAG 2.1 AAの監査
ux-copy役割マイクロコピーやエラーメッセージの作成・レビュー
user-research役割リサーチの計画と整理
research-synthesis役割インタビューや調査結果の統合

READMEの表は、これと完全には一致しません。コマンドの表に /handoff が載っている一方、実体のあるのはスキルの design-handoff だけです。スキル表にある design-system-management と ux-writing も、ディレクトリ名は design-system と ux-copy です。迷ったら、READMEの名前ではなく入れた後の /skills の一覧を信じるのが確実です。一覧の見方は/skillsコマンドの記事にあります。

導入と呼び出し方

導入は、マーケットプレイスの追加とプラグインの導入の2段階です。READMEのコマンドは次の2行です。

claude plugin marketplace add anthropics/knowledge-work-plugins
claude plugin install design@knowledge-work-plugins

セッションが開いたままなら、/reload-plugins で反映します。--marketplace フラグを使う経路はclaude plugin installの導入経路の記事、プラグイン全般の仕組みはClaude Codeプラグイン完全ガイドにまとめています。

スラッシュコマンドの名前は何になるか

Claude Codeのドキュメントによると、プラグインのスキルは /プラグイン名:スキル名 の形で呼び出せます。このプラグインなら /design:design-handoff です。SKILL.md本文の見出しは /design-handoff と書かれていますが、プラグイン経由では名前空間が付く点に注意してください。

/design:design-handoff https://www.figma.com/design/xxxx/checkout-flow

スラッシュで呼ばなくても、依頼の文面がスキルの description に合えば、Claudeが自動で読み込みます。descriptionは「デザインがエンジニアリングに渡せる状態で、レイアウト・デザイントークン・コンポーネントのprops・操作状態・レスポンシブ・エッジケース・アニメーションを網羅した仕様書が要るとき」という趣旨です。

引数は1つの文字列にまとめる

スキルの本文には、引数を受ける場所が2つあります。使い方のコードブロックにある $ARGUMENTS と、その下の「Generate handoff specs for: @$1」の $1 です。

Claude Codeのドキュメントでは、$ARGUMENTS が入力全体、$1 は2つ目の引数と定義されています(番号は0始まり)。この規則を当てはめると、引数を1つだけ渡した場合、$1 に該当する値がなく、@$1 はそのまま文字列として残ります。入力そのものは $ARGUMENTS の側に入るので、動作に支障は出ないはずです。

ただし、画面の説明を空白区切りで何語も渡すと、引数が複数に割れます。説明文を渡すときは、全体を引用符で囲んでおくと意図どおりに扱われます。

/design:design-handoff "注文確認画面: 商品リスト、クーポン入力、合計金額、注文ボタン"

出力される仕様書の構造

スキルは、出力の雛形を本文に持っています。仕様書は次の9つの節で組まれます。

出力

雛形の節

  • Overview / Layout

    画面の目的とユーザーの文脈。グリッド、ブレークポイント、レスポンシブの挙動。

  • Design Tokens Used

    トークン名・値・使いどころの3列の表。

  • Components

    コンポーネント・バリアント・props・特記事項の表。

  • States and Interactions

    要素ごとに、状態と挙動を対応させた表。

  • Responsive / Edge Cases

    ブレークポイント別の変更点と、空・長文・読み込み中・エラーの扱い。

  • Animation / Motion

    要素・トリガー・動き・所要ミリ秒・イージングの表。

最後に、フォーカス順・ARIAラベル・キーボード操作を書く「Accessibility Notes」が付きます。

雛形より重要な4つの原則

スキルには、雛形とは別に4つの原則が書かれています。

  1. 指定のないものは開発者が推測する。だから全部を指定する
  2. 値ではなくトークンで書く。16px でなく spacing-md
  3. 既定・ホバー・押下・無効・読み込み・エラー・空の全状態を示す
  4. 理由を書く。「モバイルで折りたたむのは片手操作が多いから」のような一文が、開発者の判断を助ける

4つ目は、仕様書を「命令書」でなく「判断材料」にする指示です。実装中に仕様の想定外が出たとき、理由が書いてあれば開発者が自分で埋められます。

雛形の表には #[hex] や [X]px のような穴埋め記号が並びます。スキルが埋めるのは、渡した情報から分かる範囲です。Figmaから値が取れなければ、穴のまま残るか、推測で埋まる可能性があります。この点は次の節の渡し方に直結します。

渡し方で出来が変わる

プラグインの CONNECTORS.md は、デザインツールを ~~design tool というカテゴリで扱っています。含まれているサーバーはFigmaで、他の選択肢としてSketch・Adobe XD・Framerが挙がっています。.mcp.json にはFigmaのほか、Slack・Linear・Asana・Atlassian・Notion・Intercomの接続先が事前に書かれています。

スキル本文は、接続の有無で次のように分けています。

接続できること
Figmaを接続できること正確な寸法・トークン・コンポーネント仕様を取り込み、完全な仕様書を作る
プロジェクト管理ツールを接続できること実装チケットに仕様書を紐づけ、節ごとにサブタスクを作る
接続なしできること渡された説明かスクリーンショットから作る

Claude CodeでFigmaに繋ぐ手順はFigma MCPサーバーの使い方にあります。接続していなくても、説明やスクリーンショットで動きます。ただ、正確な寸法とトークンが欲しいなら、Figmaをつなぐ価値があります。

3つのヒントを、依頼文に落とす

スキル末尾の「Tips」は3つです。Figmaリンクを渡す、エッジケースを一言添える(「100件あったら?」)、技術スタックを伝える(「React + Tailwind」)。これを依頼文の型にすると、たとえば次のようになります。

/design:design-handoff "https://www.figma.com/design/xxxx/checkout-flow
スタックはReact + Tailwind。
エッジケース: 商品が100件のとき、クーポンが無効のとき、決済APIが遅いとき"

CLAUDE.mdにトークンの規約を置く

スキルが「トークンで書け」と指示しても、そのプロジェクトのトークン名をスキルは知りません。ここは、リポジトリ側の CLAUDE.md で補えます。次は、Tailwindのトークン規約を置く一例です。

## デザイントークン
- 色・余白・文字は `tailwind.config.ts` の theme に定義した名前で書く
- 仕様書では値(`#1A73E8` や `16px`)を直接書かず、トークン名で参照する
- 新しいトークンが必要な場合は、仕様書の末尾に「追加提案」として分けて書く

こうしておくと、仕様書のトークンの表が、実装側のコードと同じ名前で埋まりやすくなります。ここに書いた規約は例で、効き方はプロジェクトの構成で変わります。

出てきた仕様書を実装に使う

生成された仕様書は、チャットの返答として出ます。SKILL.mdには保存先の指定がありません。リポジトリに残したいときは、「docs/specs/checkout.md に保存して」と依頼文に書き足します。

実装との突き合わせにも使えます。たとえば、仕様書の「States and Interactions」の表を残したうえで、次のように頼む方法があります。

docs/specs/checkout.md の状態表の各行について、
実装(src/components/Checkout*.tsx)が対応しているかを確認し、
欠けている状態を一覧にして

仕様書が状態を「全部」列挙しているので、実装の抜けを機械的に探しやすくなります。仕様から実装、実装から仕様への往復は、1回で完結する作業ではありません。出力が仕様と違うときは、仕様書側の記述が曖昧だった可能性も疑います。

隣のスキルとの使い分け

設計が固まる前なら design-critique、デザインシステムとの整合を見るなら design-system が向いています。仕様書を作る前の確認には accessibility-review が使えます。descriptionには、引き渡しの前にデザインを見直す場面が想定されていると書かれています。

状況向くスキル
画面の案を見てもらい、改善点が欲しい向くスキルdesign-critique
トークンや命名の揺れを洗い出したい向くスキルdesign-system
コントラストやキーボード操作を確かめたい向くスキルaccessibility-review
エラー文言や空状態の文言を決めたい向くスキルux-copy
実装担当に渡す文書を作りたい向くスキルdesign-handoff

UIの品質をコード側から整えたいなら、別のプラグインが受け持ちます。frontend-designプラグインの記事は、コードを書く前に設計計画を見直させる仕組みを扱っています。designプラグイン全体の位置づけは部門別プラグインの解説にもつながります。

まとめ

design-handoffの価値は、雛形そのものより、「指定のないものは開発者が推測する」という原則にあります。全状態・全ブレークポイントを書かせる設計なので、Figmaを接続し、スタックとエッジケースを一言添えて渡すほど出来が上がります。READMEとディレクトリの食い違いがあるため、呼び出しは /skills で名前を確かめてから、/design:design-handoff で行います。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →