# Visual Craft

> 設計或重新上樣式結構化視覺化作品：先判定 generate 或 edit；edit 保留指定的既有內容， generate 從文字需求建立新圖，並套用 canvas composition 原則。 使用者要求「幫我設計一張圖」「產出架構圖」「畫流程圖」、 「幫我把這張圖的樣式調一調」「換個配色」「這幾張圖要看起來一致」時使用。 輸入可為 SVG、PPTX、Mermaid、圖片、節點與關係條列，或只有主題與需求。

- Skill: `leoluyi/visual-craft` (Agent Skill, multi-file: 59 files)
- Install (CLI): `npx skillmds@latest add leoluyi/visual-craft`
- Raw SKILL.md: https://api.skillmd.com/api/skills/leoluyi/visual-craft/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: leoluyi (https://skillmd.com/u/leoluyi)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/leoluyi/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`。** 沒有角色詞彙，下面三層無從掛載。

| 層 | 決定 | 預設 | 定義在 |
|---|---|---|---|
| 筆調 | 每個角色的幾何：圓角、線寬、線型、密度 | `pens/` 三選一 | `references/layer-pen.md` |
| 顏色 | 每個角色的墨色：填色、邊框、文字 | `themes/` 八選一 | `themes/` |
| 結構 | 怎麼排 | **沿用素材** | `references/layer-structure.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`。

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

## 選筆調與顏色

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

| 起手式 | 給誰看 |
|---|---|
| `console` + `muted-ledger` | 內部文件、簽呈、評估報告，之後會印出來 |
| `console` + `solarized-light` | 技術文件、規格書，在螢幕上讀 |

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

**筆調**（`pens/`）

| 給誰看 | 用哪個 | 特徵 |
|---|---|---|
| 技術文件、螢幕、節點多 | `console` | 方正緊湊、細框 |
| 投影、會議、非技術聽眾 | `briefing` | 柔和寬鬆、粗框 |
| 附錄線稿、黑白影印 | `blueprint` | 純框線、無填色 |

**顏色**（`themes/`）

| 給誰看 | 用哪個 | 類別數 |
|---|---|---|
| 技術讀者、長時間螢幕閱讀 | `solarized-light` | 3 |
| 會被印出來或影印 | `muted-ledger` | 3 |
| 要跟既有前端介面一致 | `tailwind-default` | 4 |
| 技術簡報、網格紙感、亮藍焦點 | `gridline-studio` | 4 |
| 教學簡報、暖白底、橘色焦點 | `warm-clarity` | 3 |
| 四階流程，起點深、暖冷有方向、會印出來 | `dusk-ramp` | 4 |
| 四階流程，螢幕、要色相跨得遠 | `spectral-ramp` | 4 |
| 附錄線稿（僅配 `blueprint`） | `blueprint-mono` | 3 |

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

### 換色前先列對照表

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

| 圖上的東西 | 角色 | 色槽 |
|---|---|---|
| 主要流程節點 | `surface/card` | `cat-1` |
| 這一步最重要 | `text/emphasis` | `accent` |
| 失敗與風險 | `state/issue` | `cat-s` |

對照表列出來，`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. 讀素材，抽出結構

| 素材 | 讀法 |
|---|---|
| SVG | 直接讀原始碼。節點取 `rect`／`path` 加其內的 `text`；連線取 `line`／`path` 加 `marker-end` 判方向；群組取包住多個節點的底層 `rect` 或 `<g>` |
| PPTX | 用 `pptx` skill 解壓後讀 `ppt/slides/slideN.xml`。圖形取 `<p:sp>`，文字取 `<a:t>`，連線取 `<p:cxnSp>`。先跑 `markitdown` 存一份文字基準供步驟 4 比對 |
| Mermaid／DOT 等原碼 | 直接解析，節點與邊都是明寫的 |
| 文字條列 | 節點是名詞，連線是「→」「接著」「送到」，群組是縮排或小標 |

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

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

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

| 群組代表 | 維度 | 可用 preset |
|---|---|---|
| 階段、步驟、時序 | 有序 | `phase-bands`、`layered-stack` |
| 角色、系統、團隊 | 參與方 | `swimlanes` |
| 沒有群組 | — | `chain` |

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

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

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

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

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

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

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

### 參考檔

| 檔 | 內容 | 何時讀 |
|---|---|---|
| `roles.md` | 角色詞彙：文字／表面／線條 | **最先讀**，其餘都掛在它上面 |
| `layer-color.md` | 顏色層：色階推導與對比約束 | 選定主題後 |
| `layer-pen.md` | 筆調層：圓角、線寬、線型、空間骨架 | 選定筆調後 |
| `layer-structure.md` | 結構層：維度判定與 preset | 步驟 2 |
| `typography.md` | 型級、最小字級、版面最佳化 | **寫任何文字前** |
| `adding-a-theme.md` | 從色票到新主題的完整流程 | 使用者給新色票時 |
| `render-svg.md` | SVG 實作：節點路徑、輸出結構 | 產出 SVG 前 |
| `render-pptx.md` | PPTX 實作：圖形對映、文字保護 | 產出 PPTX 前 |
| `canvas-design-system.md` | 新圖的 visual philosophy、構圖、色彩、節奏與精修準則 | **generate 模式必讀** |

**要修改這個 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。** 動作、元件、資料源、治理關卡畫成同一種圓角矩形，
讀者每次都得重新讀字才知道那是什麼。

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