pomelo-digital/pomelo-deck

Pomelo Deck Template

用於以 PptxGenJS 建立 Pomelo 品牌 .pptx 簡報的可重複使用範本，確保設計系統無需每次重新推導。

使用時機

任何當任務是「以 Pomelo 風格建置／重做／重新設計簡報」時——客戶績效報告、提案簡報、標書。如果使用者上傳現有簡報要求重新設計，請完全保留所有資料，僅將佈局改為此系統。

設定（每次工作階段）

1. 確保工作目錄中存在以下檔案：pomelo.js、pomelo_logo.png（以及作為參考的 example.js）。
2. 若需要，安裝引擎：npm install -g pptxgenjs 並以 NODE_PATH=$(npm root -g) node build.js 執行腳本。
3. 先閱讀 example.js——它從頭到尾展示每個投影片建置器的用法。將其複製作為起點。

設計系統（已編碼在 pomelo.js 中——請勿手動重做）

• 底板： 10" × 5.625"（16:9），白色背景。
• 字型： Georgia = 標題／數字；Calibri = 內文、標籤、表格。
• 顏色： ink 1F2A2E（標題）、body 3D4A4E、muted 8A9498（圖說／頁碼）、coral EB6B4F（主要強調色／眉標／數字／弧線／標誌）、mint 76BBA8 + green 4F8B7B（次要強調色）、sand E8E5DD / light sand F7F6F3（面板與總計列）、hairline D9D7D0。
• 眉標： 9pt Calibri、珊瑚色、大寫、charSpacing:3。
• 投影片標題： Georgia 約 24pt（封面章節 28pt、分隔頁 40pt、封面 50pt）。
• 裝飾元素： 從角落延伸的嵌套圓環（外圈顏色 + 白色內圈）。arcsTR/arcsBL = 大圓環（封面／結尾頁）；smallArcTR = 小圓環（內容投影片）。
• 頁尾： pómelo 標誌置於右下角；頁碼 NN / TOTAL 置於左下角（灰色）。

API（const { PomeloDeck, TOKENS } = require('./pomelo')）

建立：const d = new PomeloDeck({ total: N, title, logo:'pomelo_logo.png' })——total 驅動頁碼。

投影片建置器（每個都回傳投影片物件，方便你加入自訂內容）：

• d.cover({ kicker, title, subtitle, sub2, stats:[[num,label,sub]], footer })——統計資料以五欄形式呈現；長數字會自動縮小。
• d.divider({ kicker, title, sub, accent })——章節分隔頁。accent = TOKENS.CORAL（預設）或 TOKENS.MINT。
• d.content({ kicker, title, note, size, arc, page })——標準內容投影片，包含眉標 + 標題 + 頁尾。回傳投影片；內文部分請自行組合。
• d.closing({ kicker, title, subtitle, footer })。

元件（在投影片上呼叫）：

• d.statGrid(s, [[num,label,sub,color]], { x,y,w,cols,gh,gapx,gapy,numSize })——KPI 卡片。
• d.statCell(s,x,y,w,num,label,sub,color,numSize)——單一 KPI。
• d.metricRows(s,x,y,w,[[label,val]])——標籤／數值行（帶分隔線，適合放在創意圖片旁邊）。
• d.table(s, head, rows, { x,y,w,colW,fs,hfs,rowH,totalLast,boldFirst,margin })——Pomelo 表格（深色表頭、斑馬紋行、沙色總計行）。
• d.eyebrow / d.title / d.note / d.line——基本元件。

儲存：await d.save('out.pptx')。

注意事項（經驗教訓——請務必遵守）

• 長數字會換行。 在約 1.74" 的統計儲存格中，超過 6 個字元的值（例如 ₹1,27,629、2,652,386）在預設 30pt 時會換行。請傳入 numSize:20（statGrid）——封面會自動處理此問題。
• 寬／長表格會超出底部。 全寬表格在 rowH:0.235 時約可容納 13 行資料。如果表格更長或位於統計網格下方，請將其分割為兩個並排表格（每個約 4.4" 寬，colW 5 欄），而不是將行高縮小到無法辨識。請參考 n-SHIELD 投影片 20 的模式。
• 不要過度裝飾封面。 當全寬內容（如統計條）可能與左下角圓環碰撞時，僅使用 arcsTR（跳過 arcsBL）。
• 重新設計時務必保留客戶資料原樣——包括看似數學上不正確的數字。請單獨向使用者標記，切勿擅自「修正」。

工作流程

1. 閱讀 example.js；複製為 build.js。
2. 使用上述建置器建立投影片；以原始長寬比使用任何客戶提供的創意圖片。
3. 每次都需要轉換為圖片進行品質檢查：soffice --convert-to pdf 然後 pdftoppm -jpeg，或使用 thumbnail.py。在交付前務必目視檢查——檢查是否有數字換行或表格溢出的情況。
4. 將最終的 .pptx 複製到 outputs 目錄並提交。