Dive Into

Themestudio

A quick primer on how Codex maps a theme JSON payload to interface tokens so you can shape your own theme from that contract.

Introduction

I was genuinely excited when Codex themes launched, but I kept running into the same friction: the default selection felt limited, and comparing options took too much back-and-forth. I wanted to move faster without losing confidence in what I was shipping.

The bigger issue was context. A theme could look fine in a small preview, then feel wrong in a real coding environment once spacing, contrast, and especially fonts came into play. That gap between preview and real usage was the main reason this project exists.

Theme Studio is a dev-for-dev web app built to close that gap. It maps theme tokens into a Codex-compatible JSON payload, so you can generate, tweak, and export themes quickly while keeping the output predictable and reusable.

It also includes extra generated presets for anyone who wants a strong starting point with minimal setup. As Codex introduces more theming controls, this project will continue to adopt those capabilities and expose them here.

On a personal note, rebuilding a Codex-like experience in the browser was genuinely fun and surprisingly challenging. It made me respect even more how much structure sits behind an app like Codex. If this tool saves you even a few clicks, it already did its job. Happy theming!

Installation

Choose the path that matches your goal. Most users should use the web builder directly.

Under the hood, both paths converge on the same contract: source colors are mapped into a stable Codex theme payload, semantic fields are normalized, and the final JSON is shaped for predictable import behavior.

Quick Start

Start with the fastest flow first. If you prefer a local terminal pipeline, expand the advanced section below.

Download
Apply
Explore
Create
Configure

Recommended Flow

01

Open Theme Studio and start from any preset.

02

Set your core tokens (accent,surface,ink) then fine-tune contrast and semanticColors.

03

Export, download, and apply the JSON in Codex. Then validate in a real coding session.

All flows converge to the same codex-theme-v1 contract. For field-by-field key details, continue to the next section: Codex JSON Format.

Advanced Flow

Best when you want reproducible generation from raw terminal palettes.

Prerequisites
  • Node.js - 20.x or newer (but we recommend the active LTS release).
  • Package manager - pnpm (recommended), npm, yarn, or bun.
  • iTerm Preset - at least one .itermcolors file placed in input/ (see iTerm2 Color Schemes).
Terminal
git clone https://github.com/lafllamme/codex-themes
02

Add an iTerm preset file to input/, either from the official iTerm2 collection or your own custom preset.

Place your preferred iTerm2 color preset (or your own custom preset) in the local codex-themes input folder as input/yourTheme.itermcolors, as shown in the Adventure example below.

input/Adventure.itermcolors
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Ansi 0 Color</key>
  <dict>
    <key>Alpha Component</key>
    <real>1</real>
    <key>Blue Component</key>
    <real>0.015686275437474251</real>
    <key>Color Space</key>
    <string>sRGB</string>
    <key>Green Component</key>
    <real>0.015686275437474251</real>
    <key>Red Component</key>
    <real>0.015686275437474251</real>
  </dict>
  <key>Ansi 1 Color</key>
  <dict>
    <key>Alpha Component</key>
    <real>1</real>
    <key>Blue Component</key>
    <real>0.2010747492313385</real>
    <key>Color Space</key>
    <string>sRGB</string>
    <key>Green Component</key>
    <real>0.29108250141143799</real>
    <key>Red Component</key>
    <real>0.84613037109375</real>
  </dict>
  <key>Background Color</key>
  <dict>
    <key>Alpha Component</key>
    <real>1</real>
    <key>Blue Component</key>
    <real>0.015686275437474251</real>
    <key>Color Space</key>
    <string>sRGB</string>
    <key>Green Component</key>
    <real>0.015686275437474251</real>
    <key>Red Component</key>
    <real>0.015686275437474251</real>
  </dict>
  <key>Foreground Color</key>
  <dict>
    <key>Alpha Component</key>
    <real>1</real>
    <key>Blue Component</key>
    <real>1</real>
    <key>Color Space</key>
    <string>sRGB</string>
    <key>Green Component</key>
    <real>1</real>
    <key>Red Component</key>
    <real>0.99607843160629272</real>
  </dict>
</dict>
</plist>

Install dependencies (once) with your preferred package manager:

pnpm install
03

Run the converter command shown below to generate Codex-compatible JSON themes in output/.

Terminal
cd codex-themes
pnpm convert

Converter output is written to output/ as Codex-compatible theme JSON files ready for import.

Next step: after generating or exporting your theme, validate semantic balance in the real workbench, then refine in small passes.

Codex JSON Format

Payload exchange uses the codex-theme-v1 prefix as parser signature. The contract is stable and designed for predictable import/export.

Schema Overview

Schema

Top-Level
Fields

codeThemeId (theme identity), variant (dark/light), and theme (all visual tokens).

Tokens

Theme
Fields

accent, surface, ink, contrast, opaqueWindows, fonts, and semanticColors.

Token Definitions

Field Name
Visual Effect
codeThemeId
Selects the syntax theme preset used for code highlighting output.
variant
Controls whether the rendered theme should be used as dark or light mode.
theme
Main theme object that groups the runtime visual tokens below.
accent
Primary highlight color for emphasized UI states: mentions, skill files, @-references, and other interactive callouts in Codex surfaces.
surface
Base background plane for the UI; sets the dominant panel/shell atmosphere.
ink
Primary foreground/readability color used for text and high-contrast foreground content.
contrast
Global separation between content and background.
opaqueWindows
Toggles translucent glass-like system surfaces vs. fully opaque solid backgrounds for UI window elements.
ui
UI font family string for interface text. Works with system/web-safe fonts and custom installed fonts available on the target system.
code
Code/editor font family string for monospaced code surfaces. Availability depends on fonts installed on the target system.
diffAdded
Semantic color for added lines/positive diffs in compare and review views.
diffRemoved
Semantic color for removed lines/negative diffs in compare and review views.
skill
Semantic accent for skill-related labels and contextual skill cues.

Payload Example

theme-payload.json
codex-theme-v1:{
  "codeThemeId": "rose-pine",
  "variant": "dark",
  "theme": {
    "accent": "#ea9a97",
    "surface": "#232136",
    "ink": "#e0def4",
    "contrast": 60,
    "opaqueWindows": false,
    "fonts": { "ui": null, "code": null },
    "semanticColors": {
      "diffAdded": "#9ccfd8",
      "diffRemoved": "#908caa",
      "skill": "#c4a7e7"
    }
  }
}

Theme Generation

The generator is deterministic and script-driven: identical source input produces identical output JSON. The flow below mirrors the real codex-themes pipeline and not a simplified mock.

Algorithm Engine // Architecture
Step 01convert-iterm-themes.ts

Source Ingest

Read .itermcolors files from input/themes-raw and convert plist payloads into structured JSON.

Lowest

#0E0E0E

Base

#131313

High

#2A2A2A

Step 02convert-iterm-themes.ts

Token Mapping

Map source channels to Codex tokens: surface, ink, accent, plus semantic colors for diff and skill states.

Step 03assign-fonts.ts

WCAG Validation

PASS AAA
21:1Ratio
Step 04resolve-code-theme-id.ts

Theme Resolver

Signalcontrast thresholds
Signalsemantic color distance
Outputrecommended codeThemeId
Step 05normalize-code-theme-ids.ts

Normalization Pass

{
  "target": "rescore",
  "status": "normalized",
  "field": "codeThemeId"
}
verify-resolver.ts
Step 06

Smoke Validation

Run resolver smoke tests on representative dark/light payloads to verify non-empty stable recommendations.

Explore Themes

The important behavior is intentional convergence: visually different source palettes can still map to similar runtime themes after readability normalization and resolver scoring.

This keeps generated themes predictable for production usage while still preserving each preset's identity.

Preset Sources

The current catalog combines official Codex presets with a large imported iTerm set. We use iTerm as a source because its palette ecosystem is widely known across developer workflows, including familiar classics like Monokai, Ayu, and many other proven themes. Every entry is normalized into the same codex-theme-v1 payload contract so browsing, previewing, and exporting stay consistent.

Theme Catalog

0

Total Themes

0

Codex Native

0

iTerm Sources

This split is deliberate: Theme Studio stays the fastest creation path, while the codex-themes repository pipeline provides reproducible local generation for automation and versioned workflows.

Reference

Known Limitations

Some syntax and semantic behavior remains constrained by upstream Codex mappings, so not every color token can be fully overridden in every editor context.

View GitHub Discussion

Disclaimer

Theme Studio is an independent, editorial project: a personal exploration of how theme payloads map to UI tokens in the browser. It exists for learning and demonstration, not as an official product, template, or substitute for anything shipped by OpenAI or any other company.

Nothing here is meant to incorporate, clone, or imitate OpenAI products, services, or branding beyond what is necessary to describe compatibility with the Codex theme JSON format. The only third-party visual asset used in this project is the Codex logo, included solely to anchor the workbench preview in a familiar context; if that use is a problem, it can be removed or replaced.

If you have concerns, questions, or notice something that should be corrected, please reach out or message us. Feedback is welcome.