Codex Design

Codex Design is a Codex plugin that turns scattered design evidence into repeatable agent workflows. It helps developers and agents extract a design system from a codebase, write a grounded DESIGN.md, generate image prompts from that design contract, capture rendered UI evidence, and build selected visual targets into React and shadcn/ui code.

This is an unofficial community plugin. It is not an OpenAI-owned plugin.

Why This Exists

Most agent-built UI fails for the same reason: the agent starts designing before it understands the product's actual design language. It invents colors, guesses spacing, ignores existing components, and produces something that looks plausible but does not belong in the app.

Codex Design forces a better workflow:

1. Inspect the repository and collect real design evidence.
2. Synthesize a DESIGN.md that names tokens, patterns, assets, gaps, and open questions.
3. Use that DESIGN.md as the design contract for future UI work.
4. Generate visual targets and implementation plans from evidence instead of taste guesses.
5. Validate the result before claiming the work is complete.

For developers, this means fewer generic redesigns and less cleanup after agent work. For agents, this creates a workflow they can actually follow.

What It Gives You

• DESIGN.md generation from source files, assets, screenshots, user notes, and rendered browser captures.
• Evidence-aware design synthesis with confidence levels and conflict tracking.
• Prompt enhancement for UI image generation and redesign work.
• Component-gallery generation from a design contract.
• Image-generation prompt packages for conservative, improved, and bold visual directions.
• Browser HTML capture support for using a real rendered page as design evidence.
• React and shadcn/ui build guidance when a generated design image is selected for implementation.
• Validation scripts for manifests, skills, templates, syntax, tests, and design-token exports.

Install In Codex

Install the marketplace from GitHub:

codex plugin marketplace add Rafler/codex-design
codex plugin marketplace list

Then restart Codex, open the plugin directory, choose the Local Design Plugins marketplace, and install Codex Design.

This repository includes a repo marketplace at:

.agents/plugins/marketplace.json

The marketplace points Codex to the plugin at:

plugins/codex-design

Use It

Ask Codex for one of the plugin workflows:

Use codex-design to generate DESIGN.md for this repo.
Use codex-design to enhance this UI prompt.
Use codex-design to build this generated image with React and shadcn.

You can also invoke specific skills when you already know the job:

• codex-design-director: choose the right Codex Design workflow.
• codex-design-extract-design-md: extract a design system from source code.
• codex-design-agentic-import: add explorer-agent interpretation when raw extraction is not enough.
• codex-design-browser-html-extract: capture a rendered local page as HTML, metadata, and screenshot evidence.
• codex-design-enhance-prompt: turn a vague UI idea into a structured visual prompt.
• codex-design-taste-design: create a stronger opinionated DESIGN.md when the current design is weak or generic.
• codex-design-component-gallery: build a gallery and inventory from DESIGN.md.
• codex-design-visual-target: create image-generation prompt packages from DESIGN.md.
• codex-design-generate-design: run the design-image generation workflow.
• codex-design-react-shadcn-build: implement a selected visual target in React with shadcn/ui.
• codex-design-quality-gate: verify the output before calling the work complete.

Agent Rules

Agents using this plugin should follow these rules:

• Treat DESIGN.md as the design contract.
• Read the relevant skill before acting.
• Prefer repository evidence over generic design advice.
• Label inferred defaults as starter defaults or open questions.
• Do not invent logos, screenshots, brand colors, or product assets.
• Preserve the app's existing component and styling conventions unless the task explicitly asks for a redesign.
• Run validation before handing work back.

These rules are the point of the plugin. If an agent skips evidence gathering and jumps straight to a polished mockup, it is using this plugin wrong.

Developer Workflow

Work from the plugin directory:

cd plugins/codex-design
npm test
npm run validate:core

Run the full validation suite when Image Gen prerequisites are available:

npm run validate

The full suite checks:

• prerequisite tools
• plugin manifest
• skill metadata and structure
• templates
• script syntax
• Node tests
• DESIGN.md linting
• design-token export

Main Scripts

node scripts/extract-design-sources.mjs --repo /path/to/project --out .codex-design
node scripts/synthesize-design-md.mjs --source-map .codex-design/source-map.json --out DESIGN.md
node scripts/design-md.mjs lint --file DESIGN.md
node scripts/build-component-gallery.mjs --file DESIGN.md --out artifacts/codex-design/component-gallery
node scripts/build-visual-target.mjs --file DESIGN.md --out artifacts/codex-design/visual-target

Use OPENAI_API_KEY only when running Image Gen commands that actually call the OpenAI API. The plugin's extraction, linting, gallery, and validation scripts do not need it.

Repository Layout

.agents/plugins/marketplace.json      Repo marketplace consumed by Codex
plugins/codex-design/.codex-plugin/   Plugin manifest
plugins/codex-design/skills/          Agent-facing workflows
plugins/codex-design/scripts/         Validation, extraction, and generation scripts
plugins/codex-design/src/             Shared implementation modules
plugins/codex-design/assets/          Logo, icon, templates, and generated token exports
plugins/codex-design/test/            Node test suite

Generated evidence and output directories are ignored by git:

plugins/codex-design/.codex-design/
plugins/codex-design/artifacts/

When To Use It

Use Codex Design when you need an agent to:

• understand an existing frontend before changing it
• document a design system from code
• create a design contract for future UI work
• generate design images grounded in existing tokens and assets
• move from selected visual target to React implementation
• audit whether design output is supported by evidence

Do not use it for arbitrary image generation, Figma authoring, slide decks, non-React implementation, or quick copy-only changes.

Official Codex Plugin References

• Codex plugins: https://developers.openai.com/codex/plugins
• Build Codex plugins: https://developers.openai.com/codex/plugins/build
• Codex skills: https://developers.openai.com/codex/skills

License

MIT. See LICENSE.