design-to-code-check

デザインとコードの照合

デザイン仕様とコード実装の整合性をレビューし、差異をディメンションと重大度別に分類した構造化レポートを作成するスキルです。

開始前に：参照先を確認する

このスキルのフロントマターにある references: のパスがすべて、この SKILL.md からの相対パスで存在することを確認してください。見つからないものがある場合は、そこで中止してください。通常、これはインストーラーがリポジトリのルートにある knowledge-notes/ ディレクトリを落としてしまうフラット化インストーラー（例：npx skills install）が原因で、インストールが不完全な状態です。ユーザーに 1-INSTALL.md に記載された方法で再インストールし、インストールルートから verify-install.sh を実行するよう伝えてください。ユーザーが明示的に続行を指示した場合に限り、参照先なしで作業を進め、その場合は出力に、このパックの参照資料を使用せずに作成したことを記載してください。

コンテキスト

デザインとコードの整合性レビューでは、異なる2種類の問題が見つかります。1つ目は実装ミスです。開発者が、誤って、または仕様が不明確だったために、指定と異なるものを作ってしまったケースです。2つ目は仕様の曖昧さです。デザインで動作が十分に定義されていなかったため、開発者が正しく実装できず、妥当な推測をしたものの、その推測が結果的に誤っていたケースです。

どちらの問題も重要ですが、対応は異なります。実装ミスはコードで修正する必要があります。仕様の曖昧さは、同じ推測が繰り返されないよう、デザインを修正して記録する必要があります。

このスキルは、両者を区別したレポートを作成します。

---

設定

.ds-ops-config.yml が存在する場合は、設定と継続的なナレッジに関するノート（../../knowledge-notes/configuration-and-recurring.md）に従い、設定の読み込み、統合のフォールバック、継続実行の方法を確認してください。このスキルでは以下を読み込みます。

• severity.* — 差異の重大度の上書き設定。特に specification_gap と missing_interaction_state
• system.framework と system.styling — フレームワーク固有の確認ガイダンスを事前に選択します
• integrations.figma — デザイン仕様（以下を参照）
• integrations.chromatic — 補足情報としてのビジュアルリグレッションデータ
• integrations.github — コンポーネントのソース
• gates.design_to_code — component-to-release の一部として実行する場合に、どの指摘事項がリリースをブロックするかを決定します

統合の自動取得

Figma MCP（integrations.figma.enabled: true、またはリクエストに Figma のリンクがある場合）：

• 公式 Figma MCP：コンポーネントのノードに対して get_design_context を実行し、プロパティ、バリアント、レイアウト、スタイルを取得します。また、ノードがバインドする変数を取得するには get_variable_defs を実行します。これにより、仕様で使われているトークン名がわかります。どちらも選択範囲またはノード単位のため、ファイルキーだけが提示された場合はノードのリンクを求めてください。
• Figma Console MCP：開発用の仕様には figma_get_component_for_development、レンダリングされた参照画像には figma_capture_screenshot を使用します。
• Figma から取得した各値にはノード ID を記録してください。これは証拠としてログに記載します。

Chromatic（integrations.chromatic.enabled: true）：

• 確認対象のコンポーネントについて、最新のビジュアルスナップショットを取得します
• Chromatic のベースラインと現在の実装との差分を、ディメンション1～3（間隔、色、タイポグラフィ）の補足情報として使用します。手動レビューで確認すべき差異を表面化させるものであり、ディメンションが一致していると判定するために使用してはいけません。

GitHub（integrations.github.enabled: true）：

• コンポーネントの実装が設定済みのリポジトリにある場合は、コンポーネントのソースファイルを直接取得します
• 指摘事項の背景を把握するため、コンポーネントの最終更新日と最近の変更を確認します

ステップ 1：比較資料を集める

次の情報を尋ねるか、確認してください（自動取得で回答済みの質問は省略します）。

• デザインの参照資料：Figma ファイルのリンク、エクスポートした仕様、または説明された仕様（Figma MCP から取得済みの場合は省略します）
• 実装の参照資料：コード内のコンポーネント（React、Vue、Twig など）、稼働中の実装へのリンク、または構築内容の説明。スタイリングの手法（CSS カスタムプロパティ、SCSS 変数、Tailwind ユーティリティクラス、CSS-in-JS）にも注意してください。これは、チェック中にトークン参照を特定する方法に影響します。
• レビュー対象のコンポーネントまたは画面
• 初回レビューか、前回の修正後のフォローアップチェックか
• レビューで特に注意すべき、既知の懸念事項

デザインと実装の両方を直接確認できる場合は、チェックに進みます。どちらか一方しか確認できない場合は、比較のどちら側を直接確認せずに推定したかをレポートに記載します。推定した側に依存する項目は、✅ ではなく「未チェック」と報告します。

ステップ 1b：デザイン仕様チェックリスト

チェックを実行する前に、デザイン仕様がチェックに十分な内容か確認します。不完全な仕様はタイプ II（仕様の不足）の指摘の根本原因です。事前に見つけることで、レポートのノイズを減らせます。

デザイン仕様の完全性チェックリスト：

• すべてのインタラクティブな状態が定義されている（デフォルト、ホバー、アクティブ、フォーカス、無効、エラー、読み込み中）
• 余白の値がピクセル値ではなくトークン名で指定されている
• 色の値が 16 進数値ではなくトークン名で指定されている
• タイポグラフィがタイプスケールトークンで指定されている
• 少なくとも 2 つのブレークポイントに対するレスポンシブ動作が定義されている
• フォーカスインジケーターのスタイルが指定されている
• コンテンツのオーバーフロー動作（省略、折り返し、スクロール）が定義されている
• モバイルのブレークポイントにおけるタッチターゲットのサイズが指定されている

仕様がこのチェックリストを満たさない場合： 不足項目を記録してからチェックを進めます。仕様の不足項目はレポートでタイプ II の指摘として扱われます。ただし、あらかじめ明示しておくことで、これらは実装エラーではなくデザイン上の不足であることを適切に伝えられます。

ステップ 2：すべての観点からチェックを実行する

5 つの観点から整合性をレビューします。各観点で目指すのは、差異をすべて列挙することではありません。丸め処理によるサブピクセル単位の軽微な差異は、報告すべき不一致ではありません。視覚的な一貫性、ユーザーエクスペリエンス、またはシステムの整合性に影響する差異を特定することが目的です。

観点 1：余白とレイアウト

次の点を確認します。

• パディングとマージンの値：デザイン仕様と一致しているか、正しいスペーシングトークンを使用しているか
• 要素の配置：コンテナー内でコンポーネントが水平方向および垂直方向にどう配置されているか
• Flex または Grid レイアウトにおける要素間の間隔
• コンポーネントのサイズ：指定されている場合の幅と高さ、または固定値が指定されていない場合の比例的な動作
• レスポンシブ動作：実装が仕様どおりにブレークポイントへ対応するか

仕様でトークンが指定されている場合（またはシステムに該当する値のトークンがある場合）、実装で生の値を使用していると、数値が一致していても不一致です。テーマに合わせたり、スケールに沿って管理したりできないためです。仕様で対象とされているプロパティについて記録してください。仕様に関係なくコンポーネント全体から生の値をくまなく探すのは token-compliance の役割であり、スタイリング手法ごとに、何をトークン参照とみなすか（SCSS 変数、var()、任意値ではなく Tailwind ユーティリティ、Emotion ヘルパー）のルールがあります。ここでも同じルールを適用し、チェック範囲を仕様で定められたプロパティより広げないでください。

ディメンション 2：色と視覚的な処理

確認項目：

• 背景色、枠線の色、テキストの色：正しいデザイントークンを参照していますか？
• 影とエレベーション：値は正しいですか？正しいトークンを参照していますか？
• 角丸：値は正しいですか？デザインシステムの角丸スケールに一貫していますか？
• 不透明度：値は正しいですか？正しい要素に適用されていますか？
• グラデーションや背景の処理がある場合、その内容は正しいですか？

ディメンション 1 と同様に、仕様の対象となるプロパティに生の色指定があれば指摘してください。

ディメンション 3：タイポグラフィ

確認項目：

• フォントファミリー：正しい書体が適用されていますか？
• フォントサイズ：正しいサイズで、適切なタイポグラフィトークンを使用していますか？
• フォントウェイト：各テキストの役割に応じて正しいウェイトですか？
• 行の高さ：適切な行送りで、正しいトークンまたは文書化された値を使用していますか？
• 文字間隔：指定がある場合、適切な字間になっていますか？
• テキスト配置：デザインどおりに左揃え、中央揃え、右揃え、または両端揃えになっていますか？
• テキストの切り詰めやオーバーフローへの対応：長い文字列をデザインどおりに処理していますか？

ディメンション 4：インタラクションの状態

確認項目：

• デフォルト状態：視覚的な処理がデザインと一致していますか？
• ホバー状態：ホバー時に正しい処理が適用されていますか？
• アクティブ／押下状態：クリックまたはタッチ時に正しい処理が適用されていますか？
• フォーカス状態：視認でき、適合性のあるフォーカスインジケーターが適用されていますか（これもアクセシビリティの確認項目です）。
• 無効状態：適切に視覚的な強調度が下げられていますか？
• ローディング状態：デザインで定義されている場合、正しく実装されていますか？
• エラー状態：該当する場合、正しく適用され、関連する要素に正しく紐付けられていますか？
• 空状態：該当する場合、正しく実装されていますか？

インタラクションの状態は、実装が不足しがちなディメンションです。デザインで定義されているのに実装に存在しない状態があれば指摘してください。

ソースから状態を確認する方法。 実装に状態が存在するのは、ソースにその状態のルールがある場合です。例：:hover、:focus-visible（または:focus）、:active、:disabledまたは[disabled]／[aria-disabled="true"]、[aria-busy="true"]またはローディング用のプロパティ分岐、[aria-invalid="true"]またはエラー用のプロパティ分岐、テンプレート内の空状態の分岐。これらのセレクターや分岐を確認し、値を仕様と比較してください。デザインで定義された状態にルールまたは分岐がない場合は、「未実装」です。これらのルールが実際にどのように描画されるか（画面上の実際のホバー色、背景上でのフォーカスリングの視認性など）は、実行中のビルドまたは Storybook でしか確認できません。どちらも使用していない場合は、値はソースから比較したものとして報告し、描画については「未確認」としてください。「✅」は使用しないでください。

ディメンション 5：レスポンシブおよび適応動作

確認項目：

• ブレークポイントでの切り替え：レイアウトは設計されたブレークポイントで変化しますか？
• 狭いビューポートでのコンポーネントの挙動：何かが崩れたり、はみ出したり、予期せず切り詰められたりしていませんか？
• タッチターゲットのサイズ：インタラクティブ要素は少なくとも 24×24 CSS px ですか（WCAG 2.5.8、AA）？44×44 CSS px は AAA の基準です（2.5.5）。プラットフォームのガイダンスは iOS では 44pt、Android では 48dp です。仕様またはチームが採用している基準を使用し、どれを使ったか明記してください。
• コンテンツのリフロー：すべてのブレークポイントでテキストが適切にリフローしますか？

ソースで確認する場合は、メディアクエリとコンテナークエリ、レスポンシブなプロパティ分岐を確認してください。各ブレークポイントでの描画には実行中のビルドが必要です。ビルドがない場合は、描画を「未確認」としてください。

ステップ 3：各不一致を分類する

見つかった不一致ごとに、次のように分類してください。

タイプ I：実装エラー 仕様は明確です。実装が仕様と一致していません。コードを修正してください。

タイプ II：仕様の不足 デザインでこのケースが定義されていません。実装では妥当な仮定がされています。意図した挙動を記録するためにデザイン仕様を更新し、その後、実装を一致させてください。

タイプ III：システムとの不整合 デザイン自体がデザインシステムから逸脱しています（システムにない色を使用している、スケールにない間隔の値を使用しているなど）。問題があるのは実装ではなく、デザインファイルです。

タイプ IV：許容済みの差異 既知かつ意図的な違いです。通常は、デザインが想定していなかった技術的な制約が原因です。すでに記録されていない場合は、文書化してください。

ステップ 3b：引き継ぎ（依頼があった場合のみ）

• Prop API の契約（prop の欠落、ドキュメント未記載、またはデフォルト値の誤り）：ここで確認するのではなく、component-api-validator を実行してください。
• AI の説明の乖離（6 セクションの説明がビルドと一致しなくなった場合）：ai-component-description を実行して再生成または検証してください。

ステップ 4：レポートを作成する

---

デザインとコードの照合レポート

全体の状況と、重点を置くべき箇所を伝える見出し文から始めます。

コンポーネント／画面： [名前] デザインの参照先： [Figma のリンクまたは説明] 実装の参照先： [リンクまたは説明] レビュー日： [日付] レビュー回： [初回／フォローアップ]

---

概要

1 段落で記載します。全体的な整合性はどうですか？相違点は特定の観点に集中していますか？修正は少数の箇所に集中していますか、それとも大幅なやり直しが必要ですか？

---

相違点の記録

ID	観点	種別	重大度	要素	デザイン仕様（証拠）	実装（証拠）	対応
DC-01	[観点]	[I–IV]	🔴 Critical ／ 🟠 High ／ 🟡 Medium ／ ⚪ Low	[具体的な要素]	[デザインの指定内容と Figma ノード ID または仕様の行]	[実装内容とファイル:行]	[担当者と対応内容]

各行には、両側の証拠を記載します。実装側にファイルと行がない場合、またはデザイン側にノード ID や仕様の行がない場合、その相違点は記録せず、「未確認」に確認に必要な情報を記載します。

重大度の目安：

• 🔴 Critical：アクセシビリティの後退。視認できないフォーカス（代替手段なしでアウトラインを削除）、不十分な色のコントラスト、またはキーボードで到達・操作できないコンポーネント
• 仕様で定義されていないフォーカススタイルでも、ブラウザーのデフォルトのフォーカスリングが表示される場合は、後退ではなく 🟠 High の Type II 仕様の不足です。フォーカスは視認できますが、デザインされていない状態です。Critical と判定する前に、CSS の outline: none ／ outline: 0 を確認してください
• 🟠 High：エンドユーザーに見え、品質の印象や使いやすさに影響する
• 🟡 Medium：システムの一貫性に関する問題（値のハードコード、トークンの誤り）。詳しく確認すると分かる
• ⚪ Low：ユーザーに影響しない軽微な差異

---

観点別の概要

各観点を 1 行で示します。✅ PASS（比較済みで相違点なし。証拠も明記）、⚠️ WARN（Medium または Low の相違点のみ）、❌ FAIL（Critical または High の相違点あり）、または 未確認（片方が推測または入手不可。その内容も明記）。作業がどこに集中しているかをチームが把握するのに役立ちます。

---

特定された仕様の不足

Type II の指摘事項は個別に記載します。これらは開発者ではなくデザイナーの対応が必要なため、開発バグではなくデザインタスクとして管理してください。

---

対象範囲

• 確認済み： [実際に比較したデザインソース（Figma ノード、書き出し、説明）と実装ファイルまたは実行中のビルド]
• 未確認： [片方で確認できなかった状態、ブレークポイント、またはバリアント]
• 「問題なし」の確認方法： [✅ の観点について、各状態の計算済みスタイルと Figma の値を比較するなど、比較した内容]
• 前提条件： [例：Figma フレームが現在承認済みの仕様である]

これらの相違点が意図的なもの（既知の制約、または合意済みの差異）であれば、お知らせください。今後の実行では Type IV として記録します。

品質チェック

• 不一致には、デザインの仕様と実装内容の両方が含まれます。「色が違う」だけではありません
• Type I（エラー）とType II（仕様の不足）の指摘が明確に区別されています。それぞれ担当者が異なります
• デフォルト状態だけでなく、インタラクティブな状態も十分に確認されています
• トークンへの準拠は、見た目の正しさだけでなく、色と間隔の評価項目でも確認されています
• アクセシビリティの後退（フォーカスが見えない、コントラスト不足、キーボード操作不可）は常にCriticalです。デザインされていないフォーカススタイルでも、ブラウザーのデフォルトスタイルが表示されていればHighです
• レポートは、追加のやり取りなしですぐに対応できる具体性を備えています
• 記録されたすべての不一致について、実装側のファイル名と行番号、デザイン側のノードIDまたは仕様の行が記載されています
• 状態とブレークポイントは、ソース内のセレクターと分岐を基に比較されています。ビルドまたはStorybookを使用していない場合、レンダリングは「未確認」と記載されています