better-ui

UI の仕上げ

仕上がりは、積み重なった小さなディテールによって生まれます。このスキルでは、取り入れる価値のあるディテールと、その具体的な値を示します。

レビューするときは、インターフェースの動きを遅くして確認します。速度を10％にしたときに違和感がある部分は、通常の速度でも微妙にずれているところです。

プロジェクトのコンポーネントライブラリ、トークン、密度を維持し、以下のルールで正確なインタラクションが指定されている場合を除いて、プロジェクトのモーション表現に合わせます。

以下に記載するすべての時間、曲線、スケール、ぼかしは、近似するための範囲ではなく、具体的な値です。cubic-bezier(0.2, 0, 0, 1)はcubic-bezier(0.4, 0, 0.2, 1)とは異なり、0.96は0.95とは異なります。記載された値を使用してください。

テキストの折り返し、フォントのレンダリング、等幅数字、文字間隔についてはbetter-typographyを参照してください。ヒット領域、フォーカス、キーボード対応、ARIA、動きの軽減についてはbetter-accessibilityを参照してください。グループ化、セクション間隔、ブレークポイント、空間的なRTL対応についてはbetter-layoutを参照してください。

同心円状の角丸

外側の角丸半径 ＝ 内側の角丸半径 ＋ パディングです。入れ子になった要素の角丸半径が一致していないことは、インターフェースに違和感を与える最も一般的な原因です。角丸、シャドウ、アウトラインのレシピはsurfaces.mdにあります。

幾何学的な整列より視覚的な整列

幾何学的に中央揃えしたときにずれて見える場合は、視覚的に揃えます。アイコン付きボタン、再生ボタンの三角形、非対称なアイコンには、手動での微調整が必要です。

高さにはシャドウ、構造にはボーダー

ボーダーが奥行きを出すことだけを目的としている場合は、透明なbox-shadow値を重ねて使用します。仕切り線、区切り線、選択状態やフォーカス状態など、構造や状態を伝えるボーダーは維持します。

割り込み可能なアニメーション

インタラクティブな状態変化にはCSSトランジションを使用します。アニメーションの途中でも割り込めるためです。キーフレームは、一度だけ実行される段階的なシーケンスに使用します。

分割して時間差をつける入場アニメーション

順序によって階層を伝える、頻度の低い段階的な入場では、コンテンツを意味的なまとまりに分割し、それぞれの開始を約100msずつずらします。コンテナー全体をアニメーションさせても、同じコストに対する効果は小さくなります。頻繁に行われるインタラクションでは、開始をずらさないでください。enter-exit.mdを参照してください。

控えめな退出アニメーション

高さ全体ではなく、小さな固定値のtranslateYを使用します。退出は入場よりも控えめにします。両方向ともease-outを使用します。

状況に応じたアイコンアニメーション

表示・非表示を切り替えるのではなく、opacity、scale、blurでアイコンをアニメーションさせます。次の値をそのまま使用してください。scaleは0.25から1、opacityは0から1、blurは4pxから0pxです。

モーションライブラリ（package.jsonにあるmotionまたはframer-motion）を使用する場合は、そのパッケージのインポートパスを使用します。両方がある場合は、近くのインポートに合わせます。transition: { type: "spring", duration: 0.3, bounce: 0 }を使用します。bounceは常に0です。

モーションライブラリを使用しない場合は、両方のアイコンをDOMに配置し、一方を絶対配置して、cubic-bezier(0.2, 0, 0, 1)でクロスフェードします。これにより、依存関係を追加せずに入場と退出を実現できます。どちらのレシピもicon-transitions.mdにあります。

画像のアウトライン

奥行きを一貫させるため、画像に不透明度の低い1pxのアウトラインを付けます。ライトモードでは純粋な黒（oklch(0 0 0 / 0.1)）、ダークモードでは純粋な白（oklch(1 0 0 / 0.1)）を使用します。スレートや亜鉛のような黒に近い色や、色味のあるニュートラルカラーは使用しないでください。色味のあるアウトラインは下地の表面の色を拾い、画像の縁が汚れているように見えます。

押下時のスケール

クリック時にscale(0.96)を適用すると、ボタンに触覚的なフィードバックを与えられます。常に0.96を使用してください。0.95未満にすると大げさに感じられます。動きが気を散らす場所では無効にできるよう、static propを追加します。CSS、Tailwind、Motionのレシピを参照してください。

ページ読み込み時のアニメーションを省略

AnimatePresenceにinitial={false}を指定し、最初のレンダリングでは入場アニメーションを無効にします。意図したページ入場の演出が維持されていることを確認してください。

テーマ切り替え時のトランジションを抑制する

テーマを切り替えると、ほぼすべての要素で色、背景、境界線、影が一度に変化します。これらのプロパティに設定されたトランジションがすべて同時に発火し、切り替えが瞬時に行われず、にじむように見えます。*,*::before,*::after{transition:none !important} を挿入し、リフローを強制してから、次のフレームで削除します。レシピを参照してください。

変化するプロパティだけをトランジションさせる

対象のプロパティを必ず明示します：transition-property: scale, opacity。Tailwind の transition-transform は transform, translate, scale, rotate を対象にします。

will-change は控えめに使う

GPU で合成できる transform、opacity、filter にのみ使います。will-change: all は絶対に使わないでください。最初のフレームでカクつきが見られた場合に追加し、事前には追加しないでください。performance.mdを参照してください。

アイコンの線幅をテキストの太さに合わせる

テキストの横に置かれたアイコンは、テキストの視覚的な太さに合わせます。通常（400）のテキストには 1.5px、セミボールド（600）には 2px の線幅を使います。アイコンセットごとに線幅を統一し、各サーフェスで使うアイコンライブラリは1つにします。サイズと RTL の反転についてはicons.mdを参照してください。

SVG は1つにし、状態ごとに色を変える

アイコンには currentColor を使い、ホバー、選択済み、無効の状態は別々のアセットではなく、CSS の色と不透明度で表現します。デフォルトのバリアントはアウトラインで、アクティブ状態は塗りつぶしで示します。

動きは控えめに

頻繁に発生する操作には即座に反応するか、150ms 以下の不透明度と色のトランジションを使います。ここでカスタムアニメーションを使うと、発火のたびにユーザーの注意を消費します。

アニメーションを伴う状態変化には、色、アイコン、ラベルのいずれかによる静的な手がかりも必要です。動きだけをフィードバック手段にしてはいけません。

完了前の確認

間違い	修正
アイコンが中央からずれて見える	パディングで視覚的に位置を調整するか、SVG を修正する
登場や退出が段階的で唐突に見える	頻度の低い登場は時間差をつけ、退出は控えめにする
テーマ切り替え時にページ全体がクロスフェードする	切り替え中はトランジションを無効にし、リフローを強制して、次のフレームで元に戻す
要素に transition: all が設定されている	対象のプロパティを明示する
アニメーションの最初のフレームでカクつく	will-change: transform を控えめに追加する
太字テキストの横に細すぎるアイコンがある	線幅をテキストの太さに合わせる

報告

重大度。 HIGH は操作を妨げる、動きを使いものにならなくする、またはアニメーション中にしか状態変化が見えない問題です。MEDIUM はサーフェス、アイコン、動きに見られる不整合です。LOW は局所的な仕上げの問題です。

検証。 ブラウザーを使わない場合は、コンポーネントで定義されているすべての状態（ホバー、フォーカス、アクティブ、読み込み中、空の状態）に加え、コードから読み取れる動きの継続時間とイージングを確認します。ブラウザーを使う場合は、各状態を確認し、ブラウザーの Animations パネルで動きを10％の速度で再生します。実行できなかった確認事項はすべて Not verified として報告します。

形式。 違反している原則ごとに重大度順で指摘をまとめ、根本原因ごとに1行を使って、該当するすべての箇所を記載します。

重大度	場所	修正前	修正後	理由

場所 は path/to/file:line の形式です。理由 には原則とユーザーへの影響を記載します。

HIGH が残っている場合は最後に Block と記載し、それ以外の場合は Approve と記載します。残りの作業は表に記載します。確認していない範囲について Approve としてはいけません。報告事項がない場合は「実施可能な UI の仕上げに関する指摘はありません」と記載し、検証結果も報告します。