Communitygithub.com

沉浸式网页开发

构建沉浸式、电影般的“未来网站”体验,同时保持快速和可访问性——浏览器中的3D场景(Three.js, React Three Fiber, WebGL, WebGPU)、着色器(GLSL, TSL)、滚动驱动的故事讲述、电影级动画和页面过渡,以及从Blender到浏览器的路径(glTF, Draco, meshopt, KTX2, 烘焙光照)。当用户要求3D、WebGL、着色器、粒子、3D产品查看器、滚动动画、视差、固定或粘性滚动故事、滚动叙事、动画或交互式英雄区、视图过渡、沉浸式、电影感或“获奖”网站,或在网站、桌面应用(Electron, Tauri)、移动应用或仪表板中实现类似游戏、科幻或电影感时使用。也用于加速现有的3D或动画页面,添加减少动画和无WebGL的降级方案,或将Blender模型带入页面。与ui-craft技能配合使用,后者负责布局、排版、颜色和组件,而本技能则添加场景、着色器和动效叠加。

沉浸式网页开发 是什么?

本技能(immersive-web)专为构建高性能、可访问的沉浸式Web体验而设计,确保效果不牺牲内容优先级或用户体验。它提供了一套严格的规则和工作流程,用于在浏览器中集成3D场景、着色器(GLSL/TSL)和滚动驱动的故事讲述,主要使用Three.js和React Three Fiber等库,但也涵盖了使用`<model-viewer>`或纯CSS的轻量级方法。关键在于分层方法:始终先构建确保内容优先的HTML/CSS基础(由配套的ui-craft技能处理),然后将沉浸式层作为渐进增强叠加,并设计强健的降级方案。该技能强调性能预算、可访问性(支持减少动画、无WebGL和键盘导航)以及通过“沉浸式阶梯”(从0级静态到3级故事)进行节制,其中签名时刻经过精心设计。它提供全面的清单、性能目标、主题集成指南(确保UI和3D场景使用统一的风格token)以及针对场景设置、相机、光照、着色器、滚动叙事、电影运动和Blender导出管道的特定引用文档。主要平台支持包括Web(通过Three.js、React Three Fiber、WebGL/WebGPU、`<model-viewer>`、GSAP)以及桌面应用(如Electron和Tauri)。

兼容平台~Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/najeebafridi/ui-craft/tree/HEAD/skills/immersive-web

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

沉浸式网页开发 是做什么的?

如何构建感觉像最好的电影和游戏、加载像普通页面、并且不落下任何人的3D、着色器和滚动驱动体验。

此技能是其中一层。 ui-craft技能(同一插件)负责常规界面设计:布局、层级、排版、颜色、组件、表单、状态。使用它来完成所有这些,并且不要在此重复。此技能添加的是其上的那一层:场景、光照、材质、着色器、相机、滚动和电影式动态。两者都读取相同的主题token,因此一个主题驱动页面和场景(references/theme-bridge.md)。

诚实的限制。 你可以导演一个场景,为其打光,移动相机,编写着色器,并接入模型。你无法凭空雕刻出电影级别的3D艺术。通过简单的几何体、着色器、排版和光照进行创作,或者使用团队提供的模型。切勿用主题的粗糙绘图来敷衍了事。

1. 九条硬性规则

违反其中一条,即使看起来再好,工作也未完成。

  1. 内容优先。 标题、正文、链接和按钮是真实的HTML,在任何脚本运行之前即可读取。场景是叠加其上的,并且可以在不造成损失的情况下消失。切勿将页面的文字绘制到画布中。切勿在CSS中使用opacity: 0隐藏内容以等待脚本来揭示它。
  2. 每个效果三种状态。 完整;减少动画(一帧静态图像或一个短淡入:prefers-reduced-motion,以及在原生应用中检查操作系统设置);无GPU(在WebGL或WebGPU缺失、失败或上下文丢失时显示的占位图像或CSS/SVG艺术)。首先设计两个降级方案。它们也是最先加载的内容。降级方案是同一幅画面的更安静版本:相同主题、相同角度(从场景本身生成的占位图像),对于数据场景,则是以平面方式绘制的相同数据。空白框、纯渐变或“图片待更新”都是失败的。
  3. 构建前确定速度预算(§4)。页面文本首先渲染;引擎随后加载。在手机上,场景的成本应低于内容。
  4. 每页一个标志性时刻,并让它有意义。 一个场景,一个想法,彻底完成。其他一切保持安静。处处都是效果看起来像模板并使人疲惫。克制限制的是效果的数量,而非其强度:这一个时刻是事件,属于这个产品(水壶正在倒水;随着眼睛适应,天空布满星星),其舞台效果足够大胆,以至于人们会向朋友描述它。一个仅随滚动旋转的对象不算一个时刻。
  5. 绝不劫持滚动。 浏览器滚动;你只读取位置。没有改变的速度或方向,没有滚轮劫持,没有虚假的滚动条。使用position: sticky进行固定,保持简短(不超过5屏),并提供跳过的途径。
  6. 文字和场景永不重叠。 在每个滚动位置,文字都位于主题旁边或其自身的表面上,绝不能横跨主题。覆盖在场景上的导航和按钮需要背景遮罩或表面。检查每个滚动位置的截图,而不仅仅是第一个。
  7. 键盘和屏幕阅读器可访问所有真实内容。 Tab键顺序遵循阅读顺序。装饰性画布设置为aria-hidden="true";有意义的画布需要在其旁边有文本等价物。任何可以通过拖拽场景完成的操作,也必须能通过按钮完成。
  8. 动效会静止,声音需等待,不闪烁。 环境动效在5秒内稳定下来,或具有可见的暂停控制。声音默认关闭,直到用户请求。每秒闪烁不超过3次。任何内容都不能在屏幕外或隐藏标签页中运行。
  9. 原创且已获授权。 学习一种风格的语言;切勿复制某个产品的外观、模型、角色、标志或声音。仅使用你自己制作的或具有清晰许可证的资源(像Poly Haven和ambientCG这样的CC0库是安全的),并记录每一个。

2. 工作流程(每次都这样做)

  1. 构建前先观察。 找到主题:theme.css、DESIGN.md(来自ui-craft Studio)、token、Tailwind配置、品牌颜色。阅读--immersive变量和简报中的“沉浸式和动效”部分(如果存在):它们说明了所有者选择的强度。检查技术栈(纯HTML、React、Vue、应用外壳)以及任何已提供的3D资源。如果没有主题,首先使用ui-craft来选择方向。

  2. 从§3的阶梯中选择级别。 如果主题指定了级别,则采用它;否则,选择能够实现该想法的最低级别。第3级很少使用。

  3. 选择能完成任务的最轻量工具。

    需求使用成本
    揭示效果、无视差的滚动效果、页面过渡仅CSS:滚动驱动动画、position: sticky、视图过渡0 KB
    平坦的动态纹理、线条、场、2D图形Canvas 2D或SVG,或单个三角形上的一个片段着色器(原始WebGL,无库)2-5 KB
    显示一个可供用户旋转的3D模型<model-viewer>约250 KB,懒加载
    真实场景:多个对象、灯光、移动相机three.js(React应用:React Three Fiber)使用动态import()加载150-180 KB gzip,懒加载
    CSS无法表达的、与滚动绑定的时间线GSAP ScrollTrigger(免费但不开源:加载它,切勿复制代码)或 Motion25-45 KB
    最新的GPU特性WebGPU作为对WebGL路径的升级,而不是单独使用-

    不要默认添加平滑滚动库。如果简报要求使用,它必须在减少动画模式下自行关闭。

  4. 编写沉浸式简报(将其添加到ui-craft设计简报中),在编码之前:

    级别: 2 标志性(主题说 --immersive: 2)        技术栈: 纯 HTML + three.js,懒加载
    标志性时刻(一个事件,而非转盘):在节拍3时,水壶倾斜,一股细流倒出,保持水线
    场景:一个哑光陶瓷水壶,位于页面背景上的一片光晕中;来自左上方柔和主光,温暖边缘光
    文字通道:桌面端左侧栏中的文案,手机端固定在场景下方;水壶永远不与之重叠
    相机:类似35mm视角,略高于视线,不自行移动         节奏:柔和(--dur-slow 400ms)
    节拍(仅第3级):1 整个水壶 - 2 壶嘴特写 - 3 倒水 - 4 放置在桌子上
    减少动画:每个节拍一张静态渲染图,交叉淡入        无GPU:相同场景、相同角度的占位图像
    预算:文本先渲染;引擎之后;手机端场景小于1.5 MB;触摸屏像素比1.5
    
  5. 按此顺序构建。 (a) 使用ui-craft将整个页面构建为纯HTML和CSS,在场景位置放置占位图像或CSS降级方案。它必须已经是一个好页面。 (b) 场景外壳:assets/scene-shell.js提供懒启动、静态帧、降级方案、屏幕外暂停、像素比限制、上下文丢失恢复。 (c) 主题桥接:assets/theme-bridge.js使颜色、圆角半径和节奏来自token。 (d) 场景本身,以最简单形式呈现。 (e) 动效和滚动。 (f) 打磨:光照、材质、颗粒感、时间。assets/starter.html是一个已完成了(a)-(c)的工作页面;替换其占位符场景。

  6. 检查,然后查看。 运行 node <skill-dir>/scripts/immersive-check.mjs page.html。它会以五种方式加载页面(桌面端、手机端、减少动画、无WebGL、无JavaScript),测量重量、绘制调用、像素比、原生滚动和暂停,并保存截图。对于应用窗口(Electron, Tauri, 已登录的Web应用),添加 --app 以跳过无JavaScript测试。打开每一张截图。 修复失败的内容。最仔细地查看三处:滚动中间(是否有任何文字与主题交叉?)、手机屏幕中间(场景和文字在同一屏内,没有空白带?)以及无WebGL的那一张(相同画面,还是空洞?)。从场景本身生成占位图像:--poster hero-poster.png 从桌面端渲染(--scheme light 或 dark 选择主题)保存场景的截图框,准备用作降级图像。然后运行ui-craft的 ui-audit.mjs 检查对比度、触摸目标和排版,并对手机端像桌面端一样严格评判。最终检查:references/accessibility-fallbacks.md 清单。

3. 沉浸式阶梯

每个产品都位于一个梯级上。主题可以将其表示为 --immersive: 0-3;每个ui-craft方向(共16个)都设置了一个默认值(references/theme-bridge.md)。

级别是什么适合不适合
0 静态无3D、着色器或滚动效果。仅常规界面动效财务工具、管理后台、政府、健康表单、密集仪表板、任何全天使用的应用-
1 点缀一个安静生动的细节:一种材质、一个缓慢的着色器纹理、一个视图过渡。它在几秒后静止。无滚动驱动的场景SaaS应用、文档、大多数产品UI、桌面和移动应用用户感到焦虑或匆忙的任务
2 标志一个英雄时刻:一个对象或着色器响应鼠标指针或首次滚动。然后是普通页面落地页、产品页面、作品集、引导页、启动屏幕用户每天重复访问的页面
3 故事一个滚动驱动的序列,包含3-5个节拍,具有一个持续的场景发布、活动、编辑专题、博物馆和品牌故事应用、结账、任何有任务的操作

阶梯的规则:级别是上限,而不是目标。使用频率会降低级别:人们看到屏幕的频率越高,级别就越低。任务会降低级别:当用户在付款、签名或解决问题时,使用0级。不确定时,降低一个级别并更好地完成它。

4. 预算

工作目标。测量,不要猜测。带*的数字是合理的默认值,而非公布的硬性限制。

项目手机桌面
最大内容绘制(必须是文本或占位图像,绝不能是画布)2.5秒或更少2.5秒或更少
首次渲染前请求的脚本压缩后小于170 KB相同
引擎(three.js约180 KB gzip)首次渲染后,动态 import(),仅当场景接近视口时相同
场景首次加载资源:引擎+模型+纹理 *小于1.5 MB小于4 MB
主角模型(GLB,已压缩) *小于2 MB,20-60k 三角形小于5 MB,最多100k
纹理1024 px;仅主角使用2048;内存优先使用KTX22048;仅特写使用4096
像素比上限1.5,慢速时降至1上限2
每帧绘制调用 *小于100小于300
实时光源1个主光(+环境光);1个1024分辨率阴影贴图,或烘焙/模糊阴影1-3个;阴影贴图最多2048
后处理通道0-11-3
帧时间稳定60 fps;在降至30 fps前降低画质60 fps
滚动故事3-5个节拍,每个100-150vh,固定部分不超过5屏 *,提供跳过链接相同
预加载器无;页面在1-2秒内可读,场景在准备好时淡入相同

一张2048像素的纹理在解压后大约消耗22 MB的显存,无论其文件大小是多少,除非是KTX2格式。详细信息和降级顺序:references/performance.md。

5. 一个主题驱动每一层

  • 从token读取颜色(--bg、--surface、--accent、--accent-soft、--text、--border...),切勿在着色器或材质中硬编码十六进制色值。assets/theme-bridge.js 中的 readTheme() 返回每种颜色的线性RGB(用于光照计算)和sRGB(用于平面绘图),watchTheme() 在明/暗主题切换时重新读取。
  • 场景位于页面背景之上:透明画布,或与 --bg 相同的纯色。无可见矩形,无第二背景色。
  • 在3D中,强调色也应稀有:一个对象、一束光、一条线。大部分保持中性。
  • 主题的形状属性延续:圆角半径变成倒角和边缘半径;深度风格变成阴影风格(极细线:细轮廓,几乎无阴影;柔和:宽而柔的接触阴影;锐利:更紧致更有光泽;唇边:硬偏移边缘;平面:无)。
  • 动效token设定节奏:--dur-* 和 --ease-out 影响相机移动和滚动缓动(桥接中的 bezier()),因此一个“即时”工具和一个“缓慢”的奢侈品牌使用相同的代码会有不同的动效。仅在主题曲线出现超调时才添加回弹。
  • 排版保持为HTML,使用 --font-display 和 --font-sans 字体,叠加在画布之上或旁边。

6. 工艺简述

场景与相机 (references/scene-camera.md)

  • 一个主题,一个清晰的轮廓,大量留白。首先为手机的纵向框架构图。
  • 长焦镜头(视场角20-35度)使对象更美;广角镜头会变形。相机移动缓慢且有理由,或者根本不移动。
  • 按需渲染。不变化的场景不绘制任何内容。

光照与材质 (references/materials-lighting.md)

  • 一束来自上方的关键光(与UI相同单一光源)、一个柔和的补光、一个边缘光以将主体与背景分离。光照绝不是纯白色;阴影也绝不是纯黑色。
  • 为主体添加地面接触阴影,否则它会显得漂浮。
  • 在判断任何内容之前先设置好色彩空间。太暗或褪色是色彩空间错误,而不是光照问题。
  • 当场景是静态时,将光照烘焙到纹理中。这是最经济的光照方式。

着色器 (references/shaders.md)

  • 着色器是有任务在身的材质、光照或纹理。不是墙纸。
  • 调色板来自2-4种主题颜色,在OKLab颜色空间中混合以保持中间调干净。没有彩虹色。
  • 添加2-4%的颗粒感以隐藏柔和渐变中的色带。保持片段着色器在手机上廉价:少量纹理读取,无长循环。

滚动故事讲述 (references/scroll-storytelling.md)

  • 每个节拍是一个想法,配有一行真实文本。如果节拍无话可说,则删除它。
  • 文本正常滚动;场景保持静止(粘性)并随之变化。清除位置,而非时间。
  • 减少动画将电影变成幻灯片:每个节拍一张静态图。

电影级动效 (references/cinematic-motion.md)

  • 在想法之间切换或溶解;在单个想法内移动。停留在重要的内容上。缓动是表演:重量感,而非装饰。
  • 界面动效保持ui-craft的时长(100-300 ms)。场景和相机移动需要600-1200 ms。页面过渡200-500 ms,并且URL、后退按钮和焦点继续保持工作。

从Blender到浏览器 (references/blender-pipeline.md)

  • 仅使用Principled BSDF着色器,将其余部分烘焙,导出GLB,然后压缩:gltf-transform optimize、meshopt或Draco、KTX2纹理。检查文件…

… [为翻译而截断]

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

相关技能