Customize Your Codex Dream Skin Theme

Prepare the image

• Use PNG, JPEG, HEIC, TIFF, or WebP on macOS.
• Keep the source at or below 50 MB; the prepared asset must remain at or below 16 MB.
• A width of at least 2000px is recommended rather than enforced as a source minimum.
• Favor a calm left side and enough tonal contrast for native headings.

Why one image needs a compromise

The same source image appears as the ultrawide home banner and as the task-page background. A crop that looks perfect on one surface can hide the face, text, or important details on the other, so compose for the shared safe zone instead of a single screenshot.

CodexSkin tested composition guidance

These values come from CodexSkin hands-on testing, not from OpenAI or the upstream project.

• Start with a 20:9 ultrawide canvas.
• Place the face center at 70% to 82% of the canvas width and 35% to 50% of its height.
• Keep the subject height at no more than 45% and preserve generous headroom.
• Reserve the left 55% as dark, low-detail negative space for readable home and task text.
• Keep important details away from the bottom composer region, which can cover the image.
• Avoid dense background detail, and generate no text, logo, border, or UI elements.

Copy a source-image prompt

Use this tool-neutral prompt with an image generator that can create a wide source image, then validate the crop before applying it.

Validate before you keep the image

• Generate a 20:9 source image with the prompt above.
• Preview both an ultrawide banner crop and a conventional task-background crop.
• Apply the image using the upstream-documented macOS workflow below.
• Inspect the home page and a real task page, including headings and the bottom composer.
• Move the subject or simplify the background, regenerate, and repeat if either surface loses readability.

Use the Finder picker

~/.codex/codex-dream-skin-studio/scripts/customize-theme-macos.sh

Omit flags to choose an image in Finder. The studio prepares the local asset and updates the theme configuration.

Use the macOS CLI

~/.codex/codex-dream-skin-studio/scripts/customize-theme-macos.sh \
  --image "/path/to/image.png" \
  --name "My theme" \
  --accent "#7cff46" \
  --secondary "#36d7e8" \
  --highlight "#642a8c"

Reapply and check readability

Start or reapply Dream Skin after changing the image. Check the home and task routes, including the project picker and composer. If text contrast is weak, choose a quieter crop or adjust the accent colors.

Editorial review context

Design for two surfaces, not one screenshot

The home view behaves like a wide banner with prominent titles and cards, while a task view contains a taller reading column, code, status messages, and a composer near the bottom. The same image can be cropped and covered differently. Begin with the harder requirement: uninterrupted reading. Reserve a broad, low-detail region behind likely text, then position the subject where the home crop still recognizes it. A decorative image succeeds only when the interface remains effortless to scan for an extended session.

The 70% to 82% horizontal face range and 35% to 50% vertical range are working zones, not a demand that every image contain a person. For landscapes, products, architecture, or abstract art, place the primary focal mass in the same right-side zone and keep the left 55% quiet. The 45% subject-height ceiling preserves headroom and reduces accidental cropping. Treat the bottom composer region as unavailable: texture can continue through it, but faces, hands, symbols, horizon lines, and other meaningful details should not depend on being visible there.

Test contrast with real interface states

A dark image is not necessarily readable. High-frequency stars, hair, foliage, city lights, or generated micro-text can create local contrast that competes with letters even when average luminance is low. Preview headings, normal paragraphs, muted metadata, code, selection, links, error messages, disabled controls, and focus rings. The quiet zone should remain quiet at full desktop size and after responsive cropping. If the interface needs a heavy opaque panel everywhere, simplify the source image before increasing overlays.

• Inspect the image at window sizes you actually use rather than only at export resolution.
• Check the lightest and darkest areas behind small muted text, not only the main heading.
• Use a temporary grayscale preview to reveal tonal conflicts that saturated color can disguise.
• Scroll a long task so different content occupies the same background regions.
• Check focus and selection outlines; a background should not make keyboard navigation ambiguous.
• Prefer reducing texture, brightness variation, or subject scale before hiding more of the image.

Run a repeatable crop review

Keep the master file outside the theme state directory. Export a working copy, apply it through the documented platform flow, and record what changes between home and task views. Look for three failures: the focal subject is cut or hidden; interface text overlaps detailed or bright regions; and the composer covers a meaningful element. Change one variable at a time—subject position, scale, background detail, or tonal range—so the next export shows whether the adjustment helped.

• Preview a 20:9 home crop and 16:9 task approximation before importing.
• Inspect full-width, medium, and narrow desktop windows after import.
• Compare an empty home screen with a populated task; neither alone represents normal use.
• Keep export names versioned so a failed crop can be compared or rolled back without overwriting the master.
• After final crop approval, repeat platform verification and restore checks.

Keep a usable image-rights record

For your own photograph or illustration, retain the original file and creation date. For commissioned work, keep the agreement explaining adaptation and display rights. For stock or generated material, save the provider, asset page or generation record, license version, purchase receipt when applicable, and restrictions on commercial use, redistribution, recognizable people, trademarks, or sensitive locations. A prompt alone does not establish an unambiguous rights chain, and removing a logo does not cure an unauthorized source.

Personal desktop use and publishing a downloadable theme are different uses. Before sharing a theme, confirm that redistribution of the background itself is allowed and required attribution can accompany it. Avoid presenting OpenAI or Codex marks as your own branding and do not imply official approval. CodexSkin original theme pages identify asset origin and usage terms; use the same discipline for material you distribute elsewhere.

When the image looks wrong after import

• If the subject is clipped, reduce its scale or move the focal mass farther inside the right-side safe zone.
• If text looks noisy, remove detail or compress tonal range in the reading zone instead of only increasing text brightness.
• If the composer hides a key element, move that element upward; bottom padding in the source is usually more reliable than changing interface layout.
• If colors feel inconsistent, test the background independently from accent colors and change one variable at a time.
• If import fails, verify documented format and size limits with a copy, then check the platform guide for diagnostics.
• If only one Codex view changes, preserve verification evidence and treat it as a runtime or compatibility issue.