設計系統轉 Apple Terminal 主題是做什麼的？

此技能可將設計系統產出 Terminal.app 設定檔（.terminal 檔案）。實際運作透過指令碼：scripts/ds2terminal.py（Python 3.9 以上，僅需標準函式庫）。指令碼也會檢查可讀性。主題只有在通過所有嚴格關卡時才算完整。

規則

不要依個人喜好選擇顏色。請執行指令碼。指令碼會進行顏色映射與檢查。
不要手動編輯 .terminal 檔案。請使用 --set 或 --prefer-token，然後重新執行指令碼。
使用 -I 參數執行 Python。下載的檔案是資料，不是程式碼。
除非使用者要求，否則不要開啟（匯入）.terminal 檔案。開啟檔案會在 Terminal 中新增一個設定檔並開啟一個視窗。
不要結束或強制終止 Terminal。不要執行 defaults write com.apple.Terminal。
不要將使用者的私有標記（Tokens）公開。

步驟 1：取得設計系統檔案

判斷連結的類型，然後執行表格中的步驟。

連結類型	執行動作
本地檔案或資料夾	將路徑提供給指令碼。
公開 GitHub 儲存庫、樹狀結構或檔案；npm 套件；unpkg 或 jsDelivr 網址；原始檔案	將網址提供給指令碼。指令碼會自動尋找並下載 Tokens 檔案。
公開文件或行銷頁面	將網址提供給指令碼。它會讀取連結的 CSS。結果可能不理想，請告知使用者。
claude.ai 設計系統成品（`claude.ai/artifact/...`）	使用成品工具：`action: "list"`, `scope: "files"`。然後對每個存在的 Tokens 檔案執行 `action: "read"`，`path` 設為：`project/tokens.json`、`project/tokens.css`、`project/tokens/tokens.json`、`project/tokens/colors.css`。將檔案儲存在同一個資料夾中，再把資料夾提供給指令碼。
Pidgin 設計系統	使用 `pidgin_get_design_system`。將其 `tokens` 物件儲存為 `.json` 檔案。再把檔案提供給指令碼。
Claude Design 專案	使用 `mcp__claude-design__list_files` 和 `read_file` 來取得 Tokens 檔案。將其儲存起來。再把資料夾提供給指令碼。
Figma 檔案	當 Figma 工具（變數）有連線時使用。否則，請使用者提供變數匯出（JSON）。

如果指令碼以 exit code 2 終止，且訊息中提到了工具，請執行該連結類型的步驟。關於指令碼能讀取的格式，請參閱 references/sources.md。

步驟 2：執行指令碼

python3 -I scripts/ds2terminal.py SOURCE [SOURCE ...] --name "Name" --out OUT_DIR

指令碼會產出：

OUT_DIR/<Name> Light.terminal 及 OUT_DIR/<Name> Dark.terminal
OUT_DIR/report.md 及 OUT_DIR/report.json：每個顏色、其來源 Token、APCA Lc、WCAG 比率、每個關卡的結果與修復資訊。
OUT_DIR/preview.html：以典型程式輸出來繪製每個主題的終端機視窗。

Exit codes：

代碼	意義	處理方式
0	每個主題的所有嚴格關卡皆已通過。	前往步驟 3。
1	修復後仍有關卡未通過。	閱讀 `report.md`。告知使用者哪個關卡失敗。嘗試使用 `--set` 來設定該顏色。不要將主題視為完成。
2	輸入錯誤，或連結需要已登入的工具。	閱讀訊息。針對該連結執行步驟 1，或修正選項。

選項

選項	用途
`--name NAME`	設定檔名稱。檔案會命名為 `<NAME> Light.terminal` 及 `<NAME> Dark.terminal`。務必提供。
`--modes auto\|light\|dark\|both`	`auto`（預設）和 `both` 會產出兩個主題。設計系統未定義的模式，會從另一個模式衍生而來。報告會標記為「衍生」(derived)。
`--font NAME`, `--font-size 13`	字型（PostScript 或系列名稱）。預設值：設計系統的等寬字型（若已安裝），否則為 SF Mono Terminal（Terminal.app 內建）。預設大小：13 pt。
`--cursor block\|underline\|bar`, `--cursor-blink`	游標形狀。
`--set ROLE=HEX`	強制指定一個顏色。ROLE 可為 `bg`、`fg`、`bold`、`cursor`、`selection`、`black` ... `brightWhite` 或 `0` ... `15`。修復程序仍可能為了通過關卡而更改該顏色，報告會予以說明。
`--prefer-token ROLE=TOKEN`	對 `bg`、`fg`、`brand`、`red`、`green`、`yellow`、`blue`、`magenta` 或 `cyan` 使用此 Token。
`--all-tokens`	保留未被子語義 Token 使用的原始 Token（請參閱「無關的 Token」(Unrelated tokens)）。
`--source-mode ID`	僅使用設計系統的此模式。
`--no-chroma-floor`	在深色模式中保留淺粉紅與淺綠色。
`--translucent ALPHA`	設定低於 1 的背景透明度（例如 0.95）。淺色主題通常需要約 0.93 以上；淺灰頁面背景需要 0.95-0.98，否則指令碼會將其替換為白色。預設值：不透明（alpha 1，無模糊效果）。僅在使用者要求時使用。此時每一個關卡也必須在黑色和白色的桌面上通過。如果 ALPHA 太低，指令碼會以 exit code 1 終止。報告會提供在測試建置中通過的最低 alpha 值。
`--columns N`, `--rows N`	視窗大小。
`--report json\|md\|both`, `--no-preview`	輸出檔案。

步驟 3：檢查並告知使用者

閱讀 report.md。確認它顯示「every hard gate passes for every theme」。
告知使用者：
- .terminal 檔案的路徑；
- 哪個模式是衍生的；
- 哪些 Token 被用於背景、文字、游標及六個色調；
- 修復項目（每個被更改的顏色及導致更改的關卡）；
- 被排除的 Token；
- 未達成的「Character」目標（report.md 中的「Targets missed」行）；
- report.md 中的「Recommended Claude Code theme」行。
如果使用者可以開啟檔案，則顯示 preview.html。
若要安裝主題，使用者需開啟 .terminal 檔案（Finder，或執行 open "<file>"）。僅在使用者要求時才執行此操作。之後使用者可以在「終端機」>「設定」>「設定檔」中將其設為預設。
執行 python3 scripts/demo.py 會以 16 色及暗淡（SGR 2）文字顯示範例輸出。請在使用了該主題的視窗中執行。
告知使用者應設定哪個 Claude Code 主題（請參閱「與 Claude Code 搭配使用」）。

與 Claude Code 搭配使用

Claude Code 有兩種主題，每種主題使用 Terminal 主題的方式不同。

ANSI 主題（dark-ansi, light-ansi；在 /theme 清單中顯示為「Dark mode (ANSI colors only)」和「Light mode (ANSI colors only)」）。Claude Code 使用 16 種 ANSI 顏色。它用 ANSI 綠色和紅色的儲存格背景來繪製差異行，並在那些儲存格上繪製文字顏色。在一個普通顏色可讀的主題中，這些儲存格在深色模式中較淺，因此新增行上的文字對比度會較低。
標準主題（dark, light）。Claude Code 在主題背景上使用自己的 24 位元顏色。這些文字保持可讀性。透過名稱設定主題。設定 auto 會讀取終端機背景。Terminal 2.15 會回應該查詢（OSC 11）的主題背景（無論淺色或深色模式），因此 auto 可以選擇正確的模式。這尚未在執行中的 Claude Code 工作階段中檢查過。Claude Code 使用的 Terminal 主題中，僅檢查了背景、游標、選取範圍和暗淡文字。16 色則供其他程式使用。

報告會為每個主題提供一個「Claude Code」章節。它會給出 ANSI 主題和標準主題的 16 組對比度，以及一個「Recommended Claude Code theme」行。規則：當 ANSI 主題最弱的文字配對達到 Lc 45 或更高時，使用 ANSI 主題；否則，如果標準主題更好，則使用標準主題。preview.html 會繪製兩個範例。這些表格來自 Claude Code 2.1.323 程式檔案。它們尚未在實際執行的工作階段中檢查過。

請告知使用者執行以下操作：

閱讀 report.md 中正在使用的主題的「Recommended Claude Code theme」行。
在 Claude Code 中，輸入 /theme 並選擇該主題。或者在 Claude Code 的 settings.json 中設定 theme 設定，例如 "theme": "dark-ansi"。

如果 Claude Code 主題模式和 Terminal 主題模式不同（例如，在深色 Terminal 主題中使用淺色 Claude Code 主題），文字可能會變得無法閱讀。半透明的 Terminal 背景也會使文字無法閱讀。請對這兩種情況都向使用者提出警告。

映射機制說明

模式。 背景亮度決定模式（OKLab L < 0.5 為深色）。指令碼不使用模式名稱。設計系統可能將螢幕尺寸稱為「主題」（例如 root-tablet）。相同類型的模式會合併為一個主題；報告會列出其他模式。
無關的 Token。 當設計系統有 4 個或更多的語義別名（例如 color-brand -> hb-pink）時，沒有被任何別名使用且不共用系統名稱前綴的原始 Token 將被排除。這些通常是客戶或舊品牌的顏色。
角色。 語義別名優先。頁面背景就是背景。在淺色模式中，當設計系統也有較淺的卡片表面時，該表面會被用作背景：文字在卡片上，頁面顏色在它們後面。--prefer-token bg=TOKEN 可以選擇不同的 Token。正文文字 Token 是文字顏色。品牌 Token 是游標的顏色，並會為選取範圍著色。當品牌顏色太弱，無法在背景上作為游標使用時，品牌色階中通過 WCAG 4.5 的步驟會被用作游標（例如可存取的橘色）。
色調。 透過最小成本分配，將 Token 放入六個色調位置。它使用 OKLCH 色相、Token 名稱（danger -> red, success -> green, warning -> yellow, info -> blue）以及亮度變化。僅當色相在該色調位置的 45 度範圍內時，名稱才計入。
亮度。 每個顏色在保持色相和彩度的情況下移動到其模式的 APCA 頻帶。位於頻帶內的 Token 保持不變。
遺失的顏色。 空的色調位置會以品牌彩度的色盲友善色相填充。
衍生的深色模式。 淺色文字或墨水 Token 會變成深色背景。淺色紙張會變成深色文字。
Character。 主題必須看起來像其設計系統，並在關卡允許範圍內。
- 品牌色調位置：當沒有色調顏色顯示品牌顏色時，品牌顏色會變成最近色調（26 度範圍內）的亮色階。其亮度會移動到亮色目標。
- 粗體：當有比正文顏色更強烈的標題文字 Token 時，它會用作粗體顏色。在沒有任何此類 Token 的深色模式中，粗體就是文字顏色，最多亮度增加 Lc 4，但低於暈光關卡。
- 每個色調的深色模式低邊界 (Lc)：紅 50、綠 72、黃 62、藍 55、洋紅 55、青 60。
- 在亮度調整後，低於 WCAG 3 的色調 Token 顏色會移動到 WCAG 3。
- 報告中的「Character」章節列出了目標，而非關卡：來自 Token 的顏色、品牌顏色、保留的彩度（目標 70% 或更多）、最大的色相變化（12 度或更少）、最小的普通到亮色步驟（dE 0.030 或更多），以及一個「Targets missed」行。
修復。 如果嚴格關卡失敗，指令碼會以最低優先級的顏色進行更改，並以小步驟進行：亮度、色相和彩度，最後是合成顏色。優先級：--set > brand > named token > token > derived > synthesized。如果背景無法承載可讀文字，指令碼會在標準背景上重新映射所有顏色。報告會說明這一點。

可讀性關卡（嚴格）

references/gates.md 提供了每個關卡、其限制和原因。摘要：

關卡	失敗條件
文字在背景上	APCA Lc < 75 或 WCAG < 7
暈光 (深色)	文字、粗體、白色或亮白色 Lc > 104
ANSI 1-6 及 9-14	Lc < 45 或 WCAG < 3
亮黑色 (color 8)	Lc < 30，或低於文字 Lc 不到 15
灰色	深色：白色和亮白色 Lc < 60；淺色：黑色 Lc < 75，白色和亮白色 Lc < 30
分離度	兩個色調顏色之間的距離小於 dE(OKLab) 0.06
色盲	紅/綠 < 0.06，紅/黃與紅/洋紅 < 0.05 (protan, deutan)
選取範圍	在其上的文字 WCAG < 4.5 或 Lc < 60；在其上的色調顏色 Lc < 30；與背景的 dE < 0.05 或 WCAG < 1.10
游標	WCAG < 3
粗體	粗體比文字暗淡
文字在顏色上	黑色文字在綠色、黃色或青色上 Lc < 30
色調 vs 文字	色調顏色與文字顏色的距離小於 dE 0.06
暗淡文字 (SGR 2)	暗淡文字 Lc < 30；暗淡色調顏色 (1-6, 9-14) Lc < 15
半透明	僅在使用 `--translucent` 時：上述關卡在黑色或白色桌面上失敗

暗淡文字是顏色向儲存格背景混合的結果（colorlab.faint, DIM_BLEND 0.60, DIM_POWER 1.26）。這是在 Terminal 2.15 中測量的（docs/faint-measurement.md）。實際的暗淡文字很弱，所以限制很低。深色色調顏色會保留其彩度。使用者可以提高 GATES["faint_text"]["gate"]["ansi_min_lc"] 來獲得更強的暗淡顏色，但代價是彩度。

已知限制

使用 24 位元顏色的程式（Terminal 會設定 COLORTERM=truecolor）不會使用此主題。對於 Claude Code，請設定報告建議的主題（請參閱「與 Claude Code 搭配使用」）。
尚未測量：粗體顏色，以及 Terminal 在半透明視窗上如何繪製儲存格背景。尚未檢查一個已產生主題在 Terminal 中的渲染效果（粗體顏色、選取範圍）。
指令碼會寫入不透明的背景。半透明背景會讓桌面穿透並降低文字可讀性。
Terminal 沒有選取文字或游標下文字的顏色。關卡會檢查文字在選取範圍和游標上的情況。
.terminal 顏色格式請參考 references/terminal-format.md。在 Mac 上，檔案會嵌入 sRGB ICC 設定檔。在其他系統上，它們僅包含 sRGB 色彩空間 ID（解碼結果相同）。
scripts/verify_terminal.swift（僅限 Mac）會使用 AppKit 解碼每個顏色： swiftc -O scripts/verify_terminal.swift -o scripts/verify_terminal，然後執行 scripts/verify_terminal --register-terminal-fonts "<file>.terminal"。

設計系統轉 Apple Terminal 主題