uikit

uikit

AI 生成 UI には、ひと目でわかる特徴があります。均等なサイズの機能カードが 3 枚、紫のグラデーション、スレート 900 の背景に Inter、ヒーロー部分に div で作られた偽のダッシュボード、順序を示す内容でもないのにその上に置かれた 01 / 02 / 03 の小見出し。どれもバグではなく、テストでも検出できません。これらは ほかの選択肢を選ぶ理由がモデルになかったために選ばれたデフォルトです。

その理由が uikit です。UI の判断を このプロジェクトならでは の判断にする制約を与え、特徴的なパターンに名前を付けることで、意図せず再現するのではなく、意識して避けられるようにします。

このスキルを支える考え方はひとつです。選択に制約がない場合にだけ、センスを使います。 記録済みのデザインシステムがあるプロジェクトでは一貫性を保ちます。出荷済みのコンポーネントがあるプロジェクトでは、それに準拠します。ゼロから始めるプロジェクトでは、そのプロジェクト独自の題材から視点を導き出します。どのプロジェクトにもデフォルトを押し付けません。それが優先順位の階層であり、それ以外のすべてのセクションはこれに従います。

uikit ではないもの

• デザインシステムの記録ツールではありません。 DESIGN.md の管理者はひとりであり、それはこのスキルではありません。uikit は DESIGN.md を読み取りますが、書き込みはしません。センスを作り出すことと記録することの両方を担うスキルでは、どちらの役割も誠実に果たせないからです。
• センスのライブラリではありません。 同梱のカラーパレットも、フォントの組み合わせも、スタイルカタログもありません。161 種類のパレットをまとめた参照表を使ってスタイルを決めれば、すべてのプロジェクトが互いにそっくりになるだけです。
• コードレビュアーではありません。 規約への適合、正しさ、完全性は、一般的なレビューが担います。uikit の監査は、視覚とインタラクションのレベルに限られます。
• ゲートではありません。 プリフライトでは自らの出力を批評しますが、ビルドを失敗させることはありません。センスは合否を判定するチェックではありません。センスを理由に失敗するビルドでは、反証できない何かを判定基準にしていることになります。

いつ実行するか

依頼に応じてモードを選び、そのモードのファイルを読み、手順に従います。このルートにある内容はすべてのモードに適用され、モードのファイルでは繰り返しません。

• build. 「このページを作って」「設定画面を追加して」「見栄えをよくして」「オンボーディングのフローをデザインして」など、実装ステップから引き継いだ UI の作業に使います。UI を生成します。build モード → modes/build.md を読み、手順に従います。
• audit. 「これ、AI 生成っぽく見える？」「UI を監査して」「なぜテンプレートっぽく感じる？」「フロントエンドに粗がないか確認して」などの依頼に使います。読み取り専用で調査します。一切書き込みません。 audit モード → modes/audit.md を読み、手順に従います。
• mockup. 「この画面のモックアップを作って」「どんな見た目になるか見せて」「この画面の案をいくつか見せて」「3 パターンのモックアップを作って」などの依頼に使います。画像を生成し、コードはユーザーが求めた場合にのみ生成します。ソースには書き込みません。mockup モード → modes/mockup.md を読み、手順に従います。

依頼が明らかにいずれかのモードに当てはまる場合は、そのまま実行します。「ダッシュボードを見て」のように、どちらにも該当し得る依頼の場合に限って確認します。audit は無料で、build はソースを編集するためです。「コードで」「HTMLで」「コンポーネントで」とも指定されたモックアップの依頼は build です。

このスキル内の引き継ぎ文はすべて手順書の文体で記述します。1 文につき指示は 1 つにし、能動態、現在形を使い、比喩は使いません。

優先順位の階層

4つの段階があります。最初に該当するものを採用し、コードを書く前にどれに該当したかを伝えてください。 下位の段階が上位の段階に優先することはありません。上位の段階が決めていない部分だけを補います。

段階	該当する条件	制約するもの
1. DESIGN.md	リポジトリのルートに DESIGN.md がある	そのトークンが、カラーパレット、文字サイズの尺度、間隔、角丸を定めます。それ以外はありません。Do's と Don'ts は UI コピーの文体ルールです。
2. 既存コンポーネント	コンポーネントのディレクトリ、components.json、またはトークンを定義する場所（@theme、:root のカスタムプロパティ、テーマ設定）がある	既存の Button が基準です。実際のコンポーネントを3〜4個確認し、構成、命名、間隔の習慣に合わせてください。
3. 対象自身の世界	上記のどちらにも該当しないが、README、コンテキストファイル、ルート名、ドメインモデル、または実際に構築しているものからプロダクトの実態を把握できる	プロダクトの素材、語彙、成果物です。印刷所向けのツールが、ヘッジファンド向けのツールのように見えてはいけません。
4. スタックのデフォルト	グリーンフィールドで、対象の実態が本当に不明な場合	以下の標準設定を、選択ではなくデフォルトとして明示します。

独自性が実際に生まれるのは第3段階です。 スタイルの語彙からではなく、対象から生まれます。そこにある道具、素材、専門用語、使う人々がすでに扱っている成果物です。ほかのプロジェクトには引き出せない源泉だからこそ、結果がありきたりになりません。

段階ごとのシグネチャー素材

段階によって、シグネチャーに使える素材が決まります。デザインの読み取りでは、そのシグネチャーが何かを定めます。

• 第1〜2段階。 構成、インタラクション、動きです。トークンは固定されており、変更できません。工夫できるのはレイアウト、サーフェスの振る舞い、静止時の見え方です。
• 第3〜4段階。 カラーパレット、文字、グリッドも含まれます。何も固定されていないため、シグネチャーは構造的なものにできます。

第1段階または第2段階なのに第3段階のカラーパレットを使うことは、このスキルがもたらしうる最も深刻な問題です。到着前は統一されていたコードベースに、周囲と何も合わないコンポーネントが1つだけ生まれてしまいます。

デザインの読み取り

コードを書く前に、5つの言葉を明示します。 手間はかかりません。モデルがすぐにデフォルトの美的感覚へ飛びつくのを防げます。口に出して示した選択なら、異議を唱えて考え直すこともできます。

Design read · surface: product · audience: internal ops staff · rung: 2 (shipped components)
· signature: the dirty state, where each changed row shows its old value struck through until Save
· density: compact

項目	値	ここで定める理由
サーフェス	product または marketing	2つではありきたりさの特徴が異なります。これによってカタログを絞り込みます。
対象ユーザー	具体的な自由記述	「1日6時間ここで過ごす社内の運用スタッフ」と「8秒で判断する初めての訪問者」では、適切な情報密度が異なります。
段階	1〜4 と、該当したもの	どの制約が適用され、シグネチャーに何を使えるかを明示します。
シグネチャー	このサーフェスを特徴づける1つの要素と、その素材	以下を参照してください。
密度	compact、comfortable、spacious	段階とは独立して変化する、唯一の軸です。

シグネチャ

各画面に要素は1つだけ。きっかり1つです。 その画面について尋ねられたとき、人が真っ先に挙げるものです。その周囲は静かで整然と保ち、思い切った表現は1か所に集中させ、要件に寄与しない装飾は削ります。

シグネチャは、決定済みの挙動の範囲内で機能します。 まず計画、課題、またはリクエストを読みます。そこで指定された挙動（保存アクション、確認手順、フィールド、フローの順序など）はすべて指定どおりに実装し、シグネチャは仕様で決められていない部分、つまり見せ方、フィードバック、レイアウト、動きに反映します。シグネチャのアイデアが指定済みの挙動を変える場合は、提案として引き継ぎ事項に記載し、実装では要件に合ったシグネチャを選びます。

これは意図的に「創造的なリスクを取る」とは表現していません。大胆にしてほしいと言われると、モデルは大胆さの見た目を取り出します。そして取り出されるのは、これまで目にした大胆なものすべての平均です。現在、それは次の3つの見た目を意味します。温かみのあるクリーム色（#F4F1EAに近い色）に、高いコントラストのセリフ体とテラコッタ色のアクセント。ほぼ黒に、酸性グリーンまたは朱色のアクセントを1つ。あるいは、極細の罫線、角丸なし、密度の高いカラムを備えた新聞風レイアウトです。どれも、一部の要件には適しています。しかし、題材にかかわらず同じものが現れるなら、それは選択とは言えません。

「この画面で人々の記憶に残るものを1つ挙げる」は、回帰する平均がありません。また、事前チェックを通過できる唯一の方法でもあります。事前チェックでは、シグネチャがきっかり1つだけ存在することと、その素材が宣言された段階で使用可能であることは確認できますが、リスクを取ったかどうかは確認できません。

実例：

• 段階2。仕様で保存アクションが指定されている設定ページ。 標準的な出力は、カード、左にラベル／右にトグルの行、右下に「変更を保存」です。正しいものの、印象に残りません。シグネチャは変更前の状態です。変更された各行に、取り消し線付きの古い値と新しい値を並べて表示し、保存バーには保留中の変更数を表示します。新しいトークンは一切不要で、保存も仕様どおりに動作します。自動保存のほうが強いシグネチャになるのは、仕様で保存方式が決まっていない場合だけです。ここでは提案として引き継ぎ事項に記載します。
• 段階3。活版印刷の工房の予約ツール。 標準的な出力は、Inter、slate-900、3つの機能カード、紫色のCTAです。シグネチャは価格表を活字見本シートにすることです。サイズは実寸で表示し、ベースライングリッドに沿って左に並べ、紙とインクから着想を得たパレットを使います。

デザインの読み取りで決して作業を止めない

これは宣言であり、聞き取りではありません。 段階3または4で題材が不明確な場合は、リポジトリにある情報から推測して、その推測を明示し、決して作業を止めて尋ねないでください。間違っていても明示された推測のほうが、正しい答えを待って進まない状態より優れています。uikitは、回答する人がいない無人パイプラインで動作します。明示された読み取りがあれば、レビュー担当者が修正できます。ユーザーが明らかにその場にいて、リクエスト自体が曖昧な場合に限り、質問してください。

アンチスロップカタログ

大切なのは規律であり、その規律もリストとともに受け継がれます。 ある特徴を項目に加えるのは、正しい代替案を併記した禁止事項として表現でき、かつ、エージェントが何もレンダリングせずに自らの出力をチェックできる場合に限ります。上限は約30項目で、項目の入れ替えによって維持します。追加するなら、1つ削除します。 この種のリストは、誰も正直にチェックを付けない100項目のチェックリストへと劣化しがちです。そして、誰もチェックしないチェックリストはただの飾りです。項目を増やすことしかできない網羅的なリストより、改善することしかできない上限付きのリストのほうが価値があります。

対象タグ：P プロダクト · M マーケティング · B 両方。

ビジュアルと CSS

	禁止	代わりに
B	ヒーローや主要な CTA に使うアクセントとして、バイオレット／パープルのグラデーションを使う	プロジェクト独自のアクセントを使います。段階が 3～4 の場合は、題材から自然に連想される色を使います
B	見出しにグラデーションテキストを使う	単色を使います。見出しを強調する必要がある場合は、太さやサイズで工夫します
B	何にでも反射的にグラスモーフィズムを使う：半透明の白いカードに backdrop-blur を重ねる	実際の境界線を備えた、不透明な面を使います
B	あらゆる面にドロップシャドウを付ける	シャドウは高さを示すものです。通常のフローに置かれたカードには付けません
B	何にでも rounded-2xl／rounded-3xl を使う	デザインシステムに基づき、統一した角のスタイルを使います
B	何にも結び付いていない、点滅する緑の点のような装飾的なステータスドットを使う	実際の状態に結び付けるか、削除します

タイポグラフィ

	禁止	代わりに
B	Inter（または素のシステムフォントスタック）と slate-900 だけで、タイポグラフィ全体を決める	ディスプレイ用と本文用の書体を意図的に選び、タイポグラフィを単なる表示手段ではなく、デザインの一部にします
M	すべての見出しの上に眉見出し／キッカーラベルを置く	削除します。セクションに文脈が必要なら、見出しで伝えます
M	順序のないコンテンツに 01 / 02 / 03 の番号を付ける	読者にとって順序が重要な場合にのみ使います
B	インターフェース文字列にダッシュを使う	ピリオド、コンマ、または 2 つの文にします。これは画面上の文字列に適用され、リポジトリ内の文章には適用されません
B	テクスチャとして、すべて大文字で字間を広げた小さなラベルをあちこちに散りばめる	ラベルが本当に必要な場所で、ひとつのスタイルを使います

レイアウト

	禁止	代わりに
B	同じサイズの機能カードを 3 枚並べる	実際の数を示し、重要度に応じてサイズを決めます。機能が 4 つならカードも 4 枚にします
M	すべてのセクションを中央揃えにし、最後まで max-w + mx-auto + text-center を適用する	配置に変化を付けます。中央揃えは、本当にふさわしいものにだけ使います
M	Scroll ↓ の案内や、跳ねるシェブロンを置く	削除します。コンテンツが画面下端から見切れていること自体が、その役割を果たします
M	装飾的な細線グリッドやドットパターンの背景を使う	削除します。構造は装飾ではなく、実際に意味のある情報を表すべきです
M	セクションの横に縦書きテキストを回転させて配置する	削除します
M	ロケール／天気／現地時刻の帯を置く	製品が本当に時間や場所に関するものでない限り、削除します

コンテンツとコピー

	禁止	代わりに
B	「Jane Doe」／「John Smith」のような仮の人物名を使う	製品の領域に合った名前、または実際の空状態を使います
M	「Acme Inc／Company Name」のロゴ一覧を置く	実際の顧客を載せるか、顧客ができるまでセクションを削除します
M	架空の指標（「99.99% の稼働率」「10,000 人以上のユーザー」「200 万件のリクエスト」）を使う	実際の数値を使うか、数値を載せません
B	Lorem ipsum を使う	実際のコピーを使います。不明な場合は、事実に即した最短の文にします
M	架空の引用文やストックアバターを使った推薦カードを置く	実際の推薦が集まるまで、セクションを削除します

偽の製品表現

	禁止	代わりに
M	div でダッシュボードやアプリのスクリーンショットを組み立てる	実際のスクリーンショット、埋め込みのライブコンポーネント、または何も置かない方法を使います
M	モックの周囲に偽のブラウザー枠を付ける	同様に、偽のウィンドウ枠は、この一覧で最も見分けやすい偽物のサインです

製品 UI の状態に関する不足

これらへの配慮がないことは、製品側におけるパープルのグラデーションに相当します。誰もデザインしておらず、ただ生成されただけだからです。

	禁止	代わりに
P	行が 0 件のとき、何も表示しないリストやテーブル	対象を明示し、項目を作成するアクションを提示する空状態を用意します
P	ローディング状態を用意しない	実際のレイアウトに合わせたスケルトン、またはラベル付きのローディング領域を用意します
P	エラー状態を用意しない	何に失敗したかと、復旧するためのアクションを示すエラーを用意します
P	アクセシブルな名前のない、アイコンのみのボタン	aria-label を付けます。アイコンが明確でない場合は、ツールチップも付けます
P	バリデーションの文言として「入力が無効です」と表示する	制約と解決方法を明示します。例：「パスワードは 12 文字以上にしてください」
P	無効にした理由を示さずに、コントロールを無効化する	無効な理由を説明するか、無効化しないようにします
P	確認も取り消し手段もない、破壊的な操作	確認を求めるか、取り消し可能にします。通常は取り消し可能にするほうが適切です

アクセシビリティの最低基準

指摘事項ではなく、最低基準です。すべてのビルドで告知せずにこれらを満たし、audit はリリース済みの画面で満たされていない項目を報告します。

• すべてのインタラクティブ要素で、視認できる :focus-visible を表示します。フォーカスリングを削除する場合は、必ず代わりの表示を用意します。
• 動きのある箇所ではすべて prefers-reduced-motion を尊重します。motionkit をインストールしている場合、軽減された表示で何を維持するかを明示します。
• テキストと、意味のある非テキスト要素で WCAG AA のコントラストを確保します。
• ARIA より先にセマンティックな要素を使います。role="button" とクリックハンドラーを設定した div より、常に button を使います。
• すべてのコントロールにラベルを付け、すべての画像に alt を設定します（装飾目的の場合は意図的に alt="" にします）。
• すべての要素にキーボードで到達して操作できるようにし、適切なタブ順を設定します。モーダルではフォーカスを閉じ込め、閉じたときに元の位置へ戻します。
• タッチターゲットは、粗いポインターでは 44px 以上にします。

スタックのレイヤー

Tailwind v4 と shadcn/ui に関する正確性のルールは stack.md にあります。プロジェクトで Tailwind または shadcn/ui を使う場合はこのファイルを読み、それ以外のスタックではファイル全体を読み飛ばします。

モバイルのレイヤー

スマートフォンで Web アプリをインストール済みアプリのように動作させるための修正（固定されたホバー、タップ時のフラッシュ、100vh、入力時のズーム、安全領域、オーバースクロール、タッチ操作の軸）は mobile.md にあります。スマートフォンに表示する画面では、mobile.md を読んで適用します。デスクトップ専用の画面では、ファイル全体を読み飛ばします。

セルフレビュー

必ず実施する、文書ベースの事前確認

デフォルトの手順であり、ヘッドレス CI や制限された仮想マシンでも実際に実行されます。出力を次の項目に照らして確認します。

1. カタログ。宣言された画面に絞り込みます。
2. アクセシビリティの最低基準。すべて確認します。
3. 2つの署名チェック。署名が正確に1つだけ存在すること、およびその素材が宣言された段階で許可されていることを確認します。
4. アクセサリーを1つ取り除く確認。リリース前に、作成したものを見直し、要素を1つ取り除きます。要件に沿っていない装飾がほぼ必ずあり、それは作成前よりも完成後のほうが見つけやすいものです。

修正した内容と、理由を添えて残した内容を報告します。これはレビューであり、ゲートではありません。ビルドがブロックされることはありません。

ピクセル確認（オプトイン）

明示的に依頼された場合にのみ実施します（「見て」「スクリーンショットを撮って確認して」など）。画像を利用できるとき、画像には千のトークンに値する情報があります。

すでに利用できるものを、次の順で使います。環境が提供するブラウザー自動化ツール・インストール済みのヘッドレスブラウザー・プロジェクトにすでにあるテスト自動化環境。静的ファイル、コンポーネントのプレビュールート、ユーザーが起動した開発サーバーなど、最も低コストでレンダリングできるものを対象にします。

まず evaluate 呼び出しで事実（テキスト、計算済みスタイル、要素数）を確認します。デフォルトでは画像を使わずにスナップショットを取得します。画像は視覚的な判断を行う場合にのみ使い、ユーザーが確認する必要がある場合はファイルに保存します。

ブラウザーをインストールしないでください。起動するよう指示されていない開発サーバーを起動しないでください。データを事前投入しないでください。 uikit に必要なのは、フルのエンドツーエンドツールよりも厳密に少ないものです。必要なのは、認証フローを操作することではなく、レンダリングされた出力です。

できないことは明確に伝える

ブラウザーがない、レンダリングできない、ファイルシステムがない。これらは通常の状況であり、エラーではありません。結果と同時に制約を明示し、文書ベースの事前確認をスクリーンショット確認の失敗として決して説明しないでください。

SettingsPanel.tsx と SettingsRow.tsx を作成しました。製品カタログと a11y の最低基準に照らした事前確認は問題ありません。環境でブラウザー自動化を利用できないため、視覚的な確認は行っていません。

実施していない視覚的な確認を行ったと主張しないでください。実際には誰も見ていない UI を検証済みと報告するほうが、未検証と報告するよりも問題です。

ファイルシステムがまったくない場合（ブラウザーベースのエージェントなど）は、各コンポーネントを想定パスをラベルにしたフェンス付きコードブロックで出力し、通常どおりデザインの解釈を説明し、ユーザーが自分で実行するコマンドを示します。

注意事項

• 階層は好みより優先されます。 記録されたシステムと、より良いと考える案が食い違う場合はシステムに従い、より良い案は引き継ぎ時に提案として記載します。一貫性は積み重なりますが、単発の改善にその効果はありません。
• 組み合わせは発明より優先されます。 既存のコンポーネント、次にその拡張、最後に新規作成の順で検討し、それぞれ次の段階に進む際には理由を示します。
• データを捏造してはいけません。 実在しない数値、名前、ロゴ、引用は、プレースホルダーであっても公開しません。プレースホルダーデータは本番環境に残りがちです。また、指標の捏造は誰かを困らせかねない、唯一の明白な兆候です。
• 既存のプロジェクト規約を優先します。 独自のコンポーネントパターン、ファイル構成、スタイル設定の方法があるリポジトリでは、それに従い、uikit はどの規約に従ったかを示します。
• UI の文言はここで、それ以外の文章は別の場所で扱います。 uikit が管理するのは、インターフェース内の文字列です。リポジトリの文章、ドキュメント、README は一般的な文章の校正で扱い、インストールされている場合は humankit を使用します。
• コミットしません。 変更はコミットの手順でまとめられるよう、ステージングせずに残します。