# Wox Theme Creator

> Design, create, and refine Wox theme JSON files, including schema v2 base colors, optional styles, transparency, platform overrides, and local debugging. Use for authoring themes or converting an existing theme while preserving its appearance.

- Skill: `wox-launcher/wox-theme-creator` (Agent Skill)
- Install (CLI): `npx skillmds@latest add wox-launcher/wox-theme-creator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/wox-launcher/wox-theme-creator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: wox-launcher (https://skillmd.com/u/wox-launcher)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/wox-launcher/wox-theme-creator

---


# Wox Theme Creator

Create a deliberately designed theme with a coherent palette, readable states, and a valid authored JSON document. Prefer schema v2 for new themes. Preserve the requested output location and existing theme identity when editing; generate a fresh UUID for a new theme.

## Source of truth

Paths below are relative to the Wox repository root. Read the current implementation before choosing fields; do not invent theme tokens or copy resolved runtime values into a new theme.

- `wox.core/common/theme_schema_v2.go`: complete v2 document, accepted fields, color/geometry defaults, validation, and platform resolution.
- `wox.core/resource/themes/`: built-in themes as working examples.
- `wox.core/common/theme_schema_v1.go`: legacy wire format and behavior, needed when converting an old theme.
- `wox.core/common/theme_runtime.go` and `theme.go`: independent runtime representation, schema dispatch, and Wox version checks. These are not the authored JSON schema.

Each schema owns its complete document and parser. Missing `SchemaVersion` or historical zero means v1. Loading must not rewrite old files. Changing v2 default semantics would change sparse themes; a new format belongs in a separately registered schema, not a retrofit of v1 or v2.

## Author the document

A minimal v2 document looks like this; replace the sample ID and name:

```json
{
  "SchemaVersion": 2,
  "MinWoxVersion": "2.4.3",
  "ThemeId": "66288aad-d3fa-493b-bc46-7e8e7280c40d",
  "ThemeName": "Jade",
  "BaseBackgroundColor": "rgba(28, 35, 37, 0.72)",
  "BaseTextColor": "#E5ECE9",
  "BaseAccentColor": "#70D6A6"
}
```

The three base colors, ID, and name are required. Explicitly declare schema 2. Set `MinWoxVersion` to the release supporting the features used; check current built-ins rather than lowering the floor to make installation succeed. `Version` is the theme's own version, separate from schema and minimum Wox versions. Include truthful author, description, and URL metadata when available. Do not mark a custom theme as system-installed. Automatic appearance themes use `IsAutoAppearance`, `DarkThemeId`, and `LightThemeId`; their required base colors still provide a fallback.

Group overrides by surface: window, query/Glance/Attention, result container/items, Action Panel/items/query, preview/tags, toolbar/keycaps. Keep the document sparse; add overrides for intentional design differences.

| Authored value | Meaning |
| --- | --- |
| Missing or `null` optional style | Inherit/default |
| Integer `0` | Explicit zero; never substitute a default |
| `transparent` or alpha zero | Explicit transparency |
| Empty color, negative/fractional geometry | Invalid |

Colors accept `#RRGGBB`, `#RRGGBBAA` (alpha last), `rgb(r,g,b)`, `rgba(r,g,b,a)`, and `transparent`. RGB channels are 0–255; alpha is 0–1. Geometry uses logical units, not physical screen pixels.

Font sizes are controlled by the application Interface size setting; do not add theme font-size overrides.

## Default window shape and transparency

Unless the user explicitly requests a custom app outline or window corners, omit `AppBorderColor`, `AppBorderWidth`, and `AppBorderRadius` at the root and all platform/variant levels. Do not infer a custom window outline or radius from a reference screenshot or a general request for a rounded visual style. Keep the system/default window shape and use a slightly translucent `AppBackgroundColor` by default (for example, alpha 0.90).

If the user explicitly requests a custom app outline or window corners, author the requested `AppBorder*` fields and default `AppBackgroundColor` to fully opaque (alpha 1). An explicit request for transparency or opacity overrides that default. QueryBox, result, preview, and Action Panel corner settings do not count as a request for custom window chrome. Toolbar and Action Panel may retain modest in-app translucency in either case.

These are theme-authoring defaults, not changes to schema parsing. Apply them when creating themes or when the user asks to restyle an existing theme; do not silently rewrite other existing themes. Keep `BaseBackgroundColor` independent when an explicit app background override is sufficient, so changing window alpha does not unintentionally change every derived surface.

## Design the surfaces together

Start with background, text, and accent roles. Optional colors derive independently from these roles; changing one optional token does not change another. Base alpha also affects derived colors. Consult the resolver for exact defaults instead of duplicating its entire catalog here.

- For translucent themes, consider app, query, Action Panel, action query, preview, and toolbar backgrounds together. An opaque surface can hide translucency beneath it; layered alpha and native materials affect the final appearance.
- V2 `AppContentInset` reserves a uniform logical inset around the entire launcher content, including the toolbar, previews, and floating panels. `AppContentBackgroundColor` paints the inner panel and `AppContentBorderRadius` rounds its background. Defaults are 0, transparent, and 0, preserving existing themes. These fields do not select custom window chrome: use a translucent `AppBackgroundColor` and omit `AppBorder*` to expose a native-material rim. Existing `AppPadding*` remains spacing inside the content panel. Child surfaces retain their own corner styles; the toolbar follows the panel's bottom corners.
- V2 uses `ResultItemActiveIndicatorColor`, `ResultItemActiveIndicatorWidth`, `ResultItemActiveIndicatorInsetLeft`, `ResultItemActiveIndicatorInsetTop`, `ResultItemActiveIndicatorInsetBottom`, and `ResultItemActiveIndicatorBorderRadius` for the selected-result marker. Width defaults to 0, color to the base accent, and insets/radius to 0. Zero insets/radius reproduce the edge strip; use positive insets and radius for a short rounded marker. Reserve icon space with result-item padding; marker geometry does not shift content. The unreleased v2 `ResultItemActiveBorderLeftWidth/Color` fields were removed; v1 keeps its original fields. Check normal, selected, and hovered rows separately; `ResultItemHoverBackgroundColor` controls hover.
- `QueryBoxBorderBottomColor` and `QueryBoxBorderBottomWidth` draw an inside bottom edge without changing query layout. Width defaults to 0; color defaults to the base accent. Zero disables it and explicit transparency is preserved.
- Action Panel border fields are `ActionContainerBorderColor`, `ActionContainerBorderWidth`, and `ActionContainerBorderRadius`. `ActionContainerDividerColor` controls internal separators independently of `PreviewSplitLineColor`.
- Toolbar primary actions (default/bare Enter) support `ToolbarPrimaryFontColor` and `ToolbarPrimaryHotkey{Font,Background,Border}Color`. Omitted values inherit the corresponding effective toolbar colors; explicit transparency is preserved. Configure emphasis here rather than relying on automatic dimming of other actions.
- Keycaps have three independent v2 groups: `ToolbarHotkey{Font,Background,Border}Color`, `ActionItemHotkey{Font,Background,Border}Color`, and `ActionItemActiveHotkey{Font,Background,Border}Color`. All accept explicit transparency. Omitted values derive from base colors, not another surface's overrides: normal text uses secondary text and border uses divider; active text/border use base text; backgrounds default transparent. Set active colors explicitly for contrasting selection backgrounds (for example, white keycaps on blue). The unreleased shared `Hotkey*` fields were removed. Keep keycaps readable without competing with labels.
- `PreviewBorderRadius` and `PreviewTagBorderRadius` control generic preview and metadata-tag corners in logical units. Omitted values retain 8; zero is square.
- Preview has `PreviewBackgroundColor`, `PreviewBorderColor`, existing text/property/selection colors, and `PreviewTagFontColor`, `PreviewTagBackgroundColor`, `PreviewTagBorderColor`. Generic preview tokens do not necessarily control specialized chat, terminal, media, or native/web surfaces.
- Glance has `GlanceFontColor`, `GlanceIconColor`, `GlanceBackgroundColor`, and `GlanceHoverBackgroundColor`. Raster images retain their own colors.
- Attention has `AttentionFontColor`, `AttentionIconColor`, `AttentionBackgroundColor`, `AttentionBorderColor`, `AttentionHoverBackgroundColor`, and `AttentionHoverBorderColor`. Omitted values match Glance: transparent idle fill/border and a query-text hover wash. Raster images retain their own colors.
- Shared scrollbars expose `ScrollbarThumbColor`, `ScrollbarThumbHoverColor`, `ScrollbarThumbActiveColor`, `ScrollbarWidth`, `ScrollbarHoverWidth`, and `ScrollbarBorderRadius`. Widths default to 3/7 logical units; omitted radius follows half the animated thickness. Zero width/radius and transparent colors are explicit. Horizontal bars use width as thickness. Native/web-owned scrollbars remain outside this contract.
- Filters use `RefinementButton{Font,Icon,Background,Border,HoverBackground}Color` and their `RefinementButtonActive...Color` counterparts. Active means expanded or a non-default filter is applied. The expanded strip uses `Refinement{Background,Border,Title,Divider,Hotkey}Color`; options use `RefinementItem{Font,Background,HoverBackground}Color` and `RefinementItemActive...Color`. These are JSON overrides; preserve explicit alpha for every state, including selected-hovered options. Control dimensions remain launcher-density geometry.
- `AppBorderColor`, `AppBorderWidth`, and `AppBorderRadius` control launcher outer chrome. Width/radius use logical units; zero disables the outline or makes corners square. Omitted fields keep the previous platform behavior. Set width explicitly when designing an outline. If any one of these three fields is authored, every platform disables system window material (Windows Acrylic, macOS Liquid Glass/vibrancy, Linux compositor blur) so Go UI can paint the outline. Windows still applies a DPI-scaled region plus DirectComposition clip only when a radius is authored; color or width alone leaves DWM's default corners. macOS detaches the glass/vibrancy wrapper and clips the renderer. Linux turns compositor blur off and can then paint rounded corners. Theme-color alpha still controls ordinary window transparency. Verify shadow and transparency on each target OS before promising identical results.

## Explain the custom-chrome tradeoff

When creating, editing, or recommending a theme that authors any of `AppBorderColor`, `AppBorderWidth`, or `AppBorderRadius`, explicitly tell the user that this disables system window material on every platform (Acrylic, Liquid Glass, Linux compositor blur). The native window switches to transparent composition; theme-color alpha controls ordinary window transparency. This does not disable Wox's own in-app frosted-glass surfaces. Include this limitation in the delivery message, not only in JSON or internal notes.

Toolbar and Action Panel retain their application-rendered frosted-glass transparency independently of the native window material. When designing custom-chrome themes, consider modest transparency in `ToolbarBackgroundColor` and `ActionContainerBackgroundColor` (for example, alpha around 0.88–0.90), while keeping text readable. Do not make these surfaces opaque merely because custom window chrome is enabled. An opaque `AppBackgroundColor` can remain intentional: these panels reveal or blur underlying app content, not the desktop through that opaque background.

An explicit zero (`AppBorderWidth: 0` or `AppBorderRadius: 0`) also selects this path. To restore system material, omit all three fields or set them to `null` at every applicable root/platform/variant level. Assigning a default-looking number does not restore the material. Background colors still need alpha below 1 to reveal anything underneath.

Suggested user-facing wording: “主题只要设置了 AppBorderColor、AppBorderWidth 或 AppBorderRadius 中的任意一项，所有平台都不会再使用系统窗口材质（Windows Acrylic、macOS Liquid Glass、Linux 合成器模糊）。窗口改用普通透明合成，透明程度由主题颜色的 Alpha 决定。Toolbar 和 Action Panel 的应用内磨玻璃效果仍保留，可以适度保留透明度。若要恢复系统材质，需要移除这三项配置。”

## Platform overrides and compatibility

Resolution order is root authored values, then `windows`/`macos`/`linux`, then that platform's matching `variants` entry, then defaults. Read `theme_platform.go` for supported variant names. Omitted or null platform fields inherit the parent; base colors may be overridden so dependent defaults derive from the effective palette. All platform variants are validated, including inactive ones.

Preserve authored values and platform nodes when editing or saving. Never flatten a resolved platform theme into the source document. When explicitly converting v1, retain its effective appearance with explicit v2 overrides where defaults differ; verify zero values, aliases, and legacy contextual color behavior rather than only changing `SchemaVersion`.

## Deliver and check

For local debugging, use the user's requested path; the normal user theme directory is `~/.wox/wox-user/themes/`. Use `<ThemeId>.json` for a new file. Do not overwrite an unrelated theme or publish to the store as part of local authoring.

Validate JSON and use Wox's actual parser/resolver to check fields, colors, platform nodes, and version compatibility. Existing checks live in `wox.core/common/theme_v2_test.go` and `theme_document_test.go`; for changes to parsing run `go test -tags 'sqlite_fts5,wox_automation' ./common` from `wox.core`. That suite validates the implementation, not an arbitrary new file: load the authored file through Wox or a focused parser check as well.

When a running preview is available, inspect selected/hovered results, the Action Panel, keycaps, toolbar, preview/tags, and Glance. For transparency, compare against light and dark desktop content. Report which platforms were actually observed; do not claim native material behavior from a static JSON check.