Institutional Site Builder

一项专注于根据客户提供的参考资料，构建高质量机构类网站的专业技能。该工作流旨在最大限度地利用客户交付的素材（Logo、视觉识别系统、演示文稿、PDF 等），将其转化为一个专业的 React 网站，具备交互动画、响应式布局与优化的性能表现。

技术栈

本项目始终使用以下技术：

• Vite（v6+）作为打包工具（bundler）
• React 19 + TypeScript
• Tailwind CSS 4，通过 @tailwindcss/vite 集成
• Framer Motion 实现动画效果
• Lucide React 提供图标支持

可选依赖（按需安装）：

• three + @types/three —— 用于实现动态 3D 背景（如 DottedSurface、着色器背景等）
• react-use-measure —— 支持 InfiniteSlider（例如 Logo Cloud、跑马灯效果）

六阶段工作流

第一阶段：素材探索与清点

在编写任何代码之前，请全面审视用户提供的所有素材。此阶段至关重要，因为素材将决定网站的整体调性、配色方案、文案内容与图像资源。

请将素材按以下逻辑类别进行心智归类：

素材探索检查清单：

1. 对用户提供的整个文件夹执行递归 ls -la
2. 使用 Read 工具读取所有图像（Logo、视觉识别素材、关键幻灯片截图等）
3. 解析 PDF / PPT 文件，提取文本内容
4. 精准识别并记录主配色方案（hex codes）
5. 映射每张图像适用的页面位置（即哪张图用于哪个模块）
6. 记录联系信息、产品名称、宣传语（taglines）等关键文本

第二阶段：网站规划

完成素材清点后，通过 AskUserQuestion 向用户确认以下问题：

1. 语言 —— PT-BR、EN，还是双语？
2. 页面结构 —— 完整版（Hero、Problema、Solução、Features、Benefícios、Clientes、CTA、Contato、Footer）还是精简版？
3. 视觉风格 —— 暗黑高端（Dark premium）、明亮简洁（Light/clean），还是混合模式（Híbrido）？
4. 联系方式呈现方式 —— 表单 + WhatsApp 浮动按钮、仅展示链接，还是完整表单？

大多数 B2B 类机构网站遵循如下标准页面顺序（可根据实际需求调整）：

1. Navbar（固定定位，滚动时启用模糊效果）
2. Hero（价值主张 + CTA）
3. Contexto/Problema（产品存在的原因）
4. Solução（产品具体功能）
5. Pipeline/Processo（运作流程，分步说明）
6. Funcionalidades（带图的功能卡片）
7. Detalhes técnicos（IoT、集成能力等）
8. Benefícios（按类别划分的卡片组）
9. Canais de Entrega（多渠道集成能力）
10. Clientes（Logo Cloud + 社会证明）← CTA 前置
11. CTA Final（冲击力文案 + 按钮）
12. Contato（表单 + 联系信息）
13. Footer（链接、Logo、版权信息）
14. WhatsApp Flutuante（悬浮 WhatsApp 按钮）

第三阶段：项目初始化

npm create vite@latest  -- --template react-ts
cd 
npm install
npm install -D tailwindcss @tailwindcss/vite --legacy-peer-deps
npm install framer-motion lucide-react

配置 vite.config.ts：

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
  plugins: [react(), tailwindcss()],
  build: {
    rollupOptions: {
      output: {
        manualChunks: {
          // 根据重型库的实际使用情况添加
          'framer-motion': ['framer-motion'],
        },
      },
    },
  },
})

在 src/index.css 中配置客户配色方案：

@import "tailwindcss";

@theme {
  /* 从客户视觉识别系统中提取的色值 */
  --color-primary-900: #XXXXXX;
  --color-primary-800: #XXXXXX;
  /* ... 全量映射客户配色方案 ... */
  --color-accent: #XXXXXX;
  --font-sans: 'Inter', system-ui, sans-serif;
}

配置 index.html：

• 设置正确的 lang 属性（如 pt-BR 或 en）
• 设置包含产品关键词的
• 通过 defer 加载 Google Fonts（避免阻塞渲染）：

复制静态资源（assets）：

• 创建 public/images/ 目录，并复制全部产品相关图像
• 如有客户 Logo，创建 public/images/clientes/ 目录
• 复制 Logo 文件（优先选用横版用于 Navbar）

第四阶段：网站开发

对于总行数约 ≤800 行的中小型网站，全部实现在单一 App.tsx 文件中；更大规模的网站，则应在 src/components/ 下拆分为独立组件。

所有图像必须遵守以下强制规范：

必须包含的实用工具组件：

• useInView() —— 基于 Intersection Observer 实现进入视口时的动画触发
• Section —— 封装容器，支持滚动时自动触发动画（opacity + translateY）
• TextCycle —— 支持滑动向上（slideUp）切换关键词的文本轮播组件

每个页面模块开发前，请查阅 references/components.md，其中提供了针对本技术栈（无 shadcn、Next.js 或 cn() 依赖）定制的完整模板。

第五阶段：性能优化（强制执行）

此阶段必须在向用户交付前完成。

5.1 图像优化 —— 转换为 WebP 格式：

from PIL import Image
import glob, os
for f in glob.glob("public/images/*.png") + glob.glob("public/images/*.jpg"):
    if os.path.getsize(f) > 100_000:
        img = Image.open(f)
        if img.width > 1200:
            ratio = 1200 / img.width
            img = img.resize((1200, int(img.height * ratio)), Image.LANCZOS)
        img.save(f.rsplit('.', 1)[0] + '.webp', 'WEBP', quality=80)

更新代码中所有图像引用路径为 .webp 后缀。

5.2 字体加载 —— 消除渲染阻塞： 在 index.html 中采用 media="print" onload="this.media='all'" 模式。

5.3 JavaScript —— 代码分割（Code splitting）：

• 重型库（如 Three.js）采用 lazy import + Suspense 方式加载
• 在 vite.config.ts 中配置 manualChunks
• 主 JS bundle 大小应控制在 300KB 以内

5.4 最低可访问性（Acessibilidade mínima）要求：

• 主容器添加 role="main"
• 所有 标签均需提供 alt 属性
• 所有 标签均需显式声明 width 和 height
• 标题层级（heading）须严格按顺序使用（h1 → h2 → h3）
• 文本与背景之间需满足足够的对比度

5.5 基础 SEO 支持：