デザインシステムの同期
概要
デザインシステムがすでにコードに存在する場合、デザインツールはそれを再発明するのではなくミラーリングすべきです。
- インポートは、コードのトークンとユーザーが選択したコンポーネントを、同じ名前でツールに取り込みます。
- エクスポートは、ツールのガイドで行われた変更を、レビュー済みの差分としてコードに戻します。
プロジェクトルートにある小さなファイル design-sync.json が、最後に同期された内容を記憶します。ユーザーが明示的に指示しない限り、コードが信頼できる情報源であり続けます。変更はまずツール上で描画され、承認されたエクスポートを通じてコードに反映されます。
使用するタイミング
- コードにデザインシステムがあり、ツールにガイドがないプロジェクトでデザインタスクが始まろうとしている場合。
craft-setupとcraftがこのスキルに引き継ぎます。 - 「デザインシステム(トークン、コンポーネント)をPaper/Figma/デザインツールにインポート/持ち込む」と依頼された場合。
- 「ガイドの変更をコードに適用/プッシュ/同期する」と依頼された場合。
使用すべきでないタイミング
- コードにデザインシステムがない場合:代わりに
craft-system(作成モード)を使用します。 - レビュー、選択肢の提示、またはそのようなプロジェクトでの小さな編集の場合:それらのスキルはコードの現状に基づいて動作します。
- ユーザーが口頭で指定した単一のトークン値(「アクセントカラーをコードで #3d7f69 にして」など)の場合:直接編集し、その名前の
design-sync.jsonを更新し、影響を受ける内容を説明します。
開始前の準備
DESIGN.md(Brandセクションにシステムの場所が記載)とdesign-sync.jsonが存在すれば読み込みます。references/adapters/の中からツールに合ったアダプターを選びます(paper.md、figma.md、html.md)。ツールに合うアダプターがない場合、同じ動詞を自分のツールで実行し、どの動詞を手動でマッピングしたかを説明します。デザインツールがまったくない場合は、HTMLで構築します(html.md)。画像しかない場合は、そこから読み取った値は推定値であると記載します。
design-sync.json
{
"source": "packages/ui/tokens.css",
"tool": "paper: file 'Fieldnote', page 'Guide'",
"naming": "CSSカスタムプロパティ名をソースのまま使用",
"synced": "2026-11-15",
"tokens": { "--color-accent": "#2e6b57", "--radius-md": "10px" },
"components": { "Button": "drawn", "Badge": "drawn", "Input": "in code only" }
}
tokensは、前回の同期時に両者で合意された値のみを保持します。- コンポーネントのインポートは、自身の
componentsエントリのみを変更します。
インポート(コード → デザインツール)
-
検出 シグナルを使用して行います。値の信頼できる情報源(生成された出力ではなく、トークンソース)と、ツールが使用する命名ルールを見つけます。UIパッケージが2つある場合 → 両方をリストアップし、どちらがソースかを尋ねます。
-
棚卸しを行い、停止します。 棚卸しフォーマットを使用します:
- ロール別のトークン(カウントとパスを含む)
- コンポーネント(約15個を超える場合はグループ化してカウント)
- ガイドラインドキュメント
- ギャップ
- 競合:ツールにすでに存在し、異なる値を持つ名前、およびツールが保持できないトークンタイプ。
どのコンポーネントを今描画するか尋ね、次の画面に向けて3~6個を提案し、各競合をどのように解決するかも尋ねます。デフォルトですべてを描画することは決してありません。
-
ツール内で構築します 回答を受けてから:
- 命名ルールに従ってトークンを登録します。ユーザーが解決していないツールの値を上書きしないでください。
- ファンデーションガイドページを作成し、ガイドラインドキュメントを凡例として追加します。
- コンポーネントインデックスを作成します:名前、コードパス、ステータス(
drawn/in code only)、描画後はバリアントを記入します。 - 選択されたコンポーネントを、ステータスマトリックスとともに描画し、コードの値を使用します。コードで定義されていないステータスは描画し、「proposed」 とラベル付けします。
-
自己チェック。 ガイドをレンダリングします。コードがコンポーネントをレンダリングできる場合(Storybook、デモページなど)、同じサイズで比較します。できない場合は、値はコードから読み取られたがレンダリングされていないと記載します。
-
記録:
design-sync.jsonを書き込みます(すべてのトークン値が両側で等しくなり、コンポーネントのステータスも含まれます)。DESIGN.mdで、Brandセクションに「デザインシステムソース:<パス>;<ツール> のガイドがこれをミラーリングしています」と追加し、Decisionログに日付付きのインポート行を追加します。DESIGN.mdが存在しない場合は、最初の行が<!-- sync record only: run craft-setup for the brief -->で、BrandセクションとDecisionログのみを含むものを作成します。ProductセクションがないDESIGN.mdは、craftによって存在しないものとして扱われます。
単一コンポーネントのインポート(craft からの場合)
ユーザーはすでにシステムのミラーリングに同意しているため、棚卸しによる停止はありません:
- そのコンポーネントを描画します。
- その
componentsエントリをdrawnに設定します。 tokensはそのままにします。
ツールにまだガイドがない場合、またはユーザーがインポートに同意したことがない(または拒否した)場合、一度確認します:「Inputはコードにのみ存在します。まずガイドにインポートしますか?」
エクスポート(デザインツール → コード)
-
読み取り ガイドの値(アダプター経由)とコードの値を、名前ごとに読み取ります。
-
すべての名前を分類します
design-sync.jsonと差分フォーマットを使用して:- 現在等しい → 同期済み
- ガイドが変更 → 提案
- コードが変更 → ガイドの更新を提案
- 両方が変更 → 3つの値を表示し、どちらを優先するか尋ねます。
design-sync.jsonがない場合、すべての差異をリストアップし、それぞれの方向を尋ねます。 -
編集内容を提案します ソースファイルに対して(生成された出力には決して行いません):ファイルと行、それぞれが影響する内容、および色のコントラスト。 「Proposed」ステータスと代替フォントはエクスポートすべき変更ではありません。ここで停止します。
-
適用 承認されたもののみを適用し、コード側で決定されたものについてはガイドを更新し、プロジェクトのチェックを実行します(lint、型チェック、テスト、ビジュアルテスト)。存在しない場合はその旨を記載します。
-
記録:
design-sync.jsonを、現在両側で等しい値で更新します。DESIGN.mdのDecisionログに日付付きの行を追加します。- 未解決の競合をOpen questionsに追加します。
ルール
| ルール | 理由 |
|---|---|
| コードとツールで同じ名前を、1つの書き言葉による命名ルールで使用 | 決定ごとに1つの名前。マッピングのずれを防ぐ |
design-sync.json は合意された値のみを記録 | 最後に合意された値がなければ、「誰が変更したのか」は推測になる |
| 描画前に棚卸しと選択を行い、競合をリストアップ | 大規模なパッケージや既存のツールトークンにはユーザーの判断が必要 |
| スクリーンショットではなくコードからの値を使用 | スクリーンショットは色やサイズを丸める |
| 欠落しているステータスは「proposed」として描画 | ガイドはコードが実際には持っていない機能を主張してはならない |
| エクスポートは提案し、停止する。ソースを編集し、生成された出力は編集しない | コードはユーザーに出荷される。生成されたファイルは次のビルドで上書きされる |
| 両方が変更された場合は尋ねる | どちらかを上書きすると、誰かの決定が失われる |
| ユーザーが別の指示をしない限り、コードが信頼できる情報源である | 「コードは古い概要書に勝る」という原則に合致 |
完了条件
- インポート: 棚卸しと競合が解決され、選択されたコンポーネントが描画され、ガイドがレンダリング(または「レンダリングされていない」と明示)され、
design-sync.jsonとDESIGN.mdが書き込まれている。 - 単一コンポーネント: 描画され、そのステータスが更新されている。
- エクスポート: 承認された編集が適用され、チェックが実行(または「なし」と明示)され、
design-sync.jsonが更新され、競合が解決されるか未解決のままになっている。
よくある間違い
| 考え | 現実 |
|---|---|
| 「コードにシステムがあるので、セットアップはブリーフだけで良い」 | インポートを提案しなければ、ツールにガイドが作成されず、画面がコードから乖離する |
| 「ファンデーションとインデックスだけ作って、コンポーネントは後でやる」 | 棚卸しを表示し、どのコンポーネントを今描画するか尋ねる |
「インポート中に --sand-200 をロール名にリネームしよう」 | コードの名前を保持し、ロール名は未解決の質問として提案する |
「ツールにはすでに --color-accent があるので、更新しよう」 | それは棚卸しの停止ポイントでの競合であり、無言の上書きではない |
| 「ガイドとコードが異なるので、ガイドが古くなっている」 | design-sync.json を確認する。ユーザーがまだエクスポートしていない変更の可能性がある |
| 「差分が小さいので、そのまま適用しよう」 | 提案し、停止し、それから適用してプロジェクトのチェックを実行する |