Codex Theme Creator

Create a Codex theme

Create a reversible decorative theme without modifying app.asar, the signed app bundle, WindowsApps, user tasks, or authentication data. Preserve native layout and interaction behavior unless the chosen layout mode explicitly permits a bounded composition change.

Authority boundary

Use this skill as the sole design and QA authority for a new Codex theme. Do not read, copy, or combine another installed theme skill, finished theme manifest, finished theme CSS, or local theme collection unless the user explicitly names that source. Do not describe the workflow as combining this skill with “local theme conventions.” Start from this skill's matching skeleton and the user's brief or reference image.

This skill is standalone. Its TypeScript scripts own scaffolding, validation, reversible session application, and restore. Never detect, invoke, read configuration from, or claim a dependency on CodeDrobe, Dream/Fiona, or another theme injector unless the user explicitly asks to use that product. Do not reuse their marker names or runtime data. The only required local tools are Node.js, npx, and the official Codex desktop app.

Managed storage

Keep every generated theme file in the managed library ~/.codexthemes unless the user explicitly requests another location:

• editable source and artwork: ~/.codexthemes/themes/<theme-id>/
• previews: ~/.codexthemes/themes/<theme-id>/previews/
• shareable packages: ~/.codexthemes/exports/
• runtime state: ~/.codexthemes/state/

Never create a staging, scratch, or temporary copy of theme files in or near the current workspace (for example a .codexthemes-stage directory). If the sandbox or permission mode blocks writing to ~/.codexthemes, ask the user to approve writing there instead of writing somewhere else first and moving files later.

Read the required references

Before creating or substantially redesigning a theme, read these files completely:

• references/design-playbook.md: layout modes, semantic palette, selectors, and surface coverage.
• references/qa-checklist.md: real-app acceptance matrix and hard failures.
• references/theme-schema.md: manifest and portable package contract.
• references/asset-rights.md: user-material handling and submission handoff.

Do not begin artwork or CSS until the design contract below is written.

Gate 1: write the design contract

Record:

• layoutMode
• backgroundScope
• decorDensity
• light or dark mode and the reason
• artwork focal point and text-safe region
• semantic palette
• surfaces allowed to change
• native geometry and states that must remain unchanged
• target desktop and narrow viewports

Choose the layout mode in this order:

1. Use native-immersive as the default when the user supplies a reference image or names a visual world (a game, film, anime, brand, season, or other strong art direction): keep the native layout and deliver coordinated sidebar, card, menu, composer, settings, diff, and terminal materials plus the decoration menu in references/design-playbook.md.
2. Use native-background only when the user explicitly restricts the theme to a background change.
3. Use editorial-showcase only when the reference clearly requires a bounded portrait, product, or campaign hero with a different home composition.
4. Use palette-only when no dominant artwork is required.

Record decorDensity as minimal, balanced, or rich. Default to rich when the reference has a strong art direction and balanced otherwise; use minimal only when the user explicitly asks for a background-only or quiet theme. The design playbook defines the element coverage each density requires. A theme that ships one background image and a veil does not satisfy balanced or rich.

backgroundScope decides where the dominant background artwork appears. It is not a runtime toggle — it is baked into the CSS selectors, so changing it later means rebuilding the theme. Because most users do not know this option exists, surface it explicitly instead of deciding silently:

• When the user has not stated a preference, ask once in plain language before building, for example: "Should the background artwork appear on the home page only (recommended -- keeps conversation text and code clearest), or on conversation pages too?" Recommend home as the readability-safe default.
• Only pick workspace when the user chooses it or clearly asks for artwork on task/conversation pages.

State the chosen scope in the design contract you report back, so the user knows what they are getting. Never infer a conversation page merely because the page is not home; settings and system pages must not inherit task artwork. With workspace, put a stronger veil behind conversation text so long-form content and code stay readable.

Do not default to dark mode. Match an explicit request or the reference luminance. Ambiguous editorial, floral, portrait, stationery, lifestyle, productivity, and pastel concepts default to light.

Gate 2: capture the native contract

Inspect the unmodified live app at the same viewport and record evidence for:

• home heading, native suggestion cards, project selector, and composer
• populated conversation and activity rows
• settings and profile pages
• personal menu, dropdown, dialog, and tooltip
• attachments, file cards, changed-files/diff, and output panels
• terminal before and after xterm mounts
• sidebar idle, hover, selected, project hover, long titles, and row actions
• header actions at narrow and wide widths

Treat geometry, visibility, hit targets, keyboard focus, and hover-only actions as invariants unless the design contract explicitly permits a change.

Gate 3: scaffold the correct skeleton

Run from the installed skill directory:

npx tsx scripts/scaffold-theme.ts \
  --id <safe-slug> \
  --name "<display name>" \
  --layout-mode <native-background|native-immersive|editorial-showcase|palette-only> \
  --background-scope <home|workspace> \
  [--art /absolute/artwork.png]

The default source location is ~/.codexthemes/themes/<safe-slug>/. Always use that managed library unless the user explicitly requests another location; only then pass --output /absolute/theme-parent. Never use the current workspace merely because it is writable.

Never start by copying a finished theme that uses another layout mode.

Gate 4: implement in controlled layers

Build CSS in this order:

1. semantic tokens
2. shell surfaces
3. exact route-scoped backgrounds
4. native component roots
5. interaction states
6. non-interactive decoration
7. responsive and reduced-motion rules

Restraint applies to geometry and interaction, not to coverage: implement every surface material and decoration element the contracted decorDensity requires (see the playbook's decoration menu). A theme that only swaps the background and leaves native cards, composer, sidebar, header, typography, and scrollbars untouched is unfinished at balanced or rich density. Use stable roles, test IDs, verified component classes, and narrowly anchored :has(...). Avoid localized text selectors when a structural hook exists.

Never apply broad opacity, display, visibility, position, overflow, or color overrides to aside *, main *, generic svg, or broad descendant groups. Never use descendant opacity: 1 to repair contrast; it exposes hidden row actions.

Define one owner for every divider, outline, sidebar edge, card boundary, and header boundary. Use a solid readable header surface; keep gradients and artwork behind content rather than behind low-contrast toolbar controls. Keep all decoration below native controls with pointer-events: none.

For light themes, keep settings, menus, dialogs, output/diff panels, code surfaces, and terminal hosts in the same light semantic system unless the contract deliberately defines a contrast panel. Theme terminal host, xterm viewport, and xterm screen together.