Neo-brutalist 作品集套件
一個從正式網站提取的完整且經過測試的作品集範本。所有內容都在 assets/ 中 — 將其複製到一個新的 Vite + React 專案中，將佔位資料替換為擁有者自身的資料，然後即可上線。該套件已經過驗證，可以從頭開始執行 vite build 並進行渲染，且無任何控制台錯誤。
你會獲得什麼
- 設計系統 — 平面飽和色彩、3px 邊框、實心偏移陰影、傾斜瓷磚（
assets/src/brutal/brutal.css，範圍限定在.nb下）。 - 章節 — 載入畫面 · 固定導航欄（滾動監聽、主題 + 語言 + 音效切換、手機選單） · 帶有逐字母懸停效果的英雄區 · 關於我 · 作品網格及全螢幕 案例研究覆蓋層（上一頁/下一頁、鍵盤操作、焦點恢復） · 技術棧 · 經歷手風琴 · 聯絡表單 · 帶有即時時鐘的頁尾。
- 雙語 + RTL — 英語/阿拉伯語，使用邏輯 CSS 屬性；明暗主題切換無閃爍。
- 音效 — 生成的 124 BPM synthwave 循環音樂以及懸停/點擊效果（每個英雄字母會播放一個五聲音階音符）。無需音訊檔案，無需授權。
- 助手 — 由
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→ 檢查明暗主題、EN/AR、375px 和 1440px 的顯示效果。npx vite build必須成功。- 部署：請參閱
references/deploy-and-secrets.md。
需要個人化的內容（唯一包含內容的檔案）
| 檔案 | 需要填入的內容 |
|---|---|
src/data/siteFacts.js | 名稱（EN/AR）、英雄區名稱拆分、導航縮寫、位置、時區、聯絡連結、EmailJS 公開 ID、技術棧欄位、工具 |
src/data/projectsMeta.js | 專案：標題、標籤、上線 URL（或 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），切勿使用 class — React 重新渲染會覆蓋 class。 - 案例覆蓋層需要
data-lenis-prevent，否則 Lenis 會阻止內部的滾輪事件。任何可滾動的覆蓋層（助手聊天、手機選單）都相同。 - 使用邏輯 CSS（
inline-start/end、margin-inline），在 RTL 中翻轉箭頭，將數字計數器包裹在dir="ltr"中，切勿對阿拉伯語進行字母間距調整。 - 切勿在生產環境程式碼中呼叫
localhost— 瀏覽器會向訪客請求本機網路權限。僅在 API 的 URL 環境變數已設定時才呼叫 API。 - 效能： 對摺疊以下的章節進行延遲載入；使用帶有
loading="lazy"的 WebP 圖片；僅對transform/opacity進行動畫處理；尊重prefers-reduced-motion；不要在公開路徑上使用重型 3D/UI 函式庫。 - 機密： API 金鑰僅存在於伺服器環境變數中（
GEMINI_API_KEY）。切勿將機密加上VITE_前綴（它會被捆綁到瀏覽器中）。公開的 EmailJS ID 可以在客戶端程式碼中使用。 - 無障礙性： 可見的焦點環、跳過連結、切換按鈕的
aria-pressed、覆蓋層的role="dialog"+ 焦點恢復、減少動畫支援。
在說「完成」之前進行驗證
npx vite build成功。- 明暗主題、EN + AR（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— class 目錄、章節配方、如何重新著色或新增章節。references/interaction-and-sound.md— 懸停/按壓行為、顯示系統、音樂 + SFX 架構及調整。references/i18n-and-rtl.md— 語言環境結構、按鍵對應、阿拉伯語排版、RTL 檢查清單。references/assistant-rag.md— 聊天端點的工作方式、知識區塊、調整檢索和提示詞。references/deploy-and-secrets.md— GitHub + Vercel 步驟、環境變數、金鑰輪換、故障排除。