Themes
Gemini CLI themes 的用途：終端 UI 個性化、可讀性和團隊教程截圖一致性。
Themes 影響 Gemini CLI 的終端顯示。它不是核心能力，但會影響長時間使用的可讀性。
主題配置的目標是可讀和一致，不是把教程截圖做得花哨。終端工具最重要的是文本、diff、warning 和 error 都能看清。
可以透過 /theme 互動選擇，也可以在 settings.json 的 ui.theme 或 ui.customThemes 固定。官方內建深色和淺色主題，也支援 extension 提供主題。
什麼時候需要配置主題
- 深色/淺色終端不匹配。
- 錄屏或截圖需要統一風格。
- 字型顏色在當前終端裡不清晰。
- 團隊教程要保持截圖一致。
配置方式
互動方式：
/theme如果 settings.json 裡已經固定了 ui.theme，需要先移除該配置，否則 /theme 中的互動選擇可能不會覆蓋檔案裡的配置。
自定義主題放在 ui.customThemes，至少要定義 name、type: "custom"、背景色和主要文字色。也可以把主題放在獨立 JSON 檔案裡，再在 ui.theme 指向該檔案路徑。出於安全考慮，Gemini CLI 只會載入位於使用者 home 目錄內的主題檔案。
官方主題變數不只影響普通文字。常見變數包括 Background、Foreground、AccentBlue、AccentPurple、AccentCyan、AccentGreen、AccentYellow、AccentRed、Comment、Gray，以及用於 diff 的 DiffAdded、DiffRemoved、DiffModified。如果主題沒有覆蓋關鍵狀態色，程式碼修改和錯誤提示會很難讀。
一個穩定的教程主題至少要檢查三類畫面：普通對話、工具確認、diff 展示。只看歡迎頁好不好看沒有意義，真正影響學習體驗的是 warning、error、added、removed 這些狀態是否清晰。
教程截圖建議
教程站不要追求花哨主題，優先選對比度穩定、淺深色都可讀的主題。截圖前固定主題、終端字型和視窗寬度，否則同一篇教程裡 UI 變化會顯得不專業。
| 場景 | 推薦做法 | 避免 |
|---|---|---|
| 教程截圖 | 固定主題、字型、視窗寬度 | 每張圖隨機主題 |
| 長時間編碼 | 選擇對比度穩定的主題 | 低對比度彩色主題 |
| 團隊文件 | 用專案文件記錄截圖環境 | 只靠個人終端偏好 |
| 自定義主題 | 先檢查 warning、error、diff 色 | 只看普通文本 |
如果教程面向新手，主題更應該接近預設體驗。過度自定義會讓讀者開啟自己的終端後找不到對應 UI 狀態。
不要過度投入
主題不會提升 agent 質量。先把上下文、許可權、工具、驗證流程做好，再調視覺。
如果主題只是個人偏好，放使用者級 settings；只有教程錄屏、團隊截圖規範或共享開發環境需要一致時，才考慮寫入專案文件。不要因為自己喜歡某個顏色，就把 ui.theme 固定進儲存庫級配置。
常見排錯
主題不生效時，先看 settings.json 裡是否已經固定 ui.theme。如果檔案裡寫死了主題，/theme 的互動選擇可能不會覆蓋這個配置。第二步檢查自定義主題檔案是否在 home 目錄內；官方出於安全原因不會從任意路徑載入主題 JSON。
顏色看不清時，不要只調背景色。優先檢查 Foreground、Comment、AccentRed、AccentYellow 和 diff 相關變數。warning、error、diff 刪除行是教程截圖裡最容易出問題的地方。
截圖驗收清單
教程站截圖要固定三件事：終端寬度、字型大小、主題名稱。每次換主題後，至少截一張普通對話、一張命令確認、一張檔案 diff。三張都清楚，才說明主題適合教學內容。
如果頁面要給讀者複製配置，建議同時說明這是視覺配置，不影響模型能力、配額、上下文和工具許可權。新手最容易把 UI 變化誤解成“模型模式變化”，這一點要在教程裡主動消除。
主題只服務可讀性，不應承擔功能解釋，也不應掩蓋真實命令輸出和錯誤資訊。
驗收方式
執行 /theme 確認可選列表裡出現預期主題。自定義主題要同時檢查普通文本、程式碼塊、diff added/removed、warning/error 狀態色，確保錄屏和截圖中不會看不清。
接下來去哪
Trusted folders
UI 配置結束後，繼續看 workspace 信任和安全邊界。
Settings
主題最終要回到 settings.json 固化。
Local development
如果是錄屏或教程環境，繼續看本地開發配置。