better-ui

インターフェースをより使いやすくする細部

優れたインターフェースは、たいてい一つの要素だけで生まれるものではありません。小さな工夫が積み重なり、優れた体験につながるものです。UI コードの作成やレビューでは、以下の原則を適用してください。

レビューの際は、インターフェースの動きをゆっくり確認します。ブラウザーの Animations パネルで動きを 10% の速度で再生し、ホバー、フォーカス、アクティブ、読み込み中、空の状態など、すべての状態を確認してください。10% の速度で違和感がある部分は、通常の速度では気づきにくい問題が潜んでいます。

プロジェクトのコンポーネントライブラリ、トークン、情報密度を維持してください。以下の原則に具体的な操作パターンが定められている場合を除き、既存のモーション表現に合わせてください。

タイポグラフィ（テキストの折り返し、フォントのレンダリング、等幅数字、間隔）は better-typography スキルで扱います。テキストに関する作業には、そちらを使用してください。アクセシビリティ（タップ領域、フォーカス状態、キーボード対応、ARIA、動きを抑える設定）は better-accessibility スキルで扱います。レイアウト構造（グループ化、セクション間の間隔、ブレークポイント、空間的な RTL）は better-layout スキルで扱います。

クイックリファレンス

カテゴリー	使用する場面
サーフェス	角丸、視覚的な位置合わせ、シャドウ、画像のアウトライン
アニメーション	中断可能なトランジション、押下時の拡大縮小、ページ読み込み時のアニメーションのスキップ、テーマの切り替え、動きの抑制
表示と終了	段階的な表示、時間差の設定、終了時のトランジション
アイコンのトランジション	モーションライブラリの有無に応じた、状態変更時のアイコンのクロスフェード
アイコン	アイコンの線の太さ、currentColor による状態表現、アウトラインと塗りつぶし、サイズ、RTL 時の反転
パフォーマンス	トランジションの指定範囲、will-change の使用
レビュー出力形式	重大度の基準、指摘事項の表、検証、判定

基本原則

1. 同心円状の角丸

外側の半径 ＝ 内側の半径 ＋ パディング。ネストされた要素で角丸が一致しないことは、インターフェースに違和感を与える最も一般的な原因です。

2. 幾何学的な位置合わせより視覚的な位置合わせ

幾何学的な中央揃えに違和感がある場合は、視覚的に位置を合わせてください。アイコン付きボタン、再生ボタンの三角形、非対称なアイコンは、いずれも手動での調整が必要です。

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

ボタン、カード、コンテナーのボーダーが奥行きを出す目的だけに使われている場合は、透明度を重ねた box-shadow の値を使用してください。区切り線やレイアウトの仕切り、選択状態やフォーカス状態など、構造や状態を伝えるボーダーは維持してください。

4. 中断可能なアニメーション

操作による状態変更には CSS トランジションを使用してください。アニメーションの途中で中断できます。一度だけ実行する段階的なシーケンスには、キーフレームを使用してください。

5. 分割した段階的な表示アニメーション

階層を伝えるために順序が有効な、頻度の低い段階的な表示では、コンテンツを意味的なまとまりに分け、それぞれを約 100ms ずつずらして表示してください。コンテナー全体を一度にアニメーションさせないでください。日常的に発生する高頻度の操作では、表示をずらさないでください。時間差表示と終了時のレシピ。

6. 控えめな終了時のアニメーション

高さ全体を変えるのではなく、小さな固定値の translateY を使用してください。終了時の動きは、表示時よりも控えめにします。表示時と終了時の両方に ease-out を使用してください。

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

アイコンの表示切り替えには、可視性を切り替えるのではなく、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 に残し（片方を絶対配置にします）、CSS トランジションの cubic-bezier(0.2, 0, 0, 1) でクロスフェードしてください。これにより、依存関係を追加せずに表示時と終了時の両方をアニメーションできます。2 つのレシピ。

8. 画像のアウトライン

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

9. 押下時に縮小する

クリック時に控えめな scale(0.96) を適用すると、ボタンに触覚的なフィードバックが加わります。必ず 0.96 を使用してください。0.95 未満は誇張されているように感じられます。動きが気になる場合に無効化できるよう、static プロパティを追加してください。CSS、Tailwind、Motion のレシピ。

10. ページ読み込み時のアニメーションをスキップする

初回のレンダリング時に開始アニメーションが実行されないよう、AnimatePresence に initial={false} を指定します。意図した開始アニメーションが壊れていないことを確認してください。

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

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

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

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

13. will-change は控えめに使う

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

14. アイコンのストロークをテキストのウェイトに合わせる

テキストの横にあるアイコンは、テキストと視覚的なウェイトを合わせます。レギュラー（400）のテキストには 1.5px、セミボールド（600）には 2px のストロークを使用します。アイコンセットごとにストロークの太さを統一し、同じサーフェスでライブラリを混在させないでください。

15. SVG は 1 つだけ使い、状態ごとに色を変える

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

16. 動きは控えめにする

高頻度で発生するインタラクションには、カスタムアニメーションを追加しないでください。注意を引くコストが、発生のたびに繰り返されるためです。動きだけをフィードバック手段にしてはいけません。アニメーションを伴う状態変化には、色やアイコン、ラベルなど、静的な手がかりも必要です。

よくある間違い

間違い	修正方法
入れ子になった親要素と子要素で同じ境界線の半径を使う	outerRadius = innerRadius + padding を計算する
アイコンが中央に見えない	パディングで視覚的に調整するか、SVG を直接修正する
高さを擬似的に表現するためだけに境界線を使う	透明度を設定したレイヤー状の box-shadow を使い、構造や状態を示す境界線は維持する
段階的に始まる唐突な開始アニメーションや、文脈を失う終了アニメーション	頻度の低い開始アニメーションには時間差をつけ、文脈を維持する終了アニメーションは控えめにする
状態を持つアイコンやトグルのデフォルト状態がページ読み込み時にアニメーションする	対象の AnimatePresence に initial={false} を追加し、意図したページ開始アニメーションは維持する
テーマの切り替えでページ全体がクロスフェードする	切り替え中はトランジションを無効にし、リフローを強制して、次のフレームで元に戻す
要素に transition: all を指定する	対象のプロパティを明示する
最初のフレームでアニメーションがカクつく	will-change: transform を（控えめに）追加する
細すぎるストロークのアイコンが太字テキストの横にある	ストロークの太さをテキストのウェイトに合わせる
状態ごとにアイコンのアセットを分ける	currentColor を使った SVG を 1 つだけ使い、状態は CSS で表現する
あらゆる場面で塗りつぶしアイコンを使う	デフォルトはアウトラインとし、アクティブ状態に限り塗りつぶしを使う
ホバーやキー入力のたびに開始アニメーションを実行する	即時に反応させるか、opacity/color のトランジションを ≤150ms にする

報告

単独の UI 仕上げレビューは、確認済みの指摘事項をすべてreview-output.mdの形式で、検証と判定を含めて報告した時点で完了です。better-interface では、そちらの形式に従ってください。