Portfolio Skill

建立一份讓雇主、招募人員或客戶在關閉分頁後仍能記住的個人作品集：一個自信的視覺概念、具體的文案、有理由的動態效果，以及在打開開發者工具時經得起考驗的工程技術。

主題是根據個人選擇的。這裡沒有任何固定色彩、字體或版面風格。本文件中的所有具體數值都是該模式的範例，而非要複製的預設值。

1. 品質標準（完成前請全部檢查）

一致的藝術指導，並徹底執行。 一個有命名的概念驅動字體、色彩、版面、動態和文案語氣。絕不在一個網站上混合不相關的風格（例如玻璃擬態 + 霓虹 + 野獸派 + 漸層）。
真實、具體的內容。 每個主張都來自使用者的履歷、儲存庫、個人資料或訊息。具體數字、技術棧名稱、角色、日期。沒有 lorem ipsum，沒有虛構的指標，沒有「熱愛程式碼的充滿熱情的開發者」。
作品是主角。 2-4 個頂尖專案獲得最大篇幅，理想情況下擁有自己的案例研究頁面並包含互動元素。其他所有內容則放在一個可掃讀、可篩選的索引中。
字體主導設計。 表現性的標題字體 + 易讀的正文字體 + 可選的等寬/工具字體。使用流暢的 clamp() 尺寸。Inter、Roboto、Arial 或系統字型堆疊絕不能作為表現性字體。
動態是經過編排的，而非隨意點綴。 一個開場動畫、滾動揭示，以及 1-2 個標誌性時刻。所有動態都需尊重 prefers-reduced-motion 並優雅降級。
隨處可用。 從 360px 到超寬螢幕，支援鍵盤操作，符合 WCAG AA 對比度，首次繪製速度快，在沒有 WebGL 或 JS 動畫的情況下也能完全閱讀。
上線發布。 零類型錯誤，生產建置通過，每個路由都有 meta/OG 標籤，履歷連結，可運作的聯絡方式，部署配置。

2. 工作流程

收集資料。 閱讀所有提供的資料：履歷 PDF/DOCX、現有網站、README、GitHub 資料、備註。僅針對遺漏的必需品提問（姓名、角色、目標受眾、2-4 個旗艦專案、連結、視覺偏好）。如果沒有給出偏好，請自行選擇一個方向，並說明選擇的原因。
挑選原型與抱負等級（第 6A.2 節），使其符合個人與時程表，然後在編寫任何 UI 程式碼之前撰寫一份設計簡報（第 3 節）。
建立基礎（第 5 節）：內容模組、代碼標記、字體、路由器、平滑滾動。
以合理的順序編排頁面： 內容 -> 代碼標記/字體 -> 導覽/頁尾 -> 英雄區 -> 旗艦專案 -> 作品索引 -> 關於我/能力/時間軸 -> 聯絡 -> 案例研究頁面 -> 404。然後是動態（第 6 節）。WebGL 和標誌性效果最後才做。
驗證（第 9 節）在真實瀏覽器中，大約在 1440px 和 390px 的寬度下進行。切勿僅憑閱讀程式碼就宣告完成。

如果儲存庫已使用某個技術棧（Next.js、Astro、SvelteKit、純 HTML），請保留它。以下所有模式皆可轉換。

3. 藝術指導

3.1 從個人衍生主題

詢問：誰會看這個，他們應該在 5 秒內感受到什麼，這個人的作品看起來像什麼？將此映射到一個概念。使用者指定的品牌色、字體或主題始終優先。

人物 / 信號	範例方向（選擇一個，或自行發想）
後端 / 系統 / 基礎設施	編輯風格的紙張 + 墨水；藍圖/技術繪圖；終端機野獸派；帶有數據可視化點綴的瑞士網格
前端 / 創意開發	大膽的動態字體；沉浸式 WebGL 體驗；俏皮的貼紙/雜誌風格；高對比單色搭配一個霓虹色
產品 / UX 設計師	冷靜的畫廊留白空間；溫馨工作室風格（奶油色、陶土色、柔和襯線字體）；案例研究雜誌
機器學習 / 研究 / 數據	實驗室筆記本風格（方格紙、等寬字體註釋）；科學期刊；帶有繪製點線的暗色天文台風格
行動開發者	以裝置為主的展示；柔和的觸感表面；帶有真實手機模型的 App Store 風格
攝影師 / 藝術家	以圖像為主的滿版設計；極簡金屬線條；暗色電影風格；底片式網格
創業者 / 通才	自信的編輯風格；宣言式字體；以指標為導向的可信度
學生 / 職場新鮮人	乾淨、有活力、誠實；強調專案與學習路徑而非職稱

避免那些看起來像 AI 生成的預設值：白色背景上的紫到藍漸層、通用的玻璃擬態卡片、置中英雄區搭配「嗨，我是 X」+ 波浪 emoji、三個相同的特色卡片、通用的 3D 球體。

3.2 設計簡報模板（請先撰寫此項）

概念：        <名稱 + 一句話說明意圖>
受眾：         <對象，他們必須帶走的訊息>
色盤：         背景色, 背景色-2, 前景色, 前景色-2, 柔和色, 線條色, 強調色（+ 每個專案的強調色，如果使用）
字體：         標題 / 正文 / 等寬字體（含替代字型），縮放比例
版面語法：    網格、邊距、區塊節奏、規則/邊框 vs 卡片
動態：         個性（乾脆/彈性/緩慢/機械），主要曲線，持續時間
標誌性效果：  人們會記住的 1-2 個時刻
紋理：         顆粒感 / 網格線 / 無 / 著色器

3.3 代碼標記（結構固定，數值依主題變化）

:root {
  /* 色盤：依主題替換數值 */
  --bg: #eeeae2;  --bg-2: #e5e0d5;
  --fg: #121210;  --fg-2: #2a2925;
  --muted: #6d695f;
  --line: rgba(18,18,16,.14);
  --accent: #ff4d1c;
  /* 字體角色 */
  --display: 'Instrument Serif', 'Times New Roman', serif;
  --text: 'Geist', 'Helvetica Neue', sans-serif;
  --mono: 'Geist Mono', ui-monospace, monospace;
  /* 節奏 */
  --gutter: clamp(1.1rem, 3.2vw, 2.75rem);
  --ease: cubic-bezier(.16, 1, .3, 1);
  /* 頁面級別名，以便案例研究頁面可以透過覆蓋這些變數來重新設定主題 */
  --page-bg: var(--bg); --page-fg: var(--fg); --page-muted: var(--muted);
  --page-line: var(--line); --page-accent: var(--accent);
}

組件僅引用 --page-*。案例研究頁面在其 <main> 元素上設定新的 --page-* 數值，整個 UI（按鈕、分隔線、游標、選取範圍）即可免費重新設定主題。

3.4 字體規則

對比配對：襯線標題字體 + 怪誕正文字體，或粗重怪誕標題字體 + 等寬字體，或窄版標題字體 + 人文主義正文字體。透過 Google Fonts 或自託管的 woff2 檔案載入，並設定 display=swap 和 preconnect。
使用 clamp 實現流暢縮放，例如 h-xl: clamp(3.6rem, 14.5vw, 15rem)，h-lg: clamp(2.8rem, 8vw, 8.5rem)，h-md: clamp(2.1rem, 5vw, 4.6rem)，lede: clamp(1.05rem, 1.45vw, 1.3rem)。
標題：緊湊行高（0.85-0.95）和負字距（-0.02 到 -0.04em）。正文：行高 1.5-1.65，max-width 38-62 字元。
中繼資料使用小型大寫等寬字體並帶輕微字距（例如「(02) 精選作品」、「2024 - 至今」）。
在標題中使用斜體或一個字的粗細變化來增加語調（例如「那些我會先展示的。」）。
為計數器和統計數據套用 font-variant-numeric: tabular-nums。

3.5 版面語法

滿版英雄區（min-height: 100svh），內容靠左下對齊或橫跨網格，而非正中間。
區塊標題使用細線條搭配左側的編號等寬標籤和右側的上下文。
偏好使用細線條和網格，而非帶有投影的卡片（除非概念是觸覺/柔和的）。
變化區塊節奏：大膽陳述、密集索引、水平輪播、兩欄分割。絕不要連續六個相同的區塊。
全程使用一致的 --gutter；區塊內邊距 clamp(5rem, 13vw, 11rem)。

3.6 紋理選項

底片顆粒（在 body::after 上使用 SVG feTurbulence data-URI，透明度 0.04-0.08，pointer-events:none）、藍圖網格線、微妙的放射狀漸層，或 WebGL 場域。選擇一個；不要疊加使用。

4. 內容策略

4.1 資訊架構

首頁（單頁滾動）：

英雄區： 姓名、一句話定位、1-2 句引言、主要行動呼籲（看作品）+ 次要行動呼籲（履歷 / 聯絡）、小型的 meta 資訊列（角色、專注領域、地點、開放狀態）。
陳述 / 關於我： 2-4 句以個人語氣寫成的句子，加上 3-4 個真實的統計數據（已發布的專案數、年資、使用者數、星數、學生的 GPA）。
旗艦專案： 2-4 個主打專案，大型卡片，每個都連結到一個案例研究頁面。
作品索引： 其他所有專案以行形式呈現（編號、名稱、一句話簡介、技術棧、年份/連結），可按類型篩選。
能力： 分組的技能（例如後端、行動裝置、AI、工具），僅包含他們能在面試中捍衛的技能。
歷程 / 時間軸： 教育經歷、職位、顯著成就。
聯絡： 大型行動呼籲標題、電子郵件、表單、社群連結、履歷下載。

每個旗艦專案對應一個案例研究頁面：主題英雄區（名稱、標語、角色、技術棧、連結）、問題、建置內容、一個互動式展示（模擬器、遊樂場、真實模型、可懸停的架構圖）、關鍵決策/取捨、指標/成果，然後是「下一個專案」的引導與聯絡方式。

404 頁面保持相同風格。

4.2 文案規則

第一人稱、平實、具體。以建置了什麼以及為何重要開頭，然後說明如何做到。
好的例子：「連接你自己的 AWS、GCP 和 Azure 帳戶，它們的免費方案會像一個磁碟一樣運作。」壞的例子：「一個利用尖端技術的革命性雲端解決方案。」
禁止使用的填充詞：充滿熱情、尖端、利用、無縫、強健、創新、旅程、深入探討、「我熱愛寫程式」。
每個指標都必須有來源，否則省略。絕不捏造。
微型文案可以有個性，但必須清晰易懂（例如 404 頁面的「迷失在走帶中。」、「滾動以平移」的提示）。

4.3 單一內容模組

所有文案和數據都存放在 src/content.ts 中。組件永遠不應硬編碼傳記文字。

export const PROFILE = { name, role, location, email, github, linkedin, resume: '/resume.pdf', statement };
export type Metric = { value: string; label: string };
export type Flagship = {
  slug: string; path: string; index: string; name: string; kicker: string; tagline: string;
  summary: string; role: string; stack: string[]; metrics: Metric[]; repo: string;
  accent: string; bg: string; fg: string;          // 每個專案的主題
};
export const FLAGSHIPS: Flagship[] = [ /* 2-4 */ ];
export type WorkKind = 'Systems' | 'AI' | 'Mobile' | 'Web'; // 根據個人調整
export const WORKS: { name: string; blurb: string; stack: string[]; kind: WorkKind; year: string; href: string; route?: string }[] = [];
export const CAPABILITIES: { title: string; items: string[] }[] = [];
export const PATH: { when: string; what: string; detail: string }[] = [];
export const STATS: Metric[] = [];

5. 架構

5.1 預設技術棧

Vite + React + TypeScript；使用自訂屬性的純 CSS（如果團隊偏好可以使用 Tailwind）；gsap + @gsap/react（ScrollTrigger）；lenis 實現平滑滾動；three 僅在方向使用 WebGL 時使用；nodemailer 處理聯絡表單；部署在 Vercel / Netlify。

5.2 結構

index.html                 字體、基本 meta/OG、noscript 備用文字
public/                    favicon.svg, resume.pdf, og-image
src/content.ts             所有文案和數據
src/index.css              代碼標記、字體、版面、組件、響應式、減少了動畫
src/lib/smooth.ts          Lenis + GSAP ticker，減少動畫標記，滾動速度
src/lib/motion.tsx         useReveals, useHeroIntro, <Split>, useMeta
src/lib/router.tsx         歷史路由器 + 遮罩轉場 + <Link>
src/components/Chrome.tsx  導覽、行動選單、游標、預載入器、頁尾/聯絡
src/components/Field.tsx   可選的 WebGL 英雄區背景
src/components/CaseShell.tsx 共享的案例研究框架
src/pages/*.tsx             首頁、每個旗艦專案一個頁面、NotFound
api/contact.ts             無伺服器郵件處理器
vercel.json                SPA 重寫規則

5.3 路由

一個微型歷史路由器對於作品集來說已經足夠，並且讓你能夠控制轉場效果：

normalizePath（移除尾部斜線、轉為小寫）。
navigate(to)：相同路徑 + 錨點 -> 平滑滾動到該錨點；不同路徑 -> 播放遮罩，在遮蓋時切換頁面，滾動到頂部，然後揭示。
監聽 popstate；每次路由變更後呼叫 ScrollTrigger.refresh()；切換後處理待處理的 #hash。
<Link>：外部連結（http、mailto）渲染為純錨點，並帶有 target="_blank" rel="noopener noreferrer"；內部連結攔截點擊，除非按下 metaKey/ctrlKey/shiftKey 或非左鍵，以便新分頁仍能正常運作。
Next.js / Astro：使用它們的路由器，並在佈局/轉場鉤子中實現遮罩效果。

5.4 每個路由的 SEO

useMeta(title, description, themeColor) 會在每個路由上更新 document.title、description、og:*、twitter:*、theme-color 和 canonical。index.html 包含完整的預設值，加上一個 <noscript> 文字摘要。如果可能，請加入 summary_large_image Twitter 卡片和一個 OG 圖片。考慮加入 JSON-LD Person 綱要。

5.5 聯絡 API（無伺服器，`api/contact.ts`）

要求：

僅接受 POST（否則回傳 405），Cache-Control: no-store。
蜜罐欄位（例如隱藏的 website）：如果填寫，回傳 200 並丟棄。
修剪並限制每個欄位的長度；使用簡單的正則表達式驗證電子郵件；最小訊息長度。
從用於標頭/主旨的任何內容中移除 \r\n（防止標頭注入）；對 HTML 主體中的任何內容進行 HTML 跳脫。
replyTo = 寄件者；from = 你的 SMTP 使用者。
對每個 IP 進行盡力而為的頻率限制（例如，透過記憶體中的 Map，每 10 分鐘 3 次，IP 從 x-forwarded-for 取得）。
如果缺少 SMTP 環境變數，回傳 503，並帶有友善的「直接透過電子郵件聯絡我」的訊息；前端 UI 必須顯示電子郵件作為備用方案。
環境變數：SMTP_HOST、SMTP_PORT、SMTP_USER、SMTP_PASS、CONTACT_TO。提供 .env.example。絕不提交機密。
前端表單：閒置/發送中/已發送/錯誤狀態，具有 aria-live="polite" 狀態，發送時停用提交按鈕，每個輸入框都有標籤。

5.6 部署

Vercel vercel.json：

{ "cleanUrls": true,
  "rewrites": [{ "source": "/((?!api/|assets/|.*\..*).*)", "destination": "/" }] }

Netlify：在 _redirects 中加入 /* /index.html 200。履歷存放在 public/resume.pdf；每個履歷按鈕都連結到該檔案，並帶有 download 屬性。

6. 動態系統

6.1 原則

一個統一的動態曲線（例如 expo.out / cubic-bezier(.16,1,.3,1)），揭示動畫持續時間 0.6-1.4 秒，懸停效果 0.3-0.6 秒。
僅動畫化 transform、opacity、clip-path。絕不動畫化版面屬性。
遮罩揭示（文字從 overflow:hidden 的盒子中升起）看起來更高級；純粹的淡入淡出看起來廉價。
編排：英雄區開場動畫等待預載入器/遮罩轉場結束（共享 intro.delay）。
每個效果都受 prefers-reduced-motion 條件限制。

portfolio-skill：履歷+倉庫 → 量身個人作品集