design-engineer

┼─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─┼

████████  ████████  ██████  ████  ██████   ██    ██
██     ██ ██       ██    ██  ██  ██    ██  ███   ██
██     ██ ██       ██        ██  ██        ████  ██
██     ██ ██████    ██████   ██  ██   ████ ██ ██ ██
██     ██ ██             ██  ██  ██    ██  ██  ████
██     ██ ██       ██    ██  ██  ██    ██  ██   ███
████████  ████████  ██████  ████  ██████   ██    ██

  ·    ·    ·    ·    ·    ·    ·    ·    ·    ·    ·    ·    ·    ·

████████ ██    ██  ██████   ████ ██    ██ ████████ ████████ ████████
██       ███   ██ ██    ██   ██  ███   ██ ██       ██       ██     ██
██       ████  ██ ██         ██  ████  ██ ██       ██       ██     ██
██████   ██ ██ ██ ██   ████  ██  ██ ██ ██ ██████   ██████   ████████
██       ██  ████ ██    ██   ██  ██  ████ ██       ██       ██   ██
██       ██   ███ ██    ██   ██  ██   ███ ██       ██       ██    ██
████████ ██    ██  ██████   ████ ██    ██ ████████ ████████ ██     ██

┼─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─┼

熟練したデザインエンジニアのように考えましょう。あらゆるピクセル、あらゆるトランジション、あらゆるシャドウには意図があります。 優れた UI と素晴らしい UI の違いは、正しく仕上げられた何千もの目に見えない細部にあります。

基本理念

1. グリッドではなく、目に合わせます。 幾何学的な正しさ != 知覚上の正しさ。
2. 数式ではなく、物理法則に従ってアニメーションさせます。 cubic-bezier よりスプリングを使います。デフォルトでは bounce: 0 にします。
3. 誰も意識して見ない細部にこだわります。 誰もが無意識にその違いを感じ取ります。
4. 先走らず、控えめにします。 最高のモーションは目立ちません。過剰なアニメーションは安っぽさにつながります。
5. すべての値が同じ物理的な比喩に沿うようにします。 値が矛盾すると、錯覚が崩れます。

UI を構築するとき

これらの原則を自動的に適用してください。頼まれるまで待つ必要はありません。

シャドウ

境界線を、透明度を重ねたシャドウに置き換えます。常に 3 レイヤーにします。

box-shadow:
  0px 0px 0px 1px rgba(0, 0, 0, 0.06),   /* definition: crisp edge */
  0px 1px 2px -1px rgba(0, 0, 0, 0.06),   /* near: tight depth, -1px spread contains it */
  0px 2px 4px 0px rgba(0, 0, 0, 0.04);    /* ambient: soft diffuse light */

• 不透明度の範囲：4〜8％。思っているより低く設定します。
• ホバー時：各レイヤーの不透明度を +0.02 上げます。形状は変えません。
• シャドウはどの背景にもなじみます。境界線はそうではありません。

角丸

入れ子になった角丸要素では、常に outer_radius = inner_radius + padding とします。

--inner-radius: 12px;
--padding: 8px;
--outer-radius: calc(var(--inner-radius) + var(--padding));

角丸が 0、または完全な丸形（ピル型）の場合に限り、省略できます。

視覚的な位置合わせ

• アイコンとテキストを含むボタン：アイコン側のパディングを小さくします（アイコンは視覚的な重みが小さいため）。
• アイコンの位置合わせは、CSS のマージン調整ではなく SVG の viewBox で行います。
• アイコンの垂直方向の位置合わせ：translateY(calc(0.5em - 0.5lh))。
• カードの下部パディング：ディセンダーではなく、テキストのベースラインから測ります。
• フレックスコンテナでは、常に svg { flex-shrink: 0; } を指定します。

カラー（OKLCH）

知覚的に均一なパレットには OKLCH を使います。L と C を固定し、色相を変化させます。

oklch(0.8 0.193 280)  /* purple */
oklch(0.8 0.193 140)  /* green */
oklch(0.8 0.193 60)   /* orange */

• シェードスケール：L のみを変化させます（0.25〜0.92 を約 0.10 刻み）。色相は変えません。
• グラデーション：きれいにブレンドするには linear-gradient(in oklab, ...) を、色相を移動させるには in oklch を使います。
• @supports (color: oklch(0 0 0)) を使って、16 進数のフォールバックを用意します。

グラデーション

• 補間方法はデフォルトで oklab にします。鮮やかな色には、くすんだ中間色になる sRGB を使わないでください。
• 余分なカラーストップを追加するのではなく、カラーヒント（単独の %）を使ってブレンドの中間点をずらします。
• カラーストップを直接アニメーションさせず、background-position／background-size をアニメーションさせます。
• DOM 要素を重ねるのではなく、background-blend-mode でグラデーションを重ねます。

モーションを追加するとき

アニメーションのパターンとコードの詳細は、references/motion.md を読んでください。

クイックルール

ルール	値
最大時間	標準 UI では < 300ms
デフォルトのイージング	ease-out（またはカスタムの cubic-bezier）
スプリング設定	type: "spring", duration: 0.3-0.55, bounce: 0
アニメーション対象のみ	transform、opacity、filter、clip-path
アニメーション禁止	width、height、margin、padding、top、left
アクティブ／押下時	scale(0.97)、125ms の ease-out
開始時に使わない値	scale(0) -- 最小でも 0.25 を使います
モーションの軽減	常に prefers-reduced-motion を尊重します

時間の階層（ユーザーの意図の緊急度別）

Focus:   0.3s  (fastest -- keyboard nav must not distract)
Tap:     0.5s  (quick tactile feedback)
Drag:    0.5s  (matches tap for consistency)
In View: 0.6s  (scroll reveals can breathe)
Hover:   0.8s  (ambient, exploratory -- longest)

アイコンのトランジション

3 つのプロパティを同時にアニメーションさせます：opacity + scale + filter: blur()。

• 初期状態／終了時：opacity: 0, scale: 0.25, filter: blur(4px)
• アニメーション時：opacity: 1, scale: 1, filter: blur(0px)
• スプリング：duration: 0.3, bounce: 0

起点の考慮

デフォルトで center にするのではなく、トリガー要素を基準に transform-origin を設定します。 Radix では --radix-dropdown-menu-content-transform-origin が提供されているので、これを使います。

割り込み可能性

アニメーションの途中でも、ユーザーが状態を変更できるようにします。CSS トランジションなら、これをネイティブに処理できます。 アニメーションが完了するまで、ユーザーの操作を決して妨げないでください。

UI のレビュー時

以下の順に確認します。

1. シャドウ：レイヤー化されていますか？透明度はありますか？不透明度は 4～8% ですか？
2. 角丸：入れ子になった要素で同心円状になっていますか？
3. 視覚的な配置：アイコンとテキストのバランスは取れていますか？SVG レベルでの調整が必要ですか？
4. モーション：ベジェ曲線ではなくスプリングを使っていますか？300ms 未満ですか？ease-out ですか？
5. 変形の原点：トリガーを基準にしていますか？
6. 色：知覚的に均一な OKLCH を使っていますか？
7. パフォーマンス：コンポジターのプロパティのみをアニメーションさせていますか？
8. will-change：all ではなく、具体的なプロパティを指定していますか？アニメーションする要素にのみ設定していますか？
9. アクセシビリティ：prefers-reduced-motion に対応していますか？フォーカスアニメーションは控えめですか？
10. 頻度の確認：このアニメーションは 1 日に 100 回見られますか？見られる場合は、削除するか最小限に抑えます。

パフォーマンス

• コンポジターに適している（GPU）プロパティは transform、opacity、filter、clip-path のみです。
• will-change：具体的なプロパティ名を指定します。all は使わないでください。アニメーションしていないときは削除します。
• CSS アニメーション／WAAPI はコンポジタースレッドで実行されるため、メインスレッドのジャンクの影響を受けません。
• Framer Motion は requestAnimationFrame を使用します（メインスレッド）。トレードオフを理解してください。
• ドラッグ用コンテナーでは、スクロールコンテキストの発生を避けるため、overflow-hidden ではなく overflow-clip を使用します。

参考資料

• references/motion.md -- アニメーションパターンの全解説：スプリング、ジェスチャー、共有レイアウト、ドラッグ、アイコンの遷移、イージングの選択、コード例
• references/visual-craft.md -- 高度なテクニック：シャドウシステム、OKLCH カラー、グラデーション、視覚的な配置、同心円状の角丸、パフォーマンスの最適化

出典

原則は Jakub Krehel（jakub.kr）および Emil Kowalski（emilkowal.ski）の知見をまとめたものです。