Skip to content

yzsp-studio/mediakit-shared-suite / html

专门设计、生成和修改可直接在浏览器中打开的 HTML 页面或已发布的 html 链接。交付物以独立 .html 文件为主,可包含内联或本地 CSS、JavaScript,支持页面布局、视觉样式、交互效果、响应式适配、组件设计和内容展示。适用于静态网页、单页展示、活动页、原型页、HTML 模板及页面片段。不处理前后端工程、应用框架、服务端接口、数据库、用户系统、构建部署或运营数据。

references/design/3d-design.md

View on GitHub
# 3D 设计

不要为了「炫酷」强行使用 3D 场景,你会做成三维版的模板页。

在计划使用 3D 之前,你需要思考为什么需要第三个维度。只有三个理由成立:

- 要展示形体
- 要给出尺度
- 要让人自己选择视角

「想让它动起来」不是理由。

## 先判断要不要开 WebGL

主体本身是实体、形状承载信息(产品、建筑、器件、分子、地形),或者需要观者绕着看——这两种才值得开 WebGL。

其余情况用更轻的手段:

- 只想要「有深度的氛围」→ CSS 3D transform、等距投影、视差层。
- 数据可视化 → 除非第三个轴真的承载一个变量,否则一律 2D。
- 具象画面(人、物、场景)→ 走图片,见 `SKILL.md` 的图像素材规则。手搓的低多边形人物永远不如一张真实图片。

多页产物里放 3D 要更谨慎:每个场景都在占资源,移动端更紧张。

## 材质:先说清这是什么物质

从物质和成因出发,不从参数滑杆出发。落笔前先说清:这块表面是什么材料、经历过什么——磨损、氧化、潮湿、积灰、加工留下的纹路。然后让颜色、粗糙度、金属度、法线从同一段思考里面自然得出。

这几个通道必须描述同一块表面。各自挂一份互不相关的噪声,是程序化材质最常见的假:颜色在说这里有锈,粗糙度却说整块都一样光滑,法线又在讲第三个故事。凹处该积灰因此更粗糙、凸起该被磨亮因此更光滑——这种耦合才是真实感的来源。

金属度是二元的物理属性,不是光泽度滑杆。非金属给 0,金属给接近 1。中间值只出现在真的有金属与非金属混合的地方(锈蚀、氧化层、涂层剥落)。给塑料填 0.5 换「高级感」,得到的是一块灰橡皮。

粗糙度是信息量最大的通道。全场景一个均匀粗糙度,读起来就是塑料玩具。让它有空间变化,变化的依据来自上面那段成因。

透明与玻璃的实体感来自光穿过的路径长度,不来自降低 `opacity`。厚处更暗更饱和、薄边更亮,这个差异才让人读出体积。而且反射、折射和背景必须属于同一个光照世界——不一致时,透明物看起来像一层贴在场景上的滤镜。

别把物理现象降格成 RGB 装饰:彩虹色不等于衍射,半透明不等于玻璃,加一层紫色不等于次表面散射。做不到就选一个做得到的材质方向。

## 光照:先定关系,再定亮度

先定关系。三个角色各有职责:主光决定形体和投影方向;补光决定暗部是否还能读出结构;轮廓光或环境反射负责把主体从背景里剥出来。只给一个平行光的场景一定是死平的——这是「默认 three.js 场景」最明显的特征,比任何配色问题都刺眼。

亮度关系要属于同一个世界。「这里太暗就再加一盏」式的随手补光会互相补偿,最后高光炸白、暗部脏死。先想清这个场景的光从哪来,再给强度。

环境光是可信度的来源,不是可选项。完全不给环境光的物理材质会读成塑料。零资产条件下:室内或产品用程序化的 `RoomEnvironment` 过 PMREM 拿一套中性 studio 环境(不需要任何 HDR 文件);室外用程序化天空加主光,再给一个低强度的天空补光。

直射光和天空补光是两个独立的决定:直射决定形体,天空决定暗部仍然可读。把它们并成一个亮度调,就失去了对暗部的控制。

接触处必须有暗。没有接触阴影的物体一定在漂浮,这是最容易发现也最容易忽略的破绽。但环境遮蔽只用来收紧接触和缝隙,不给整幅画面抹一层灰——那是把「有 AO」做成了「画面变脏」。

色彩管理有三条不做就系统性翻车:

- 在线性空间里完成光照与发光关系,**从线性到屏幕的转换全程只做一次**。没有后处理时这件事由渲染器做;接了后处理就交给链末的输出 pass,同时关掉渲染器那一侧。两边都做,tone mapping 和 sRGB 编码就各叠了两次——画面会灰、会洗白,而且极难查,因为每一处单看都是对的。
- 曝光在 tone mapping 之前,不是之后。
- 不要用互相补偿的调色去掩盖光照错误。画面偏了先回去查光,别在末端加一层滤镜。

## 运镜:镜头是构图,不是取景框

镜头是作者化的构图。先决定主体在画面里占多大、留白留在哪、地平线在哪,再摆物体——不要先把世界摆满、最后拿相机去补救。

焦距是表达。窄一些(35–50 度)给形体和尺度感,画面稳重;70 度以上带明显透视变形,读起来像游戏引擎默认值。默认不要用 `fov` 75——那是库的默认值,不是选择。

用主体尺寸推导相机距离,不要给所有场景填同一个固定距离。换了模型就该重新算,而不是手调到「看起来差不多」。

换镜头要有叙事理由。一个段落一套镜头;滚动时持续漂移的相机是噪声,它让观者一直在重新定位,什么也看不清。

能不能自己转是个选择,但允许转就必须限位。能转到看见模型背面的空壳、能转到相机穿进物体内部、能转到主体跑出画面,都是没做限位。给极角和距离设上下限,让任何角度都是一个成立的构图。

正交投影不是「更技术」的选择——它抹掉深度线索。只有等距、工程感、示意图这类方向才用它。

## 动作与轨迹:让运动读出状态

动效要让人读出状态——接近、对准、展开、完成、分离——而不是让若干 transform 曲线各自永动。匀速自转是最典型的「没有状态」的动效:它第一秒和第一分钟没有区别,观者学不到任何东西,却一直在耗电。

一个编排好的时刻胜过满屏零散特效。

运动曲线按语义选:纯视觉参数的平滑用指数响应;只有需要表现质量和惯性的对象才用弹簧。而且弹簧必须收敛——视觉上已经静止、实际仍在微动的残余是噪声。

随机不等于生动。碎屑、粒子、漂浮物的运动方向要继承对象已有的动势和因果关系;凭空的随机速度看起来像屏保。

抖动只能是受控的强调层,有明确的边界值,且和真实轨迹分开。让抖动替代运动本身,或者大到污染观者对路径的判断,都是错的。

可读性优先于物理真实。为了让两个物体在画面里分得开而调整它们的分离方向,是正确的取舍,不是作弊。

## 反 3D slop

当下 AI 生成 3D 页集中在这几种长相上:

1. 深蓝紫渐变背景配星空点阵;
2. 匀速自转的低多边形球体或二十面体;
3. 跟随鼠标做视差的漂浮粒子;
4. 过曝 bloom 加全黑镜面地板,再来一束没有动机的体积光;
5. 霓虹描边的 wireframe;
6. 全场景共用一个物理材质,只换 `color`;
7. 相机永远停在 45 度俯视、三分之一距离处。

这些对某些 brief 站得住脚,但它们是默认值而非选择,而且不看题材就冒出来。brief 钉死了方向的地方照办;brief 留出自由的地方,别把自由花在这些默认值上。

## 首帧与自检契约

这一节全部从自检脚本的实际行为推导,是 3D 产物最容易翻车的地方。

**首帧必须在页面 `load` 之前渲染完。** 自检的就绪判定只等字体、图片和布局稳定,不等 WebGL,超时后照截。把首次渲染推进 `IntersectionObserver`、滚动回调或定时器,自检就会截到一张空白 canvas。

**如果 3D 是首屏的签名元素,就不要懒加载。** `visual-techniques.md` 的「懒加载、首屏别拉」只适用于首屏之外的 3D 区块——首屏懒加载会让自检在资源请求发起前就判定页面已静止。

**`reduced-motion` 降级必须仍渲染一帧静态画面。** 自检会强制开启 reduce。降级路径只停动画循环,不跳过渲染;直接隐藏 canvas 或干脆不 render,等于把自检和真实的无障碍用户一起推到空白页。

场景就绪后置一个显式标记,自检可以用 `--eval` 读它来确认渲染真的发生过。不要把「截到图了」当成「渲染完成了」的证明。

黑屏是 3D 最隐蔽的失败:canvas 存在、没有 console error、截图也拿到了,但画面全黑或全空。所以交付前必须**实际看截图**,确认主体可见、有明暗层次——只看报告没报错不算自检过。

桌面(1440×900)和移动(390×844)两个视口是分别重新加载的,所以初始化时读窗口尺寸是安全的。但仍然要处理 `resize`,因为真实用户会改窗口大小。

## 性能与降级

- 像素比设上限,2 以内,移动端更低。视网膜屏上按全分辨率渲染复杂场景会掉帧发烫。
- 面数和 drawcall 要有预算意识:网页级场景不需要几十万面。重复对象用实例化,不要复制几百个 mesh。
- 帧率不达标时降质量档(关阴影、降像素比、减采样),不要降帧。卡顿比画质差更毁体验。
- 页面切到后台时停掉渲染循环,别在不可见的标签页里烧电。
- 后处理按需开。直接光、阴影、环境光、单次 tone mapping 这四件事决定画面品质的大部分;bloom、AO、调色是加成不是前提。只有以发光、霓虹、能量体、电影感氛围为核心的方向,才值得付后处理那一层的复杂度和性能成本。
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall