humbleteam/design-handoff

デザインハンドオフ

完成したモックアップを、開発者がソースに実際に表示されている内容について追加質問することなく実装を開始できる仕様書に変換します。ただし、表示されていない内容について回答を捏造することは決してしません。

入力

以下を受け付けます：

• チャットに貼り付けられた、またはファイルパスで指定された1つ以上のモックアップ画像またはスクリーンショット。
• HTMLファイルまたはライブページのURL。
• オプションのトークンセット：カスタムプロパティを含むCSSファイル、JSONトークンファイル、または既存のデザイントークン（パレット、タイプスケール、スペーシングランプ、角丸、シャドウ）のプレーンな説明。

トークンセットが指定されなかった場合は、出力にその旨を記載し、モックアップ自体からドラフトを導出します（ステップ3を参照）。

出力

画面ごとに1つのMarkdownファイル（<screen-slug>-handoff.md）を作成します。構造はreferences/handoff-template.mdの8セクション構成に従います。最初の仕様を書く前に、正確な骨格をコピーするためにそのファイルを読んでください。

最初に画面数を決定します。 2つ以上の入力が同じレイアウトでコンポーネントの状態のみが異なる場合（デフォルト状態とホバー状態のボタン、エラー前後のフォーム）は、それは1つの画面です。証拠を統合して1つの仕様書のセクション4にまとめてください。入力が異なる画面、ルート、またはブレークポイントを示している場合は、画面ごとに1つの仕様ファイルを作成してください。複数のブレークポイントで提供された画面の場合は、画面ごとに1つのファイルを作成し、ファイル全体を複製するのではなく、セクション2（レイアウト）の下にブレークポイントごとのサブセクションを追加してください。

基本原則：見えないものは決して発明しない

これが他のすべてのステップが従うルールです。値、状態、または動作がソース素材に直接表示されていない場合：

• 推測しないでください。
• 「妥当なデフォルト」で導出しないでください（ホバー推測のために色を10%暗くしない、一般的だからといって200msのフェードを想定しない）。
• OPEN QUESTION と記述し、セクション8に番号を付けて、BLOCKING または NON-BLOCKING のタグを付けて追加してください。

ソースが1つの状態しか示していないために10個の未確定事項がある仕様は、その役割を果たしています。すべてのギャップをもっともらしい推測で埋めたために未確定事項がゼロの仕様は、存在する唯一の目的に失敗しています。

ステップ

1. 画面概要

寸法（画像サイズ、HTMLビューポート、または指定されたブレークポイントから - 比率から推測した場合は (estimated) とマーク）、1文の目的、およびこの仕様にフィードされたソース画像またはファイルの数を記録します。

2. レイアウト

画面をリーディング順（上から下へ、行内では左から右へ）で走査し、すべての領域を列挙します：名前、位置またはサイズ、内部パディング、および次の領域までのギャップ。ソースがサポートする任意の単位を使用します（HTML/CSSからの正確なピクセル、または静的画像からの (estimated) 比率）。同じ画面の2つのソースが競合するスペーシングを示す場合（例えば、わずかに異なるパディングの2つのスクリーンショット）、このセクションで競合を明示的にフラグしてください。2つの値を平均したり、黙って一方を選択したりしないでください。

3. トークンマップ

画面に表示されるすべての異なる色、フォント、スペーシング値、角丸の半径、およびシャドウを、それぞれ1回だけ、次の4つの列でリストします：プロパティ、観測値、マッピングされたトークン、ステータス。

• トークンセットが提供された場合、各観測値を最も近い既存のトークンに一致させます。小さな許容範囲を使用します（スペーシングの場合は数ピクセル、色の場合は近い視覚的隣接色）。その許容範囲内に一致するものがない場合、その値は新しいものです。
• 一致するものがない値は、マッピングされたトークン列に NEW-TOKEN: <提案名> を取得します。既存のトークンに命名規則が確認できる場合はそれに従い（例：color-<role>、space-<n>、radius-<size>）、既存の規則がない場合はプレーンなロールベースのkebab-case名を使用します。
• トークンセットがまったく提供されなかった場合、すべての行は NEW-TOKEN です。完全な提案セットをドラフトし、仕様書にそのどれも実際のシステムに対して確認されていないことを明記してください。

4. コンポーネントインベントリ

すべての異なるインタラクティブ要素（ボタン、入力、カード、ナビゲーションアイテム、トグルなど）について、正確に次の8つの標準状態を列挙します：デフォルト、ホバー、フォーカス、アクティブ、無効、ローディング、空、エラー。

各状態について、次のいずれかをマークします：

• 具体的な仕様行（塗り、ラベル、境界線、アイコン）。ただし、その状態がソースに実際に表示されている場合のみ。
• not applicable と1節の理由（静的ラベルにはホバー状態がない、単一アイテムのリストには空の状態がない）。
• OPEN QUESTION #n この状態がこのコンポーネントにとって妥当であるが、表示されていない場合。

ソースが画面全体のデフォルト状態のみを示している場合は、このセクションの先頭にその旨を明記してください（「ソースはデフォルト状態のみを示しています - 以下の状態テーブルは設計上、ほとんどが未確定事項です」）。発明したホバー色やフォーカス色でテーブルを埋めないでください。

5. 振る舞いノート

トランジション、スクロール動作（固定ヘッダー、無限スクロール、パララックス）、および検証タイミング（ブラー時、送信時、キーストローク時） - ただし、ソースが直接表示しているか、注釈に記載されているもののみ。矢印アイコンはナビゲーションを示唆しますが、トランジションスタイルを示唆するものではありません。推測的なものは、事実として説明する代わりに未確定事項としてマークしてください。

6. アクセシビリティ注釈

• 視覚的構造から推測されるランドマークロール（header、nav、main、list、button、dialog）。
• 可視テキストから、またはアイコンのみのコントロールの場合はアイコンの意味から提案されるアクセシブルな名前。
• リーディング順と視覚的階層に一致する、番号付けされた提案フォーカス順序。
• トークンマップに現れるすべての前景/背景テキストペアのコントラスト比。WCAG 2.2 SC 1.4.3（通常テキストは4.5:1、大きなテキストは3:1）および非テキストUIコンポーネント向けSC 1.4.11に対してチェックします。ソースから正確な16進数が抽出できない場合は、比率は推定値であると記載し、しきい値に近い場合は未確定事項としてフラグしてください。

7. アセット一覧

エクスポートが必要なすべての画像、アイコン、またはイラスト：推奨フォーマット（アイコンとイラストはSVG、写真はPNGまたはWebP）、およびサイズ - ラスターアセットは @1x/@2x/@3x、ベクターは単一ファイル。

8. 未確定事項

セクション2から6で発生したすべての OPEN QUESTION を1つの番号付きリストに収集します。それぞれにタグを付けます：

• BLOCKING - 回答なしでは実装を正しく進められない。
• NON-BLOCKING - 記載された妥当なデフォルトで実装を進められ、出荷前に対応すればよい。

仕様全体で連続番号を付けます（セクション2〜6でインライン参照される番号は、このリストと一致している必要があります）。

エッジケース

• 画面全体に1つの状態のみ表示。 期待される結果であり、失敗ではありません。コンポーネントインベントリはほとんどが OPEN QUESTION になります。テーブルを完全に見せるためにホバー/フォーカス/アクティブを発明するのではなく、明示的にそのように述べてください。
• トークンセットが提供されていない。 モックアップから完全なドラフトトークンセットを導出し、すべての行を NEW-TOKEN (proposed) とマークしてください。導出された値を、与えられていない既存のシステムに一致するものとして決して提示しないでください。
• 同じ画面の2つのリファレンス間でスペーシングまたは色が競合する。 両方の値を名前付きで関連セクションにフラグしてください。平均化せず、また一方を選択したこととその理由を明示せずに選択しないでください。
• 低解像度または切り取られたスクリーンショット。 影響を受ける値を (estimated) とマークしてください。不確かな値が実装の決定を変える場合（トークンの一致、WCAGしきい値に近いコントラスト比）、事実として述べる代わりに未確定事項に追加してください。
• 同じ要素にインラインスタイルとCSSクラスの両方を持つHTML入力。 競合する場合は、生のインライン属性よりも計算/レンダリングされたスタイルを優先します。マッピングされたトークンに影響する場合は、セクション3で競合を記載してください。
• 1回だけ出現し、明確なインタラクティブなアフォーダンスがないコンポーネント（例：静的なバッジ）。8行の not applicable を埋める代わりに、そのコンポーネントのセクション4を完全にスキップしてください。

作成後

返信の最後に、次の内容を明確に記載してください：作成した仕様ファイルの数、未確定事項の総数、およびそのうち BLOCKING の数。この数が、この画面を実装する準備ができているかどうかの実際のシグナルです。