user-interface

用户界面

为 3D 应用构建优秀的 UI，需要做出两个决定：UI 放在哪里（空间式还是屏幕式），以及外观如何（设计质量）。本技能负责引导第一个决定，并为第二个设定标准。

选择技术

针对不同界面分别决定——单个应用通常会同时使用两者：

界面	使用
位于 3D 世界中的面板或控件	drawcall-ai/uikitml
面向 AR/VR 的应用中的任何 UI（即使是平面面板——它也会渲染为 3D 几何体）	drawcall-ai/uikitml
非 AR/VR 应用中的 2D HUD、菜单或叠加层	HTML/CSS

空间式和 XR UI 使用 drawcall-ai/uikitml 技能（npx skills add drawcall-ai/uikitml）：它提供采用严格类 HTML 标记编写的 pmndrs/uikit 界面，可进行验证、预览，并转换为 Three.js / R3F / IWSDK。非 XR 应用中的平面 HUD/菜单界面则是在画布上叠加普通 HTML/CSS——速度更快、功能齐全，并且在任何分辨率下都清晰；这种情况下无需使用 uikit。

要让 3D 对象（包括空间式 UI）响应点击和悬停，请使用 @pmndrs/pointer-events 包。

加载画面

3D 应用在显示第一帧之前要完成实际工作——加载模型、纹理、环境贴图、音频——在完成之前画布会一片空白，因此如果不加遮挡，玩家的第一体验就是冻结的黑屏。从一开始就显示加载画面（非 XR 应用中可在画布上叠加普通 HTML/CSS），呈现产品标识和加载进度；场景就绪后再将其淡出。这是 UX 的一部分，也是每次游玩时首先看到的内容，不应事后才考虑——设计标准应与其余 UI 相同，并根据实际加载阶段推进进度，而不是伪造一个固定计时器。根据加载完成情况控制画面显示，并使用计时器触发淡出，而非仅依赖 requestAnimationFrame——后台运行或无头模式下的标签页（例如捕获/验证运行）可能会暂停 rAF，导致加载画面永远停留在屏幕上。

根据元素尺寸调整

UI、画布、摄像机和后期处理应跟随渲染元素的实际尺寸，而不是只读取一次 window.innerWidth。加载画面显示期间，用户可能进入全屏、旋转设备、调整浏览器大小，或应用宿主更改 iframe 尺寸。如果只在异步加载完成后注册尺寸变化监听器，首个可玩的画面可能仍使用旧的画布缓冲区尺寸和摄像机纵横比，而 HUD 已铺满新的视口。

优先使用固定的全视口应用容器，并将画布样式设置为填满容器：

html, body { width: 100%; height: 100%; overflow: hidden; }
#app { position: fixed; inset: 0; width: 100%; height: 100%; }
canvas { width: 100%; height: 100%; display: block; }

画布创建后应立即注册尺寸监视，在等待大型资源加载之前完成。相比 window.resize，在画布或其容器上使用 ResizeObserver 通常是更可靠的信息来源，因为它还能捕获宿主/布局变化，这些变化不一定表现为普通的浏览器尺寸调整。每次尺寸更新时，都要同时调整所有与屏幕尺寸相关的渲染目标：渲染器后备缓冲区、摄像机纵横比/投影、后期处理合成器，以及任何固定像素的叠加画布（例如小地图）。保留 renderer.setSize(width, height, false)，让 CSS 控制显示尺寸；设备缩放比例可能变化时，也要更新像素比。fullscreenchange 和 visualViewport.resize 可作为辅助触发信号；它们应调用同一个尺寸调整函数，而不是重复实现逻辑。

检查方法很明确：在加载画面仍显示时触发尺寸调整或全屏切换，然后确认加载画面消失之前，画布客户端尺寸、画布后备缓冲区尺寸和摄像机纵横比都与当前视口一致。

像专业人士一样设计

目标是打造看起来专为这款产品精心设计的界面——游戏的 UI 应该有游戏 UI 的感觉，工具的 UI 应该有工具的感觉。常见的失败模式是千篇一律的“AI 应用”风格：它源于选择看似合理却毫无特色的模式，而不是做出深思熟虑的设计决策。像工作室负责人一样，为产品塑造独特个性。

把心思花在重要之处，其他地方保持简洁。 在用户会操作的少数元素上精雕细琢——主要操作、实时读数、焦点状态——让其余内容退居次要。处处装饰只会带来噪声；有意营造对比才是设计。渐进式呈现：只显示当前相关的内容，其余内容淡化或隐藏。

建立一套设计体系，并始终贯彻。 精心选择的配色、字体层级和一致的间距能体现品质；随意的局部样式则显得像 AI 生成。让设计与产品的世界观和基调相符。

字体。 避免使用默认字体栈（Inter、Roboto、Arial、system），也不要把等宽字体当作“技术感”的捷径。选择符合产品气质的字体，并通过字重和字号建立层级。（uikit 附带 MSDF 字体——参见 uikitml 技能。）

颜色。 选定一种主色，再搭配鲜明的强调色，不要让各种颜色平均分布、显得畏首畏尾。让中性色稍微偏向品牌色；避免使用纯 #000/#fff。远离 AI 配色——紫蓝渐变、深色背景上的青色、霓虹光效。

布局。 通过变化间距营造节奏（分组紧凑、留白充足）；相比所有内容都居中，左对齐通常更显设计感。优先利用留白、对齐、尺寸和对比，而不是添加界面装饰。不要把所有内容都塞进卡片，也不要重复使用完全相同的卡片网格。

动效。 几处精心设计的瞬间胜过持续不断的动画——一次编排得当的入场动画，或一次有意义的悬停／揭示效果。动效要快速、克制，并使用 ease-out 缓动；避免弹跳或弹性效果。在 HTML 中，动画应作用于 transform/opacity，而不是布局。

避免这些 AI 特征： 到处使用玻璃拟态、带通用投影的圆角卡片、霓虹光效、用表情符号充当图标、标题／指标上的渐变文字、装饰性迷你折线图、把模态框当作默认方案。（这些限制针对 UI 的装饰层——并不限制游戏世界本身的表现，因为泛光和自发光效果确实可以成为视觉风格的一部分；参见 world 和 postprocessing 技能。）

易读性与易用性。 确保对比度充足、字号舒适、焦点／悬停状态清晰；在空间 UI 中，交互目标要足够大，文字要能在远处读清。沉浸感永远不能凌驾于易用性之上。

粗糙感测试：如果有人瞥一眼就觉得“这是 AI 做的”，那就重新设计。这些是指导原则，不是牢笼——只要设计意图明确、符合产品气质，产品所需的任何配色、布局或动效都可以尝试。