UIポリッシュは何をしますか？

画面がうまく整理されていても、まだ完成した感じがしないことがあります。2列のフィールドが17pxずれている、390pxの電話画面に88pxのボックスがある、各フィールドに単位の単語が付いている、親指でタップできないリンクがあるなど。人はこうした問題を即座に感じ取りますが、モデルがスクリーンショットをレビューしてもめったに見えません。このスキルは、まず測定し、次に判断し、測定値が合格を示したときにのみ欠陥を修正したと呼びます。

入力

不足しているものだけを尋ねてください。

ターゲット. URL、またはHTMLファイル、またはリポジトリ内のコンポーネントとそれがレンダリングされるURL。レンダリング可能な方法が必要です。何もレンダリングできない場合はその旨を伝え、ルーブリックのみにフォールバックし、測定対象のすべてのチェックを「未測定」としてマークします。
スコープ (オプション). ポリッシュするページの部分を示すCSSセレクター（例: フォームまたは main）。デフォルト: main、次いで body。
リファレンス (オプション). ユーザーがより良いと考える画面（URL、ファイル、スクリーンショット）。これも測定し、ルック（見た目）の方向性として使用します。ブランド、コンテンツ、主張をコピーしてはいけません。

ワークフロー

1. 現在の画面を測定する

バンドルされたスクリプトを実行します（Node.jsとPlaywright（Chromium）が必要。プロジェクトにない場合は npm i -D playwright && npx playwright install chromium でインストール）。

node <skill-dir>/scripts/measure.cjs <file-or-url> --out ui-polish/before [--scope "<selector>"] [--primary "<selector>"] [--hide "<selector>,…"] [--profile form|content]

電話サイズ（390×844）とデスクトップサイズ（1366×900）でレンダリングし（エラーの発見がある間は終了コード1、使用方法エラーは2、実行自体の失敗は3）、measure.json を --out に書き込みます（カレントディレクトリからの相対パス）。ビューポートごとに2つのスクリーンショットを含みます: <viewport>.png（最初の画面）、<viewport>-scope.png（スコープ全体、スクロールして見える部分も含む）。すべての発見事項をセレクターとともに出力します。同じ原因の要素は、カウントと例示セレクターを持つ1つの発見事項として扱われ、電話とデスクトップで同じ発見事項は1回だけ出力され、両方のビューポートが viewports に含まれます（ビューポートでマージされた発見事項をフィルタリングする際は viewport ではなく viewports を使用）。
スクリプトはデフォルトでオフになっているため、静的なレイアウトが測定されます。JavaScriptでのみレンダリングされるページには --js を追加します。--offline はターゲットページ以外のすべてのネットワークリクエストをブロックします（hermetic）。--assets-only はリモートフォント、スタイルシート、画像の読み込みも許可し、フォントが必要なローカルコピーに使用され、それらのホストに接続します。
--hide は、クッキーバナーやチャットランチャーなどのオーバーレイを測定とキャプチャの前に display: none に設定し、スクリーンショットを隠したり発見事項を追加したりしないようにします。--hide セレクターが何にもマッチしない場合は警告を出力します。
--profile content は記事やその他の長文ページ用です。フォームステップ用に作られたチェック（type-scale、action-distance、action-below-fold、dead-space）をスキップします。デフォルトは form です。
1回の実行で複数のターゲットを指定すると（measure.cjs <page1> <page2> … --out dir）、それぞれが dir/<slug>/ に出力され、dir/summary.json が複数ページで繰り返される発見事項を1行にまとめてページをリストします。共有コンポーネントは1回修正します。--compare before/<slug>/measure.json after/<slug>/measure.json でページごとに比較します。
チェック内容、しきい値、および各チェックの通常の修正方法は reference/checks.md にあります。エラーは実行を失敗させます。警告は修正または理由の記載が必要です。
理由は毎回ではなく一度だけ述べてください。カレントディレクトリの ui-polish.config.json（または --config <file>）は許可された決定をリストします。例: { "ignore": [{ "check": "text-size", "selector": ".eyebrow", "reason": "ブランドのキッカーレベル" }] }。マッチした発見事項は理由とともに accepted に移動し、独自のセクションに出力され、終了コードに影響しません。所有者が下した決定のみを記録し、数値を通すために自分で追加しないでください。

リファレンスが指定された場合、同様に ui-polish/reference に測定します。

2. 見てみる

スクリーンショットを開き（-scope.png はスコープ全体を示します）、reference/rubric.md の10項目すべてを確認します。各項目に1行（および項目10の各サブチェックに1行）の判定表を作成します: pass、fail、または n/a、特定された問題、修正方法。画面に表示されているものだけを判断します。測定値はルーブリックの根拠であり、代替ではありません。測定された発見事項がゼロの画面でも、階層、ラベルと単位、グループ化、信頼性で不合格になる可能性があり、これらは通常、人が最初に気づく失敗です。

3. 修正を計画する

すべての測定された発見事項と、不合格だったルーブリックの各項目を、それが触れる要素ごとにグループ化してリストします。各発見事項を個別に修正するのではなく、複数の発見事項を一度に取り除く構造的な修正を優先します（例: 2列グリッドのフィールドの上にラベルを配置すると、配置、等幅、フィールドの塗りつぶし、ラベル配置、アクセシブルな名前が同時に修正される）。画面を使用する人への影響の大きい順に並べます。

4. ソースに修正を適用する

実際のソースを編集します。リポジトリ内のコンポーネントとそのスタイル、またはHTMLファイル。ルール:

仕事とコンテンツを維持する。 同じ質問、同じ入力と単位、同じアクション、同じブランド。チェックを通すために機能を削除しないでください。
何も発明しない。 画面が言葉で述べていない事実（ステップ数、時間、価格、臨床・法律・プライバシーに関する主張）を追加しないでください。コードから計算した値（プログレスバーの aria-valuenow、CSSの幅、ルート名）も述べられていないものと見なし、同様に角括弧で囲みます。デザインにそのようなコピーが必要な場合は、角括弧で囲んだプレースホルダー（質問 [n] / [N]、[約3] 分、[質問する理由: …]）を使用し、所有者が記入するためにリストアップします。
既存のシステムを使用する。 プロジェクトのトークン、コンポーネント、スペーシングスケールを再利用し、適合するものがない場合にのみ新しい値を追加します。
動作を維持する。 すべてのコントロールは以前と同じ動作をしなければなりません（そして、壊れていた場合は動作するようになる）。キーボードフォーカスが見える状態を維持します。

5. 合格するまで再測定する

node <skill-dir>/scripts/measure.cjs <file-or-url> --out ui-polish/after [same options]
node <skill-dir>/scripts/measure.cjs --compare ui-polish/before/measure.json ui-polish/after/measure.json

比較ステップでは、所有者がレビューするための新しいコピーもリストアップし、新しいコピーに [角括弧] で囲まれていない数字が含まれている場合、invented-number で失敗します（例: 「ステップ2 / [5]」: 「2」は元々述べられていなかった）。

エラーがなくなり、残っているすべての警告が修正されるか理由が述べられているかつ、不合格だったすべてのルーブリック項目が修正されるか理由が述べられているまで、ステップ4〜5を繰り返します（最大3ラウンド）。新しいスクリーンショットで各ラウンドごとにルーブリックを再度確認します。エラーがゼロでも完了ではありません。36pxのタップターゲットや末尾のラベルなどの警告こそ、このスキルが仕上げるために存在する詳細です。各ラウンドで新しいスクリーンショットを開いてください。チェックに合格しても画面の見た目が悪化することがあり、それは回帰としてカウントされます。

6. 報告

電話とデスクトップでの修正前後のスクリーンショット。
比較出力: 修正済み、残っているもの（理由付き）、新しいもの、受け入れられたもの（設定の理由付き）。
修正前後のルーブリック判定表。不合格のままのものには理由を記載。
所有者が記入する必要があるすべての角括弧で囲まれたプレースホルダー。
ポリッシュではなくプロダクト判断が必要なもの（それらは design-review または所有者に引き継ぎます）。

注意点

スクリーンショットは幾何学的情報を隠す。 17pxのカラムのずれや、390px画面での88pxフィールドは、人間には明らかでも、縮小されたスクリーンショットでは見えません。幾何学的情報は数値を信頼し、バランスと階層は自分の目で判断してください。
末尾の単位単語がカラムのずれの通常の原因です。 「Feet」と「Stones」では幅が異なるため、それ以降のすべてがずれます。ラベルはフィールドの上に配置してください。
大きなファイルでの小さな編集は効果が小さい。 ソースが大きな生成ファイルの場合、属性ごとにパッチを当てるのではなく、フォームのマークアップとスタイルをブロックとして編集しないと、レイアウトは決して変わりません。
数値が合格した時点で止めるのは典型的な失敗です。 幾何学的情報はポリッシュの半分に過ぎません。残りの半分はルーブリック（実際の見出し、フィールドごとのリンクではなく1つのモードスイッチ、センシティブな質問の理由、方向性）です。
1つのトークン、多数の発見事項。 すべてのページで繰り返される小さなテキストやタップターゲットの発見事項は、通常、1つのデザインシステムトークンまたはコンポーネントに起因します。そこで修正するか、所有者の決定を ui-polish.config.json に記録し、ページごとにトリアージしないでください。
チェックに合格することが目標ではない。 焦点が定まった1つの明確な見出し、グループ化されたフィールド、近くにあるプライマリアクションのある画面が目標です。チェックはそこに到達したことを証明するために使用してください。

Built by aictrl.dev. このスキルはワークフローを教えます。aictrl はそれを運用化します — バックログ、チーム標準、コードベース知識グラフに基づいて。詳細を見る →

UIポリッシュ