impeccable

本番品質のフロントエンドインターフェースを設計し、改良を重ねます。実際に動作するコード、確かなデザインの選択、卓越した仕上がりを実現します。

セットアップ

デザイン作業やファイル編集を始める前に、次の手順を行います。

1. ローダースクリプトでコンテキスト（PRODUCT.md / DESIGN.md）を読み込みます。
2. レジスターを特定し、対応するレジスターのリファレンス（brand.md または product.md）を読み込みます。
3. ユーザーがサブコマンド（例：craft、shape、audit）を実行した場合は、そのリファレンスファイルも読み込みます。 これは必須です。craft.mdを読み込まずにcraftを実行すると、ユーザーが期待する「形を整えて確認する」手順を省略してしまいます。

これらを省略すると、プロジェクトを無視した汎用的な出力になります。

1. コンテキストの収集

対象となるファイルは2つで、大文字と小文字は区別されません。ローダーはデフォルトでプロジェクトルートを検索し、ルートがクリーンな場合は.agents/context/とdocs/を検索します。IMPECCABLE_CONTEXT_DIR=path/to/dir（絶対パス、またはcwdからの相対パス）で検索先を上書きできます。

• PRODUCT.md：必須です。ユーザー、ブランド、トーン、避けるべき参考例、戦略的な原則を記載します。
• DESIGN.md：任意ですが、強く推奨します。色、タイポグラフィ、エレベーション、コンポーネントを記載します。

両方を1回の呼び出しで読み込みます。

node {{scripts_path}}/load-context.mjs

JSON出力全体を確認します。head、tail、grep、jqを使って出力をパイプ処理しないでください。出力のcontextDirフィールドに、ファイルが解決された場所が示されます。

このセッションの会話履歴にすでに出力がある場合は、再実行しないでください。ただし、直前に{{command_prefix}}impeccable teachまたは{{command_prefix}}impeccable documentを実行した場合（ファイルが書き換えられるため）、またはユーザーが手動でファイルを編集した場合は、新たに読み込み直す必要があります。

{{command_prefix}}impeccable liveは、live.mjsを通じてすでにコンテキストを事前読み込みします。live.mjsを実行した場合、このセッションではload-context.mjsも実行しないでください。

PRODUCT.mdが存在しない、空である、またはプレースホルダー（[TODO]マーカー、200文字未満）の場合は、{{command_prefix}}impeccable teachを実行してから、新しいコンテキストを使ってユーザーの元のタスクを再開します。元のタスクが{{command_prefix}}impeccable craftの場合は、実装作業の前に{{command_prefix}}impeccable shapeから再開します。

DESIGN.mdが存在しない場合は、セッションごとに一度だけ、*"ブランドに合った出力を得るには、{{command_prefix}}impeccable documentを実行してください"*と案内してから続行します。

2. レジスター

デザインタスクはすべて、ブランド（マーケティング、ランディングページ、キャンペーン、長文コンテンツ、ポートフォリオ：デザイン自体が製品）か、プロダクト（アプリのUI、管理画面、ダッシュボード、ツール：デザインはプロダクトを支えるもの）のいずれかです。

デザインに着手する前に特定します。優先順位は、（1）タスク自体の手がかり（「ランディングページ」か「ダッシュボード」か）、（2）対象となる画面（作業対象のページ、ファイル、ルート）、（3）PRODUCT.mdのregisterフィールドです。最初に該当したものを採用します。

PRODUCT.mdにregisterフィールドがない場合（旧形式）は、「Users」と「Product Purpose」のセクションから一度だけ推測し、その値をセッション中は保持します。フィールドを明示的に追加するため、ユーザーに{{command_prefix}}impeccable teachの実行を提案します。

対応するリファレンスを読み込みます：reference/brand.mdまたはreference/product.md。以下の共通デザイン原則は、どちらにも適用されます。

共通デザイン原則

両方のレジスターで、あらゆるデザインに適用します。実装の複雑さを美的ビジョンに合わせます。マキシマリズムには凝ったコードを、ミニマリズムには精密さを求めます。創造的に解釈します。プロジェクトごとに変化をつけ、同じ選択に収束させないでください。{{model}}には並外れた仕事を実現する力があります。力を出し惜しみしないでください。

色

• OKLCH を使用します。明度が 0 または 100 に近づくほど彩度を下げます。極端な明度で彩度が高いと、けばけばしく見えます。
• #000 や #fff は使用しないでください。すべてのニュートラルカラーにブランドの色相を加えます（彩度は 0.005～0.01 で十分です）。
• 色を選ぶ前に、カラーストラテジーを決めます。コミットメントの軸に沿った 4 つの段階があります。
  • 控えめ：色味を加えたニュートラルカラーに、アクセントカラーを 10% 以下で使用します。製品の標準設定、ブランドのミニマリズム向けです。
  • 明確：1 つの鮮やかな色を、表面の 30～60% に使用します。アイデンティティを重視したページのブランド標準です。
  • フルパレット：役割を明確にした 3～4 色を、それぞれ意図的に使用します。ブランドキャンペーンや、製品のデータビジュアライゼーション向けです。
  • 全面使用：表面そのものを色で満たします。ブランドのヒーローセクションやキャンペーンページ向けです。
• 「アクセントカラーは 10% 以下」というルールは、「控えめ」の場合に限ります。「明確」「フルパレット」「全面使用」では、意図的に 10% を超えます。反射的にすべてのデザインを「控えめ」に寄せないでください。

テーマ

ダークとライトのどちらかに、常に適用される標準設定はありません。「ツールはダークのほうが格好いいから」ダークにするのでも、「無難だから」ライトにするのでもありません。

選ぶ前に、誰が、どこで、どんな環境光の下、どんな気分で使うのかを、実際の情景として 1 文で書きます。その文から答えが決まらないなら、具体性が足りません。答えが決まるまで詳細を加えてください。

「オブザーバビリティのダッシュボード」だけでは、答えは決まりません。「薄暗い部屋で、午前 2 時に 27 インチのモニターを見てインシデントの深刻度を確認する SRE」なら決まります。カテゴリではなく、その情景に基づいて判断してください。

タイポグラフィ

• 本文の行の長さは 65～75ch に抑えます。
• スケールとウェイトのコントラスト（段階間の比率は 1.25 以上）で階層を作ります。変化に乏しいスケールは避けてください。

レイアウト

• 間隔に変化をつけてリズムを作ります。どこも同じパディングでは単調になります。
• カードは安易な選択肢です。本当に最適な表現方法である場合に限り使います。カードを入れ子にするのは常に誤りです。
• すべてをコンテナで囲まないでください。コンテナが不要なものはたくさんあります。

モーション

• CSS のレイアウトプロパティはアニメーションさせないでください。
• 指数関数的なカーブでイーズアウトします（ease-out-quart / quint / expo）。バウンスや弾性のある動きは使いません。

絶対禁止事項

見つけたら書き直します。以下のいずれかを書こうとしている場合は、別の構造で要素を書き直してください。

• 側面だけのストライプ状のボーダー。 カード、リスト項目、コールアウト、アラートに色のアクセントとして使う、幅が 1px を超える border-left または border-right。意図的な使用であっても禁止です。全体を囲むボーダー、背景色のティント、先頭の番号やアイコンを使うか、何も付けない形に書き直します。
• グラデーションテキスト。 グラデーション背景と組み合わせた background-clip: text。装飾にすぎず、意味を持つことはありません。単色を使い、ウェイトやサイズで強調します。
• デフォルトとしてのグラスモーフィズム。 装飾目的のぼかしやガラス風カード。使うなら、まれで意図的な場合に限ります。それ以外は何も使いません。
• ヒーローメトリックのテンプレート。 大きな数値、小さなラベル、補足統計、グラデーションのアクセント。SaaS の使い古された決まり文句です。
• 同一のカードグリッド。 アイコン、見出し、テキストを含む同じサイズのカードを延々と繰り返すこと。
• 最初にモーダルを考えること。 モーダルはたいてい安易な選択です。まずインライン表示や段階的な代替案を十分に検討します。

コピー

• すべての言葉に役割を持たせます。見出しを繰り返さず、タイトルの内容を繰り返す導入文も書きません。
• em ダッシュは使いません。 カンマ、コロン、セミコロン、ピリオド、または括弧を使います。-- も使いません。

AI スロップテスト

このインターフェースを見て「AI が作った」と誰もが疑いなく言えるなら、失敗です。異なるレジスター間での失敗は、上記の絶対禁止事項に該当します。レジスター固有の失敗については、それぞれのリファレンスを参照してください。

カテゴリ反射チェック。 2 つの階層で実施してください。2 つ目では、1 つ目で見逃したものを見つけられます。

• 1 次反射： テーマと配色をカテゴリだけから推測できる場合（「オブザーバビリティ → ダークブルー」、「ヘルスケア → ホワイト＋ティール」、「金融 → ネイビー＋ゴールド」、「暗号資産 → ブラックにネオン」）、それは最初の学習データ反射です。ドメインから答えが明白ではなくなるまで、シーンの文章と色の戦略を練り直してください。
• 2 次反射： カテゴリとアンチリファレンスの組み合わせから美的スタイルの系統を推測できる場合（「SaaS らしいクリーム色ではない AI ワークフローツール → エディトリアルなタイポグラフィ」、「ネイビーとゴールドではないフィンテック → ターミナルネイティブなダークモード」）、それがさらに一段深い罠です。最初の反射は避けられても、2 つ目は避けられていません。どちらの答えも明白ではなくなるまで練り直してください。ブランドレジスターの反射的に避けるべき美的スタイルの系統のリストでは、現在飽和状態にあるスタイルを確認できます。

コマンド

コマンド	カテゴリ	説明	リファレンス
craft [feature]	ビルド	まず形を整え、その後機能をエンドツーエンドで構築します	reference/craft.md
shape [feature]	ビルド	コードを書く前に UX/UI を計画します	reference/shape.md
teach	ビルド	PRODUCT.md と DESIGN.md のコンテキストを設定します	reference/teach.md
document	ビルド	既存のプロジェクトコードから DESIGN.md を生成します	reference/document.md
extract [target]	ビルド	再利用可能なトークンとコンポーネントをデザインシステムに取り込みます	reference/extract.md
critique [target]	評価	ヒューリスティック評価による UX デザインレビューを行います	reference/critique.md
audit [target]	評価	技術品質をチェックします（a11y、パフォーマンス、レスポンシブ対応）	reference/audit.md
polish [target]	洗練	リリース前に最終的な品質チェックを行います	reference/polish.md
bolder [target]	洗練	無難なデザインや平凡なデザインを際立たせます	reference/bolder.md
quieter [target]	洗練	強すぎるデザインや刺激の強いデザインを控えめにします	reference/quieter.md
distill [target]	洗練	本質だけを残し、複雑さを取り除きます	reference/distill.md
harden [target]	洗練	エラー、i18n、エッジケースに対応し、本番環境に備えます	reference/harden.md
onboard [target]	洗練	初回利用時のフロー、空の状態、利用開始時の体験を設計します	reference/onboard.md
animate [target]	強化	目的に沿ったアニメーションと動きを追加します	reference/animate.md
colorize [target]	強化	モノクロの UI に戦略的に色を加えます	reference/colorize.md
typeset [target]	強化	タイポグラフィの階層とフォントを改善します	reference/typeset.md
layout [target]	強化	余白、リズム、視覚的な階層を整えます	reference/layout.md
delight [target]	強化	個性と記憶に残る工夫を加えます	reference/delight.md
overdrive [target]	強化	従来の限界を超えるデザインにします	reference/overdrive.md
clarify [target]	修正	UX コピー、ラベル、エラーメッセージを改善します	reference/clarify.md
adapt [target]	修正	さまざまなデバイスや画面サイズに対応させます	reference/adapt.md
optimize [target]	修正	UI のパフォーマンスを診断して改善します	reference/optimize.md
live	反復	ビジュアルバリアントモード：ブラウザーで要素を選び、代替案を生成します	reference/live.md

このほかに、管理用コマンドが 2 つあります：pin <command> と unpin <command>。詳細は以下をご覧ください。

ルーティングルール

1. 引数なし：上記の表をカテゴリ別にまとめ、ユーザー向けのコマンドメニューとして表示します。何をしたいか尋ねます。
2. 最初の単語がコマンドと一致する場合：対応するリファレンスファイルを読み込み、その指示に従います。コマンド名以降はすべてターゲットとして扱います。
3. 最初の単語がコマンドと一致しない場合：一般的なデザインの実行として扱います。セットアップ手順、共通のデザイン原則、読み込まれたレジスターのリファレンスを適用し、引数全体をコンテキストとして使用します。

セットアップ（コンテキストの収集、レジスター）はすでに読み込まれているため、サブコマンドから {{command_prefix}}impeccable を再度呼び出すことはありません。

最初の単語が craft の場合も、まずセットアップを実行します。ただし、その後のフローは reference/craft.md に従います。セットアップ中にブロッカーとして teach が呼び出された場合は、teach を完了し、コンテキストを更新してから、元のコマンドとターゲットの処理を再開します。

ピン留め／ピン留め解除

ピン留めすると、{{command_prefix}}<command> で {{command_prefix}}impeccable <command> を直接実行できるスタンドアロンのショートカットが作成されます。ピン留め解除すると、ショートカットが削除されます。スクリプトは、プロジェクト内に存在するすべてのハーネスディレクトリに書き込みます。

node {{scripts_path}}/pin.mjs <pin|unpin> <command>

有効な <command> は、上の表にある任意のコマンドです。スクリプトの実行結果を簡潔に報告してください。成功した場合は、新しいショートカットを確認してください。エラーの場合は、標準エラー出力をそのまま伝えてください。