既存プロジェクトのUI改修と体験改善：業務ロジックを壊さずにUIを立て直す
新しいデモページを一から生成するのは簡単です。難しいのは、すでに稼働している実プロジェクトの改修です。API項目は安易に変更できず、既存のフォーム検証とルートパラメーターは失えず、ホームページを変えたらリストや設定ページとの統一感も必要になります。既存プロジェクトを確実に改修するには、まず業務上の不変条件を固定し、必要な改修の深さを選びます。最初の基準ページを決定したらDESIGN.mdへ整理し、他のページへ展開するのが有効です。
重要なポイント
- 作業前に越えてはいけない線を引きます。変更してはいけないAPI項目、ルートパラメーター、権限判定、中心となる送信フローを列挙します。
- 実際の課題に合わせて改修の深さを選びます。レベル1は視覚的ノイズの整理、レベル2は単一ページのレイアウトと状態の再構成、レベル3は複数ステップにまたがる使いにくいフローの再設計です。
- 実際のタスクを行ってクリック数を数え、改修の効果を確かめます。頻繁な操作が6クリックから2クリックに減れば、配色を変えるだけより大きな価値があります。
- 基準ページがレビューに合格したら、色変数、文字サイズの階層、余白、罫線のルールをリポジトリのDESIGN.mdにまとめ、後続ページを同じ基準にそろえます。
npx github:oil-oil/oil-cli install oil-ui-proまず1ページで基本的な方向比較と定型表現の削減を試すだけなら、npx skills add oil-oil/oil-ui で無料のオープンソース版をインストールすることもできます。
既存プロジェクト改修の3段階：小さな修正を大規模リファクタリングにしない
多くのチームがAIに既存プロジェクトを触らせることへ慎重になるのは、「このページを見やすくして」という一言で、モデルがコンポーネントをバラバラにし、使えていたフィルターやエクスポートボタンまで削除してしまうことがあるからです。Oil UIでは（特にOil UI Proの既存プロジェクト改修モジュールで）、現状に応じて改修を明確に3段階へ分けます。
| 改修レベル | 現在の状況 | 変更範囲 | 変更しない部分 |
|---|---|---|---|
| レベル1：視覚的ノイズの整理（Tidy up） | 機能フローに問題はないが、罫線が多すぎる、文字サイズが不統一、配色が濁っている、初期のAI定型表現が残っている | 文字サイズと行間の統一、余分な外枠と入れ子カードの削除、色の整理、テーブルとフォームの余白の整列 | DOMの主構造、ルート、状態管理、すべてのインタラクションフローを維持 |
| レベル2：単一ページのレイアウトと状態の向上（Upgrade） | 情報の優先順位が逆転し、ファーストビューで要点をつかめない。または空、読み込み中、エラーからの復帰が不足している | ページセクションの優先順位の再配置、多列の比率調整、読み込み中／空／エラー／完了の4状態とモバイル対応の補完 | バックエンドAPIの契約、既存の業務ルール、ページ間の遷移関係を維持 |
| レベル3：タスクフローの再設計とデザイン規約の整備（Rework flow） | 操作経路が遠回りで、ダイアログが重なり、ページ間のスタイルがばらばら。1タスクの完了に余分なクリックが必要 | 冗長なステップの統合、奥に隠れた頻繁操作を前面へ移動、基準ページの確立と全サイト向けDESIGN.mdの生成 | 下位層のデータモデルと中心的なビジネスロジックは変えず、フロントエンドの操作経路を減らして再構成 |
稼働中のプロジェクトを確実に改修する4ステップ
契約書レビューツール（ギャラリーの「MOQI」）、スプリントボード（Relay）、メールクライアント（Post）、ECのチェックアウト（Pinch Checkout）など、どのプロジェクトでも次の4ステップで改修を進められます。
現在のページをキャプチャし、番号付きの単一ページ診断を行う
まずエージェントにローカルで動く旧ページを開いてキャプチャさせ、読み取りと操作を本当に妨げている問題を番号付きで示します。例えば「1. 上部の同じ色の3ボタンで優先順位が分からない」「2. 12列のテーブルを1000pxに詰め込み、文字が縦に折り返されている」「3. エラーがalertだけで、該当入力欄に表示されない」などです。
代表的な基準ページを一つ選び、方向を探索する
最初から20のルートを同時に変更しないようにします。ユーザーが毎日最も長く使うページ（メインワークスペースや重要な詳細ページなど）を選び、実際の業務データで2～3の改修方向を作り、ブラウザーで並べて比較します。
実際のタスクを最後まで行い、クリック数を数える
改修したページで、ユーザーが入ってからタスクを完了するまでを再現します。入力、フィルター、エラーを一度発生させて復帰、送信と保存を行い、不要な確認ダイアログやページ間の往復が減ったかを確認します。
基準ページをDESIGN.mdにまとめ、他のページを一括で統一する
基準ページの受け入れが完了したら、背景の色階調、本文の文字サイズ、テーブル密度、ボタンスタイル、禁止する定型表現をプロジェクトルートのDESIGN.mdに書き込みます。その後、同じ規約で隣接ページを順に改修します。
既存プロジェクトの単一ページ改修プロンプトテンプレート
Claude Code、Codex、Cursorで既存ページを改修するときに、次のプロンプトを使うとリスクを管理しやすくなります。
Oil UIを使って、現在のプロジェクトにある[ページルートまたはコンポーネントパス（例：app/billing/page.tsx）]を改修してください。
- 変更を厳禁する業務上の動作：既存の[データ取得フック、フィルターパラメーター、フォーム検証ルール、エクスポートと送信イベント]を完全に維持し、既存の業務項目を一つも削除しないでください。
- 現在のページの課題：[例：すべての情報が同じ幅のカードに詰められて優先順位が分からない。テーブル列が窮屈。フィルター結果が空の場合や支払い失敗時のフィードバックがない]。
- 今回の改修レベル：[1) 視覚的ノイズの整理と余白の整列のみ／2) 単一ページの優先順位とレイアウトを再構成し、状態を補完／3) 操作ステップを簡略化し、DESIGN.mdを抽出、から選択]。
まず現在の旧ページをキャプチャして問題を診断し、改修案を比較できるようにしてください。完了後は1440×900と390×844でスクリーンショットを撮って確認してください。「変更を厳禁する業務上の動作」を最初の項目に書くと、エージェントが業務コードを誤って削除するのを防ぎやすくなります。
実際に動くギャラリー作品とプロンプト
1440pxまたは390pxのライブデモを開き、モデルとプロンプトが最終的なUIにどう表れたかを確認できます。
MOQI
AI契約レビューウェブサイト
社内法務チーム向けAI契約レビュー製品のウェブサイト。ホームページを構築する。
作品とプロンプトを見る →
Relay
プロジェクト・スプリント管理
製品：Relay。20～200人のソフトウェアチーム向けタスク・スプリント管理ツール。 メインワークスペース（1440×900）を構築する： - 左側のナビゲーションにチーム、プロジェクト、自分のタスク、受信トレイを配置する。中央には現在のスプリントをタスクリストまたはボードで表示する。タスクにはID、タイトル、ステータス、優先度、担当者のアバター、見積もりを持たせる。実際のソフトウェア開発に見える名前のタスクを20～30件用意し、十分な現実的データを使う。 - 手ごたえ：1日8時間使う専門ツールのように、暗く、洗練され、密度の高い画面にする。行をコンパクトにし、キーボードショートカットを随所に表示し、ステータスアイコンを一貫した分かりやすいものにする。 - キーボードコマンドパレットを印象的にする。ショートカットで開き、数文字入力するだけで移動、ステータス変更、担当者の割り当てができるようにする。クエリを入力している状態で開いた画面を撮影する。 - タスク詳細のサイドバーを開いた状態も撮影する。
作品とプロンプトを見る →
Post
メールクライアント
製品：Post。1日に数百通のメールを処理する人向けのメールクライアント。 メインインターフェース（1440×900）を構築し、受信トレイ、開いたメール、クイック返信を表示する。仕事のやり取り、請求書、通知を混ぜた現実的なメール内容を使う。 受信トレイを片付ける操作に独自の手ごたえを持たせる。例えば、処理済みのメールがすぐにスライドして消え、件数が減るようにする。 空の受信トレイ状態のスクリーンショットも撮影する。
作品とプロンプトを見る →
Pinch Checkout
Eコマースチェックアウトモジュール
独立デザイナーブランドのオンラインストア向けチェックアウトモジュール（デスクトップ1440×900、チェックアウトパネルを中央に配置）。ショッピングリスト、配送先住所、支払い方法、注文確認を含める。 各ステップを滑らかにつなぎ、すべての入力に、入力中、無効、完了の明確な状態を示す。注文完了時は、チェックマークを表示するだけでなく、喜びを感じられるようにする。 フォーム入力中、検証エラー、注文成功の3状態を撮影する。
作品とプロンプトを見る →Oil UI Proの既存プロジェクト改修キット
Oil UI Proには、既存プロジェクト専用の「単一ページのスクリーンショット診断と注釈」「3段階の改修フロー」「クリック数を数えるタスクレビュー」「複数ページにまたがるDESIGN.mdの抽出と一貫性チェック」が含まれます。オンラインプロダクトを改善し続ける個人開発者やエンジニアチームに適しています。
npx github:oil-oil/oil-cli install oil-ui-proよくある質問
既存プロジェクトを改修するときは、グローバルCSS変数と具体的なページのどちらを先に変更すべきですか？
最も代表的な具体的なページを先に変更してください。実際の業務密度を見ずにグローバルCSS変数を決めても、うまく合わないことが多いためです。まず中心のワークスペースやランディングページを見た目と使いやすさの両面で整え、そこからDESIGN.mdとグローバルスタイル変数を逆算した方が、ずっと正確になります。
既存のサードパーティ製コンポーネントが多いプロジェクトでも、少しずつ改修できますか？
はい。レベル1（視覚的ノイズの整理）やレベル2（単一ページのレイアウト向上）では、外側のグリッド、余白、文字サイズ、色変数だけを調整し、内部の複雑な既存コンポーネントはそのまま残せます。ページごとに少しずつ進められます。
見た目を変えただけでなく、本当に使いやすくなったと判断するには？
2点を確認します。一つは、文字を隠して色面だけを見たときに、ファーストビューの主操作と異常警告を一目で見つけられるかどうかです。もう一つは、最もよく使うタスクを実際に行い、クリック数、視線の移動、フォームエラーからの復帰が旧版よりスムーズになったかを確かめることです。
生成したDESIGN.mdはどこに置き、その後どう使いますか？
プロジェクトルートまたは docs/ に置きます。その後、自分やチームメンバーがClaude Code、Codex、Cursorで新しいページを作るときに、「プロジェクトのDESIGN.mdに従い、Oil UIを使ってください」と一文添えるだけで、統一されたビジュアル言語を引き継げます。