設定UIの注釈過多 (2026-08-04)
ユーザー報告:「必要以上に注釈が入りすぎて、扱いづらい(過剰な情報負荷)」。
本番エディタで開いているパネルから測った。
| 指標 | 実測値 |
|---|---|
| 設定のスクロール全長 | 3158px(表示領域 574px = 5.5画面分) |
| 注釈ラベルの合計高さ | 1180px = カード高さの40% |
| 注釈だけで | 2.1画面分 |
| コントロール数 / 注釈数 | 54 / 49(ほぼ1対1) |
| 注釈の平均長 | 71文字 |
均等に多いのではない。 セクション別:
| セクション | コントロール | 注釈 | 注釈文字数 |
|---|---|---|---|
| モデル | 2 | 7 | 799 |
| Unity操作(UapOps) | 7 | 11 | 986 |
| uLoop連携 | 8 | 8 | 354 |
| 会話 | 5 | 5 | 233 |
| (他10セクション計) | 32 | 18 | 1139 |
上位2セクションが、全コントロールの17%で全文章の51%を占める。
L10n フィールド単位では英語で最長387文字(SettingsUapOpsGateEnabledHint)。
2. 根本原因
Section titled “2. 根本原因”長い注釈の中身を読むと、設計判断の説明がそのままUIに載っている。例:
- 「…あくまでガイダンスであり、タスクごとに Claude が判断して上書きできます。 古い CLI で作成されたセッションではタスク単位のモデル指定が無視される場合があります」(223字)
- 「…生成されたPreToolUseフックにより、acceptEditsの権限モード下でも有効です (既存の権限カードチェックに加えて)。推奨: 有効。」(235字)
これは「なぜこの実装なのか」「どんな例外があるか」であって、チェックボックスの隣に置く内容ではない。 一方で短いもの(「次回の再接続時に反映されます。」15字、「ポート53760で実行中」12字)は状態表示で、 これは邪魔になっていない。削る対象は散文であって、注釈という仕組みそのものではない。
3. UITK ツールチップの実測(方式を決める前に)
Section titled “3. UITK ツールチップの実測(方式を決める前に)”このプロジェクトは UITK の挙動を推測して2回外している(Clickable、BaseField.contentContainer)ので、
方式全体を賭ける前に測った。
| 検証 | 結果 |
|---|---|
未アタッチの Toggle に tooltip を設定して TooltipEvent を投げる | ''(空) |
| 実パネル上の Toggle で同じことをする | 'PROBE TOOLTIP' + rect を返す |
| 親に設定し、ツールチップを持たない子で投げる | 'PARENT ONLY' — 親のものが届く |
| 親子両方に設定 | 子が勝つ |
| Label に設定 | 効く |
重要な帰結が2つ。
(a) 親に1つ付ければラベルと入力欄の両方をカバーできる → 行コンテナが正しい粒度。
(b) 未アタッチ要素ではツールチップが解決されない → 回帰テストは TooltipEvent を投げてはならず、
element.tooltip プロパティを直接検査すること。ここを間違えると、
「実装と同じ前提で書かれたテスト」がまた1つ増える。
4. 採用案と却下案
Section titled “4. 採用案と却下案”- 採用: インラインは1行、長文はツールチップへ。 縦の占有はゼロで情報は失われない。 Unity 標準の設定画面と同じ作法。
- 却下: カード末尾の「詳しく」折りたたみ。行を1つ消費し、開けば結局同じ長さが出る。
- 却下: 長文を単に削除。パネル内だけで判断したい人に情報が届かなくなる。
- 例外: 安全に関わる3つ(スクリプト検証ゲート / 自動承認レベル / コンパイル後の自動継続)は 画面に残す。これらは「有効にすると何が起きるか」の警告であり、 ホバーしないと読めない警告は警告として機能しない。短く書き直したうえで警告スタイルを与える。
5. 回帰ガード
Section titled “5. 回帰ガード”L10nTests は既にリフレクションで全フィールドを走査しているので、そこに上限を足す。
Settings*Hint / Settings*Help は英日どちらのカタログでも上限以内であること。
警告3件は明示的な許可リストで除外し、その3件にも別の(緩い)上限を課す。
これがないと、次に機能を足す人が同じ場所に同じ散文を書いて元に戻る — 実際、今回の 387 文字はそうやって育っている。
6. 実装後の実測(同じ計測を再実行)
Section titled “6. 実装後の実測(同じ計測を再実行)”| 指標 | 変更前 | 変更後 |
|---|---|---|
| スクロール全長 | 3158px(5.5画面) | 2686px(4.7画面) |
| 注釈ラベルの高さ | 1180px(2.1画面) | 728px(1.3画面) |
| カード高さに占める割合 | 40% | 29% |
| 表示中の注釈ラベル数 | 35 | 30 |
| 英語の最長注釈 | 402文字 | 146文字(警告)/ 他は最大109 |
| 日本語の最長注釈 | 235文字 | 70文字 |
| ツールチップを持つ要素 | 0 | 24(配線した24フィールドと一致) |
長文は消していない。28個の Settings*Tooltip に英日とも入っている。
7. 実装中に出た3つの発見
Section titled “7. 実装中に出た3つの発見”(a) コンテナ共有で他人のツールチップが出る。 tooltip は単なるプロパティなので、
複数フィールドが1つの section を共有していると最後に設定したものしか残らず、
他のフィールドをホバーすると無関係な説明が出る。Unity操作セクションだけで5件、
会話セクションで4件が該当していた。各フィールドをスタイル無しのラッパーで包んで分離した
(AddHintScope)。ラッパーにはコントロール自体も入れる必要がある —
インライン文が空になったフィールドでは、ラベルだけ包んでも高さゼロで掴めない。
(b) 空文字列の L10n フィールドは既存ガードが正しく弾いた。 インライン表示を完全に
やめた6件を空文字列にしたところ、AllStringFields_AreNonEmpty_InBothCatalogs が落ちた。
テストを緩めるのではなくフィールドごと削除し、呼び出し側で scope.tooltip を直接設定した。
表示しないものにカタログのエントリを残す理由がない。
(c) 死んだ文字列が2件見つかった。 SettingsUapOpsAutoApproveReadOnlyHint と
同 Label は呼び出し元ゼロ(自動承認レベルに置き換わった際の残骸)。
気づかず片方にツールチップまで作りかけたので、両方削除した。
(d) 「いつ反映されるか」は13行・256px を占めていた。 同じ意味の文が13通りの書き方で
各フィールドに書かれていたが、パネルには既に SettingsChangeDetector.RequiresReconnect が
駆動する保留インジケータがある。これは実際に変更があったときだけ出るので、
静的な per-field の文より情報として正確である。全部ツールチップへ移した。