Skip to main content

​
Build and Customize a Theme with AI

Start here if you want to use Claude Code or Codex to build or customize a Shoppex theme. The workflow is: start from an existing theme (or create one), let the AI inspect it first, make one small change at a time, then validate and preview before you publish.
You do not need to understand the Theme Control Plane first. This page is the practical beginner workflow. If you want the underlying platform details later, read Theme Control Plane.

​
What You Can Do With AI

  • Change homepage copy
  • Update colors, spacing, and button styles
  • Add a new static page like /about
  • Scaffold a new section like testimonials or FAQ
  • Create a new theme from a base theme and customize it
Start with focused changes — avoid asking AI to redesign the whole storefront in one step.

​
What You Need

You need:
  • a Shoppex theme
  • a way to run or preview it
  • an API key if the AI should use the Shoppex theme tools
For most people, the easiest starting point is:
  1. start from themes/default
  2. create an API key with themes.read and themes.write
  3. use Claude Code or Codex to inspect and edit in small steps
If you want the concrete dashboard and CLI setup flow, read Hosted Theme Sync.

​
Pick Your Starting Point

Use one of these:

​
Option 1: Customize an Existing Theme

Use this if you already have a theme and want to improve it. Change the homepage hero, add a new about page, tweak colors and typography — anything targeted.

​
Option 2: Create a New Theme from a Base Theme

Use this if you want a fresh starting point. Supported base themes:
  • default
  • classic
  • nebula
  • pulse
Start from default, then ask the AI to adapt the visuals, sections, and pages to your brand.
  1. Pick or create a theme
  2. Ask the AI to inspect it first
  3. Ask for one small change
  4. Validate the result
  5. Preview it
  6. Publish only when it looks right
In practice, your prompts might look like: “Inspect my theme and find the homepage hero” → “Change only the headline, CTA text, and button color” → “Validate the change” → “Open a preview” → “Publish it if the preview looks correct.”

​
Step 1: Let the AI Inspect Before Editing

Always inspect first. The AI needs to learn the theme structure so changes are targeted and safe instead of blind patches. Good prompt: 
Inspect this Shoppex theme first.
Find the homepage files and tell me which file controls the hero section.
Do not change anything yet.

​
Step 2: Ask for a Small Change

After inspection, ask for one focused change. Good examples:
  • “Change only the hero headline and CTA text.”
  • “Keep the layout, but change the primary color and button radius.”
  • “Create a new /about page in the same visual style as the current theme.”
  • “Add a testimonials section, but do not publish anything yet.”
Weak examples:
  • “Redesign everything.”
  • “Rewrite the whole storefront.”
  • “Change whatever you think is wrong.”

​
Step 3: Validate and Preview

After the AI makes a change, always do these next:
  • validate
  • preview
validate checks whether the theme still builds cleanly. preview lets you see the real result before going live. Good prompt: 
Validate the current theme draft.
If validation passes, open a preview.
Do not publish yet.

​
Step 4: Publish Only After Review

Only publish after you review the preview. Preview is for checking. Publish is permanent. If something is wrong:
  • ask the AI for one more focused change
  • validate again
  • preview again

​
The Best Prompts for Beginners

These work well: 
Inspect my theme and explain what parts are safe to edit on the homepage.

Search for the homepage hero, read the relevant files, and change only the CTA copy and button color.

Create a new About page in the same style as the current theme. Then validate it and open a preview.

Add a testimonials section to this theme. Keep the existing design language. Do not publish yet.

Create a new theme from default, then inspect it and suggest the first three safe customizations.

​
What To Avoid

Avoid these habits:
  • asking for a huge rewrite before inspection
  • changing many unrelated files at once
  • publishing without previewing
  • treating AI like it already knows your theme structure
  • Good: “Inspect first, then change the hero.”
  • Risky: “Rebuild the whole store in a luxury style.”

​
Which Page Should You Read Next?

Use this page order:
  1. this page if you are new
  2. Quickstart if you need a local theme running
  3. AI Theme Workflows if you want the more advanced CLI and MCP patterns
  4. Theme Control Plane if you want the technical backend model

​
Next Steps

Quickstart

Run a reference theme locally before you start customizing it.

AI Theme Workflows

Learn the more advanced CLI and MCP workflow after the beginner path.

Theme Control Plane

Read the advanced platform page behind inspect, validate, preview, and publish.

Theme Config

Understand how sections and settings are defined inside a theme.