UI Polish

UI Polish

AI プロダクト向けの洗練された UI：あらゆる状態、遷移、エッジケースをあらかじめ考慮した React コンポーネントと、その背後にあるデザインルールを、コーディングエージェントが従える形で記述しています。ドキュメントとライブデモは uipolish.comでご覧いただけます。

このリポジトリは MIT ライセンスの無料版です。45 個のコンポーネント、10 個のエージェントキットのパーツとブロック、トークンとテーマジェネレーター、デザインルール、エージェントスキルが含まれます。

設計上の考え方

すべてのコンポーネントが同じ判断基準に従い、エージェントが周囲に記述する UI にも同じルールを求めます。そのうちの 3 つを紹介します。

• ビジー状態は表示までに 300ms 待ちます。 すぐに返ってくる結果でスピナーが一瞬だけ表示されることはありません。スピナーが表示されたら、読み取れるように少なくとも 400ms 表示し続けます。
• すべての非同期アクションには 4 つの状態があります。 アイドル、ビジー、完了、失敗のそれぞれを設計し、失敗時には次に何をすればよいかを示します。
• 何もずれません。 変化するラベルは幅を維持し、数値には等幅数字を使い、読み込み時に表示されるコンテンツのためにスペースを確保します。

10 個すべてのルールはfoundation/opinions.mdにあります。

3 つの導入方法

1. MCP サーバー。 一度接続すれば、エージェントにコンポーネントを名前で依頼できます（「日付選択を追加して」など）。エージェントはファイルをプロジェクトに書き込み、自ら記述する UI にもルールを適用します。

claude mcp add --transport http uipolish https://uipolish.com/mcp

Cursor、VS Code、Codex、その他のクライアント向けのセットアップ方法は uipolish.com/docsにあります。

2. shadcn CLI。 各アイテムには r/にレジストリファイルがあります。uipolish.com、またはこのリポジトリの raw ファイルのいずれかを CLI に指定します。

npx shadcn@latest add https://uipolish.com/r/date-picker.json

npx shadcn@latest add https://raw.githubusercontent.com/cortez/uipolish/main/r/date-picker.json

どのアイテムも同じ方法で使えます：https://uipolish.com/r/<name>.jsonまたは https://raw.githubusercontent.com/cortez/uipolish/main/r/<name>.json。

コンポーネントを追加すると、それが使用するコンポーネントも追加され、トークンは一度だけインストールされます。 r/theme.jsonを使うと、トークンを既存の shadcn/ui テーマに割り当てられます。

3. ルールファイル。 skills/ui-polish/には、エージェントスキルとしてのデザインルールがあります。このフォルダーをエージェントのスキルディレクトリ（Claude Code の場合は .claude/skills/）にコピーするか、AGENTS.mdからエージェントに SKILL.mdを参照させます。同じルールが、トピックごとに 1 ファイルでfoundation/rules/にあります。

foundation/tokens.cssと一緒に、registry/からフォルダーを手動でコピーすることもできます。インタラクティブなコンポーネントには @base-ui/reactが必要です。

内容

• registry/<name>/：1 つのコンポーネント。React コンポーネント、その CSS モジュール（--ui-*トークンのみを参照）、エージェント向けのguide.md、meta.jsonが含まれます。 animated-size、field、icons、listbox、text、text-morphは、ほかのコンポーネントがインポートする構成要素です。
• foundation/：設計上の考え方、ルール、tokens.css、Tailwind v4 ブリッジ、shadcn マッピング、チェックリストです。
• theme/theme.ts：色相を 1 つ指定すると、テキスト色のコントラストをすべて調整した、ライトとダーク両方の--ui-*パレットを生成します。その CSS をtokens.cssの後に貼り付けます。
• skills/ui-polish/：foundation/から構築されたエージェントスキルです。
• r/：registry/とfoundation/から構築された shadcn レジストリです。

UI Polish Pro では、プロダクト画面一式、テンプレート、その他のエージェントキットのパーツが追加されます： uipolish.com/pricing。

コンポーネント

• Accordion：グリッド行のトランジションで開く開閉セクションです。一度に1つでも複数でも開けます。URLハッシュで指定された項目は、最初の描画時から開いています。
• Alert：情報、成功、警告、エラーを表示するインラインバナーです。あらかじめスペースを確保するか、押したときに開くため、遅れて表示されたステータスがページを押し下げることはありません。
• Avatar：不透明で控えめな塗りの上にイニシャル付きの写真を表示するか、名前なしで頭と肩のシルエットを表示します。写真の読み込みが速くてもイニシャルが一瞬表示されることはなく、読み込みに失敗しても壊れた画像のマークは表示されません。グループ表示では重なり合い、人数を示す +N が表示されます。
• Badge：ステータスや件数を示す静的なラベルです。配置される行と高さがぴったり揃います。1桁の件数は丸く表示され、数字には等幅フォントを使用します。
• Breadcrumbs：現在のページまでのリンクの階層です。長い階層の途中は … に折りたたまれ、クリックするとその場で開きます。長いラベルは折り返さずにフェードし、どのルーターのリンクにも対応します。
• Button：すぐに押し込まれ、弾むように戻るピル型ボタンです。処理中も幅を保ち、テキストの変更に合わせてラベルが変形します。
• Checkbox：チェックマークが描画されながら切り替わる Base UI のチェックボックスです。混合状態を示すダッシュはチェックマークに変形し、ボックスはラベルの1行目に揃います。
• Chip：押された状態を保つフィルターチップと、専用の名前付き削除ボタンを備えた削除可能なチップです。プラス記号は幅を変えずにチェックマークへ変わり、削除されたチップがフェードアウトしてから、残りのチップがスライドして詰まります。
• Code input：貼り付けやプラットフォームの自動入力で埋まり、Backspace で前に戻るワンタイムコード入力欄です。アクティブなボックスには濃い枠線とキャレットが表示され、無効な場合は枠線に表示されます。オプションのステータスを使うと、ボックスが中央揃えで枠のない「Verifying」ピルに折りたたまれて「Verified」に変わり、コードが間違っている場合は再び開きます。
• Combobox：ローカルまたは非同期の結果を入力して絞り込むオートコンプリートです。一致した項目では入力テキストが強調表示され、新しい結果の読み込み中も古い結果がそのまま表示されます。
• Command palette：あいまい検索、最近使った項目、グループ化された結果に対応する ⌘K パレットです。非同期のデータソースでも読み込み中の状態が一瞬表示されず、高さは結果に合わせて変わります。
• Copy field：コピーアイコンがチェックマークに変わる「Copy」ボタン付きの読み取り専用値です。スクリーンリーダーには「Copied」と伝えます。シークレットは長さが分からないよう、固定数のドットでマスクされます。
• Data table：実データ向けのキーボード操作優先グリッドです。タブストップは1つで、矢印キーでセル間を移動できます。矢印の向きが変わる安定したソート、ポインターまたはキーによる列幅の変更、範囲選択に対応し、依存関係なしで数千行を仮想化します。
• Date picker：完全なグリッド形式のキーボード操作に対応したカレンダーダイアログを開く日付フィールドです。月は移動した方向へ短くスライドし、柔らかな縁のパネル内でクロスフェードします。期間の選択は任意です。
• Dialog：トリガーから広がり、ステップの変化に合わせてコンテンツに収まるよう滑らかに変形するモーダルです。位置をずらさずにスクロールをロックし、編集内容を破棄する前に確認します。
• Drawer：末端側の辺からスライドして表示されるモーダルパネルです。スマートフォンではシート状にせり上がり、フリックの速さに合わせて下にドラッグして閉じられます。固定されたヘッダーとフッターの間で本文をスクロールできます。
• Dropdown menu：チェックボックス、ラジオ、サブメニューの項目を備えたメニューボタンです。サブメニューではポインターが斜めに移動しても閉じず、ポインター操作とキーボード操作で同じ項目がハイライトされます。
• Empty state：空のリストやビューに表示するメッセージです。スタック、ボックス、フォルダー、トレイ、虫眼鏡、カレンダー、プラグの抜けたコードを、くっきりした角のアイソメトリックな線画で描きます。画面に入ると一度だけ描画され、タイトル、1文の説明、1つのアクションが表示されます。
• File upload：高さが固定されたファイルリストを備えたドロップゾーンです。各行がアップロードの進捗に合わせて塗りつぶされ、リストはその高さの中でスクロールするため、ページは動きません。
• Inline edit：表示位置を保ったまま、同じフォントと同じ場所で入力欄に変わるテキストです。文字がずれることはありません。Enter で保存、Escape で元に戻り、エラーが発生すると編集状態を保ちます。
• Kbd：読者のキーボードに合わせてキーやショートカットを表示します。Apple では ⌘K、それ以外では Ctrl K です。最初の描画前に決定されるため、サーバーとブラウザーで表示が一致し、何も動きません。
• List：静的な行、リンク、ボタンで構成された項目リストです。各行はタブストップが1つで、内部にネストされた要素はありません。副次アクションはホバー時またはフォーカス時に表示されますが、ほかの要素は動きません。すべての行は、どの状態でも高さが変わりません。
• Nav rail：アイコン項目で構成されたコンパクトなアプリ用ナビゲーションレールです。1つのツールチップが項目間を滑らかに移動し、ショートカットを添えて各ラベルの幅に合わせて変化します。浮き上がったカプセルが現在のページまでスライドします。
• Number input：− と + のボタンを押し続けると動作が速くなるスピンボタンです。最小値または最大値の範囲外を入力すると、範囲内に調整され、その旨を示すメッセージが表示されます。
• Pagination：固定数のスロットにページ番号を表示するため、ページを移動してもコントロールの幅は変わりません。数字は1つの動くピルの下をスライドし、最後のページでも「Next」はフォーカス可能な状態を保ちます。
• Phone input：国選択機能を備えた電話番号フィールドです。入力中にキャレットを動かさずに番号をグループ化し、+44 から始まる番号を貼り付けると国が選択され、フォームには E.164 形式の値が渡されます。
• Popover：トリガーに固定され、クリックで開くパネルです。フォームではフォーカスをパネル内に移し、説明ではトリガーに残し、閉じると元の位置に戻します。
• Progress：塗りつぶし部分がスプリングに沿って動く線形プログレス表示です。不確定状態ではトラック上を光の帯が横切り、名前付きステップを表示するセグメント形式もあります。
• Prompt input：テキストに合わせて伸び、IME の変換中には送信せず Enter で送信するチャット用コンポーザーです。返信のストリーミング中は「Send」が「Stop」に変わり、ドロップしたファイルはチップになります。
• Radio group：フィールドセット内にリストまたはカードとして配置する Base UI のラジオボタンです。マークは中央から開き、矢印キーで選択できます。グループ全体のタブストップは1つです。
• Response actions：アシスタントの返信の下に表示される、コピー、評価、再試行のアクションです。低評価を選ぶと、その場に「What went wrong?」の入力欄を開けます。
• Scroll area：さらにコンテンツがある場合に限り、マスクを使って端をフェードさせるスクロールコンテナーです。どの背景でも動作し、キーボードでスクロールできます。
• Search field：入力済みのスペース上にクリアボタンがフェードインする検索欄です。テキストは動きません。Escape を押すとクリアされ、続けてフォーカスが外れます。結果の読み込み中は虫眼鏡がゆっくり動きます。
• Segmented control：Tabs の外観を備えた Base UI のラジオグループです。くっきりした細いトラックの上を、平らなピルがチェックされたオプションまで滑らかに移動します。グループには矢印キー操作とフォーム値が備わっています。
• Select：選択専用のコンボボックスです。選択されたラベルに合わせてトリガーの幅が変わり、次の項目へ滑らかに変形します。タッチスクリーンではネイティブのピッカーを使用します。
• Sidebar：AI 製品向けのアプリサイドバーです。ワークスペース切り替え、件数とショートカット付きの項目、折りたたみ可能なセクション、名前変更・ピン留め・削除ができる最近のチャットリスト、アカウントメニューを備えています。折りたたむと、1つのツールチップが滑らかに移動するアイコンレールになり、スマートフォンではドロワーになります。
• Skeleton：これから表示されるコンテンツの形をしたプレースホルダーです。テキスト行の高さは実際のテキストとぴったり揃うため、切り替わっても何も動きません。骨格ごとに要素は1つです。ページ上のすべてのスケルトンを横切る柔らかな斜めの光沢が1つだけ表示され、300ms 未満の読み込みでは何も表示されません。
• Slider：沈み込んだトラックの上に、幅が一定の値を示すラベル行、アクセントカラーの範囲、所定の位置まで滑らかに移動する浮き上がったカプセル型のつまみを備えています。下層の Base UI スライダーがポインター、キーボード、タッチ操作を処理します。
• Stat：ラベルとともに数値を表示し、変化を矢印とテキストの両方で示します。補足文は常に2行分のスペースを取るため、横並びのタイルの高さが揃います。
• Switch：role="switch" を備えた Base UI のスイッチです。ミニチュア版のセグメントコントロールで、沈み込んだトラックの上を浮き上がったピルが滑らかに移動します。コントロールの拡大縮小に対応した2つのサイズと、保存中の状態があります。
• Tabs：Base UI を基盤とし、ピルがタブからタブへ伸びて移動するタブです。オプションの URL 同期により戻る・進むに対応し、パネルはその場でクロスフェードします。
• Text field：ラベル付きの入力欄です。フォーカスを外すと検証し、値が修正されるとすぐにエラーをクリアします。エラーは補足文と同じ行を使うため、何もずれません。
• Theme toggle：ライトとダークを切り替えるアイコンカプセルです。1つの図形では、太陽の円盤が三日月に大きくなる間に、2つ目の円が上をスライドします。選択を保存し、設定が選ばれるまではシステムに従い、最初のフレームの前に正しいテーマを描画します。
• Toast：折りたたまれたスタックに表示され、ホバー時に広がる命令型トーストです。読んでいる間はタイマーが一時停止し、フリックでトーストをスワイプして消せます。
• Tooltip：少し待つと開き、トリガー間を移動するとすぐに開く短いヒントです。キーボードでフォーカスすると、すぐに開きます。

エージェントキットとブロック

• エージェント設定：キットを使って構築された、AI エージェント用の設定画面一式です。モデル、MCP 接続、確認なしで実行できる操作、1 日あたりの支出上限、メモリーを設定できます。変更は各行で保存され、固定表示のセクションナビゲーションがページをスクロールしても追従します。
• 認証：エージェントが接続を要求したときに MCP サーバーが表示する同意画面です。要求している人、可能になる操作、戻り先を示します。リスクの高い権限は初期状態で無効になっています。
• コードブロック：ちらつきや跳ねがなく、ストリーミング表示に対応した AI アプリ向けコードブロックです。コピー、行の折り返し、落ち着いたトークンカラーのハイライトを、ハイライトライブラリなしで利用できます。
• 接続：エージェントアプリに登録された MCP サーバーの一覧です。各サーバーを控えめな1行で表示し、スイッチと、問題の内容および解決方法を示すステータス行を備えています。URLでサーバーを追加し、サインインはブラウザーに引き継ぎます。
• 差分表示：各行の変更箇所を示し、変更されていない部分を折りたたむ統合差分です。ストリーミングモードでは、新しい行が届くたびにフェードインします。
• Markdown：モデルのMarkdownの返信をストリーミング中にレンダリングします。生のアスタリスクやバッククォート、入力途中のテーブルが一瞬表示されることはありません。コードフェンスはライブコードブロックとして開き、返信内のHTMLはテキストとして表示されます。
• メッセージスレッド：新たにストリーミングされた単語だけがフェードインするチャットの記録です。上にスクロールするまでは下端に固定され、返信が終わると一度だけ通知します。
• モデル選択：現在のモデル名に合わせてサイズが変わるコンパクトなトリガーです。モデルの説明を1行で表示する一覧が開き、選択中のモデルには描画されたチェックマークが付きます。
• サインイン：パスワード不要のサインイン・サインアップ画面です。仕事用メールアドレスを入力し、続いて再送カウントダウン付きのワンタイムコードを使います。任意のOAuthプロバイダーと、仕事用ドメインによるSSOにも対応しています。コードの誤り、期限切れ、レート制限、ブロックされたドメイン、プロバイダーの失敗について、それぞれ次に行うべき操作を示します。
• 使用量メーター：エージェントのコンテキストウィンドウまたは支出予算の使用量を、リングと作成ツールバー内のパーセンテージで表示します。詳細を開き、上限前に警告し、コンパクト化を提案します。

ライセンス

MITです。LICENSEを参照してください。