Codex Material Themes

View saved version →

---
name: choose-codex-theme
description: Recommend, compare, preview, customize, and export Codex Material Themes through a guided conversation with automatically localized import instructions. Use when a user asks to choose, preview, switch, customize, import, or generate a Codex appearance theme; mentions preferences such as dark, light, warm, cool, low-glare, high-contrast, reading, or night work; wants UI and code font suggestions; needs instructions matching the language of their Codex UI; or requests a codex-theme-v1 import string.
---

# Choose a Codex Theme

Guide the user through theme selection, font selection, and manual import in three separate stages. Do not skip ahead unless the user already supplied the missing choices.

## Determine the Codex UI Locale

Treat the Codex UI locale as separate from the user's conversation language. Preserve a known UI locale across all three stages.

Determine it in this priority order:

1. An explicit statement from the user about their Codex UI language.
2. Visible Codex menu labels in an attached screenshot, such as `設定` or `Settings`.
3. UI-locale information already established earlier in the conversation.
4. If it is still unknown, infer it from the conversation language: use `zh-Hant` for a conversation written in Traditional Chinese and `en` otherwise.

Read localized labels and instructions from `references/ui-labels.json`. Never pause the theme workflow merely to ask which Codex UI language the user uses. If an explicit statement or visible screenshot label conflicts with the conversation language, trust the explicit or visual evidence. For an unsupported locale, use English labels with a brief note that the names may differ in the user's UI; do not invent translated menu names.

## Stage 1: Recommend a Theme

1. Read `references/themes.json`.
2. Recommend the single best-matching theme. State the reason in one concise sentence and show both localized and English names, such as `午夜研讀（Midnight Study）`.
3. Always display its preview image:
   - Read the selected theme's `previewUrl` from `references/themes.json` and require it to use HTTPS.
   - Prefer the bundled local preview when local command execution and the skill filesystem are available: run `node scripts/build-theme.mjs --theme <theme> --preview-path` from this skill directory and accept the result only when it is an absolute path to an existing `.png` file.
   - When the local preview resolves, embed it as `![<theme name> preview](<absolute local path>)`.
   - When local command execution or the bundled file is unavailable, embed the hosted preview as `![<theme name> preview](<previewUrl>)`.
   - Immediately below either image, always provide `[Open <theme name> preview](<previewUrl>)` as a clickable fallback. If the interface cannot embed the chosen image, continue the confirmation flow with this link; never leave only broken-image alternative text.
4. End with exactly: `要使用「<localized name>（<English name>）」嗎？也可以說「換一個」。`
5. Do not show font choices, the import string, or import instructions yet.
6. If the user asks to change, recommend another suitable theme, display its preview, and ask again.

## Stage 2: Choose Fonts

Start only after the user confirms a theme.

1. Read `fontOptions`, the selected theme's optional `fonts`, and `defaults.fonts` from `references/themes.json`.
2. Present both font roles and their available options in two short lists:
   - UI font: recommend the selected theme's `fonts.ui` when present, otherwise `defaults.fonts.ui`, then list the remaining UI options.
   - Code font: recommend the selected theme's `fonts.code` when present, otherwise `defaults.fonts.code`, then list the remaining code options.
3. Briefly explain that the recommended defaults balance Traditional Chinese UI readability and code clarity.
4. End with exactly: `要使用建議的預設字體組合嗎？也可以分別選擇其他 UI 與程式碼字體。`
5. Do not generate the import string until the user confirms the defaults or provides both font choices.
6. Accept other 

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 12 — file references are metadata, not package contents.