新粗野主义作品集工具包
一个从生产站点提取的、经过完整测试的作品集模板。所有内容都在 assets/ 中——将其复制到一个全新的 Vite + React 项目中，替换占位数据为所有者自己的信息，然后即可部署。该工具包已验证可通过 vite build 从零构建，且渲染时无控制台错误。
您将获得
- 设计系统 —— 扁平饱和色彩、3px 边框、实体偏移阴影、倾斜磁贴（
assets/src/brutal/brutal.css，作用域限定在.nb下）。 - 页面区块 —— 加载器 · 固定导航栏（滚动监听、主题/语言/音效切换、移动端抽屉菜单） · 带逐字母悬停效果的英雄区 · 关于我 · 作品网格搭配全屏案例研究覆盖层（上一项/下一项、键盘操作、焦点恢复） · 技术栈 · 经历手风琴 · 联系表单 · 带实时本地时钟的页脚。
- 双语支持 + RTL —— 英语/阿拉伯语，使用逻辑 CSS 属性；明暗主题切换无闪烁。
- 音效 —— 生成式 124 BPM 合成波循环乐和悬停/点击音效（每个英雄区字母播放一个五声音阶音符）。无需音频文件，无需许可。
- 助手 —— 基于
api/chat.js的浮动聊天框：对所有者自身数据进行 RAG（阿拉伯语感知的 BM25 + Gemini 嵌入），接地气回答，模型回退，同源+速率限制。API 密钥永远不会到达浏览器。 - 部署配置 ——
vercel.json（SPA 重写）、.vercelignore。
快速开始（新项目）
npm create vite@latest my-portfolio -- --template react并安装assets/package.deps.json中列出的依赖（i18next react-i18next lenis framer-motion lucide-react @emailjs/browser @google/genai）。- 将
assets/的内容复制到项目根目录（合并src/，替换index.html和vite.config.js，添加api/、vercel.json、.vercelignore）。删除默认的src/App.css/index.css导入 —— 工具包通过brutal.css自带 CSS。 - 填写所有者数据（参见 需个性化设置的内容）。
- 将肖像放在
src/Imgs/portrait.jpg，项目截图放在public/projects/下（WebP 格式，宽度 ≤1280px）。 npm run dev→ 检查明/暗主题、英文/阿拉伯语、375px 和 1440px 宽度。npx vite build必须通过。- 部署：参见
references/deploy-and-secrets.md。
需个性化设置的内容（唯一包含内容的文件）
| 文件 | 需填写的内容 |
|---|---|
src/data/siteFacts.js | 姓名（英/阿）、英雄名拆分、导航缩写、所在地、时区、联系链接、EmailJS 公开 ID、技术栈列、工具 |
src/data/projectsMeta.js | 项目：标题、标签、线上链接（或 null）、order、i18nIndex |
src/data/projectImages.js | 每个项目的截图；第一张图片为卡片封面 |
src/i18n/locales/{en,ar}.json | 所有文案 —— 英雄陈述、关于我/统计、亮点、经历、每个项目的副标题/描述/屏幕标签、项目“类型”、联系文本、助手提示词 |
index.html | <title>、描述、favicon |
填写规则：只填所有者能确认的事实；切勿编造客户、数字、日期或链接；技术名称在两种语言中保持英文；语言文件中的 projects.items[i] 必须与 i18nIndex 对齐。
设计语言（概述 —— 精确值见 references/design-system-spec.md）
- 仅使用扁平颜色。 无渐变、发光、模糊、玻璃或紫色“AI”外观。深度 = 边框 + 硬阴影。
- 边框
3px solid var(--nb-line)· 阴影 实体偏移（5px/8px 8px 0，悬停时12–14px） · 倾斜-2°…2°，悬停时回正。 - 字体： Bricolage Grotesque 800 大写用于展示，Space Grotesk 用于正文，JetBrains Mono 大写用于标签。阿拉伯语：Cairo 700–900，无字距，无大写。
- 对比度规则： 饱和填充上的文字始终为
#111，且两种主题下边框均为#111；只有中性表面会随主题切换。 - 区块节奏： 英雄区黄色 → 关于我纸色 → 作品蓝色 → 技术栈纸色 → 经历丁香色 → 联系粉色 → 页脚黑色。通过修改
--nb-*令牌重新着色；保持节奏。
工程规则（编辑时请遵守）
- 在数据属性中显示状态（
data-reveal→data-in），绝不用类名 —— React 重新渲染会覆盖类名。 - 案例覆盖层需要
data-lenis-prevent，否则 Lenis 会阻止其内部的滚轮事件。任何可滚动的覆盖层（助手聊天、移动端菜单抽屉）也是如此。 - 使用逻辑 CSS（
inline-start/end、margin-inline），在 RTL 中翻转箭头，用dir="ltr"包裹数字计数器，绝不对阿拉伯语进行字母间距调整。 - 切勿在生产代码中调用
localhost—— 浏览器会请求访问者授予本地网络权限。仅在 API URL 环境变量设置后才调用 API。 - 性能： 懒加载首屏下的区块；WebP 图片使用
loading="lazy"；仅对transform/opacity进行动画；尊重prefers-reduced-motion；公共路径上不使用繁重的 3D/UI 库。 - 密钥： API 密钥仅存储在服务器环境变量中（
GEMINI_API_KEY）。绝不为密钥添加VITE_前缀（它会被打包进浏览器）。EmailJS 公开 ID 可以在客户端代码中。 - 无障碍： 可见焦点环、跳过链接、切换按钮的
aria-pressed、覆盖层的role="dialog"+ 焦点恢复、减少运动支持。
在标记“完成”前进行验证
npx vite build通过。- 明 + 暗、英 + 阿（RTL）、375px 和 1440px；无水平溢出。
- 打开案例研究 → 上一项/下一项/
Esc，用鼠标滚轮在其中滚动。 - 悬停英雄名和控件（点击一次后）确认音效；切换按钮状态保持。
- 如果助手已部署：询问联系问题、列出所有项目的问题以及不在数据中的某个问题（它必须说不知道）。
- 预览面板可能被隐藏（动画暂停）—— 通过第二张截图或真实浏览器确认动效。
设计系统产物
DESIGN-SYSTEM.md— 概览 + 带有链接的调色板/规则表。design-system/tokens.css和tokens.json— 在 React 工具包外部使用的令牌。design-system/styleguide.html— 在线样式指南（在浏览器中打开）：带对比度的调色板、字体比例、阴影/倾斜比例、每个组件、动效、做/不做。
参考资料（需要时阅读）
references/design-system-spec.md— 精确的设计系统：原则、每种颜色及其位置、对比度数值、字体比例、间距、阴影/边框/倾斜比例、动效令牌、z-index、断点、组件解剖结构和状态。references/design-system.md— 类目录、区块配方、如何重新着色或添加区块。references/interaction-and-sound.md— 悬停/按下行为、显示系统、音乐 + 音效架构和调优。references/i18n-and-rtl.md— 语言环境结构、键值映射、阿拉伯语排版、RTL 检查清单。references/assistant-rag.md— 聊天端点工作原理、知识块、检索调优和提示词。references/deploy-and-secrets.md— GitHub + Vercel 步骤、环境变量、密钥轮换、故障排除。