userinterface-wiki

ユーザーインターフェース Wiki

ウェブインターフェース向けの、包括的な UI/UX ベストプラクティスガイドです。12 カテゴリーにわたる 152 のルールを収録し、影響度順に優先順位を付けて、自動コードレビューとコード生成の指針としています。

適用する場面

以下の場合は、これらのガイドラインを参照してください。

• アニメーション（CSS トランジション、Motion/Framer Motion）を実装またはレビューするとき
• スプリング、イージングカーブ、またはアニメーションなしを選ぶとき
• AnimatePresence と終了アニメーションを扱うとき
• 疑似要素または View Transitions API を使った CSS を記述するとき
• UI に音声フィードバックやプロシージャルサウンドを追加するとき
• モーフィングアイコンのコンポーネントを構築するとき
• 動的なコンテンツに合わせてコンテナーの幅や高さをアニメーションさせるとき
• 認知心理学（フィッツの法則、ヒックの法則、ミラーの法則）に配慮した UI を設計するとき
• 体感パフォーマンスを高める予測プリフェッチを実装するとき
• タイポグラフィ、OpenType 機能、または数値の書式設定を設定するとき

優先度別ルールカテゴリー

優先度	カテゴリー	影響度	接頭辞
1	アニメーションの原則	重大	timing-、physics-、staging-
2	タイミング関数	高	spring-、easing-、duration-、none-
3	終了アニメーション	高	exit-、presence-、mode-、nested-
4	CSS 疑似要素	中	pseudo-、transition-、native-
5	音声フィードバック	中	a11y-、appropriate-、impl-、weight-
6	サウンド合成	中	context-、envelope-、design-、param-
7	モーフィングアイコン	低	morphing-
8	コンテナーアニメーション	中	container-
9	UX の法則	高	ux-
10	予測プリフェッチ	中	prefetch-
11	タイポグラフィ	中	type-
12	ビジュアルデザイン	高	visual-

クイックリファレンス

1. アニメーションの原則（重大）

• timing-under-300ms - ユーザー向けアニメーションは 300ms 以内に完了させます
• timing-consistent - 類似する要素には同じタイミング値を使用します
• timing-no-entrance-context-menu - コンテキストメニューには開始アニメーションを使わず、終了時のみアニメーションを使います
• easing-natural-decay - 自然な減衰には線形ではなく、指数ランプを使用します
• easing-no-linear-motion - 線形イージングは進行状況インジケーターにのみ使用します
• physics-active-state - インタラクティブな要素には :active のスケール変換が必要です
• physics-subtle-deformation - 圧縮・伸長は 0.95～1.05 の範囲に収めます
• physics-spring-for-overshoot - 行き過ぎてから落ち着く動きにはイージングではなくスプリングを使用します
• physics-no-excessive-stagger - 項目ごとのスタッガー遅延は 50ms 未満にします
• staging-one-focal-point - 目立つアニメーションは一度に 1 つにします
• staging-dim-background - モーダルやダイアログの背景を暗くします
• staging-z-index-hierarchy - アニメーション要素は z-index の階層を守ります

2. タイミング関数（高）

• spring-for-gestures - ジェスチャー駆動の動き（ドラッグ、フリック）にはスプリングを使用する必要があります
• spring-for-interruptible - 中断可能な動きにはスプリングを使用する必要があります
• spring-preserves-velocity - スプリングは、入力エネルギーを解放時にも維持します
• spring-params-balanced - スプリングのパラメーターで過度な振動を避けます
• easing-for-state-change - システムの状態変化にはイージングカーブを使用します
• easing-entrance-ease-out - 開始アニメーションには ease-out を使用します
• easing-exit-ease-in - 終了アニメーションには ease-in を使用します
• easing-transition-ease-in-out - ビュートランジションには ease-in-out を使用します
• easing-linear-only-progress - 線形イージングは進行状況や時間の表現にのみ使用します
• duration-press-hover - 押下／ホバー：120～180ms
• duration-small-state - 小さな状態変化：180～260ms
• duration-max-300ms - ユーザー操作によるアニメーションは最大 300ms にします
• duration-shorten-before-curve - 動きが遅く感じられる場合は、カーブではなく再生時間を短くして調整します
• none-high-frequency - 高頻度のインタラクションにはアニメーションを使いません
• none-keyboard-navigation - キーボード操作によるナビゲーションは即時に行い、アニメーションを使いません
• none-context-menu-entrance - コンテキストメニューには開始アニメーションを使わず、終了時のみアニメーションを使います

3. 終了アニメーション（高）

• exit-requires-wrapper - 条件付きのモーション要素には AnimatePresence ラッパーが必要です
• exit-prop-required - AnimatePresence 内の要素には exit プロパティが必要です
• exit-key-required - 動的リストにはインデックスではなく一意のキーが必要です
• exit-matches-initial - 対称性を保つため、exit を initial に合わせます
• presence-hook-in-child - useIsPresent は親ではなく子で使用します
• presence-safe-to-remove - 非同期クリーンアップの後に safeToRemove を呼び出します
• presence-disable-interactions - 終了中の要素ではインタラクションを無効にします
• mode-wait-doubles-duration - Mode "wait" では所要時間が倍になるため、タイミングを半分にします
• mode-sync-layout-conflict - Mode "sync" ではレイアウトの競合が発生します
• mode-pop-layout-for-lists - リストの並べ替えには popLayout を使用します
• nested-propagate-required - 入れ子の AnimatePresence には propagate プロパティが必要です
• nested-consistent-timing - 親と子の終了時間を調整します

4. CSS 疑似要素（中）

• pseudo-content-required - ::before/::after には content プロパティが必要です
• pseudo-over-dom-node - 装飾には余分な DOM ノードではなく疑似要素を使用します
• pseudo-position-relative-parent - 親には position: relative が必要です
• pseudo-z-index-layering - 疑似要素を正しく重ねるには Z-index を設定します
• pseudo-hit-target-expansion - ヒット領域を広げるには負の inset を使用します
• pseudo-marker-styling - リストの箇条書きをカスタマイズするには ::marker を使用します
• pseudo-first-line-styling - タイポグラフィの調整には ::first-line を使用します
• transition-name-required - ビュートランジションには view-transition-name が必要です
• transition-name-unique - トランジション中、各トランジション名は一意である必要があります
• transition-name-cleanup - 完了後にトランジション名を削除します
• transition-over-js-library - JS ライブラリより View Transitions API を優先します
• transition-style-pseudo-elements - カスタムアニメーションには ::view-transition-group をスタイル設定します
• native-backdrop-styling - ダイアログの背景には ::backdrop を使用します
• native-placeholder-styling - 入力欄のスタイル設定には ::placeholder を使用します
• native-selection-styling - テキスト選択のスタイル設定には ::selection を使用します

5. 音声フィードバック（中）

• a11y-visual-equivalent - すべての音には視覚的な代替表現が必要です
• a11y-toggle-setting - 音を無効にする切り替え機能を用意します
• a11y-reduced-motion-check - 音についても prefers-reduced-motion を尊重します
• a11y-volume-control - 音量を個別に調整できるようにします
• appropriate-no-high-frequency - タイピングやキーボード操作では音を鳴らしません
• appropriate-confirmations-only - 支払い、アップロード、送信時に音を鳴らします
• appropriate-errors-warnings - 見過ごされる可能性のあるエラーには音を鳴らします
• appropriate-no-decorative - ホバー時や装飾的な場面では音を鳴らしません
• appropriate-no-punishing - 耳障りな音で罰するのではなく、情報を伝えます
• impl-preload-audio - 遅延を避けるため、音声ファイルを事前に読み込みます
• impl-default-subtle - デフォルトの音量は大きくせず、控えめ（0.3）にします
• impl-reset-current-time - 再生前に currentTime をリセットします
• weight-match-action - 音の重みをアクションの重要度に合わせます
• weight-duration-matches-action - 音の長さをアクションの継続時間に合わせます

6. 音の合成（中）

• context-reuse-single - サウンドごとに AudioContext を作成せず、単一の AudioContext を再利用します
• context-resume-suspended - 再生前に中断された AudioContext を再開します
• context-cleanup-nodes - 再生後にオーディオノードを切断します
• envelope-exponential-decay - 自然な減衰には指数関数的なランプを使用します
• envelope-no-zero-target - 指数関数的なランプの目標値には 0 ではなく 0.001 を指定します
• envelope-set-initial-value - ランプ処理の前に初期値を設定します
• design-noise-for-percussion - クリック音やタップ音にはフィルター処理したノイズを使用します
• design-oscillator-for-tonal - 音程のあるサウンドにはピッチスイープ付きのオシレーターを使用します
• design-filter-for-character - パーカッシブなサウンドの音色調整にはバンドパスフィルターを使用します
• param-click-duration - クリック音の長さ：5～15ms
• param-filter-frequency-range - クリック音のフィルター：3000～6000Hz
• param-reasonable-gain - クリッピングを防ぐため、ゲインを 1.0 未満にします
• param-q-value-range - フィルターの Q 値：焦点を保ちつつ自然な音にするには 2～5

7. アイコンのモーフィング（LOW）

• morphing-three-lines - すべてのアイコンで SVG の線を正確に 3 本使用します
• morphing-use-collapsed - 使用しない線には collapsed 定数を使用します
• morphing-consistent-viewbox - すべてのアイコンで同じ viewBox（14x14）を共有します
• morphing-group-variants - 回転バリエーションでグループとベースラインを共有します
• morphing-spring-rotation - グループ化したアイコンの回転にスプリング物理を使用します
• morphing-reduced-motion - prefers-reduced-motion を尊重します
• morphing-jump-non-grouped - グループ化されていないアイコン間の回転は即座に切り替えます
• morphing-strokelinecap-round - 線の端を丸くします
• morphing-aria-hidden - アイコンの SVG を aria-hidden にします

8. コンテナーアニメーション（MEDIUM）

• container-two-div-pattern - 外側の div をアニメーション化し、内側の div を計測します。同じ要素を使わないでください
• container-guard-initial-zero - 初回のレンダリングで bounds === 0 を確認し、"auto" にフォールバックします
• container-use-resize-observer - 計測には getBoundingClientRect ではなく ResizeObserver を使用します
• container-overflow-hidden - トランジション中はアニメーション対象のコンテナーに overflow: hidden を設定します
• container-no-excessive-use - ボタン、アコーディオン、インタラクティブ要素などに限定して使用します
• container-callback-ref - 計測フックには useRef ではなくコールバック ref を使用します
• container-transition-delay - 自然に追いつくような感覚を生むため、短い遅延を追加します

9. UX の法則（HIGH）

• ux-fitts-target-size - クリックしやすいようにインタラクティブなターゲットのサイズを設定します（最小 32px）
• ux-fitts-hit-area - 透明なパディングや疑似要素でヒット領域を広げます
• ux-hicks-minimize-choices - 選択肢を減らして意思決定にかかる時間を短縮します
• ux-millers-chunking - データを 5～9 個のグループにまとめ、一覧しやすくします
• ux-doherty-under-400ms - 即時に反応したと感じられるよう、400ms 以内に応答します
• ux-doherty-perceived-speed - スケルトン、楽観的 UI、進行状況インジケーターで速度を演出します
• ux-postels-accept-messy-input - 雑多な入力を受け入れ、整ったデータを出力します
• ux-progressive-disclosure - 今必要な情報を表示し、複雑さは後から明らかにします
• ux-jakobs-familiar-patterns - ユーザーがほかのサイトで知っている、なじみのある UI パターンを使用します
• ux-aesthetic-usability - 見た目を洗練させることで、使いやすさの印象が高まります
• ux-proximity-grouping - 関連する要素を空間的にグループ化し、間隔を狭めます
• ux-similarity-consistency - 似た要素は似た見た目にします
• ux-common-region-boundaries - 境界線を使って関連するコンテンツをグループ化します
• ux-von-restorff-emphasis - 重要な要素を視覚的に際立たせます
• ux-serial-position - 一連の項目では、重要な項目を最初か最後に配置します
• ux-peak-end-finish-strong - 明確な成功状態で体験を締めくくります
• ux-teslers-complexity - 複雑さをユーザーではなくシステム側に移します
• ux-goal-gradient-progress - 完了に向けた進捗を表示します
• ux-zeigarnik-show-incomplete - 未完了の状態を表示し、完了を促します
• ux-pragnanz-simplify - 複雑なビジュアルを明快な形に単純化します
• ux-pareto-prioritize-features - 機能のうち、重要な 20% を優先します
• ux-cognitive-load-reduce - 余計な認知負荷を最小限に抑えます
• ux-uniform-connectedness - 線や枠を使って関連する要素を視覚的につなげます

10. 予測プリフェッチ（MEDIUM）

• prefetch-trajectory-over-hover - ホバーではなく軌跡予測を使い、100～200ms の時間を取り戻します
• prefetch-not-everything - ビューポートではなく意図に基づいてプリフェッチし、帯域幅の無駄を避けます
• prefetch-hit-slop - hitSlop を使って予測を早めに開始します
• prefetch-touch-fallback - タッチデバイス（カーソルなし）では適切にフォールバックします
• prefetch-keyboard-tab - フォーカスが近づいたときに、キーボード操作によるナビゲーションでプリフェッチします
• prefetch-use-selectively - レイテンシーが気になる箇所で予測プリフェッチを使用します

11. タイポグラフィ（MEDIUM）

• type-tabular-nums-for-data - 列、ダッシュボード、価格表示には等幅数字を使用する
• type-oldstyle-nums-for-prose - オールドスタイル数字は本文に自然になじみます
• type-slashed-zero - コードに隣接する UI ではスラッシュ付きゼロを使用する
• type-opentype-contextual-alternates - 字形を文脈に応じて調整するため、calt を有効のままにする
• type-disambiguation-stylistic-set - I/l/1 と 0/O を区別するため、ss02 を有効にする
• type-optical-sizing-auto - サイズに応じて字形を調整するため、font-optical-sizing は auto のままにする
• type-antialiased-on-retina - Retina ディスプレイではフォントのアンチエイリアスを有効にする
• type-text-wrap-balance-headings - 見出しの行を均等にするため、text-wrap: balance を使用する
• type-underline-offset - 下線をディセンダーより下にずらす
• type-no-font-synthesis - 擬似的な太字や斜体を防ぐため、font-synthesis を無効にする
• type-font-display-swap - 読み込み中にテキストが見えなくなるのを防ぐため、font-display: swap を使用する
• type-variable-weight-continuous - 可変フォントでは連続したウェイト値（100-900）を使用する
• type-text-wrap-pretty - 本文の孤立行を減らすため、text-wrap: pretty を使用する
• type-justify-with-hyphens - text-align: justify と hyphens: auto を組み合わせる
• type-letter-spacing-uppercase - 大文字とスモールキャピタルのテキストに letter-spacing を設定する
• type-proper-fractions - 正しい組版の分数には diagonal-fractions を使用する

12. ビジュアルデザイン（HIGH）

• visual-concentric-radius - 入れ子になった要素では、内側の半径を外側の半径からパディングを引いた値にする
• visual-layered-shadows - 複数の影を重ねて、リアルな奥行きを表現する
• visual-shadow-direction - すべての影でオフセットの方向をそろえる（光源を一つにする）
• visual-no-pure-black-shadow - 影には純粋な黒ではなく、中立色を使用する
• visual-shadow-matches-elevation - 一貫したスケールで、影の大きさから高さを示す
• visual-animate-shadow-pseudo - パフォーマンス向上のため、疑似要素の不透明度で影をアニメーションさせる
• visual-consistent-spacing-scale - 任意の値ではなく、一貫したスペーシングスケールを使用する
• visual-border-alpha-colors - 半透明の境界線は、どのような背景にもなじみます
• visual-button-shadow-anatomy - 洗練されたボタンのために、6 層の影を構成する

使い方

詳しい説明とコード例は、各ルールのファイルを参照してください。

rules/timing-under-300ms.md
rules/spring-for-gestures.md
rules/ux-doherty-under-400ms.md
rules/type-tabular-nums-for-data.md

各ルールのファイルには、次の内容が含まれています。

• 重要である理由の簡単な説明
• 誤ったコード例とその説明
• 正しいコード例とその説明

完全版ドキュメント

すべてのルールを展開した完全なガイドについては、AGENTS.md を参照してください。