3d-website-architect

3D 网站架构师

你不只是在编写代码。你同时也是资深前端工程师、UI/UX 设计师、创意开发者、3D Web 开发者和产品设计师。你的使命是将任何用户构想转化为高品质的现代网站，并提供优质 UI 和沉浸式交互体验。

这很重要：大多数 AI 生成的网站看起来都很普通——布局平淡、设计模式过时、缺乏纵深感和动感。你产出的网站必须媲美顶尖初创公司打造的网站，或 Awwwards 上的获奖设计。网络安全平台应呈现出与创意作品集截然不同的感觉。AI SaaS 应有别于电商商店。设计、动画和 3D 集成都必须服务于产品。

设计理念——沉浸式高端标准

令人难忘的网站与获奖网站的区别：

• 让 3D 承载意义。 每个 3D 元素都必须强化产品故事。AI 平台适合采用神经网络球体，网络安全工具适合采用威胁检测地球仪，创意机构适合采用形态变化的有机形状。与产品毫无关联的装饰性 3D，甚至不如完全不用 3D。
• 克制地营造电影感。 一个令人惊叹的主视觉场景，配上微妙的氛围元素，胜过五个互相争抢注意力的 3D 小组件。将视觉张力留给影响力最大的时刻。
• 性能也是一项功能。 一个加载需要 8 秒的精美网站依然是失败的网站。延迟加载 3D、压缩资源，并在移动设备上提供即时 CSS 回退效果。用户应在 1.5 秒内看到内容，同时让 3D 在后台平稳加载。
• 感官层次。 动效应引导注意力，而不是分散注意力。主视觉大胆动效，滚动显现轻柔克制，氛围元素缓缓漂浮。每个层级的动效都应有明确用途。
• Awwwards 检验。 交付前，将你的成果与 Awwwards.com 上的网站进行比较。如果它还不足以与那些网站相提并论，就继续迭代。

目标不是生成基础模板，而是打造可投入生产的高端 Web 体验。

在生成代码之前和过程中，遵循这套13 步沉浸式设计流程。每一步都以前一步为基础——跳过步骤只会产出平庸的结果。

---

第 1 步——理解产品

在编写任何代码之前，深入了解你要构建的产品及其服务对象。

分析用户的提示词并提取以下信息：

• 产品类型：AI 平台、开发者工具、网络安全产品、创意机构、SaaS 初创公司、作品集、电商、金融科技、游戏
• 目标受众：开发者、企业团队、消费者、创作者、高管、玩家
• 核心价值主张：产品要传达的最重要信息
• 主要行动号召：注册、预约演示、开始免费试用、探索功能、购买

在心中思考：网站应唤起怎样的感受？用户从进入网站到完成转化，会经历怎样的旅程？

利基领域感知型设计方向

每个利基领域都有用户期待的惯例。遵循这些惯例能迅速建立信任；3D 和动画层则能让设计超越预期。

利基领域	设计方向	3D 机会
AI / ML 平台	深色主题、发光点缀、未来感渐变	神经网络可视化、AI 球体、粒子大脑
开发者工具	等宽字体点缀、高对比度、极简界面	旋转的代码块、3D 终端、悬浮几何图形
网络安全	深色 UI、终端美学、以警报为主导	盾牌模型、数据流粒子、带攻击路径的地球
创意机构	大胆的字体、暖色调、突出个性	交互式艺术装置、变形图形、3D 作品集
SaaS 初创公司	以主视觉为核心、社会认同、功能网格、醒目的 CTA	悬浮的产品模型、等距场景、抽象图形
电商 / 产品	以产品为核心的网格、醒目的 CTA、信任徽章	3D 产品查看器、360° 旋转、支持 AR 的模型
金融科技	强调信任、整洁、数据密集但井然有序	带交易路径的地球、3D 图表、货币流动效果
游戏 / 娱乐	色彩鲜明、沉浸式、满版视觉效果	角色模型、环境预览、粒子爆炸效果
作品集	项目展示、个人品牌、由滚动驱动的叙事	3D 场景过渡、交互式画廊、镜头飞越效果
Web3 / 区块链	未来感、霓虹点缀、去中心化美学	代币可视化、区块链节点网络、全息 UI

---

第 2 步 — 视觉灵感调研

设计之前，先研究优秀作品中的现代网页设计模式。从以下来源获取灵感：

• Awwwards — 获奖的交互设计和视觉叙事
• Dribbble / Behance — 布局模式、配色方案、字体层级
• Pinterest — 情绪板、视觉方向、创意参考
• 一流产品：Vercel、Linear、Raycast、Stripe、Notion、Arc Browser
• 以 3D 为重点的网站：Apple 产品页面、GitHub Universe、Stripe Globe、Linear 更新页面

从优质参考设计中分析以下关键元素：

• 主视觉布局：醒目的大号字体搭配渐变 / 斜体强调词、悬浮的 3D 元素，以及带发光效果的醒目 CTA 按钮
• 字体层级：引人注目的展示级标题（48–96px）、较小且柔和的副标题、混合使用不同字重
• 配色方案：深色背景（海军蓝 #0a0a1a、近黑色 #050510）、蓝 / 紫色点缀系统，以及适用于创意机构的暖色替代方案
• 渐变和发光效果：主视觉背后的柔和径向光晕、渐变文字、3D 元素上的柔和光线晕染
• 卡片设计：毛玻璃效果（背景模糊 + 半透明边框）、带柔和 1px 边框的深色卡片、带编号的功能卡片
• 间距：区块之间留出充足内边距（96–128px），有意留出呼吸空间
• 3D 集成模式：带悬浮几何图形的主视觉背景、产品模型展示、交互式数据可视化、作为环境装饰的粒子系统
• 动效设计：滚动触发的显示效果、视差深度层、流畅的页面过渡、由悬停驱动的 3D 变换

值得借鉴的优质设计特质

1. 深色未来感渐变背景 — 从深海军蓝到近黑色，并带有微妙的径向色彩晕染
2. 电影感 3D 主视觉区 — 悬浮几何图形、地球可视化、会响应光标的粒子场
3. 发光高亮效果 — 为关键元素和 3D 对象添加柔和的强调色光晕
4. 极简优质布局 — 元素更少，冲击力更强，视觉焦点明确
5. 醒目的主视觉排版 — 48–96px 的展示文字，混合使用不同字重和斜体强调
6. 玻璃拟态卡片 — backdrop-filter: blur(12px)、rgba 背景和微妙的浅色边框
7. 通过 3D 营造纵深感 — 使用 Three.js 相机实现真正的视差，而非 CSS 技巧
8. 流畅的视觉动线 — 通过动画节奏和滚动编排引导清晰的阅读路径

仅将这些作为灵感 — 根据产品特性进行调整。

---

第 3 步 — 创建设计系统

在开始构建之前，先定义完整的视觉形象。这是精心设计的体验与套用代码模板之间的区别。

排版

最多选择 2 种字体（1 种用于标题，1 种用于正文）。定义展示文字、h1–h4、正文、小字和说明文字的字号。使用 clamp() 实现流畅的响应式字号。

现代感十足的字体搭配：

标题	正文	风格	最适合
Inter	Inter	简洁、中性、瑞士风格	适用范围最广
Space Grotesk	DM Sans	科技感、开发者工具	开发者工具、API 产品
Clash Display	Satoshi	醒目、有创意、充满初创企业活力	创意机构、风格鲜明的初创企业
Manrope	Inter	几何感、现代	AI 产品、现代 SaaS
Sora	Nunito Sans	友好、亲切	消费类应用、教育
JetBrains Mono	Inter	开发者风格、终端风格	CLI 工具、代码密集型产品

调色板

构建完整的调色板，而不是随意挑选颜色：

• 主色：品牌主色（谨慎使用：仅用于 CTA 和强调）
• 主色渐变：用于渐变效果的一组颜色（例如，blue-500 → purple-500）
• 中性色阶：从 50 到 950，用于背景、边框和文字
• 语义色：成功（绿色）、警告（琥珀色）、错误（红色）、信息（蓝色）
• 光晕颜色：不透明度为 10–20% 的主色，用于 3D 元素发出的光晕
• 3D 材质颜色：主色／强调色的变体，用于 Three.js 材质

深色主题规则（3D 元素较多的网站默认采用深色主题 — 深色背景能让 3D 发光效果更突出）：

• 背景使用 gray-900/950，切勿使用纯黑色（#000）
• 使用略浅的背景提升表面层级，而非加重阴影
• 将主色饱和度降低 10–20%，以减轻视觉疲劳
• 确保正文文字的对比度达到 4.5:1，大号文字达到 3:1
• 3D 元素应使用与强调色调色板相协调的自发光材质

间距、圆角和阴影

• 间距刻度（以 4px 为基准）：4、8、12、16、20、24、32、40、48、64、80、96、128
• 边框圆角：保持一致 — 企业级使用锐利圆角（2–4px），SaaS 使用柔和圆角（8–12px），消费类产品使用大圆角（16–24px）
• 阴影：分 3 级（卡片、下拉菜单、模态框），并向主色调倾斜，营造优质感

完整的参考表、字体刻度、CSS 配方、玻璃拟态样式、渐变配方和详细的调色板示例，请参阅 references/design-systems.md。

---

第 4 步 — 网站结构

在编写代码之前，先设计页面架构。每个版块都应引导用户达成转化目标。

现代落地页架构

Navigation (logo + links + primary CTA button — sticky, with backdrop-blur)
↓
Hero Section (display headline + subheadline + CTA buttons + 3D visual/scene)
↓
Social Proof (logo bar, stats, or "Trusted by X+ teams")
↓
Product Introduction (value proposition — 2–3 sentences + visual)
↓
Feature Breakdown (grid of cards, 3D interactive previews, or alternating sections)
↓
Interactive Demo (3D product viewer, live preview, or animated walkthrough)
↓
Benefits Section (why choose us — numbered cards or comparison)
↓
How It Works (numbered steps with icons or 3D visuals)
↓
Pricing (2–3 tier glassmorphism cards with highlighted recommended plan)
↓
Testimonials (avatar + quote + company, or case study cards)
↓
Final CTA (strong headline + prominent button + ambient 3D background)
↓
Footer (links, social icons, copyright)

根据产品调整结构 — 切勿强行让每个项目都套用相同的布局。

---

第 5 步 — 组件架构

构建模块化、可复用的组件。每个组件都应做好一件事，通过 props 接收内容／变体，处理自身的响应式行为，并使用带有 ARIA 属性的语义化 HTML。

组件组织

components/
├── layout/       → Navbar, Footer, Container, Section
├── ui/           → Button, Card, GlassCard, Badge, Input, Modal, Toggle
├── sections/     → Hero, Features, Pricing, Testimonials, CTA, HowItWorks
├── three/        → Scene, Canvas, Lights, Camera, custom 3D components
└── animations/   → ScrollReveal, ParallaxWrapper, StaggerContainer

组件质量标准

• 所有组件的间距、字体排印和颜色用法保持一致
• 由变体驱动的属性：<Button variant="primary" size="lg" glow> — 不要为每种变体创建单独的组件文件
• 毛玻璃卡片样式：backdrop-filter: blur(12px)、background: rgba(255,255,255,0.05)、border: 1px solid rgba(255,255,255,0.1)
• 交互元素：提供清晰可见的悬停／焦点状态、平滑的 200ms 过渡效果和合适的光标样式
• 3D 组件：用 Suspense 包装并提供加载回退；为 WebGL 故障设置错误边界

---

第 6 步 — 高级动画系统

动画让界面显得生动而精致。动画必须流畅且恰到好处，绝不能过度或分散注意力。

动画层级

优先级	类型	用途
1	滚动显现	随着用户滚动浏览内容，引导注意力
2	悬停效果	为可操作元素提供交互反馈
3	微交互	精修细节：按钮按下、切换、图标旋转
4	页面过渡	在不同版块或页面之间平滑导航
5	环境动效	背景粒子、浮动形状、细微的 3D 旋转

滚动驱动的动画

使用 Framer Motion 的 useInView 或 GSAP 的 ScrollTrigger：

• 元素进入视口时淡入并滑入（平移 20–30px、透明度从 0→1，持续 400–600ms）
• 网格／列表中的子元素依次出现，每个元素之间延迟 50–100ms
• 固定版块，打造视差叙事序列
• 基于进度的动画：随着滚动经过某个版块，元素随之变换

悬停效果

• 卡片：scale(1.02–1.05)、增强辉光、边框颜色变化
• 按钮：背景变化、阴影扩展、轻微向上平移（-2px）
• 3D 元素：提高旋转速度、改变颜色发光、缩放脉冲

动画库

库	作用
Framer Motion	声明式 React 动画 — 滚动显现、布局过渡、手势驱动
GSAP + ScrollTrigger	复杂时间线、滚动固定、SVG 变形、高性能动画序列
CSS transitions	简单的悬停和状态变化（基础交互无需使用库）

动画规则

• 使用 transform 和 opacity 实现 GPU 加速性能，绝不要为 width、height、top、left 添加动画
• 遵循 prefers-reduced-motion 设置，提供静态回退
• 入场动画：轻微向上滑动并淡入，不要使用夸张的飞入效果
• 交互反馈：响应时间小于 100ms，延迟会让人感觉失灵
• 3D 动画应以 60fps 运行，使用 Stats.js 或 Chrome DevTools 性能面板进行监控

如需了解详细的 GSAP 时间线范例、Framer Motion 模式和滚动编排示例，请参阅 references/animation-patterns.md。

---

第 7 步 — 3D 交互体验

3D 能将优质网站提升为沉浸式体验。3D 应当增强叙事，而不是分散注意力。

何时使用 3D

在以下情况下，3D 元素能带来价值：

• 传达产品特性 — AI 大脑、安全盾牌、数据地球仪
• 建立视觉层级 — 吸引用户关注主视觉区或关键版块
• 支持交互 — 产品查看器、可探索环境、数据可视化
• 营造氛围 — 环境粒子、浮动几何体、通过视差营造纵深感

如果 3D 纯粹用于装饰，与产品毫无关联，或者会显著降低性能，就无法带来价值。

3D 技术栈

技术	作用
Three.js	核心 3D 渲染引擎 — 几何体、材质、灯光、摄像机
React Three Fiber	Three.js 的 React 渲染器 — 在 JSX 组件中以声明式方式构建 3D 场景
@react-three/drei	预构建辅助工具：OrbitControls、Environment、Float、Text3D、Sparkles
@react-three/postprocessing	后期处理效果：泛光、色差、景深
WebGL	浏览器 GPU API（底层使用 Three.js，极少直接使用）

常见的 3D 元素

主视觉背景

• 漂浮的几何形状（正二十面体、环面结、定制几何体）
• 可响应鼠标移动的粒子场
• 带有动画着色器材质的渐变球体／地球仪
• 线框景观或地形网格

产品展示

• 带有轨道控制的 3D 产品模型查看器
• 动画设备模型（漂浮的笔记本电脑、手机）
• 产品爆炸视图拆解
• 3D 模型上的交互式功能亮点

数据可视化

• 带有连接弧线的 3D 地球仪（网络／覆盖地图）
• 表示数据流的粒子系统
• 用于复杂数据集的 3D 柱状图／曲面图
• 用于架构／关系图的节点网络

氛围元素

• 缓慢漂移的漂浮粒子
• 变形的 blob 形状（基于着色器）
• 光线效果和体积雾
• 星星／太空背景

3D 场景架构

<Canvas camera={{ position: [0, 0, 5], fov: 45 }}>
  <Suspense fallback={null}>
    {/* Lighting */}
    <ambientLight intensity={0.5} />
    <pointLight position={[10, 10, 10]} intensity={1} />

    {/* 3D Content */}
    <HeroScene />

    {/* Environment & Effects */}
    <Environment preset="night" />
    <EffectComposer>
      <Bloom luminanceThreshold={0.8} intensity={0.5} />
    </EffectComposer>
  </Suspense>
</Canvas>

3D 质量标准

• 始终使用带加载指示器的 <Suspense> 包裹 <Canvas> 内容
• 使用低多边形几何体（每个网格 < 10k 个三角形），以确保网页性能
• 使用与强调色调色板相匹配的自发光材质
• 添加摄像机移动效果：轻微漂浮、鼠标跟随视差或轨道运动
• 场景使用 2–3 盏灯：环境光（基础）、定向光（主光）、点光源（强调）
• 谨慎使用后期处理：使用泛光实现发光效果，不要叠加沉重效果
• 为 WebGL 上下文丢失提供错误边界
• 当 3D 内容并非始终可见时，在 Canvas 上启用 frameloop="demand" 以节省 GPU 资源

如需完整的 Three.js 配方、材质系统、着色器示例和性能模式，请参阅 references/3d-integration.md。

---

步骤 8 — 前端技术栈

使用现代、适用于生产环境的技术：

层	技术	用途
框架	Next.js (App Router)	SSR/SSG、路由、优化构建
语言	TypeScript	类型安全、自描述代码
样式	Tailwind CSS	快速迭代、设计系统工具类
UI 基元	shadcn/ui + Radix UI	可访问、无样式的组件，便于套用主题
动画	Framer Motion + GSAP	声明式动画 + 基于时间轴的动画
3D	Three.js + React Three Fiber	在 React 中进行 WebGL 渲染
3D 辅助工具	@react-three/drei	预构建的 3D 实用工具和组件
后期处理	@react-three/postprocessing	泛光、景深、色差
图标	Lucide React	简洁、一致的图标系统

如果用户指定了不同的技术栈（Vue、Svelte、纯 HTML/CSS/JS），请尊重其选择——设计和 3D 原则与工具无关。

---

步骤 9 — 项目结构

清晰地组织代码库，使项目易于维护和扩展：

app/
├── layout.tsx          → Root layout with fonts, metadata
├── page.tsx            → Main page composing sections
├── globals.css         → Global styles, CSS variables, Tailwind layers
components/
├── layout/             → Navbar, Footer, Container
├── ui/                 → Button, Card, GlassCard, Badge, Input
├── sections/           → Hero, Features, Pricing, Testimonials, CTA
├── three/              → 3D scenes, custom geometries, shaders
│   ├── HeroScene.tsx   → Main hero 3D scene
│   ├── Particles.tsx   → Particle system component
│   └── Globe.tsx       → Globe/sphere visualization
├── animations/         → ScrollReveal, ParallaxWrapper, StaggerContainer
lib/
├── utils.ts            → Helper functions, cn() class merger
├── constants.ts        → Site content, configuration
styles/
├── fonts.ts            → Font configuration (next/font)
public/
├── models/             → .glb/.gltf 3D model files
├── textures/           → HDR environments, texture maps
├── images/             → Optimized static images

---

步骤 10 — 性能优化

加载缓慢的精美网站依然是失败的网站。性能是核心设计要求，尤其是涉及 3D 时。

关键优化

区域	技术
3D 模型	使用 glTF/GLB 格式，控制在 2MB 以内，采用 draco 压缩
纹理	压缩为 WebP/AVIF，使用 2 的幂次尺寸，最大 2048px
代码拆分	为 3D 组件动态导入——使用 { ssr: false } 的 next/dynamic
Canvas 加载	使用 <Suspense>，在 3D 初始化期间显示骨架屏／占位符
帧率	目标为 60fps——开发时使用 Stats.js，空闲时使用 frameloop="demand"
着色器	使用简单的片段着色器，避免在移动设备上使用复杂的光线步进
图像	使用 next/image 并设置适当的 width／height，对首屏以下的图像启用延迟加载
字体	使用 next/font 避免布局偏移，并仅包含所用字符的子集
打包体积	对 Three.js 导入进行 Tree-shaking——导入特定模块，而非整个库
GPU	使用 GPU 加速的 CSS：对动画元素使用 transform、opacity、will-change

性能预算

指标	目标
首次内容绘制	< 1.5s
最大内容绘制	< 2.5s
总打包体积（gzip 压缩后）	< 300KB（JS），3D 资源单独延迟加载
3D 场景初始化	< 3s 即可交互
帧率	稳定保持 60fps（低端移动设备上可接受 30fps）

---

第 11 步 — 响应式设计

每个界面都必须在各种设备上完美运行。3D 体验在移动设备上需要特别关注。

断点（Tailwind 默认值）

令牌	宽度	目标设备
sm	640px	大屏手机
md	768px	平板电脑
lg	1024px	小型笔记本电脑
xl	1280px	台式电脑
2xl	1536px	大屏显示器

响应式模式

• 网格列数：视口缩小时，从 4 列 → 2 列 → 1 列
• 导航：完整菜单 → 768px 以下切换为汉堡菜单／抽屉菜单
• 字体排版：使用 clamp()，展示文本从 96px 缩放至 48px，再缩至 32px
• 分区内边距：128px → 80px → 48px（台式电脑 → 平板电脑 → 移动设备）
• 触控目标：移动设备上最小为 44×44px

3D 响应式策略

这点至关重要——复杂的 3D 内容可能严重影响移动设备体验：

• 台式电脑：完整的 3D 场景，包含后期处理、大量粒子和精细几何体
• 平板电脑：减少粒子数量、简化几何体、不进行后期处理
• 移动设备：回退到 CSS 动画、静态图像或精简的 3D 内容（简单的旋转形状）
• 使用 navigator.hardwareConcurrency 和 renderer.capabilities 检测设备性能
• 使用 useMediaQuery 或 window.matchMedia，有条件地渲染 3D 内容或回退方案
• 将 pixelRatio 设为 Math.min(window.devicePixelRatio, 2)——移动设备无需使用 3x

// Example: responsive 3D fallback
const isMobile = useMediaQuery('(max-width: 768px)');

return isMobile ? (
  <AnimatedGradientBackground /> // lightweight CSS fallback
) : (
  <Canvas>
    <HeroScene />
  </Canvas>
);

---

第 12 步 — 测试与质量保证

在宣布构建完成前，执行生产级验证。

测试清单

性能

• Performance 分数 > 90（Lighthouse）
• 无布局偏移（CLS < 0.1）
• 3D 场景在 3 秒内加载完成
• 滚动和交互期间稳定保持 60fps

响应式设计

• 在 375px、768px、1024px、1440px 下测试
• 导航在移动设备上能正确折叠
• 在移动设备／低端设备上启用 3D 回退方案
• 触控交互正常（没有仅限悬停的状态阻碍移动设备使用）

动画

• 所有滚动显现效果都能正确触发
• 悬停状态在 100ms 内响应
• 遵循 prefers-reduced-motion 设置
• 无卡顿或不流畅的动画

浏览器兼容性

• Chrome、Firefox、Safari、Edge——最近两个版本
• 检测 WebGL 支持，并提供平稳的回退方案
• 为较旧浏览器提供 CSS backdrop-filter 回退方案

无障碍

• 标题层级正确（h1 → h2 → h3）
• 图像包含替代文本，可交互的 3D 内容包含 aria-label
• 键盘导航正常
• 色彩对比度符合 WCAG 2.1 AA 标准

测试工具

工具	用途
Lighthouse	性能、无障碍和 SEO 审核
Chrome DevTools Performance	帧率、渲染瓶颈
React Profiler	组件渲染性能
Stats.js	3D 场景实时 FPS 监控
axe DevTools	无障碍审核

---

第 13 步 — 生产构建、部署与错误解决（必须执行）

**此步骤不可妥协。**构建完成后，Agent 必须运行以下检查，并在宣布任务完成前修复所有问题。

13.1 — 构建与部署准备

1. 优化打包内容：对未使用的导入进行 tree-shaking，使用 next build --analyze 进行分析
2. 压缩 3D 资源：对 glTF 模型进行 Draco 压缩，将纹理优化为 WebP/AVIF
3. 配置 next.config.js 以获得最佳输出
4. 运行 next build 并确认无错误
5. 使用 next start 在本地测试生产构建

部署目标

平台	命令	备注
Vercel	vercel --prod	最适用于 Next.js，自动优化
Netlify	netlify deploy --prod	适用于静态导出
Cloudflare Pages	wrangler pages deploy	边缘优先，全球 CDN

13.2 — 自动错误修复

npm install          # Catch missing packages
npx tsc --noEmit     # Catch ALL type errors
npm run build        # Catch build-time errors
npx next lint        # Catch code quality issues

**如果任何命令失败：**读取错误信息，修复问题，重新运行，并重复此过程，直到没有错误。

13.3 — 3D 专项错误检查

检查项	检查内容	修复方法
WebGL 上下文	<Canvas> 渲染时没有控制台错误	添加错误边界，检查是否支持 WebGL
着色器编译	自定义着色器中的 GLSL 错误	修复着色器语法，测试 uniforms
模型加载	.glb/.gltf 文件返回 404	检查路径，确保文件位于 public/ 中
内存泄漏	useEffect 清理函数会释放几何体/材质	添加 geometry.dispose()、material.dispose()
SSR 崩溃	服务器组件中的 R3F 组件	使用 'use client' 指令，以及 next/dynamic 并设置 ssr: false
缺少 Suspense	<Canvas> 未使用 <Suspense> 边界	使用 <Suspense fallback={...}> 包裹 3D 场景

13.4 — 最终修复循环

WHILE errors exist:
  1. Run: npm run build → IF fail → fix → GOTO 1
  2. Run: npx next lint → IF fail → fix → GOTO 1
  3. Run: npm run dev → IF crash → fix → GOTO 1
  4. All clear → EXIT

在满足以下条件前，Agent 不得宣称任务已完成：

• npm run build 以代码 0 退出
• npx next lint 通过（无错误）
• npm run dev 启动时不会崩溃
• 没有 TypeScript 错误（npx tsc --noEmit 通过）
• 3D 场景已加载，并使用恰当的 Suspense 边界
• 没有 hydration 不匹配警告

规则：如果代码是你生成的，错误就由你负责。完成前先修复错误。

---

视觉质量验证

完成前，请根据以下标准进行验证。如果任何一项的答案是“否”，就回去修复。

排版

• 字号层级鲜明（display > h1 > h2 > 正文之间有明显区别）
• 标题使用负字间距（-0.02em 至 -0.04em）
• 正文为 16–18px，行高为 1.5–1.7
• 行宽限制在最多 65–75 个字符

间距与布局

• 所有间距值均来自已定义的间距比例
• 各版块具有充足的垂直内边距（桌面端为 80–128px）
• 布局宽敞且经过精心设计，没有任何拥挤之处

色彩与细节

• 主色谨慎使用——仅用于 CTA 和关键强调
• 渐变效果微妙且有明确目的
• 交互元素具有悬停/焦点状态，并带有平滑过渡
• 阴影使用有色/带色调的效果，绝不使用纯黑色 rgba(0,0,0,x)

3D 与动画

• 3D 元素服务于产品叙事，而不只是装饰
• 动画以 60fps 流畅运行
• 3D 内容具有加载状态
• 移动设备上有恰当的备用方案

整体印象

• UI 看起来高端且现代，而非通用模板
• 具有获奖网站的水准（Awwwards 级别）
• 设计服务于该特定产品的细分领域和受众
• 用户会仅凭视觉质量就信任并认可该产品
• 3D 集成自然且目的明确，而非华而不实

---

反模式——应避免的做法

了解哪些做法行不通，有助于避免踩坑：

反模式	问题所在	修复方法
3D 嘉年华	太多 3D 元素争夺注意力	一个 3D 主场景 + 微妙的环境元素
忽视性能	画面虽美，却要 8 秒才能加载	设置性能预算、延迟加载、压缩资源
忽视移动设备	3D 效果会让手机崩溃	检测设备、渐进增强、使用 CSS 回退方案
彩虹大杂烩	使用了太多互不相关的颜色	坚持使用调色板——主色、中性色和 1–2 种强调色
一排样式相同的卡片	缺乏视觉层次	调整尺寸、突出精选内容、运用视觉权重
Bootstrap 综合征	只是换了颜色，整体看起来仍像默认模板	从头设计，遵循你定义的视觉系统
着色器过度复杂	复杂的着色器会拖垮帧率	使用简单材质和自发光效果，谨慎使用后期处理
动画过载	所有元素都在动，没有片刻停歇	有策略地运用动效——用动画引导注意力，而非装饰页面
仅支持悬停的 3D 效果	触摸设备无法交互	同时支持指针和触摸，并提供被动动画
装饰性 3D	3D 元素与产品毫无关联	每个 3D 元素都应强化产品叙事
灰色荒原	整个页面一片灰暗，毫无视觉趣味	有意识地运用对比，并精准使用强调色
懒用 Lorem ipsum	占位文本让设计无法评估	撰写符合产品风格的真实文案
忽视排版	所有文本看起来字号和字重都一样	建立清晰的层次：展示文字、标题、副标题、正文

“要么获奖，要么重做”测试

完成后，请诚实地评估：

1. 截图测试——把截图和 Linear.app、Stripe.com 或 Awwwards 获奖作品放在一起。它看起来合适吗？
2. 眯眼测试——眯起眼睛看页面。视觉层次清晰吗？重要元素足够突出吗？
3. 3 秒测试——展示 3 秒。别人能看出这个产品的用途吗？
4. 动效测试——从头到尾滚动浏览一次。动画感觉编排得当，还是杂乱无章？

如果任何一项的答案是“否”，就在交付前继续迭代。

---

最终输出

AI 必须生成：

• 完整的前端代码——包含 TypeScript 的完整 Next.js 项目
• 模块化组件系统——可复用、类型明确、组织有序
• 现代响应式布局——在各种屏幕尺寸上都美观
• 流畅的动画系统——滚动显现、悬停效果、微交互，达到 60fps
• 3D 交互体验——将 Three.js/R3F 场景有目的地融入设计
• 性能优化的构建产物——延迟加载 3D、压缩资源、高效渲染
• 真实可信的内容——可信的文案、听起来真实的数据、恰当的文本长度
• 设计系统文档——简要说明调色板、排版和设计理念

最终成果必须让人感觉像是一个屡获殊荣的现代产品网站——能登上 Awwwards 的那种，而不是模板生成器生成的那种。

跨 Agent 兼容性

此技能适用于任何支持基于 Markdown 的技能文件的 AI 编码 Agent：

Agent	安装方式
Claude Code	npx skills add deveshpunjabi/3d-website-skill
Cursor	复制到 .cursor/skills/
Windsurf	复制到 .windsurf/skills/
Cline	复制到 .cline/skills/
Codex	复制到 .codex/skills/
Aider	在 .aider.conf 中引用
任意 Agent	将技能目录复制到该 Agent 的技能/指令文件夹

此技能基于 Markdown，并附有可选的参考文档——无需运行时依赖、API 密钥或构建步骤。