entro314-labs/ui-declutter

UI デクラッター (UI Declutter)

インターフェースを編集して、表示されるすべての単語や装飾が、それを使う人のために存在するようにします。生成された画面は、自分自身を説明しようとしがちです。タイトルの上のラベル、その下の説明文、ボタンの横のヒント。それぞれは無害に見えますが、一緒になってユーザーが求めている核心を埋もれさせてしまいます。

目標は、ユーザーに役立つ画面を作ることです。AIが生成したように見えない画面を作ることではありません。ルールとユーザーのニーズが矛盾する場合、ユーザーのニーズが優先されます。その場合は、報告書にその旨を明記してください。

対象: ユーザーが指定したファイル、フォルダ、またはコンポーネント。ユーザーが何も指定しない場合は、この会話の中で変更されたインターフェースファイルを対象とします。該当するファイルがない場合は、ユーザーに確認してください。

範囲: コピー、アクション、状態、創作コンテンツ、装飾、チャート。視覚的な表面（ルール X1 ～ X4）は、ユーザーが明示的に要求した場合、または --surface フラグを使用した場合にのみ含まれます。

ステップ1: この画面にいるのは誰か

1文字も読む前に、次の1行を書いてください。

誰: ミッション中にEscキーを押したプレイヤー。何をしている: ゲームに戻るか、設定を変更するか、再開するかを決めている。

この行が、すべてを判断する基準です。これがないと、以下のルールはパターンマッチとして適用され、不要なものと一緒にパスワード要件まで削除してしまう可能性があります。価格ページを初めて訪れる人には、管理テーブルの日常的なユーザーよりも多くの言葉が必要です。ゲームは、税務フォームにはない雰囲気のあるテキストを許容できます。

コードからユーザーが誰かを特定できない場合は、製品から推測してその推測を明記してください。2つの妥当な解釈が異なる編集結果につながる場合にのみ、ユーザーに確認してください。

ステップ2: テスト

表示されているテキストと装飾要素のそれぞれについて、次の質問を自問してください。

これがなかったら、そのユーザーは迷ったり、間違えたり、次に何が起こるかに驚いたりするだろうか？

• いいえ → 削除します。
• いいえ、しかし他のどこかで誰かが必要としている → 移動します。開発者向けの情報はコードコメントに。一部のユーザーが探す情報はツールチップやドキュメントに。支援技術だけが必要とする名前は aria-label に移動します。
• はい、ただし表現が悪い → 書き直します。コード、コンテンツ、会話の中から見つけられる事実のみを使用します。
• はい → そのまま保持します。

以下のルールは、生成された画面がこのテストに失敗する一般的なパターンです。これらは、問題のある箇所を素早く見つけるのに役立ちます。ルールで名前が付けられていない方法で画面がテストに失敗した場合でも、テストは適用されます。ルールがフラグを立てたものでも、テストに合格するものは保持します。

完全な文章に値するテキスト

これらはほとんどの場合テストに合格します。ラベルに短縮したり、削除したりしないでください。

• ユーザーが満たさなければならない制約: パスワードルール、受け入れ可能なファイルの種類とサイズ、日付と数値の形式、文字数の制限。
• 結果: 破壊的または不可逆的なアクションが何を削除するか、支払いが何をいつ請求するか、権限が何を許可するか、共有されると誰が見るか。
• エラー: 何が問題で、次に何をすべきか。
• 空の状態: ここに何が属するか、最初の項目を追加する方法。
• 同意、法律、規制に関するテキスト。文言は決して編集しないでください。間違っているように見える場合は報告してください。
• ユーザーがめったに行わず、元に戻せないタスクの手順。

ルール

各ルールには安定したIDが割り当てられています。報告書でIDを引用してください。

コピー

• C1. 眉毛ラベル (Eyebrow labels). 見出しの上にある小さな大文字や文字間隔を広げたテキスト（「PAUSED」の上の「FEATURES」「HOW IT WORKS」「OPERATION ON HOLD」など）。見出しがすでにセクションを命名しているため、眉毛ラベルは削除します。眉毛ラベルの方が優れている場合（ゲームの雰囲気テキスト、製品独自の用語など）は、それを見出しに昇格させ、汎用的な方の見出しを削除します。2つを同時に使用しないでください。
• C2. 装飾的な番号 (Decorative numbering). 「01 02 03」「01 // Features」「§」「//」などの接頭辞。順序が実際に存在し、ユーザーがそれに従う場合（チェックアウトの手順やインストールガイドなど）を除き、削除します。
• C3. サブタイトル反射 (Subtitle reflex). すべての見出しの下にある文章、すべてのメニュー項目の下にある説明（「設定: 設定を更新してください」など）。見出しに含まれていない事実を述べている場合にのみ、1つだけ残します。
• C4. ナレーション (Narration). 要素が視覚的に何であるか、何をするかを説明するヘルパーテキストやキャプション（「下のボタンをクリックして開始してください」「このカードは最近のアクティビティを表示します」など）。削除します。
• C5. 実装に関する記述の漏洩 (Leaked implementation notes). 画面が内部的にどのように動作するかについてのテキスト、またはプロンプトからの要件がそのままコピーとしてレンダリングされたもの（「再開するとマウスをキャプチャします」「(リアルタイムで更新されます)」「(AI搭載)」「データは5分間キャッシュされます」など）。ユーザーはこれに基づいて行動しません。コードコメントに移動するか、削除します。
• C6. ステータス文字列 (Status strings). 「·」や「|」で連結された事実（「12 アイテム · 2分前に更新 · 同期済み · v2.1」など）。ユーザーが行動するための事実だけを残します。他のものは必要な場所に移動するか、削除します。
• C7. 重複した手がかり (Duplicate cues). プレースホルダー、アイコン、ボタンテキスト、セクション見出しを繰り返すラベル。1つだけ残します。フォームフィールドの場合は、表示ラベルを残します。プレースホルダーは入力時に消え、アクセシブルな名前にはなりません。
• C8. スローガン (Slogans). 「One. Big. Thing.」「Built different.」「Ship faster. Think less.」物事の名前とその機能を1つの文に書き直します。ソースからその事実が得られる場合に限ります。そうでない場合は、責任者にフラグを立てます。
• C9. 汎用的なセクション見出し (Generic section headings). 「Why choose us」「Everything you need」「Built for teams like yours」。どんな製品のページにも置けるような見出しは、この製品について何も語っていません。セクションの内容に合わせて名前を変更するか、コンテンツがなくても成り立つ場合は見出しを削除します。
• C10. ヒント過多 (Hint overload). すでにテキストラベルがあるコントロールのツールチップ、すべてのアクションに対するキーボードショートカットチップ、「Tip:」「Pro tip」の呼び出し、普通の画面でのコーチマーク。コントロールが他の方法では曖昧な場合（アイコンのみのボタン）や、ショートカットが主な使用方法である場合にのみヒントを残します。

アクション

• A1. 曖昧なアクションラベル (Vague action labels). 「Get started」「Learn more」「Submit」「Continue」「OK」「Click here」。ボタンは、押されたときに何が起こるかを示します。動詞、および動詞だけでは曖昧な場合は目的語を含めます（「Create account」「Export CSV」「Send invite」）。「Continue」と「Next」は、ステップフロー内では問題ありません。
• A2. 1つのアクションに複数の名前 (One action, several names). 同じ操作に対して、ある画面では「Delete」、次の画面では「Remove」、メニューでは「Trash」、または「Sign in」の横に「Log in」。プロジェクトで最もよく使われている用語を選び、ターゲット内のすべてでそれを使用します。2つの用語が異なる操作を指す場合（リストから削除するのと完全に削除する）は、両方を残します。
• A3. 確認ダイアログ (Confirmation dialogs). 「OK」と「Cancel」が付いた「Are you sure?」。タイトルはアクションとその対象を指定し（「Delete 3 projects?」）、本文は結果がある場合にそれを述べ（「This also removes their 14 tasks. You can't undo this.」）、確認ボタンは動詞を繰り返します（「Delete projects」）。元に戻すのが簡単なアクションの確認は、それ自体が無駄です。責任者にフラグを立ててください。

状態

ローディング、成功、空、エラーテキストは、誰も画面をレビューするときにこれらの状態を見ないため、埋め草が集まりやすい場所です。これらを編集する前に references/states.md を読んでください。そこには、各状態が何を含むべきかが、削除すべきもの以上に詳しく書かれています。

• S1. ローディングの埋め草 (Loading filler). 「Hang tight!」「Crunching the numbers…」「Just a moment while we get things ready」。待ち時間が読むのに十分長い場合のみ、ロード中のものを指定します。そうでなければ、スピナーまたはスケルトンのみ。
• S2. 成功の埋め草 (Success filler). 「Successfully saved!」「Your changes have been saved successfully.」結果を最小限の言葉で述べてください（「Saved」「Invite sent to [email protected]」）。画面がすでに結果を表示している場合は、トーストは不要です。
• S3. 空の状態の埋め草 (Empty-state filler). 「Nothing here yet!」「Looks like you haven't created any projects yet. Get started by creating your first project!」ここに何が属するかを述べ、それを追加する1つのアクションを提示してください。
• S4. 曖昧またはかわいらしいエラー (Vague or cute errors). 「Oops! Something went wrong」「An error occurred. Please try again later.」何が失敗したか、ユーザーに何ができるかを述べてください。コードが失敗の原因を特定できない場合は、そのことを率直に述べ、再試行を促してください。

創作コンテンツ

• F1. 架空の証明 (Invented proof). ユーザー数、稼働時間の数値、星評価、名前と役職が付いた推薦文、「Trusted by」のロゴ行、「As seen in」。プロジェクトに出典がない場合、それは出荷されたページにおける虚偽の主張です。より小さな虚偽の主張に書き換えたりせず、削除して報告書に記載し、責任者が本物を提供できるようにします。
• F2. 出荷された画面のプレースホルダーデータ (Placeholder data in shipped screens). 「John Doe」「Acme Corp」、ダミーテキスト、example.com アドレス、ストックアバターサービス。フィクスチャ、テスト、ストーリーでは問題ありませんが、出荷された画面ではタスクとして報告してください。実際のデータを提供することはできません。

装飾

• D1. 状態のないバッジ (Badges without state). 雰囲気のために追加された「NEW」「LIVE」「AI」「Beta」「Pro」「Popular」。アプリが追跡している何かを反映している場合のみ、バッジを残します。
• D2. ステータスドット (Status dots). テキストの横にある点滅または色付きのドット。実際のステータスにバインドされている場合のみ残し、アクセシブルな名前を付けます。
• D3. 装飾的な絵文字とアイコン (Decorative emoji and icons). 見出し、ボタン、ラベル、リスト項目内。削除します。アイコンは、それがコントロールそのものである場合（aria-label 付きのアイコンボタン）、またはテキストが伝えていない意味を伝える場合に残します。

チャートとダッシュボード

• V1. チャートタイプを指定するタイトル (Titles that name the chart type). 「Bar chart of monthly revenue」は「Monthly revenue」にします。目の前のデータが示している場合にのみ、発見事項を記述してください（「Revenue doubled since March」）。
• V2. 読み方の指示 (Reading instructions). 「Each bar represents one month」「Hover for details」。削除します。
• V3. 同じことを2回言う (Saying it twice). 1つの数量に対して1つのエンコーディング。矢印、パーセンテージ、「up」という単語、そしてそれらすべてを言い換えた文章が付いたKPIは、数値と1つの比較だけを残します。
• V4. データと競合する枠組み (Scaffolding that competes with the data). プロットフレーム、暗くまたは密なグリッド線、太い軸の境界線、3D、マークの影やグロー。削除するか、残す必要があるものは極細線にします。同じチャートタイプ、同じデータ、同じ系列色を維持します。
• V5. 凡例より直接ラベル (Legend where a direct label works). 系列が4つ以下で、ラベルを配置するスペースがある場合、各系列を線の端または棒の横に直接名前を付け、凡例を削除します。

表面（要求された場合のみ）

まず references/surface.md を読んでください。このファイルは、デザイン意図を確認することから始まり、これらのルールがまったく適用されるかどうかを決定します。意図的なディスプレイタイポグラフィを持つゲーム、マーケティングページ、エディトリアルレイアウトは、正常化すべき欠陥ではありません。

• X1. グラデーションとグロー (Gradients and glows). 表面やボタンの色相間グラデーション、グラデーションテキスト、色付きのグロー、ぼやけた色の塊。
• X2. スケールから外れたスペーシング (Off-scale spacing). 兄弟要素がスケールを使用している中での mt-[13px] や gap: 7px のような例外的な値。
• X3. ランニングUIでの太いウェイト (Heavy weights in running UI). 本文テキスト、ラベル、テーブルセル、コントロールでの800や900の太さ。表示見出しは対象外です。
• X4. 装飾的なモーション (Decorative motion). transition-all、ホバー時に拡大するカード、何も説明しないバウンスやループ。

保持または書き換えるテキストのスタイル（大文字小文字、句読点、埋め草の単語、一貫性）に関する詳細は、references/writing.md を読んでください。編集の前後の具体例（テキストを保持することが正しい編集であるケースを含む）については、どの程度削除すべきか迷ったときに references/examples.md を読んでください。

ガードレール

• 決して事実を追加しないでください。 書き換えは、コード、コンテンツファイル、データ、または会話の中にあるものだけを使用します。「Edits sync within seconds」は製品の主張であり、それが真実かどうかはあなたにはわかりません。正直な書き換えにあなたが持っていない事実が必要な場合は、その行を削除するか、所有者へのタスクとしてリストアップしてください。これは最も簡単に破られるルールです。なぜなら、創作された具体的な記述は、それが置き換える曖昧な行よりも良く聞こえるからです。
• 表示テキストと装飾要素のみを変更してください。 ロジック、データ、色、タイポグラフィ、レイアウト構造はそのままにします。例外は、チャートの骨格に関するV4と、要求された場合の表面ルールです。
• アクセシブルな名前を保持してください。 アイコンボタンの aria-label、alt、title、スクリーンリーダーのみのテキストは決して削除しないでください。削除した表示テキストが唯一のアクセシブルな名前だった場合は、それを aria-label に移動してください。
• テキストはソースで編集してください。 i18nファイル、プロパティ、フィクスチャ、CMSからの文字列は、そこで編集するか、報告します。コンポーネント内にハードコードされた置換を追加しないでください。1つのロケールファイルで文字列を変更した場合は、他のロケールをタスクとしてリストアップしてください。依頼されない限り、自分で翻訳しないでください。
• 削除した後はクリーンアップしてください。 空になったラッパーと、削除された要素のために存在していたマージンやギャップを削除してください。
• きれいな画面はそのままにしてください。 テストに失敗するものが何もなければ、何も変更しないでください。
• プロジェクトに従ってください。 プロジェクトに独自のボイスガイド、用語集、トークン、デザインシステムがある場合は、このスキルのデフォルトではなく、それらに向けて修正してください。

手順

以下の手順を追跡してください。

- [ ] 1. 誰と何をしているか: 1行
- [ ] 2. カウント: python3 scripts/count_tells.py <ターゲット>      (--surface が必要な場合は追加)
- [ ] 3. 確認: 可能であれば画面のスクリーンショットを撮る
- [ ] 4. すべての状態のすべての表示文字列と装飾を読む; テストを適用; 失敗にルールIDをタグ付け
- [ ] 5. 判定: 多い、少ない、なし
- [ ] 6. 編集
- [ ] 7. 再度カウント、再度確認
- [ ] 8. 報告

scripts/ はこのスキルのフォルダ内にあります。スクリプトはフルパスで実行してください。

カウント. count_tells.py はソースに対して正規表現パスを実行します。候補を見つけ、コードシグネチャを持つパターンの前後の数を出力します。C3、C4、C5、C7、A2、V3、または意味に依存するものは検出できず、正当な使用法にもフラグを立てます。その出力は、確認すべき場所のリストとして扱ってください。残っているものが意図的に保持されている場合、カウントがゼロにならなくても問題ありません。

確認. ソースはユーザーが実際に見るものを隠します。どの文字列が一緒に表示されるか、データから来るものは何か、削除がレイアウトに与える影響などです。ブラウザやスクリーンショットツールがある場合は、編集前後の画面をキャプチャしてください。どちらもない場合は、python3 scripts/screenshot.py <urlまたはhtmlファイル> <出力.png> で、Playwrightがインストールされている場合に実行できます。キャプチャ画像で、孤立したギャップ、階層を失った見出し、移動したコントロールがないか確認してください。画面をレンダリングできない場合は、報告書にその旨を記載してください。

すべての状態を読む。 デフォルトのビューはインターフェースの一部にすぎません。ターゲット内で、ローディング、空、エラー、成功、無効のブランチ、トースト、ダイアログ、バリデーション...を検索してください。

...