ui-design-iteration

UI デザインの反復

範囲

このスキルでは、UI を初稿からレビュー済みの移植可能なページに仕上げます。デザインがまだない場合は既存のリファレンスから初稿を再構築し、ディスク上で実際に表示できるページにします。人がページ上の箇所を指し示せるようにし、その言葉を小さなパッチに変換して、結果を検証します。

このスキルは、ページの見た目を考案するものではありません。見た目は、誰かがすでにデザインしたものを基にします。ユーザーが選んだリファレンス（テンプレートのデモまたは稼働中のサイト（ステップ 0））、ユーザーが信頼するデザインスキルやデザインエージェント、ユーザー本人、または初稿の抽出元である実行中の製品が該当します。このスキルはそのデザインを再利用または再構築し、適用してレビューします。一行の要件だけからページを描くことはありません。

成果物は、実際に表示できる静的な初稿です。ビルド手順もネットワーク接続も不要でブラウザーから開ける、HTML のエントリーページ 1 つとローカルの CSS／JS を含む初稿ディレクトリです。ページ上で直接調整でき、要素ごとに話し合えるほか、レビュー済みのパッチを順番に適用できます。

意図的に対象外とする作業：

• 何もない状態からの初稿作成。 一行の要件から生成したページは、レイアウト、書体、配色を一度に考案することになり、その後の反復では、誰も決めていない選択について議論することになります。代わりにリファレンス（ステップ 0）またはデザインソースを起点にしてください。
• 移植。 初稿をフレームワーク、テンプレート言語、または CMS に移行する作業は、そのコードベースの担当者が行う別の作業です。アプリケーションの構造を足場から作ったり、データを接続したり、「親切心から」移行したりしないでください。

相互運用：デザインソースから取り込むもの

• 助言ではなく成果物を求めてください。 入力は自己完結した HTML ページです。デザインが文章で提示された場合は、すでに決まっていることを再検討せず、一度だけファイルに反映してください。
• 再デザインではなく、変換してください。 デザインシステム、スペーシングスケール、またはトークン一覧は、機械的に対応付けて初稿の :root ブロックに追加します。2 つのデザインソースが一致しない場合は、どちらを使うかユーザーに選んでもらってください。2 つのシステムを混ぜることは、この場で最もコストの高いミスです。
• 不足している要素は差し戻してください。 デザインに、ページで必要な状態や要素（空の状態、ダイアログ、エラーなど）のルールがない場合は、デザインソースに確認するか、製品独自のコンポーネントからコピーしてください。不足を補うために見た目を考案してはいけません。
• 契約はデフォルトの制限より優先されます。 references/audit.md には反復を終了するデフォルトの制限が記載されています。design-contract.md に記録された決定は、そのいずれよりも優先されます。監査は報告を行うものであり、再デザインは行わないためです。ただし、アクセシビリティのチェックは例外です。どのようなデザイン上の決定も、コントラストの不合格を免除するものではありません。

エージェント自身のツールが必要な作業

ユーザーにはユーザー自身の言語で話しかけてください。以下の質問は、スキルが分岐しないよう英語でのみ記述しています。

• Node とネットワークアクセスが使えるシェルが必要なのは、ソースをコピーするフレームワークのテンプレートをレンダリングする場合のみです（ステップ 0、ルート A）。使えるものがなければ、ユーザーに実行して出力を送ってもらうか、代わりにテンプレートのライブデモを保存してもらってください。
• エージェントが操作できるブラウザーは、参照デモのスクリーンショットや測定値の取得、アプリを操作して状態をキャプチャすること、ヒットテストの確認に必要です。ブラウザーツールがあれば、それを使ってください。シェルからスクリプトで操作するヘッドレスブラウザー（DevTools プロトコルまたは Playwright 経由）も該当します。どちらも使えない場合は、ユーザーにページを開いてスクリーンショットを送ってもらい、自分では実行できなかった確認項目をすべて明記してください。実行しなかった確認を、合格したように記述してはいけません。
• 長時間実行するプロセスは、scripts/draft_server.py の実行と、ルート A でのテンプレートの開発サーバーの実行に必要です。ランタイムで使えるバックグラウンドプロセスの仕組みを使って起動してください。ポートはユーザーまたは環境が選択するポート、あるいは空いているポートを割り当てる 0 を指定します。起動したすべてのプロセスの PID を記録してください。ポートを使用しているプロセスは、シェルが報告する PID の子プロセスの場合があります（$! がラッパーを指すこともあります）。作業が終わったら、該当する PID だけを停止し、停止したことを確認してください（プロセス一覧から消えていること、ポートが応答しなくなっていること）。マシン上で同じ名前の別サービスが動作している可能性があるため、プロセス名やパターン（pkill next、コマンドラインでの一致など）でプロセスを停止してはいけません。
• サーバーの実行中、選択内容はドラフトディレクトリ内の selection.json として届きます。ブラウザーでページを操作する場合、window.draftKit.snapshot() は同じオブジェクトを返し、window.draftKit.audit() はレンダリングされたページをカウントします。どちらも使えない場合は、ユーザーにパネルの読み取り内容を教えてもらってください。ただし、ファイルよりも信頼性の低い参照情報として扱ってください。
• 幅はブラウザーで設定します。ブラウザーツールのビューポートを使うか、ユーザーにブラウザーの幅を変更してもらいます。スナップショットには、レビュー担当者が確認した幅が記録されます。

作業の流れ

ステップ	目標	出力
0 参照からドラフトを作成	ユーザーのコンテンツとセクションに参照のデザイン言語を適用	調整可能な値を反映した <name>.html
1 取り込み	ディスク上のデザイン、トークンを反映	<name>.html、1 つの :root ブロック、design-contract.md
2 公開する	ページと同じようにドラフトが動作	ドラフトランタイムとレビュー用パネルを追加、サーバーを実行
3 反復する	変更を項目ごとに対応し、小さく保つ	要素ごとのパッチを適用し、それぞれ差分で確認
4 監査して引き渡す	制限を満たすか契約で免除し、ポート対応を完了	ドラフトディレクトリ、契約、アンカーマップ

すでにデザインが存在する場合は、ステップ 0 を省略してください。ステップ 1 のトークン反映は省略しないでください。これによってステップ 3 の作業が軽くなります。トークンを設定しておけば、「間隔を詰める／薄くする／角を丸くする」といったリクエストの多くは、書き直しではなく数値を 1 つ変えるだけで対応できます。

ステップ 0 — 参考ページをもとに草案を作成する

既存の優れたデザインのページを選び、そのデザイン言語をコンテンツに反映します。手順は references/drafting.md にあり、references/sources.md には、参考元の見極め方と、希望がないユーザー向けの候補リストが記載されています。

• 参考資料より先に論旨を固めます。 ページを主張とその根拠で構成し、実際に存在する根拠、画像、技術スタックを書き留めます。ユーザーが求めた要素を踏まえて、ページのセクションと、どの参考ページが役立つかを決めます。
• まずユーザーの参考元を確認します。 好みのライブラリ、テンプレートサイト、ギャラリー、サイトを尋ね、候補リストより先にそれらを調べます。
• メインの参考ページはユーザーが選びます。 候補を2、3件に絞って提示し、ユーザーに選んでもらいます。参考ページを選ぶことは、デザインを選ぶことです。ユーザーから選定を依頼された場合は、最も慎重に審査した候補を選び、その理由を説明し、依頼を受けて選んだことを記録して、最初の草案と合わせて確認してもらいます。
• 調査し、測定してから、デザイン言語を書き留めます。 スクリーンショットから構成を把握し、実際のデモの計算済みスタイルから値を取得します。文字サイズの尺度、余白、角丸、配色、アニメーションのタイミングなどを調整要素とし、画像や光彩、そのページ内での配置のリズムも含めて、参考ページの特徴と適用箇所を短くまとめます。固有のデザイン要素には印を付け、すべてのセクションをそれらに照らして確認します。
• コードをコピーし、スクリーンショットからの再構築は必要な場合だけ行います。 標準のルート A では、テンプレートのソースコードを使います。それがない場合は、スタイルシート、フォント、アイコン、画像と合わせて保存した実際のデモページを使い、マークアップと CSS はそのまま維持して、CSS で公開されているプロパティに調整要素を適用します。コピーできるものがない場合に限り、ルート B で一部を再構築します。
• 構成はコンテンツで決め、見た目は参考ページに合わせます。 コンテンツをもとにセクションを計画します。合うものがあれば参考ページのセクションをそのまま使い、別ページからセクションを選ぶか、参考ページの要素を組み合わせます。その際は、参考ページで使われている形式を選び、隣接するセクションとは異なる形にします。デフォルトで表を使うことはしません。ヘッダーのレイアウト、境界線、背景、アクセントカラー、イラストとアイコンのスタイル、帯の幅は、すべてのセクションで参考ページに合わせます。固有のデザイン要素もすべて残し、独自の色、書体、境界線は選びません。文章はユーザーのものを使い、ユーザー自身の画像が用意されるまでは参考ページの画像をプレースホルダーとして残します。根拠となる顧客情報、引用、数値を流用することはありません。
• 見せる前に比較します。 草案とメインの参考ページを同じ幅でスクリーンショットに撮ります。コピーしたセクションは元のセクションと、組み合わせたセクションはデザイン言語と比較します。ページ全体についても、固有のデザイン要素、同じ形式の隣接セクション、参考ページより長く画像がない箇所がないかを確認します。最初のレビュー前にずれを修正します。

ステップ 1 — 受け入れ

• 下書き用ディレクトリは 1 つ。 HTML のエントリーページを 1 つ用意し、CSS はそのページにインラインで記述するか、同じ場所にあるローカルファイルに置きます。ビルド工程は不要で、ネットワークから取得するものもありません。下書きは、数か月後でもディスクからオフラインで開ける必要があります。
• 実際のコピーを使います。 プレースホルダーテキストでは、重要な 2 つの失敗、つまり見出しが収まらないことと、何も語ることのないセクションがあることを見落としてしまいます。
• 調整項目を紐付けます。 ページとして納品するデザインでは、13 個の調整項目を 1 つの :root ブロックに記述します。--gap、--fs、--ratio、--measure、--radius、--hue、--ink、--surface、--line、--edge、--shadow、--room、--dur に加え、--ease を宣言し、調整可能な値はすべてこれらから導出します。稼働中の製品から抽出した下書きや、参考用のコードからコピーした下書きでは、そのスタイルシートが正となります。CSS を書き換えるのではなく、パネルを既存のカスタムプロパティに紐付け、対応関係を記録します。どちらのケースも references/tokens.md に記載されています。
• ビューに表示される可能性のある条件付きの表示領域を列挙します。デザインを受け取る際に抜け漏れを引き継がないためのチェックリストは references/intake.md にあります。
• 契約内容を記録します。 design-contract.md（templates/design-contract.md をコピー）に、調整項目とその参照元、別の場所で決定された内容、却下された内容、サンプル値を記録します。

ステップ 2 — 動作させる

下書きは、実際に使ってレビューします。リンクで遷移してはならず、選択機能は明示的に有効化するモードとし、デフォルトではオフにします。メニューやダイアログは開けるようにし、ページから到達できない状態にはすべてパネル上にボタンを用意します。

• references/live-draft.md — 使いやすい下書きのルール、下書きのランタイム、条件付きの表示領域のキャプチャ、稼働中のアプリから下書きを抽出する方法、目視での検証について説明しています。
• references/panel.md — パネルの取り付け方法（templates/draft-kit.js を下書き用ディレクトリにコピーし、設定ブロックとスクリプトタグを 1 つずつ追加）、設定、送信するスナップショット、サーバーについて説明しています。

ステップ 3 — 反復する

変更をすばやく行う前に、それぞれの変更箇所を特定できるようにします。

• すべてのセクションとコンポーネントのルートに、安定した属性（data-node="pricing/plan-card#1"）でアンカーを付けます。アンカーがないと、「カード」がどれなのかはモデルの推測次第になり、その推測が外れれば全面的な書き直しが必要になります。
• 選択内容を尋ねずに読み取ります。 選択すると、その要素の CSS セレクター、所有するコンポーネント、計算済みの値、テキストのコントラストが記録されます。マークでは複数の要素とレビュアーのメモが記録され、スナップショットには移動したスライダーとビューポートの幅も含まれます。変更を行うたびに読み取り、ts を確認します。
• 1 回のラウンドで変更するのは 1 つの要素だけです — 密度、階層、または温度のいずれかです。3 つを同時に変更すると、結果の要因を特定できず、次のラウンドも手探りになります。
• ファイルではなく、パッチを返します。 レビューの単位は差分です。依頼されていない兄弟要素、見出し、段落に触れる差分は、結果が正しく見えても不合格です。
• 変更前と変更後のスクリーンショットを撮ります。 キットを非表示にし（H）、依頼時のウィンドウ幅にします。調整項目や共有クラスを変更した場合は、レビュー対象となったすべての幅でページ全体を確認します。視覚的な変更に対する回帰テストはこれだけです（references/iteration.md）。

references/iteration.md には、使用するペイロード、曖昧なフィードバックのトリアージ、ラウンドのルールが記載されています。

ステップ 4 — 監査して引き渡す

references/audit.md には 3 つのパートがあります。既定の上限（2 種類の角丸、2 種類のシャドウ、5 種類の文字サイズ、1 つのカードグリッド、グラデーションなし、アイコンを上部に配置した特徴紹介行なし、…）は、あらゆる状態と幅でパネルの監査項目と合わせて数えます。それぞれを、ドラフトで追加するものに適用してください。メインのリファレンスにある独自のデバイスは、すでに決定事項です。契約書にそれを上書きする決定が記録されていない場合は、設計上の決定であって単なる逸脱ではないものを削除する前に、上限を超えている項目を報告してください。契約書では免除できないアクセシビリティチェック（コントラスト、視認可能なフォーカス、キーボード操作、ターゲットサイズ）もあります。また、確認する幅も記載されています。

ほかの人が相談なしに移植できれば、ドラフトは完成です。レビュー用ツール（DRAFT_KIT ブロック、draft-kit.js タグとファイル、data-levers 属性、selection.json）を含めずにドラフトディレクトリを引き渡し、アンカーマップ、実行時ファイル一覧、明記した近似、対応済みの幅とアクセシビリティチェック、意図的に含めていないもの（データ連携、ルーティング、キャプチャ済みのもの以外の状態）を記した 1 行を含む design-contract.md を添えてください。

ファイル

ファイル	読むタイミング
references/drafting.md	デザインなしで始めるとき：分類、候補の絞り込み、調査と測定、デザイン言語の記録、コンテンツに基づいたセクションの計画、コピー、組み合わせ、再構築、比較。
references/sources.md	ページごとに使うテンプレートカタログやギャラリー、それぞれで調べられる内容、公開コード。日付付き。
references/intake.md	デザインを受け取るとき：必要なもの、差し戻すもの、そのシステムをレバーに対応付ける方法。
references/tokens.md	レバー、抽出した製品、外部コンポーネント、ライトモードとダークモードの対応付け。
references/live-draft.md	ドラフトの動作を整えるとき：ナビゲーション、選択ルール、状態、条件付きサーフェス、抽出、検証。
references/panel.md	レビューパネルの取り付けと設定、マーク、コントラスト、監査、スナップショットスキーマ、サーバーの実行。
references/iteration.md	選択項目とマークの使用、パッチルール、曖昧なフィードバックの振り分け、作業順。
references/audit.md	完了を報告する前に：既定の上限、数え方、アクセシビリティ、幅、削除の順序。
templates/design-contract.md	すべてのドラフトで最初に行うこと。ドラフトの隣にコピーして記入します。
templates/draft-kit.js	レビューパネル — スライダー、選択、マーク、コントラスト、監査、ライブリロード。ドラフトディレクトリに変更せずコピーします。依存関係はありません。
templates/draft-kit.html	ドラフトの例：レバーブロック、アンカー、ドラフトのランタイム、取り付け済みのパネル。
scripts/draft_server.py	ドラフトを配信し、selection.json を書き込みます。Python 3 標準ライブラリのみを使用します。