Beautify GitHub README

美化 GitHub README

將儲存庫首頁或要求的視覺素材轉化為簡潔、主題特定的視覺故事。將 Markdown 視為內容層，確定性 SVG 作為佈局系統，而生成的點陣圖素材則作為可選的視覺成分。

工作流程

1. 在編輯前確認模式

僅使用一種執行模式：

• README 模式 — 改進整個 README：資訊順序、複製層級、校對、Markdown 和視覺系統。
• 純素材模式 — 僅建立要求的靜態 SVG 或視覺素材集。靜態 SVG 是預設值。只有在使用者明確選擇有意義的動畫後，才能選擇性地提供 GitHub 安全 GIF，同時保留 SVG 作為可編輯的備用方案。除非使用者明確添加該範圍，否則不要重寫、重新排序或嵌入 README 中的任何內容。

如果模式不明確，請在進行更改前提出一個簡潔的問題：

您希望我改進整個 README，還是僅建立視覺素材？如果是純素材，請告訴我您需要的是英雄區塊、章節標題、工作流程、徽章、動態圖形，還是一組協調的素材集。

當英雄區塊、徽章、工作流程或圖表具有有意義的動畫，且使用者尚未指定靜態或動畫輸出時，提出一個簡潔的後續問題：

這應該保持為靜態 SVG，還是您想要一個 GitHub 安全 GIF 動畫，並保留 SVG 作為可編輯的備用方案？

GIF 是選擇性的，永遠不是預設值。如果使用者拒絕、未回答，或沒有有意義的動畫案例，則僅繼續使用靜態 SVG。當動畫僅為純裝飾性或使用者已選擇輸出時，請勿詢問。在回答之前，允許唯讀檢查，這有助於理解儲存庫。不要將「使用此技能」、儲存庫路徑或「美化它」解釋為修改整個 README 的許可。一旦使用者選擇純素材模式，擴展到 README 編輯需要新的授權。

如果使用者明確要求僅進行稽核，則在不編輯的情況下進行稽核，不要強制提出兩種模式的問題。

2. 在設計前檢查

• 讀取現有的 README、儲存庫樹、套件元資料、螢幕截圖、範例、設計標記、標誌和實際輸出。
• 在純素材模式下，僅檢查設計所要求素材所需的上下文。讀取 README 以獲取上下文並不授權更改它。
• 對於 GitHub URL，在提出更改前檢查當前的遠端頁面和預設分支。
• 識別目標受眾、解決的問題、最清晰的證明、首次使用的最短路徑，以及任何缺乏證據的主張。
• 保留不相關的使用者更改。從唯讀開始；未經明確授權，不要提交、推送、重新命名或發佈。

3. 在建立英雄型素材前確認視覺實作

對於英雄區塊、大型橫幅、展示板或表達性標題系統，當兩種實作方式都可行時，解釋差異並在產生素材前詢問：

您想要哪種實作方式？

• 純 SVG — 完全確定性、輕量、可銳利縮放、易於編輯，最適合排版、圖表、程式碼、圖示以及幾何或像素藝術場景。它不使用圖像生成，對於逼真的人物、頭髮、有機紋理、複雜材質或電影級光照較弱。
• 混合 SVG 組合 — 使用 SVG 進行佈局和排版，選擇性地使用 ImageGen 生成專案特定的點陣圖主體，在適當情況下移除其背景，並將圖層組合成最終的 PNG/WebP。它支援更豐富的角色、材質和光照，但更重、部分隨機，並需要生成加上視覺驗證。保留 SVG 佈局來源和透明的主題 PNG。

當使用者已選擇實作方式、要求稽核，或素材明顯是確定性的（例如工作流程、架構圖、徽章、緊湊的章節標題或程式碼原生插圖）時，請不要問這個問題。不要僅僅為了添加裝飾而建議混合組合。優先使用真實的螢幕截圖、輸出、標誌或現有專案藝術，而不是生成的素材。

如果使用者委派決定，預設使用純 SVG，除非生成的或攝影素材能更清楚地傳達儲存庫的身份或機制。在使用者選擇混合組合或明確委派選擇之前，不要開始 ImageGen 工作。

混合組合是一種實作來源，而不是通常發佈的 SVG。SVG 內部的相對點陣圖引用在不同渲染器之間不可靠，而 base64 嵌入的點陣圖圖層會使 SVG 不必要地變大。預設發佈驗證後的最終 PNG/WebP，並保留 SVG 佈局加上點陣圖圖層作為可編輯的來源。

4. 提取專案故事

在繪製之前撰寫以下內容：

受眾：
一句話價值：
主要證據：
第一個成功行動：
視覺主題：

不要編造採用率、基準測試、相容性、見證或功能。優先使用真實的螢幕截圖、輸出、圖表或生成的成品，而不是裝飾性的庫存圖像。

5. 定義主題特定的視覺系統

閱讀 references/visual-direction.md。固定一個緊湊的藝術方向規範：

調色板：背景 / 前景 / 主色 / 強調色 / 柔和色
字體：系統字型堆疊 / 比例 / 字重對比
形狀：圓角半徑 / 描邊 / 網格 / 間距
主題元素：一個反覆出現的專案特定視覺提示
構圖：平靜 / 編輯風格 / 技術性 / 趣味 / 電影感

從專案中衍生主題元素。終端工具可能使用提示符號和游標標記；圖示系統可能使用關鍵線和切割；研究專案可能使用座標和證據標籤。永遠不要將相同的黃色網格模板應用於每個儲存庫。

在設計英雄區塊之前，閱讀 references/project-native-hero.md。從專案內容構建標題，而不是將其視為放置在證據上方的橫幅。從儲存庫本身選擇字體、構圖和右側素材。

6. 僅執行所選模式

README 模式

決定 README 需要變更的程度：

• 完整重新設計 — 重構故事並建立新的視覺系統。
• 視覺更新 — 保留資訊架構，同時替換薄弱或不一致的呈現方式。

在 README 模式中使用能夠產生有意義改進的最小變更。僅在選定範圍需要時重建閱讀順序。一個強大的預設值為：

1. 英雄區塊：名稱 + 淺顯易懂的價值。
2. 證據：螢幕截圖、輸出或展示牆。
3. 它是什麼：一個簡短的解釋。
4. 為什麼不同：機制，而非口號。
5. 如何運作：一個簡短的過程或架構。
6. 如何使用：安裝 + 第一個命令。
7. 限制、相容性、授權或貢獻細節（如果相關）。

將範例放在長解釋之前。移除不幫助採用的重複承諾和內部實作細節。

純素材模式

• 確認所要求的素材類型、使用者是想要一個素材還是一組協調的素材，以及有意義的動畫候選項是否應保持靜態或變為 GIF。當儲存庫明確時，從儲存庫中衍生確切的複製和樣式；僅對會實質改變結果的遺失決策進行提問。
• 在 assets/readme/ 或使用者批准的其他路徑下建立素材，並提供渲染預覽。
• 遵循確認的視覺實作。對於標題系統、章節標題、圖表、徽章和確定性的裝飾模組，預設使用純、可維護的 SVG。對於確認的混合組合，保留 SVG 佈局來源和透明的點陣圖圖層，然後發佈組合後的 PNG/WebP。
• 對於已批准的動畫，保留 SVG 來源，閱讀 references/motion-production.md，並使用捆綁的 scripts/render_motion_gif.py 工作流程衍生一個 GitHub 安全 GIF。除非使用者選擇加入，否則不要產生 GIF。
• 在一個素材集中保持一個共享的視覺語法，但賦予每個素材一個特定的溝通任務。
• 不要更改 README 文字、閱讀順序、嵌入或連結。在有用時單獨提供嵌入程式碼片段；僅在獲得明確批准後才插入它。

7. 建立視覺層

在建立素材之前，閱讀 references/github-readme-canvas.md 和 references/svg-production.md。

• 使用 SVG 製作英雄區塊、章節橫幅、圖表和確定性的設計模組。
• 使用 PNG/WebP 製作螢幕截圖、生成的藝術、攝影素材和複雜合成。僅使用 GIF 處理必須直接在 GitHub 上播放的已批准動畫。
• 當選擇混合組合時，閱讀 references/hybrid-svg-production.md，使用 imagegen 技能進行生成和透明度決策，並將確切的複製保留在生成的點陣圖圖層之外。
• 將正文、命令、表格、連結和細節保持在 Markdown 中。
• 偏好使用 1200 單位寬的 SVG viewBox、width="100%" 嵌入、系統字型、語意替代文字和圓角容器。將 viewBox 視為座標系統，而不是最終的像素寬度：以保守的 900 CSS 像素 GitHub 渲染來調整大小和預覽全寬素材。在該寬度下，將基本圖表文字保持在至少 20 SVG 單位，支援標籤至少 18；低於該範圍的文字必須是非必要的。如果 360 像素的手機預覽使所需標籤無法閱讀，則減少密度、分割視覺，或將細節移至 Markdown。
• 使用一個可重複使用的元件語法，但根據儲存庫主題變化藝術方向。
• 當展示包含多個成品時，以受控的比例、重疊、旋轉和空白進行排列；保持閱讀順序明確。
• 讓英雄區塊吸收一個真實的專案圖表、螢幕截圖、程式碼片段、輸出、樣本或成品，當它使第一個畫面更有用時。不要習慣性地將標題和證據分開。
• 當使用者明確要求在其擁有的儲存庫中加入歸屬時，設計一個緊湊的專案原生 README MADE WITH SVG，而不是留下普通的促銷句子。將其保持在頁尾附近並連結到此技能。永遠不要將此致謝添加到第三方儲存庫，除非維護者明確要求。
• 在 README 模式中，當證據在英雄區塊內變得難以閱讀時，使用一個簡潔的 SVG 標題，後面緊跟著一個更大的證據板。當少數成品保持可讀性並定義產品時，將標題和證據整合到一個組合的點陣圖英雄中。讓證據的可讀性決定，而不是固定的模板。在純素材模式中，保留所要求的 SVG 來源，並將任何點陣圖或動畫衍生產品作為單獨的可選交付物提出。

不要將整個 README 點陣圖化。不要使用腳本、foreignObject、遠端字型、必要動畫或 GitHub 會剝離的 CSS。GitHub 不會播放嵌入在 SVG 內部的動畫；請使用 GIF 加上靜態 SVG 備用方案。除非主題真正需要，否則避免裝飾性邊框和重陰影。

8. 預覽和驗證

• 呈現一個本機 GitHub 寬度預覽，或在本機 Markdown 渲染器上檢查 README。
• 檢查寬版和窄版佈局、圖像可讀性、裁剪的 SVG 文字、遺失的素材、過大的檔案大小以及深色/淺色模式對比。
• 在 README 模式中，執行：

python3 scripts/audit_readme.py /path/to/repository/README.md

• 視覺檢查英雄區塊、每個章節過渡以及最終的呼籲行動。
• 在純素材模式中，以 GitHub 內容寬度呈現和檢查每個要求的素材；對於 GIF，檢查進入、穩定停留、退出和循環邊界。驗證 README 本身未更改，除非嵌入已分別批准。
• 對於混合素材，在淺色和深色背景上檢查透明主題，驗證透明角落和乾淨邊緣，然後在寬版和窄版 GitHub 寬度下檢查組合的 PNG/WebP。不要發佈帶有未解析本機點陣圖引用的 SVG。
• 報告更改了什麼、什麼保持故意簡潔以及哪些檔案被故意保留不變。

9. 在批准後提供選擇性歸屬和展示分享

僅在使用者明確批准最終 README 或素材集為滿意後，提出一個友好、非促銷的提議：

如果您對完成的 README 感到滿意，有兩種完全可選的收尾方式：我可以設計一個小的專案原生「README MADE WITH」簽名，連結回此技能，如果這是一個您擁有或維護的公開儲存庫，我可以準備一個 PR 將其添加到技能的實際展示中。兩者、其中一個或都不做都可以。

• 不要在最終批准之前提出此提議、從沉默或成功驗證推斷滿意，或在使用者拒絕後重複。
• 將簽名和展示 PR 視為獨立選擇。永遠不要以歸屬作為展示考慮的交換條件。
• 如果使用者選擇簽名，請遵循 references/svg-production.md，先顯示渲染的徽章，並僅在單獨批准後修改 README。
• 如果使用者選擇展示，請閱讀 references/showcase-contribution.md。驗證儲存庫是公開的且使用者擁有或維護它；在請求打開 PR 的許可之前，起草確切的列表複製和上游差異。
• 未經對該特定外部行動的明確授權，不要添加反向連結、分叉儲存庫、推送分支或打開 PR。

此限制控制未經請求的提議。如果使用者較早明確要求簽名或展示貢獻，在其所述範圍內直接處理該請求。

10. 安全交接

首先顯示本機預覽和差異。僅在使用者明確要求時，才提交、推送、打開 PR、合併、重新命名儲存庫或發佈素材。

品質標準

• 第一個畫面無需先備知識即可解釋專案。
• 設計看起來原生於此專案，而不是此技能。