polish

必須の事前準備

ユーザーは /polish を使ってこのワークフローを開始します。このスキルが有効になったら、$frontend-design を読み込んでください。デザイン原則、アンチパターン、コンテキスト収集プロトコルが記載されています。先に進む前に、そのプロトコルに従ってください。デザインコンテキストがまだない場合は、必ず最初に $setup を読み込んでください。さらに、品質基準（MVP とフラッグシップ）も確認してください。

---

細部まで入念に最終チェックを行い、良い仕上がりと優れた仕上がりを分ける小さな要素をすべて見つけてください。リリースできる状態と、磨き上げられた状態の違いを見極めます。

ポリッシュでは、既存の階層やシステムをより精密にします。弱い基盤を装飾するために使ってはいけません。

ゼロデータの画面自体にデザイン作業が必要な場合は、empty-state スキルを参照してください。より広範なアクティベーションフロー、アハモーメント、初回利用時の戦略が本質的な課題である場合は、onboard を使ってください。

ポリッシュ前の評価

現状と目標を把握します。

1. 完成度を確認する：

   • 機能的に完成していますか？
   • 維持すべき既知の問題はありますか（TODO として記録してください）？
   • 品質基準は何ですか？（MVP かフラッグシップ機能か）
   • いつリリースしますか？（ポリッシュにどれだけ時間をかけられますか？）

2. ポリッシュする領域を特定する：

   • 視覚的な不整合
   • 余白や配置の問題
   • インタラクション状態の不足
   • コピーの不整合
   • エッジケースとエラー状態
   • 読み込みや遷移の滑らかさ

重要：ポリッシュは最初ではなく、最後の工程です。機能的に完成していないものをポリッシュしてはいけません。

システマティックにポリッシュする

以下の観点を順に確認してください。

グレースケールテスト、アクションの階層、ラベルと値の扱いについては、階層チェックリストを参照してください。 行の長さ、行の高さ、配置、ベースライン、タイトルの抑制については、テキスト階層と読みやすさを参照してください。 アクションの優先順位が適切かどうかを確認する際は、アクションの階層を参照してください。 アラート、ステータス、色付きのセマンティックサーフェスを確認する際は、セマンティックカラーを参照してください。 ポリッシュの問題が局所的な細部なのか、システム全体とのずれなのかを判断する際は、デザインシステムとの整合性を参照してください。 境界線、カード、シャドウ、重なり、背景の変化が煩雑または不整合に感じられる場合は、サーフェスの分離を参照してください。 スクリーンショット、アイコン、メディアが不自然で、読みにくく、収まりが悪い場合は、画像の扱いを参照してください。 標準の UI 要素、アクセント、装飾的な背景をより意図的に仕上げる必要がある場合は、仕上げの細部を参照してください。

視覚的な配置と余白

• ピクセル単位で正確に配置する：すべてをグリッドに揃える
• 余白を一貫させる：すべての間隔にスペーシングスケールを使う（13px のような無作為な間隔を使わない）
• 視覚的に整列させる：視覚的な重みに合わせて調整する（アイコンは視覚的に中央に見えるよう、位置の微調整が必要な場合があります）
• レスポンシブ時の一貫性：すべてのブレークポイントで余白と配置が適切であること
• グリッドに従う：要素をベースライングリッドに揃える
• グループを明確にする：グループ内よりも、グループの周囲に広い余白を設ける
• サーフェスを分離する：境界線、シャドウ、カード、背景の変化は、すべてを一度に使うのではなく、意図的に使う

確認項目：

• グリッドオーバーレイを有効にして、配置を確認する
• ブラウザーインスペクターで余白を確認する
• 複数のビューポートサイズでテストする
• 「何となく」ずれて見える要素を探す

タイポグラフィの調整

• 階層の一貫性：同じ要素には、全体を通して同じサイズとウェイトを使用します
• 行の長さ：本文は45～75文字にします
• 行の高さ：フォントサイズと文脈に応じて適切に設定します
• ウィドウとオーファン：最終行に単語が1つだけ残らないようにします
• ハイフネーション：言語と段組みの幅に応じて適切に設定します
• カーニング：必要に応じて文字間隔を調整します（特に見出し）
• フォントの読み込み：FOUT／FOITが発生しないようにします
• ベースラインの配置：サイズの異なるテキストを同じ行に配置する場合、きれいに揃えます
• リンクの節度：副次的なリンクの色が目立ちすぎて、主要な導線と競合しないようにします
• 数値の配置：比較が重要な場合、数値列は右揃えにします
• タイトルの節度：セクション見出しはコンテンツを引き立て、圧倒しないようにします

色とコントラスト

• コントラスト比：すべてのテキストがWCAGの基準を満たすようにします
• トークン使用の一貫性：色をハードコードせず、すべてデザイントークンを使用します
• テーマの一貫性：すべてのテーマバリエーションで機能するようにします
• 色の意味：同じ色は全体を通して同じ意味を表すようにします
• アクセシブルなフォーカス：十分なコントラストのあるフォーカスインジケーターを表示します
• 色味のあるニュートラルカラー：純粋なグレーや黒は使わず、わずかに色味を加えます（クロマ0.01）
• 色付き背景上のグレー：色付き背景にグレーのテキストを置かず、背景色の濃淡または透明度を使用します
• パレットの規律：サーフェスとアクセントには、場当たり的な色合いではなく、定義済みのカラースケールを使用します

インタラクションの状態

すべてのインタラクティブ要素に、次の状態が必要です。

• デフォルト：通常の状態
• ホバー：控えめなフィードバック（色、拡大縮小、影）
• フォーカス：キーボードのフォーカスインジケーター（代わりの表示を用意せずに削除しないでください）
• アクティブ：クリック／押下時のフィードバック
• 無効：インタラクティブでないことが明確な状態
• 読み込み中：非同期アクションのフィードバック
• エラー：検証またはエラーの状態
• 成功：正常に完了した状態

状態が不足すると混乱を招き、使い勝手が損なわれます。

状態が変化してもアクションの階層が保たれるようにしてください。ホバー、フォーカス、アクティブ、読み込み中、無効のどの状態でも、主要なアクションが主要なものとして認識できるようにします。

マイクロインタラクションとトランジション

• 滑らかなトランジション：状態変化にはすべて、適切なアニメーションを適用します（150～300ms）
• イージングの一貫性：自然に減速するease-out-quart／quint／expoを使用します。弾む動きや伸縮する動きは古く見えるため、使用しないでください
• カクつきの防止：アニメーションは60fpsで動作させ、transformとopacityのみをアニメーションさせます
• 適切なモーション：モーションは装飾ではなく、目的に沿って使用します
• モーションの軽減：prefers-reduced-motionに対応します

コンテンツとコピー

• 用語の一貫性：同じものには、全体を通して同じ名称を使用します
• 大文字表記の一貫性：タイトルケースとセンテンスケースを一貫して適用します
• 文法とスペル：誤りがないようにします
• 適切な長さ：冗長にも簡潔すぎにもならないようにします
• 句読点の一貫性：文には句点を付け、ラベルには付けません（すべてのラベルに付ける場合を除きます）

アイコンと画像

• スタイルの一貫性：すべてのアイコンを同じファミリーから選ぶか、スタイルを揃えます
• 適切なサイズ：状況に応じてアイコンのサイズを一貫させます
• 適切な配置：アイコンを隣接するテキストと見た目上揃えます
• 代替テキスト：すべての画像に内容を説明する代替テキストを付けます
• 読み込み時の状態：画像によるレイアウトシフトを防ぎ、適切なアスペクト比を設定します
• Retina対応：高DPI画面向けに2倍サイズのアセットを用意します
• スクリーンショットの可読性：構成がわからなくなるほどスクリーンショットを小さく縮小しないようにします
• アイコンサイズの規律：小さなアイコンを大きくしてずんぐりさせず、細部の多いアイコンを縮小して不鮮明にしないようにします

フォームと入力欄

• ラベルの一貫性：すべての入力欄に適切なラベルを付けます
• 必須項目の表示：明確で一貫した表示にします
• エラーメッセージ：役立つ内容にし、一貫性を持たせます
• タブ順序：論理的なキーボード操作の順序にします
• 自動フォーカス：適切に使用します（多用しないでください）
• 検証のタイミング：フォーカスを外したときと送信時のどちらで行うかを統一します

エッジケースとエラー状態

• 読み込み状態：すべての非同期アクションで読み込み状況をフィードバックします
• 空の状態：何も表示されないだけではなく、役立つ空の状態を用意します
• エラー状態：復旧方法がわかる明確なエラーメッセージを表示します
• 成功状態：アクションが成功したことを確認できるようにします
• 長いコンテンツ：非常に長い名前や説明などを適切に扱います
• コンテンツなし：データがない場合も適切に処理します
• オフライン：適切なオフライン対応を行います（該当する場合）
• 空の状態の階層：次のアクションが明確な空の状態を用意し、不要なまま操作できないコントロールを残さないようにします

レスポンシブ対応

• すべてのブレークポイント：狭い画面、中程度の画面、広い画面のレイアウトをテストします
• タッチターゲット：タッチデバイスでは最低44x44pxにします
• 読みやすいテキスト：コンパクトなレイアウトでも14px未満のテキストを使いません
• 横スクロールなし：コンテンツをビューポート内に収めます
• 適切なリフロー：コンテンツが論理的に適応するようにします

パフォーマンス

• 初期読み込みを高速化：クリティカルパスを最適化します
• レイアウトシフトなし：読み込み後に要素が跳ねることがありません（CLS）
• スムーズな操作：遅延やカクつきがありません
• 画像を最適化：適切な形式とサイズにします
• 遅延読み込み：画面外のコンテンツは遅延読み込みします

コード品質

• コンソールログを削除：本番環境にデバッグログを残しません
• コメントアウトされたコードを削除：不要なコードを整理します
• 未使用のインポートを削除：未使用の依存関係を整理します
• 一貫した命名：変数と関数の名前を規約に沿って付けます
• 型安全性：TypeScript の any や無視されたエラーを残しません
• アクセシビリティ：適切な ARIA ラベルとセマンティック HTML を使用します

仕上げのチェックリスト

以下を体系的に確認します。

• すべてのブレークポイントで視覚的な配置が完璧
• スペーシングにデザイントークンを一貫して使用
• タイポグラフィの階層が一貫
• すべてのインタラクティブ状態を実装
• すべてのトランジションがスムーズ（60fps）
• 文言に一貫性があり、洗練されている
• アイコンに一貫性があり、サイズも適切
• すべてのフォームに適切なラベルとバリデーションを設定
• エラー状態が役立つ内容になっている
• 読み込み状態が明確
• 空の状態が親しみやすい
• タッチターゲットが最低44x44px
• コントラスト比が WCAG AA の基準を満たしている
• キーボード操作が機能する
• フォーカスインジケーターが見える
• コンソールエラーや警告がない
• 読み込み時にレイアウトシフトがない
• サポート対象のすべてのブラウザーで動作する
• 動きを減らす設定に対応している
• コードが整理されている（TODO、console.logs、コメントアウトされたコードがない）

重要：仕上げでは細部が大切です。拡大して確認してください。目を凝らして見てください。自分で使ってみてください。小さなことの積み重ねが大きな違いを生みます。

絶対にしないこと：

• 機能が完成する前に仕上げに取りかかる
• 30分後にリリースするものの仕上げに何時間も費やす（優先順位を判断する）
• 仕上げの最中にバグを持ち込む（十分にテストする）
• 体系的な問題を無視する（あらゆる箇所でスペーシングがずれているなら、仕組みから修正する）
• ひとつのことだけ完璧にして、ほかを粗雑なままにする（一貫した品質を保つ）
• 解決されていない階層の問題を隠すために、ボーダー、シャドウ、色の装飾を使う
• 控えめな区切りのほうが適している箇所で、明るいリンク色や雑然としたボーダー、装飾的な重なりを使う

最終確認

完了とする前に、以下を確認します。

• 自分で使う：実際に機能を操作します
• 実機でテストする：ブラウザーの DevTools だけで済ませません
• ほかの人にレビューを依頼する：新鮮な視点で気づけることがあります
• デザインと比較する：意図したデザインに合っているか確認します
• すべての状態を確認する：正常系だけをテストしないでください

忘れないでください。あなたには細部まで見逃さない注意力と、優れた美的センスがあります。手間を感じさせず、意図が伝わり、完璧に機能するまで仕上げてください。細部にもこだわってください。細部が大切です。