uisight

uisight

AI はすでに画面を見られます。ただし、測定はできません。

スクリーンショットを見たエージェントは「この見出し、少し薄い気がする」と推測します。uisight を使えば、正確に把握できます。

- from a screenshot:  "the heading looks a little washed out, maybe adjust the color?"
+ from uisight:       INVISIBLE TEXT 1.04:1 — span.bg-gradient-to-r "your headline"
+                     (text rgba(255,255,255,.5) / bg rgb(247,247,248))

一方は印象です。もう一方はセレクターが付いた測定値です。エージェントは対象の要素を探し回らず、その要素を修正できます。

uisight は、ウェブおよびレスポンシブ UI 向けの MCP サーバーです（Claude Code、Cursor、Antigravity など、MCP に対応するあらゆるもの）。モバイルとデスクトップのセッションを並行してライブ実行し、見つかった問題を測定して、あなたとエージェントがまったく同じ画面を見られるようにします。

スマートフォンでスクリーンショットを撮り、チャットに貼り付けて、「ボタンが壊れて見えるけど、わかる？」と入力することにうんざりした、ソロの創業者が開発しました。

ライブパネル：同じサイトのデスクトップとモバイルのセッションが URL と同期しています。検査は各画面で実行され、検出結果はデバイスごとに返されます。AI は MCP を通じて、ここに表示されているのとまったく同じ画面を見ます。

他との違い

	マルチビューポートブラウザー （Polypane など）	ブラウザーツール／コンピューター操作 （Playwright MCP、エージェントハーネス）	ネイティブアプリ用ツールキット （Argent など）	uisight
UI を測定（「低く見える」ではなく1.14:1）	✅ 人間向け	—	—	✅ エージェント向けのテキスト
人間とエージェントがひとつのライブセッションを共有	—	—	—	✅
1 回の実行でデバイス × テーマのマトリックスを確認	✅	—	—	✅
人間がバグをピン留め → エージェントがメモと画面を確認	—	—	—	✅
ネイティブ iOS／Android アプリ	—	—	✅	—（ウェブのみ）

測定エンジンが中核です。AI がスクリーンショットを凝視してトークンを浪費する代わりに、inspect は次のような検出結果を返します。

[mobile · Pixel 7 · light] https://yourapp.com/
  INVISIBLE TEXT 1.04:1 — span.bg-gradient-to-r "your headline" (text rgba(255,255,255,.5) / bg rgb(247,247,248))
  BUTTON a.text-white "Get Started" → text/background contrast 3.35:1
  touch target below 44px 180x23 — "read the guide"

テキストによる検出結果は低コストで正確、すぐに対応できます。AI は推測せず、該当するセレクターを正確に修正します。

「エージェントがすでにこれをやっています」

そのとおりです。一部は正しいです。コンピューター操作、ブラウザーツール、そしてほとんどのエージェントハーネスで、すでにページを開いてスクリーンショットを撮れます。uisightが置き換えようとしていないのは、そこです。まだ足りないものが3つあります。

1. 見ることと測ることは違います。 スクリーンショットを読むビジョンモデルでは、コントラスト比はわかりません。4.6:1（合格）と4.3:1（WCAG AA不合格）の違いはわかりません。見た目が同じだからです。タップ対象が44pxではなく41pxであることや、色がハードコードされているためにライトモードでもダークモードでも同じように表示される要素にも気づきません。uisightはライブDOMから、アルファ合成された背景、グラデーションテキスト、oklch()カラーなどを測定します。

2. 同じ料金で、ずっと多くのことができます。 以前は、スクリーンショットの取得コストは測定の数倍だと謳っていました。実際に測定すると、そうではありません。モバイルフレームは約460トークンで、対応するinspectの結果は約570トークンです。inspectは安価な選択肢ではありません。画像だけではモデルが推測するしかないところを、4.38:1 (threshold 4.5)と示せる選択肢です。

本当の節約になるのは、別の選び方です。uisight <url>はモデルが一度読むだけのレポート（約800トークン）を書き出しますが、MCPツールを画面ごとに操作すると、各ステップで会話全体を再送信します。ローンチスレッドの下で、ある人がこの問題を見事に言い表していました。「トークンは多少使うけれど、何とかなる。」 このような主張は確かめる価値があるため、コストに表全体を載せています。

3. 一緒に見てくれる人はいません。 通常の構成では、エージェントは一人でページを見て、結果を報告します。ここでは、あなたとエージェントの両方が同じライブセッションを見ます。エージェントが何をしているかをその場で確認でき、あなたが何かに気づいたら、メモを添えてピン留め（📌）できます。するとエージェントは、そのメモと該当するフレームを読み取ります。バグを言葉で説明する必要はもうありません。

対象範囲について：uisightはウェブとレスポンシブUIを対象としています。ネイティブiOS／Androidアプリの操作には、Argentが優れており、この分野では私たちよりはるかに多くのことができます。

クイックスタート

# one-shot audit: PNGs + gallery + report for iPhone/Pixel/desktop, light+dark
npx uisight https://yourapp.com --theme both

# live panel: mobile + desktop side by side, you browse, AI watches (and vice versa)
npx -y -p uisight uisight-panel http://localhost:3000

初回実行時。 Playwrightはドライバーをnpm経由で提供しますが、ブラウザーは別途ダウンロードするため、初回実行時には操作対象がありません。ターミナルでは、uisightが必要なものを取得するかどうかを確認し、ダウンロード内容を表示します（Chromiumはディスク上で約700 MBで、一度だけ必要です）。CIや、エディターまたはエージェントホストが起動したパネルなど、応答する人がいない場合は、確認もダウンロードも行わず、実行すべき正確なコマンドを表示します。UISIGHT_NO_INSTALL=1を設定すると、どの環境でもこの確認を無効にできます。手動で実行することもできます。

npx playwright install chromium        # add webkit for the real iOS Safari engine

一括監査では、デバイス × テーマごとのギャラリーが生成され、各カードに検出結果が表示されます。

AIに接続する（MCP）

# Claude Code
claude mcp add --scope user uisight -- npx -y -p uisight@latest uisight-mcp

Cursor／Antigravity／その他のMCPホストでは、MCP設定に次を追加します。

{ "mcpServers": { "uisight": { "command": "npx", "args": ["-y", "-p", "uisight@latest", "uisight-mcp"] } } }

あとはエージェントに「uisightでアプリを見て」と伝えるだけです。必要に応じてパネルサーバーが自動的に起動します。

Claude Desktop（ワンクリック）

最新リリースからuisight-<version>.mcpbをダウンロードして開きます。Claude Desktopがインストールし、開くページ、ツールセット（allまたはcore）、初回使用時にブラウザーをダウンロードするかどうかの3点を確認します。JSONを編集する必要はありません。

バンドルにはサーバーとその依存関係が含まれています（約7 MB）。ブラウザーは含まれていません。3つ目の質問はそのためです。有効にしておくと、Chromiumがない場合、バンドルのビルドに使用されたPlaywrightのバージョンによって、最初のツール呼び出し時に一度だけ取得されます。node scripts/build-mcpb.mjsでバンドルを自分でビルドできます。

MCP ツール

ツール	機能
see_screen	現在の画面を画像として返します。パネルに表示されている、人が見ているのとまったく同じフレームです
inspect	コントラスト／タッチターゲット／はみ出し／テーマのチェックを実行し、測定結果をテキストで返します
goto	すべてのセッションを URL に移動します（localhost も含みます）
tap / type_text / scroll	ページを操作します。人はその様子をリアルタイムで確認できます
set_device	デバイスプロファイル（iphone-15、iphone-se、pixel、galaxy、ipad、desktop、laptop）またはライト／ダークテーマを切り替えます
status	開いている URL、セッション、最近のコンソール／ネットワークエラーを表示します。バグの調査を始めるときは、まずここを確認してください
marks	人がパネルにピン留めしたメモを読み取ります（📌 メモと、その時点のスクリーンショット）

UISIGHT_LANG=tr を指定すると、トルコ語のツール名（ekrani_gor、denetle など）が利用できます。

パネル（人が使う側）

npx -y -p uisight uisight-panel <url> を実行すると、localhost:5055 にブラウザページが開きます。

• モバイルとデスクトップを並べて表示し、どちらもリアルタイムで更新されます。URL も同期されます
• クリック＝そのデバイスでタップ · ホイール＝スクロール · クリック後に入力
• ペインごとにデバイスを切り替えられ、ライト／ダークの切り替えは共通です
• Inspect ボタンを押すと、すべての画面で測定エンジンが実行されます
• 📌 Pin：メモを入力してピン留めすると、AI が marks 経由でメモとスクリーンショットを読み取ります。「見えているものを説明します」というやり取りは不要になります

VS Code／Antigravity 内では、Simple Browser: Show → http://localhost:5055 から利用できます。

チェック内容

読み取れるか

• 見えないテキスト（コントラスト < 1.6:1）および WCAG AA のコントラスト基準違反。アルファ合成された背景、グラデーションテキスト、oklab()／oklch() の色にも対応しています
• 12px 未満のテキスト、alt のない画像
• コンテナ自体によって途中で切れているテキスト（line-clamp などは「クリッピング」ではなく、意図的な判断です）

操作できるか

• 44px 未満のタッチターゲット（モバイルプロファイルのみ。WCAG に従い、インラインのテキストリンクは幅による判定の対象外です）
• 別の要素に覆われたコントロール。ジオメトリではなく elementFromPoint で確認し、端から端までサンプリングするため、横幅の広いボタンの片端をフローティングボタンが覆っている場合も検出します
• 固定バーの下、または画面上のキーボードの下に隠れたコントロール（keyboard-audit は実際のスマートフォンと同じ方法でキーボードを開き、再測定します）
• スクロールしてもたどり着けない、コンテナによってクリップされたコンテンツ。同じボックスでも overflow-x: auto があれば、コンテンツに到達できるため問題ありません
• 行が折り返されず、テキストがコントロールの背後に入り込む状態
• はみ出している要素を含む横方向のオーバーフロー
• ノッチやホームインジケーターの下に配置された固定バー。ページが全画面表示を要求（viewport-fit=cover）したにもかかわらず、返されたインセットを使っていない場合に限ります。このフラグがない場合、iOS はページの周囲に余白を付けるため、隠れるものはありません

妥当か

• どれも同じ見た目で、どれが主要な操作なのか分からないアクションの列。タブ、メニュー、フィルターチップでは警告せず、誤クリックが損失につながる操作（保存、削除、送信、支払い）の場合にのみ検出します
• ダークモードで残る明るい部分
• 1 つの画面に混在する 2 つの言語、および米国以外のロケールで使われている米国式の日付形式
• スピナーが回転中なのに「結果は 0 件」と表示される状態。中間状態を真実として提示しています
• 「エラーが発生しました。」のように内容が分からず、そこから抜け出す方法もないエラーメッセージ
• 削除、取り除く、アカウント削除など、取り消せない操作があるにもかかわらず、確認手順がまったくないページ。ボタンはクリックされません。クリックすると本当に削除されるためです
• 説明のつく行動をユーザーが何もしていないのに、読み込み中に求められる権限
• テーマのずれ：ライトモードとダークモードで同一に見える要素は、色がハードコードされている可能性があります
• デバイスごとのコンソール／JS エラーと、失敗したネットワークリクエスト

すべてのチェックには、検出テストと並んで誤検知テストがあります。これは単なる配慮ではありません。ボトムナビゲーションバーのたびに誤警告を出すツールは無視されるようになり、本当に重要な検出結果まで読まれなくなります。

そして、正直なところ自動チェックには限界があります。デザイン上のミスは検出できません。ヘッダーが衝突していても、測定上は問題なしとなることがあります。だからこそ see_screen があり、レポートには「PNG を目視で確認してください」と記載されています。

表示を見るだけでは確認できない動作（オフライン、戻る）

レンダリングされたページを見ても測定できない項目が2つあります。実際にネットワークを切断し、実際に戻るボタンを押す必要があります。どちらもパネルのアクションとして実行されるため、監査と MCP ツールで共通して利用できます。

# through the panel
curl -X POST localhost:5055/action -H 'x-uisight-token: ...' \
     -d '{"type":"offline-audit","session":"mobile"}'

オフラインでは接続を切断してページを再読み込みし、ユーザーが何を見ているかを確認します。説明、再試行、いつまでも終わらないスピナー、あるいは何も表示されない状態のいずれかです。正確な判定を保つためのポイントは、サービスワーカーです。サービスワーカーのないページはオフラインでは応答できないため、その結果は expected としてマークされ、監査では除外されます。ワーカーを登録しているのにブラウザーのエラーページが表示される場合は、実際の問題として報告されます。失敗してもセッションがオフラインのままにならないよう、接続は finally で復元されます。

戻るでは、内部リンクをたどってから戻るボタンを押し、アドレスが開始時の状態に戻ったことと、画面が空でないことを確認します。戻ったときに空白ページが表示されると、「戻る」が「アプリを離れる」になってしまいます。

ログイン後（uisight-audit）

公開ページは、アプリの中で誰も使わない部分です。実際に手作業で見つけて報告された4件のバグのうち、3件はログイン後に発生し、1件は特定のロールでのみ発生しました。

uisight-audit                        # every configured role, 10 pages each
uisight-audit --roles guide,agency   # only these
uisight-audit --pages 20 --port 5062

アカウントは ~/.uisight/accounts.json に保存されます。サインインでは3つの方法を試します。固定の code（ストア審査用アカウントのパターン）、アプリ独自の OTP レスポンスから直接読み取る devCode（開発／デモモード。保存されたシークレットは不要）、またはパスワード欄です。成功とはログインページから移動することであり、HTTP 200 ではありません。そのため、誤ったコードが成功として報告されることはありません。アプリが拒否した場合は、デモモードだと推測するのではなく、アプリ独自のメッセージがそのまま返されます。「HTTP 429 · コードのリクエストが多すぎます」のように表示されます。

ロールは、対応するビュー切り替えエンドポイントがアプリにある場合、アプリ独自のエンドポイントを通じて切り替えます。これにより、管理者アカウント1つであらゆるロールを監査できます。いずれのロールでもまだ測定されていないページが優先されるため、2つ目のロールでは同じ公開ページを再測定するのではなく、未調査の箇所に予算を使います。

エディター拡張機能

extension/ は VS Code / Antigravity 拡張機能です。サイドバーにライブパネルがあり、デバイス、テーマ、アドレス、検査、「画面を AI に送信」するコマンドを利用できます。

Antigravity、Cursor、VSCodium の拡張機能パネルで uisight を検索してください — open-vsx.org/extension/sololabstr/uisight。必要なのは Node.js だけです。拡張機能は公開済みパッケージを npx uisight@latest 経由で実行するため、エンジンは自動で更新され、一度インストールすれば新しいチェックが追加され続けます。

このリポジトリからビルドする場合：

cd extension && npx @vscode/vsce package
code --install-extension uisight-*.vsix

拡張機能は HTTP 経由でパネルと通信しますが、そのやり取りは型チェックされません。そのため test/extension.test.mjs では両側を照合します。送信するすべてのアクションがサーバーで処理されること、すべてのルートが存在すること、表示するすべての結果フィールドがエンジンによって生成されること、マニフェスト内のすべてのコマンドが登録されていることを確認します。このテストがあるのは、かつて両者に食い違いが生じ、ページに問題がたくさんあったのに Inspect が「問題なし」と報告するという、気づけない失敗が起きたためです。

コスト

このツールを実行してプランを使い切った人がいましたが、どこに使われたのかを確認する方法がありませんでした。 そこで、推定値ではなく実測値を示します。実際のサイトで Pixel 7 を使ってセッションを行い、Claude の料金計算と同じ方法（幅 x 高さ / 750）で画像を換算しています。

	トークン数
uisight <url> を実行してから REPORT.md を読む	~800、一度だけ
uisight-audit を実行してから REPORT.md を読む	~150-800、一度だけ
MCP inspect	1 回あたり ~570
MCP see_screen	1 回あたり ~260（デフォルトの 0.75 スケール）
MCP see_screen に full を指定	1 回あたり ~2,000（上限あり。上限なしの場合は ~5,800）
ツール定義	リクエストごとに ~1,065

この表から、次の 3 つのことが分かります。

CLI が最も安価な方法で、その差は歴然です。 uisight と uisight-audit はファイルを書き出し、モデルはそれを一度読むだけです。MCP ツールを使って画面ごとに操作すると、各ステップで会話全体を再送するため、30 回の往復はレポート 1 件よりはるかにコストがかかります。MCP ツールはページ上で操作する必要があるとき――何かをタップする、デバイスを変更する、特定の状態を確認するなど――に使い、アプリ全体を調べるためには使わないでください。

画像の料金は一度だけではありません。 画像は会話に残り、それ以降のターンごとに再送されます。だからこそ inspect があり、その出力はテキストです。同じページでも、測定結果では ~570 トークン、画像を見た場合は ~460 トークンかかります。また測定結果には 4.38:1 (threshold 4.5) と表示されますが、画像だけではモデルは推測するしかありません。全画面キャプチャには現在上限（UISIGHT_MAX_IMAGE_TOKENS、デフォルトは 2000）があり、応答にはコストと省略された内容が表示されるので、気付かないうちに使いすぎることはありません。

スクリーンショットは原寸である必要はありません。 実際のページで測定したところ、同じモバイル画面でも、スケール 1.0 では 461 トークン、0.75 では 259 トークン、0.5 では 115 トークンで、コストはスケールの 2 乗 に比例して下がります。0.75 では細かい文字も含めて違いが分からないほどです。0.5 でもレイアウトと意味のあるラベルはすべて読めますが、最小サイズの法的な文言だけがぼやけます。そのためデフォルトは 0.75 で、see_screen には scale パラメーターがあります。細かい文字を確認するときは 1、手早く確認するときは 0.5 を指定してください。

ツール定義は、すべてのリクエストにかかる固定コストです。 9 個のツールは、呼び出すかどうかに関係なく ~1,065 トークンかかります。

// only what a measuring session needs: goto, inspect, see_screen, status
{ "env": { "UISIGHT_TOOLS": "core" } }        // ~419 tokens
{ "env": { "UISIGHT_TOOLS": "goto,inspect" } } // ~211 tokens

うまく動作しませんでしたか？

些細な内容でも、Issue を作成してください。まだ若いプロジェクトなので、「X で実行したら Y になった」と誰かが伝えてくれることが、改善への最短の道です。パネルのスクリーンショットや REPORT.md の内容があると、とても役立ちます。

既知の注意点を以下に示します。バグと制限事項を見分ける際に参考にしてください。

• デザイン上の問題はエンジンから見えません。 ヘッダーがロゴに重なっていても、測定上は問題ありません。see_screen を使って目で確認してください。
• 写真の背景は対象外です。 背景画像の上にある要素のコントラストは CSS から計算できないため、推測せずに対象外とします。
• テーマの変化は構造要素をサンプリングします（body、header、nav、main、footer、button、a、input、cards/panels/modals/menus）。本文だけに現れる変化は、ライト↔ダークの比較には表示されません。
• iPhone プロファイルは WebKit であり、iOS Simulator ではありません。 Safari に非常に近いものの、デバイスと完全に同じではありません。
• 内部実装はまだトルコ語です。 公開される部分（ツール、CLI フラグ、レポート）は英語ですが、src/ 内の変数名はまだ英語ではありません。どちらの言語でも PR を歓迎します。

開発

npm install
npx playwright install chromium
npm test          # runs the inspection engine against fixture pages in a real browser

テストはリグレッションを防ぐためのものです。test/inspect.test.mjs の各ケースは、誤った「問題なし」判定、誤警報、または特定の色形式を黙ってスキップする測定など、エンジンが少なくとも一度は誤った結果を出した事例です。

測定エンジンに手を加える前に、CONTRIBUTING.md を確認してください。色の計算をモジュールに切り出せない理由と、適切なバグ報告の書き方が説明されています。

注意事項と制限事項

• iPhone プロファイルは実際の WebKit（Safari のエンジン）上で実行されます。iOS に近い環境ですが、iOS シミュレーターではありません。
• ブラウザーは初回実行時に Playwright によって一度ダウンロードされます（事前にダウンロードしておきたい場合は、npx playwright install chromium webkit を実行してください）。
• すべてローカルで実行されます。クラウドもアカウントも不要で、画面がマシンの外に出ることはありません。
• v0.2 以降、コードベース全体で英語を使用しています。識別子、コメント、パネルの HTTP フィールド名が対象です。パネル API を直接呼び出していた場合は、CHANGELOG.md に名称変更の一覧があります。

ライセンス

MIT © SoloLabs