moraneus/preview-first

preview-first は何をしますか？

見てから作る。このスキルは、アプリケーションコードを書く前にデザイン段階を挿入します。開発者はブラウザで、完全で明確に異なる複数のデザイン方向性を確認し、1つを選択します。その選択は、以降のすべてのセッションが従うべき書面による契約書となります。

これはデザインスタジオの段階であり、ウェブサイト生成ツールではありません。このスキルは、開発者のアプリケーションコードを決して書きません。決定と契約書を生成します。スクリプトは決定論的で、標準ライブラリのPythonのみを使用します。判断（ブリーフの読み取り、方向性の命名、コピーの作成）はあなたの役割です。

実行・提供のタイミング

開発者がウェブプロジェクトの開始、再開、またはスタイル変更をしようとしているときに、完全な段階を実行します。例：「Xのランディングページを作って」「フロントエンドを始めて」「この見た目が気に入らない」「色とフォントを選んで」、または明示的な/preview-first。

プロジェクトにすでにUIコードがあるが、design/DESIGN.mdがない場合、1行で提供します。「最初にデザインの方向性を見てみませんか？現在の見た目と代替案を並べて表示できます。」承諾された場合、既存の見た目を方向性としてインポート（インポートを参照）し、対等な条件で比較します。

すでにスタイルが設定されたアプリへの小さな編集（「ボタンを追加」「パディングを修正」）では、決してトリガーしないでください。design/DESIGN.mdが存在する場合は、ハンドオフ後のセクションにスキップします。

フロー

すべてのスクリプトは、このスキルのscripts/ディレクトリにあります。python3（またはプロジェクトがuvを使用している場合はuv run python3）で実行します。以下のパスは、プロジェクトルートからの相対パスです。

1. プロジェクトを読み取り、最大4つの質問をする

何かを質問する前に、既存のものを読み取ります：package.json、Tailwind設定、CSSカスタムプロパティ、ロゴSVG、既存のフォント、README。見つかったものはすべて制約であり、質問ではありません。

リポジトリから答えられないことだけを、平易な言葉で、1つのメッセージで質問します。

1. 製品は何で、誰のためのものか、一文で。
2. どのような印象を与えたいかを表す3つの言葉、またはあなたが賞賛するサイト。
3. 固定されているもの：ブランドカラー、ロゴ、フォント、ライトまたはダークのみなど。
4. 最も重要なページの種類：マーケティング、アプリ、コンテンツ、ストア。

2. ブリーフを書く

答えを.design-preview/brief.jsonに正規化します。

{
  "product": "Ledgerline, フリーランス開発者向け請求ツール",
  "audience": "個人開発者と小規模スタジオ",
  "product_type": "product-type.saas",
  "moods": ["正確", "落ち着いた", "信頼できる"],
  "page_type": "marketing",
  "constraints": {"brand_colors": ["#154d8c"], "fonts": [], "scheme": "both"},
  "admired": ["https://linear.app"],
  "words": {"name": "Ledgerline", "tagline": "Gitログに合わせた請求書"}
}

自由テキストを、recommend.py --list product-typesおよび--list moodsを使用してノードIDにマッピングします。未知の単語でも問題ありません；レコメンダーはエイリアスとトークンの重複によってフォールバックします。product_typeの自由テキストも受け入れられます。

3. コピーを作成し、1分以内にプレビューを開く

最初に.design-preview/copy.jsonを作成します。これは短い返信で完了し、ドラフトをテンプレートではなく製品のように読ませるものです。製品自身の名詞を使用します：ナビゲーションはそのセクションであり、機能は製品が行うことであり、見出しはユーザーが繰り返す主張です。

{
  "headline": "501、クリケット、Around the Clockのライブスコア",
  "subhead": "Ocheがスコアを管理するので、プレイヤーはプレイに集中できます。",
  "lead": "パブリーグのプレイヤーと自宅の友達のために作られました。",
  "cta_primary": "新しいゲーム", "cta_secondary": "再開",
  "nav": ["ゲーム", "プレイヤー", "統計", "設定"],
  "features": [{"title": "501と301（チェックアウト付き）", "body": "残りのスコアごとに、標準のチェックアウトルートが表示されます。"}],
  "proof": "", "meta": {"city": "リーズ", "year": "2026"},
  "footer": "Ocheがスコアを管理します。"
}

次に、1つのコマンドを実行します。

python3 <skill>/scripts/quick_start.py --brief .design-preview/brief.json --copy .design-preview/copy.json --count 5 --open

これにより、バンドルが推奨され、directions.jsonが作成され、プレビューがビルドされ、サーバーが起動します。すぐに開発者にURLを伝えてください。--copyをスキップした場合、ドラフトはブリーフ自身の名詞から派生したコピーを使用します；完成したものとして提示する方向性に、そのようなコピーを残さないでください。開発者が見ている間にdirections.json（名前、理論的根拠、レイアウト、プログラム）を改良し、再ビルドします；ページは同じURLにリフレッシュされます。

すべてのプレビューページには、そのバーに3つのジェネレーターが配置されているため、開発者はさらに多くのものを得るために戻る必要はありません：サプライズミー（ランダムに構成された方向性：未使用のスタイル、適切なパレットとペアリング、アイデア、セクション、プログラムのランダムな組み合わせ）、バリエーション（現在見ている方向性の5つのバリエーション：同じスタイル、他のパレット、ペアリング、アイデア、プログラム）、ギャラリーではすべてのスタイルを表示（このブリーフに対するスタイルごとに1つの方向性）。それぞれが新しいドラフトに移動し、同じボタンを持ちます。ターミナルからは： random_direction.py --directions .design-preview/directions.json --build .design-preview [--like B | --all]。

3a. 手動で候補バンドルを確認

python3 <skill>/scripts/recommend.py --brief .design-preview/brief.json --count 4

各バンドルは、スタイル、パレット、タイプペアリング、コンポーネント処理、モーションパターン、アイコンセット、および8から12のデザインアイデア（ideas：分割ナビゲーションとライブ時間、標本ヒーロー、巨大な数字、フィルムグレイン、ブラケットボタン、コロフォンフッターなどのソースされた動き）で構成され、それを正当化するグラフエッジと、交換用のライブ代替案が含まれます。多様性が強制されます：異なるスタイルファミリー、同じ色温度のパレットは最大2つ、同じタイプカテゴリのペアリングは最大2つ、パレットまたはペアリングの重複はありません。デフォルトでは3〜5バンドル、開発者がもっと見たいと言った場合は最大8バンドル。3つを下回らないでください；ブリーフが狭い場合（ダークのみ、1つのブランドカラー）は、その旨を伝えてそれでも3つ表示します。

4. directions.jsonを作成する

バンドルを.design-preview/directions.json（スキーマはknowledge/schema.json、files.directions）に変換します。各方向性について、スクリプトでは提供できないものを指定します。

• name：スタイルではなくアイデア（「Ledger」、「Greenhouse」、「Night shift」）。「Modern」や「Clean」は避けてください。
• rationale：ブリーフ自身の言葉を引用し、この方向性がそれらにどのように応えるかを説明する1つの段落。1つの大胆な選択と、何が控えめであるかに言及してください。
• copy：ブリーフからの実際のコピー：見出し、サブヘッド、2つのコールトゥアクション、4つのナビゲーションラベル、3〜6の機能（それぞれタイトルと1文）、正直なプルーフ行（または空）、フォームタイトルとフィールドラベルと送信テキスト、フッター行。文形式、能動態、製品名詞、emダッシュなし、絵文字なし、矢印なし、「あなたがXであろうとYであろうと」なし、トリコロンなし、Lorem Ipsumなし、架空の数字なし。コピーは、方向性のトーンが本当に異なる場合を除き、すべての方向性で同じです。
• layout（オプション）：セクションバリアントをオーバーライドします。指定がない場合、方向性のアイデア、次にスタイルのデフォルトが選択します。
• bundle.ideas（維持または編集）：レコメンダーが添付したアイデア。製品に合わないものを削除し、ブリーフまたは賞賛されたサイトが要求するものをrecommend.py --list ideasから追加します。レンダリングフックを持つアイデアはドラフトを変更します；残りは契約書に含まれます。
• copy.numbersおよびcopy.stats（オプション）：ソースされた数値 {value, label, source}。数字ヒーローと統計壁は、これらが存在する場合にのみレンダリングされ、架空の数値では決してレンダリングされません。
• copy.meta（オプション）：{"city": "Lisbon"}（分割ナビゲーション、コロフォン、オーバーレイクロック用）。
• 製品タイプは、トピックキット（アートワークの種類、端末、残高、スケジュール、コンポーザー、スコアボードなどのトピックコンポーネント、および製品の名詞）を運びます。最初の画面とその後のセクションはそれを使用するため、スコアボードはスコアで開き、ショップは製品で開きます。layout.topicをnoneに設定すると、トピックコンポーネントを削除できます。
• overrides（オプション）：ブリーフがブランドカラーを修正する場合、{"brand_primary": "#hex", "brand_accent": "#hex"}。ビルダーはオンカラーを再計算し、コントラストの失敗を報告します。

ビルドする前に、すべての方向性に対してreferences/anti-patterns.mdのアンチテルチェックを実行します。ブリーフが名前で要求した場合を除き、テルを拒否し、その場合は理論的根拠でその旨を述べます。

最初の画面のルール：どの方向性も、汎用テンプレート（中央揃えの見出し、2つのボタン、スクリーンショット、次に3つの同一のカード）で始まりません。各スタイルは、賞賛されるサイトで観察されたレイアウトアーキタイプ（キャプション付き図のステートメント段落、フラットディスクを包むタイプ、プロダクトファーストステージ、オブジェクトの横のディスプレイフェイス、フルブリードアート、サイドバーインデックス、ポスタータイプ）と、パレットから生成されたアートワーク（ブループリント、等角図、端末、スイス構成、輪郭、ハーフトーン、オービットリング、ステッカー、スパークライン、単一のマーク）をデフォルトとします。ブリーフが名前で使い慣れた外観を要求しない限り、これらのデフォルトを維持します。方向性の少なくとも2つは、distinctとマークされたスタイルから来ています；レコメンダーはこれを強制し、また、2つの方向性がナビゲーションデバイス、最初の画面デバイス、またはテクスチャを共有しないようにします。

5. プレビューをビルドして開く

python3 <skill>/scripts/build_preview.py --directions .design-preview/directions.json
python3 <skill>/scripts/serve_preview.py --dir .design-preview --open

build_preview.pyは.design-preview/に書き込みます：ギャラリー、および各方向性について、スタイルタイル（両方のモードのコントラストグレード付きパレット、タイプスケール、スペーシング、半径、イージング、アイコン、すべての状態のすべてのコンポーネント、再生可能なモーションパターン）、ブリーフのページタイプ用にドラフトされたページ、および実際のビューポートサイズで最も人気のある電話、折りたたみ式、タブレット、ラップトップのCSS描画フレーム内にドラフトをレンダリングするデバイスビューを含みます。すべてのページのコントロールで、パレット、タイプペアリング、半径、密度、モーションレベル、テーマをライブで切り替えられます。

serve_preview.pyは、デタッチされたlocalhostサーバーを起動し、.design-preview/server.jsonに書き込み、URLを出力してすぐに戻ります。オフラインセッションの場合は、ビルドに--vendor-fontsを追加します。それ以外の場合、ウェブフォントの読み込みに失敗したときに、タイルに表示可能な通知が表示されます。

ブラウザを開けない場合（SSH、コンテナ、CI）、URLと各方向性を1行でリストして出力し、チャットで続行します。

6. 開発者に伝えて、待つ

何をビルドしたか、URL、各方向性を1行で伝え、停止します。開発者に代わって選択せず、コーディングを開始せず、ポーリングもしないでください。開発者はプレビューで長時間過ごす可能性があります。開発者から返信があった場合：

• .design-preview/selection.jsonが存在する場合、それを読み取ります。これには、選択された方向性IDと、開発者が最終的に選択したライブオーバーライド（パレット、ペアリング、半径、密度、モーション、テーマ）が含まれます。
• それ以外の場合は、開発者の言葉から選択を判断し（「B」、「ダークな方」、「AだけどDのタイプ」）、一致するオーバーライドで自分でselection.jsonを作成します。
• 変更の場合（「Bだけど暖かく」、「角の丸みを少なく」、「見出しフォントを交換」）、directions.jsonを編集し（またはバンドル内の代替案を使用）、再ビルドして、同じURLに再度誘導します。サーバーは実行を続けています；ページをリフレッシュするよう依頼してください。
• 「もっと見せて」の場合、recommend.pyを--count 5または変更されたブリーフで再度実行し、新しいIDで新しい方向性を追加し、再ビルドします。

serve_preview.py --dir .design-preview --wait 1800は、スクリプトによる使用のみで、選択が存在するまでブロックします。--statusおよび--stopでサーバーを管理します。

7. 契約書をエクスポートする

python3 <skill>/scripts/export_design.py --selection .design-preview/selection.json \
  --directions .design-preview/directions.json --project .

これにより、design/DESIGN.md（契約書：アイデンティティ、ソースとビルドノート付きのデザインアイデア、コントラストテーブル付きパレット、タイポグラフィ、スペーシングと半径、イージング、レイアウト、すべての状態とトークンを持つすべてのコンポーネント、モーショントークンと許可されたパターン、アイコノグラフィー、イメージ、ライティングスタイル、アクセシビリティフロア、デバイスチェック、「禁止」リストを含む）、design/tokens.json（W3C Design Tokens形式）、design/tokens.css、Tailwind v4が検出された場合はdesign/tailwind.css、CLAUDE.mdへのポインター行、および.gitignoreへの.design-preview/のエントリが書き込まれます。再エクスポートでは、「プロジェクトノート」セクションが保持され、以前のファイルがdesign/history/にコピーされます。

何が書き込まれ、開発者がコミットすべきもの（design/とCLAUDE.mdの行）を、短いメッセージで確認します。その後、契約書に基づいてビルドします。

ハンドオフ後

design/DESIGN.mdが存在する場合は常に：

• UIの変更前に、それを読み取ります。コンポーネントでは、design/tokens.cssの--pf-*トークンを使用し、生の16進数、ピクセル、ミリ秒の値は決して使用しないでください。
• 許可されたモーションパターンとモーションレベルを守ります。動きの軽減設定を尊重します。
• すべての新しい色の組み合わせに対して、contrast.py FG BG --role body|label|large|uiを実行します。
• 「禁止」リストに従います。リクエストが契約書と矛盾する場合は、その旨を伝え、黙って逸脱するのではなく、ステージを再実行することを提案します。
• 重要なページをビルドした後、デバイスチェックを提供します：.design-preview/<id>/devices.html?url=http://localhost:PORT/pathを開いて、実際のページを同じフレームで表示します。フレームブロッキングヘッダーを送信するページは表示できません；その旨を伝えてください。
• プロジェクトの決定のために、design/DESIGN.mdの空のセクション（終了マーカーの下）を維持します。

インポート

プロジェクトの現在の外観、または開発者が賞賛するサイトを方向性として比較するには：

python3 <skill>/scripts/import_direction.py --css src/styles.css --into .design-preview/directions.json --name "Today"
python3 <skill>/scripts/import_direction.py --tailwind tailwind.config.js --into .design-preview/directions.json
python3 <skill>/scripts/import_direction.py --tokens design-tokens.json --into .design-preview/directions.json
python3 <skill>/scripts/import_direction.py --url https://example.com --into .design-preview/directions.json --name "Reference"

インポートは、パレット、ペアリング、および最も近いスタイルを導出し、再ビルドします。インポートされたパレットは他のものと同様にチェックされ、失敗はタイルに表示されます。

知識とリフレッシュ

決定はknowledge/graph.jsonから得られます：スタイル、パレット（OKLCH、両方のモード）、タイプペアリング、コンポーネント処理、モーションパターン、製品タイプ、ムード、アイコンセット、プラットフォーム機能、参照サイト、重み付けされたpairs_with、suits、avoid_with、requires、`ex

…

[翻訳のため省略]