Prototype Sketching Skill
讓一個正常運作的網頁應用程式看起來像是手繪的，讓客戶明白這還只是原型，而非最終產品。這是一個純視覺風格的外觀套件。它是完全附加且可完全還原的。
範圍界限（請先閱讀，切勿違反）
- 只觸碰樣式進入點和
index.html。 附加一份樣式表、貼上一個 SVG 區塊、設定兩個屬性。其餘皆不可動。 - 絕不編輯 元件、樣板、
.ts/.tsx/.jsx/.vue邏輯、路由、狀態、服務或測試。 - 絕不替換元件 為草稿感的元件庫（例如 wired-elements）——那會改寫標記。禁止。
- 絕不重新上色或扭曲 必須保持清晰的標誌、照片、圖表或圖示——請使用 opt-out 類別。
- 還原必須非常簡單：移除
<html>上的兩個屬性即可關閉整個外觀。
運作原理（單一心智模型）
- 一份樣式表
assets/sketch-skin.css定義了全部 5 種風格與草稿感程度滑塊。 - 一個 SVG 區塊
assets/sketch-filters.html定義了抖動濾鏡（#sketch-25…#sketch-100）。 - 啟用方式是在
<html>上設定兩個屬性：data-sketch="<style>"與data-sketch-level="<0|25|50|75|100>"。 - 視覺效果來自：手寫字型切換 + 手繪方框（不規則邊框圓角、平面填色）+ 一個SVG 位移濾鏡，其強度由草稿感程度決定。字型負責文字；濾鏡僅使方框裝飾抖動（絕不模糊文字）。
快速入門（請依序操作）
- 確認要求僅限於外觀。 如果使用者想要修改行為或版面配置，請停止——這超出範圍。
- 辨識框架，找到其全域樣式表與
index.html（請參閱下方配方表）。 - 選擇一種風格（「風格」表格）與一個程度（
0、25、50、75或100）。 - 將外觀 CSS 加入專案的全域樣式：
- 將
assets/sketch-skin.css複製到專案中（例如src/styles.scss）或使用@import匯入。字型的@import已包含在該檔案內（適用於線上使用）。
- 將
- 貼上 SVG 濾鏡：將
assets/sketch-filters.html的內容貼到index.html中<body>開始標籤之後。（必要——filter: url(#sketch-…)僅在這些定義存在於 DOM 中時才能正確解析。） - 啟用：在
index.html中編輯<html>標籤：<html lang="en" data-sketch="balsamiq" data-sketch-level="50"> - 在瀏覽器中驗證。若要還原，請刪除兩個
data-sketch*屬性（附加的 CSS/SVG 可以保持休眠——沒有這些屬性就不會有任何作用）。
風格
data-sketch | 外觀 | 字型 | 適用場景 |
|---|---|---|---|
balsamiq | 乾淨的灰階線框，平面方框 | Balsamiq Sans | 預設「這是模型」 |
sharpie | 粗體黑色麥克筆，厚重筆觸 | Permanent Marker | 白板／工作坊草稿 |
pencil | 淺灰鉛筆，柔和筆觸 | Gaegu | 柔和「鉛筆在紙上」草稿 |
doodle | 俏皮、淺色調強調 | Short Stack | 友善、非正式的概念 |
blueprint | 藍紙上的白色墨水 | Patrick Hand | 技術性「繪圖板」風格 |
草稿感程度
data-sketch-level 控制線條的抖動程度。它會選用不同的 SVG 位移濾鏡：
| 程度 | 效果 |
|---|---|
0 | 手繪方框 + 字型，但筆直、穩定的線條（最乾淨） |
25 | 輕微抖動 |
50 | 明顯手繪感（建議預設值） |
75 | 鬆散、充滿活力的草稿 |
100 | 非常粗糙，最大「塗鴉」感 |
如果設定了 data-sketch 但未設定 data-sketch-level，外觀預設為程度 50。
對角線浮水印（選擇性）
若要為整個畫面蓋上「草稿」戳記，請在 <html> 上加入第三個屬性，並指定要顯示的文字：
<html data-sketch="balsamiq" data-sketch-level="50" data-sketch-watermark="DRAFT">
data-sketch-watermark 會在視口中以對角線方式繪製一個淡淡的、手寫樣式的單字。它是一個固定、不可互動的圖層（pointer-events: none），因此絕不會阻擋點擊、不會改變版面配置，且會在頁面切換與路由變更時保持原位。任何文字都可以使用（DRAFT、PROTOTYPE、CONFIDENTIAL、客戶名稱……）。移除該屬性即可關閉。若使用疊層，浮水印文字欄位則可即時設定。
模態框、彈出視窗與 SPA 導航
因為外觀是透過 <html> 上的屬性啟用，並以全域的 [data-sketch] … 選擇器設定樣式，所有在啟用之後出現的元素都會自動繼承此樣式——包括對話框、彈出視窗、下拉選單、工具提示、通知訊息（包含 portal 掛載的），以及單頁應用程式中導航到的每個畫面。無需為每個元件或路由手動設定。
有兩件事可確保一致性：
- 選擇器清單已涵蓋
dialog、[popover]、[role="dialog"]、[aria-modal="true"]、.modal、.popover、選單、工具提示與通知訊息，以及原生的::backdrop。 - 疊層腳本會監聽
<body>，若框架在路由變更時替換了 body，它會重新注入 SVG 濾鏡，確保抖動效果不會在無聲中消失。（使用靜態屬性模型時，只需將sketch-filters.html貼到<body>後一次即可；SPA 框架會掛載到子根節點，並保持其完整。）
框架注入配方
此外觀與框架無關。以下是精確的目標位置；完整細節請參閱 references/implementation.md。
| 技術棧 | CSS 加入位置 | SVG 貼上位置 | 屬性設定位置 |
|---|---|---|---|
| Angular | src/styles.scss（或 styles.css） | src/index.html 中 <body> 之後 | src/index.html 中的 <html> |
| React / Vite | src/index.css（在 main.tsx 中匯入） | index.html 中 <body> 之後 | index.html 中的 <html> |
| Vue | src/assets/main.css（在 main.ts 中匯入） | index.html 中 <body> 之後 | index.html 中的 <html> |
| 靜態 HTML | 在 <head> 中連結 sketch-skin.css | index.html 中 <body> 之後 | index.html 中的 <html> |
保持特定素材清晰（opt-out）
此外觀不會編輯標記，但若使用者明確要求保護某個元素（例如標誌、圖表），唯一允許的標記變更是對該單一元素加入 opt-out 掛鉤：
<img src="logo.svg" class="no-sketch" alt="Logo">
.no-sketch（或 data-no-sketch）會移除該元素的抖動濾鏡與顏色覆寫。請謹慎使用，且僅在有人提出要求時使用。
互動式預覽疊層（選擇性）
當使用者想要即時切換風格（例如向客戶展示切換效果）時，請使用疊層而非靜態屬性：
- 將
assets/sketch-skin.css加入全域樣式（如同快速入門所述）。 - 在
</body>之前加入一個 script 標籤：<script src="sketch-toggle.js" defer></script> - 完成。腳本會呈現一個浮動面板，包含 OFF + 每個風格一個單選按鈕、一個 0-100% 草稿感滑桿，以及一個浮水印文字欄位，即時切換
<html>的屬性，並將選擇記在localStorage中。它會自動注入 SVG 濾鏡（並在 SPA 替換 body 時重新注入），因此快速入門的第 5 步（貼上sketch-filters.html）就不需要了。
這仍然是純外觀、非破壞性的——腳本只是在設定屬性。移除該標籤即可停用。當要求是「讓我/客戶切換風格」時，請選擇此模型；若需要固定、可截圖的靜態外觀，則使用靜態屬性。
螢幕截圖展示
README.md 中的圖片展示了每一種風格與 0→100% 的程度階梯，這些圖片位於 demo/screenshots/ 目錄中。那些圖片是預先渲染的；互動式示範應用程式與用來產生這些圖片的 Playwright 擷取腳本位於專案的開發原始碼中，不會與已安裝的技能一起捆綁出售。技能本身僅包含 assets/ + references/ —— 無需建置步驟，也無相依套件。
範例
範例 1 — Angular 示範，Balsamiq 風格，中度草稿
- 輸入：「讓這個 Angular 應用程式在明天的示範中看起來像 Balsamiq 線框。」
- 動作：將
sketch-skin.css附加到src/styles.scss；將濾鏡貼到src/index.html；設定<html data-sketch="balsamiq" data-sketch-level="50">。 - 結果：應用程式執行完全相同；但呈現為灰階線框。
範例 2 — React，最大 sharpie 風格
- 輸入：「React 應用程式，完整白板麥克筆外觀，非常粗糙。」
- 動作：在
main.tsx中匯入sketch-skin.css；將濾鏡貼到index.html；設定data-sketch="sharpie" data-sketch-level="100"。
範例 3 — 關閉外觀
- 輸入：「切換回真實 UI。」
- 動作：從
<html>中刪除data-sketch與data-sketch-level。完成——無需其他變更。
疑難排解
| 症狀 | 原因 | 修正方法 |
|---|---|---|
| 方框看起來手繪，但線條完全筆直 | SVG 濾鏡不在 DOM 中，或程度為 0 | 確認 sketch-filters.html 已貼到 <body> 之後；設定程度 ≥ 25 |
| 完全沒有任何改變 | 屬性遺漏或 CSS 未載入 | 確認 <html data-sketch="…"> 存在，且 sketch-skin.css 已加入全域樣式 |
| 文字看起來模糊 | 濾鏡套用到了文字/整個 <body> | 不要將 filter: 加到 body 或文字上；此外觀只會濾鏡方框裝飾——請重新複製未修改的 sketch-skin.css |
| 字型不是手寫體 | 離線 / Google Fonts 被封鎖 | 自行託管字型——請參閱 assets/fonts/README.md |
| 在大型表格/網格上頁面反應遲鈍 | feDisplacementMap 在大型 DOM 上的成本 | 調低程度，或縮小抖動選擇器清單的範圍（請參閱 references/implementation.md） |
| 標誌變得去飽和/抖動 | 該素材未設定 opt-out | 在該單一元素上加入 class="no-sketch" |
| 圖示字型 / SVG 圖示消失 | 過度扁平化 | 在圖示容器上加入 no-sketch，或參閱 references/implementation.md 中的圖示說明 |
參考檔案（僅在需要時閱讀）
references/styles.md—— 每種風格的精確字型/色板/筆觸規格，以及如何新增一種風格。references/implementation.md—— SVG 濾鏡計算、每個框架的逐步操作步驟、選擇器調整、離線字型、效能、還原細節。