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 或为完全圆形（胶囊形）时，才可不遵循。

视觉对齐

• 图标+文本按钮：减少图标一侧的内边距（图标的视觉分量较轻）。
• 在 SVG viewBox 中修正图标对齐，不要用 CSS margin 变通。
• 图标垂直对齐：translateY(calc(0.5em - 0.5lh))。
• 卡片的底部内边距：以文本基线而非降部为准测量。
• 在 flex 容器中使用 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)) 提供十六进制回退值。

渐变

• 默认使用 oklab 插值。鲜艳颜色绝不要使用 sRGB（中间色会显得浑浊）。
• 使用颜色提示（独立的 %）改变混色中点，不要添加额外的颜色停止点。
• 对 background-position/background-size 添加动画，绝不要直接对颜色停止点添加动画。
• 使用 background-blend-mode 叠加渐变，而不是堆叠 DOM 元素。

添加动效时

阅读 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

感知触发位置

根据触发元素设置 transform-origin，默认绝不要使用 center。 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. 频率检查：这种动画每天会被看到 100 次吗？如果会，请移除或尽量弱化。

性能

• 只有 transform、opacity、filter、clip-path 对合成器（GPU）友好。
• will-change：指定具体属性。绝不要使用 all。不再添加动画时移除。
• CSS 动画/WAAPI 在合成器线程上运行（不受主线程卡顿影响）。
• Framer Motion 使用 requestAnimationFrame（主线程）——请了解其中的权衡。
• 拖动容器使用 overflow-clip，而非 overflow-hidden（避免创建滚动上下文）。

参考资料

• references/motion.md -- 完整的动画模式：弹簧效果、手势、共享布局、拖动、图标过渡、缓动选择、代码示例
• references/visual-craft.md -- 深入技巧：阴影系统、OKLCH 颜色、渐变、视觉对齐、同心边框圆角、性能优化

来源

这些原则提炼自 Jakub Krehel (jakub.kr) 和 Emil Kowalski (emilkowal.ski)。