Create, redesign, validate, preview, package, and prepare cohesive themes for the official Codex desktop app from a visual brief or reference image. Use when a user asks for a new Codex theme, wants to preserve or adapt the native Codex layout, wants artwork on the home or conversation page, reports

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: 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. Changing a surface's background does not restyle its text. The native app (especially in dark mode) sets explicit light text colors on many descendants, and an inherited color on main , aside , or header never overrides an explicit descendant color. Whenever a background flips luminance (a light theme over the native dark mode, or the reverse), override the text tokens on the same descendants that carry them — message bodies, markdown content, list items, buttons, labels — not just the container. This is the single most common way a theme ships unreadable. Install the stylesheet before asynchronously decoding large artwork so cold launch does not flash the native page and then jump to a different layout. Increment the manifest version after every visible change. Gate 5: validate before application Run: Fix every error. Treat warnings as unresolved until checked against the design contract. Static validation does not replace visual verification. Generate a self contained preview at both 1440x900 and a narrow viewport. Save previews in ~/.codexthemes/themes/<theme id /previews/ (the scaffold already creates this directory); never write them to the workspace or a staging directory. Label each one as a design preview, never as a verified Codex screenshot. Every preview must show the full themed workspace — sidebar, header, and home content in one frame — never the background artwork alone. Keep the primary desktop preview as a raster file (PNG, JPEG, or WebP; for example previews/home 1440x900.png ): it becomes the theme's gallery and detail image on codexthemes.ai. After Gate 6 verification, replace it with a real screenshot of the applied theme. Gate 6: apply and verify the real app Ask for explicit permission before applying a theme or restarting Codex. Use this skill's own reversible TypeScript runtime; do not search for or prefer an external theme program. If Codex is already exposing a local debugging endpoint, apply without restarting: If no endpoint exists, ask specifically for permission to restart Codex, then use the standalone launcher: When no endpoint is live, launch prints {"status": "scheduled"} and hands the quit → relaunch → inject sequence to a detached helper that survives the restart. This is required because an agent hosted inside Codex dies together with Codex; expect the current tool call (and possibly the session) to be interrupted by the restart. Never work around the restart yourself: do not write shell wrappers, launchd or scheduled tasks, copies of the script, or any other relaunch mechanism — the launch helper already survives the restart. The launcher supports macOS and Windows (on Windows it locates the Codex/ChatGPT executable, closes it gracefully with taskkill — never /F — and relaunches it with the debugging flags; pass app with the full .exe path if detection fails). If the endpoint never appears after a Windows relaunch, that installed build (for example a Microsoft Store package) drops the debugging flags — report that limitation plainly and finish source, preview, validation, and packaging instead; never modify files under WindowsApps . "scheduled" is not success. After Codex is back, verify before reporting anything: status probes every live Codex page and reports "active" with the injected theme id only when the style element is really in the DOM. If it reports "inactive" , read ~/.codexthemes/state/launch.log for the helper's result and error. If an old theme keeps re appearing after a successful apply (a stale session from an earlier task is still re injecting it), get the user's restart permission and force a clean relaunch with apply ... launch relaunch — never ask the user to quit the app by hand and never invent your own restart mechanism. For later one command switching between finished themes, hand off to the codex theme switcher skill; this skill's apply runtime is for creation time QA. The launcher binds debugging to 127.0.0.1 , injects only an owned <style element and CodexThemes page markers, does not modify the signed application bundle, and keeps the theme active across SPA route changes and renderer reloads for the current app session. A full application quit requir

codex-theme-creator