Theme Editor

Tune a React product’s visual system while the app is running. Theme Editor adds a development-only inspector for color, typography, surfaces, shape, interaction states, elevation, and motion, then exports the result as reusable CSS or JSON tokens.

The repository contains both the reusable runtime and an invokable Codex skill. Host projects keep their own token names through a small semantic adapter instead of forking the editor UI.

What it includes

• One capability-driven inspector with independently collapsible Theme Directions, Palette & Accent, Typography, Surfaces, Shape & Density, Interaction States, Elevation, Motion, and Export sections
• Curated preset browsing plus generated vivid, muted, deep, soft, and earthy five-role accent families
• Thirty reusable font directions, any number of host-defined typography roles, categorized role-specific catalogs, and arbitrary typed Google Font loading
• Full-theme generation across color, typography, surfaces, density, states, elevation, and motion while preserving the host's light or dark appearance
• Undo/redo, original-theme comparison, reset, local checkpoint, import, and export
• A semantic host adapter for project-specific CSS variables, appearance, typography roles, storage keys, Credits, and bundled fonts
• Development-only rendering with project-specific localStorage persistence

Repository layout

skill/
├── SKILL.md
├── agents/openai.yaml
├── assets/
│   ├── components/theme-editor/
│   ├── hooks/useTheme.ts
│   └── lib/
└── references/
tests/
scripts/link-active-skill.sh
DESIGN.md

skill/assets/ is the canonical runtime source. The same files are copied into host projects during injection.

Install

curl -fsSL https://raw.githubusercontent.com/madebysan/theme-editor/main/install.sh | bash

By default this installs to ~/.agents/skills/theme-editor. Set THEME_EDITOR_SKILLS_DIR to install into another compatible skills directory.

Start a fresh Codex task after installation, then invoke $theme-editor inside a React + Tailwind v4 project.

Local development

git clone https://github.com/madebysan/theme-editor.git
cd theme-editor
npm install
npm run check

Contributors can link a checkout directly into the active skills directory:

./scripts/link-active-skill.sh

How the skill works

1. Audit the host project’s real CSS variables and component usage, then expose only controls with visible consumers.
2. Copy the shared runtime without flattening its folders.
3. Generate theme-config.ts and theme-defaults.ts for the host’s semantic tokens.
4. Render the editor only in development.
5. Verify the live desktop surface, browser console, tests, and production build.

See DESIGN.md for the product principles and runtime boundaries.

License

MIT

Made by santiagoalonso.com