Visual Craft

Visual Craft - 視覺化設計與重繪

先判定意圖，再選流程。

Intent decision tree

1. 使用者要修改既有圖片，且要求保留其中部分內容時，判定為 edit。
2. 使用者提供圖片，但圖片只用於風格、構圖、氛圍或主體參考時，判定為 generate。
3. 使用者沒有提供圖片時，判定為 generate。

判定依據是使用者希望如何使用圖片，不是附件是否存在。 同一張圖片可以是 edit 的修改目標，也可以只是 generate 的參考素材。

edit：節點、連線、群組與文字以來源為準，只修改使用者授權的部分。 generate：先從需求建立內容與結構，再依 references/canvas-design-system.md 完成視覺設計。 Generate 工作開始前必須完整讀取該 reference。

樣式掛在角色上，不掛在圖元上。「主標題」「註解卡片」「控制流虛線」是角色， 具體的字級與色值是筆調與顏色對它的實作。這一層讓同一套樣式能同時落到 SVG 與 PPTX——角色是契約，媒材是實作。

先讀 references/roles.md。 沒有角色詞彙，下面三層無從掛載。

媒材對映：SVG 見 references/render-svg.md，PPTX 見 references/render-pptx.md。

Rendered-output QA branch：產出或大幅修改 SVG、PPTX 或其他固定版面視覺成品時，完成內容核對與本 skill 的格式檢查後，執行 visual-output-qa skill。 它擁有跨媒材的 rendered truth 原則與最終交付 verdict；本 skill 只保留圖表設計、內容保留與媒材建構規則。

字級是硬底線。 最小字級以畫布寬度的百分比定義（內文 2.0%、標題 3.5%）， 因為 SVG 會縮放，絕對 px 沒有意義。預設畫出來的字通常太小，就是因為 畫布給得大方而字級照抄螢幕習慣。完整表與版面最佳化定義在 references/typography.md。

一次只換一層。 使用者說「換個配色」就只動顏色；說「改成分層的」就只動結構。 同時動兩層會讓他無法判斷是哪一項造成差異——想連換就分兩次做。

選筆調與顏色

先問這張圖給誰看。 不確定就用下面兩個起手式，多數情況夠了。

要別的組合再往下看。筆調與顏色各選一個，兩者獨立。

筆調（pens/）

顏色（themes/）

唯一的搭配限制：blueprint 筆調必須配 blueprint-mono 主題，反之亦然。 其餘非 blueprint 的筆調與主題可自由組合。

換色前先列對照表

套色之前，先列出這張圖的「角色 → 色槽」對照，交給使用者確認。 單獨換配色時尤其要列——那條路徑不經過 edit 流程步驟 1 的清單， 沒有任何東西會逼你回頭確認每個顏色現在代表什麼。

對照表列出來，cat-s 被拿去當強調色這類錯配當場就看得見； 不列，它會一路活到交付——沒有腳本擋得住它（見 maintenance/checks.md）。

先問要不要看預覽

開始重繪前，問一次使用者要不要先看樣式長什麼樣，並附上 docs/style-reference.html——那頁有全部筆調與顏色的實際樣貌， 瀏覽器打開就能看，還能按「灰階檢視」確認黑白列印後仍讀得懂。

盲選的代價是整輪重畫，而「一次只換一層」的規則讓修正更慢。 先看一眼比較快。

怎麼講

推薦時說用途，不說參數。「這張給主管看且會印出來，我用 muted-ledger」 就夠了；灰階間距、明度下限這些是內部推導，不要出現在第一句。

被閘門擋下來時也一樣：先說該怎麼辦，理由收在後面。

✗ 線稿模式邊框需對畫布 3:1，明度上限 30，10% 間距放不下三類。 ✓ 線稿最多只能放兩個類別，這張有三個。可以分組成兩類， 或改用填色的畫法。（純框線的邊框要在白紙上看得見，能用的顏色深度有限。）

流程

Generate 流程

1. 將需求整理為圖的目的、受眾、核心訊息、節點、關係、群組與輸出媒材。
2. 圖片參考只提取使用者指定的風格、構圖、氛圍或主體特徵，不假設要保留其像素或內容。
3. 讀 references/canvas-design-system.md，先寫一句可操作的 visual philosophy，再以它約束空間、色彩、型級、節奏與焦點。
4. 選擇角色、筆調與顏色。結構可從需求建立，不受「沿用素材」限制。
5. 產出後依「核對後交付」檢查內容與格式，再執行 visual-output-qa skill 檢查實際呈現。

完成條件：圖能獨立說明核心訊息，需求中的每個節點與關係都有對應圖元，且沒有未經需求支持的資訊。

Edit 流程

1. 讀素材，抽出結構

抽完後列出清單給使用者確認——節點、連線、群組各幾個。 這份清單同時是步驟 4 的核對基準。 若素材看似缺少回滾、核准等流程環節，列為待確認缺口；不自行補入。

2. 判定原結構編碼的維度

這一步決定哪些 preset 可以選。詳見 references/layer-structure.md。

同維度之內可以互換，跨維度不行。

橫帶改成上下分層，還是三個有序群組，沒有多出任何資訊——換得。 橫帶改成泳道就不行：泳道編碼「誰做的」，而素材從沒說哪個節點屬於哪個角色。 硬換等於憑空指派。

使用者要求跨維度時，停下來說明缺什麼，請他補上對照關係再繼續。 補上之後就換得——缺的是資訊，不是權限。

3. 套用筆調與顏色並推導

python scripts/derive.py themes/<theme>.md

exit 0 才能繼續——腳本會擋下對比不足與灰階不可分。

類別數只有純框線模式有硬上限（3），那是邊框對畫布 3:1 推導出來的。 填色模式沒有上界，能放幾個由色票的明度跨度決定；超過 5 個時腳本會提醒， 但不擋——那是讀者的記憶負擔，不是物理限制。 fill: outline 讓所有色階塌回畫布，邊框變成唯一區隔，對比要對畫布解， 可用明度範圍因此縮小。這是筆調層唯一會影響顏色層的地方， 其餘互不干涉，細節見 references/layer-pen.md。

參考檔

要修改這個 skill 本身（改推導公式、調閘門、加色票、重構參考檔）時， 先讀 maintenance/README.md。那裡有常數登記表、閘門清單， 以及實際發生過的回歸——這套系統的多數錯誤是「修 A 引出 B」。 一般重繪工作不需要讀 maintenance/。

docs/ 底下的東西給人看，agent 不要讀。目前只有 style-reference.html： 用瀏覽器開，頁面結構就是上表這個模型。所有數值都來自上表的參考檔， 讀它的原始碼只是把已經是文字的東西再推導一次，白花 context。

4. 核對後交付

1. 文字比對 — 最優先。PPTX 用 markitdown 前後 diff，必須為空； SVG 逐字比對每個 <text>。
2. 內容核對 — 對回步驟 1 的清單，節點、連線、群組逐項比。
3. 量文字與字級 — python scripts/check_fit.py out.svg --roles <cls=role,…> 作為格式建構前置檢查，檢查估算溢出與最小字級。它不是 rendered-artifact verdict；塞不下時調版面，不縮字。
4. 重跑 derive.py — 確認交付的色值與主題檔一致。 若改動過 derive.py 或任何主題，先跑 python scripts/test_themes.py， 再跑 python scripts/render_reference.py 更新 docs/style-reference.html。
5. 檢查實際呈現：執行 visual-output-qa skill，使用最終交付 renderer 驗證 hard conditions；只有 PASS 才交付。

底線

類別色是承諾。 cat-1 一旦代表某個群組，它在該圖不得再出現在別處。

cat-s 只標異常。 warning、issue、error、blocker 才用它。強調、目前步驟、「最重要的那一步」用 accent。 紅色的訊號太強，一旦同時出現在正常內容與問題上，讀者就分不出哪個是重點、哪個是警告。

一個表面只有一個意思。 卡片是一個東西；色帶區域是一個範圍；虛線框是註解。 註解畫成卡片，讀者會把說明讀成機制的一部分。

顏色不單獨承載意義。 每個由顏色編碼的區隔都要有第二通道——標籤、位置、形狀或線型。 掉成灰階後仍要讀得懂。

同形狀等於沒有 landmark。 動作、元件、資料源、治理關卡畫成同一種圓角矩形， 讀者每次都得重新讀字才知道那是什麼。

素材原本的視覺缺陷值得指出，但不要默默修掉。 標籤太長、群組不平衡、 兩個節點其實是同一件事——說出來讓使用者決定，不要在重繪時一併「改善」。