> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shoppex.io/llms.txt
> Use this file to discover all available pages before exploring further.

# AI theme editing — concept

> What you can do with Claude Code or Codex on a Shoppex theme, and how the workflow is shaped.

Shoppex themes are designed to be edited through an AI assistant — Claude Code, Codex, Cursor,
or any other MCP-capable client. Custom code themes (forked or imported Liquid packages) are
edited over the same set of operations: **inspect → apply → preview → publish**. Visually-built
hosted themes are edited in **document mode**: the AI works on the theme's builder settings
(`settings.json`) guided by the theme's settings schema, and publishing validates every change
strictly — no copy of the theme is created, and the theme keeps receiving updates.

This page covers the concept and the boundaries: what works well, what to avoid, and how the
workflow is structured. For the concrete step-by-step (install MCP, create API key, first
prompt, first publish), follow the tutorial:

<Card title="Tutorial: Customize your theme with AI" icon="wand-magic-sparkles" iconType="duotone" href="/developers/tutorials/theme-with-ai">
  End-to-end walkthrough from a fresh shop to a live theme change.
</Card>

<Info>
  **Easiest start:** open your dashboard → **Store → Themes**, click the **⋯** menu on any
  theme card, then **Edit with AI**. The dialog generates a scoped API key, picks your client
  (Cursor / Claude Code / Claude Desktop / Codex / Windsurf), and gives you the exact terminal
  commands to wire up the MCP server in seconds — no manual key creation or `mcp install`
  step required.
</Info>

## What AI is good at on a Shoppex theme

* Targeted copy changes — homepage headline, CTAs, button labels.
* Visual tweaks — colors, spacing, button radius, typography.
* Adding a new static page (e.g. `/about`).
* Scaffolding a new section that matches the existing style — testimonials, FAQ, pricing
  table.
* Creating a fresh theme from a base theme and adapting it to a brand.

## What AI is bad at (or risky)

* "Redesign everything" prompts. AI plans by inferring intent; with a broad prompt it will
  invent things you didn't ask for. Keep prompts focused on one section / one attribute.
* Editing many unrelated files in one shot. Easier to debug and roll back when changes are
  scoped.
* Publishing without a preview. The preview step is the safety net — it's free and fast.

## The workflow

Every AI session on a theme follows the same shape:

1. **Inspect first.** Let the AI read the theme structure before it edits. A blind patch
   produces worse results than a targeted one.
2. **Apply one focused change.** "Change the hero headline" beats "make it look modern".
3. **Validate + preview.** Validate confirms the Liquid package is shippable. Preview is a sandboxed
   render at `preview.shoppex.io` — your live shop is untouched until you publish.
4. **Iterate on the preview.** Looks wrong? Tell the AI what to adjust, re-apply, refresh
   the preview.
5. **Publish only after review.** Publish queues a deploy job; your live shop updates in
   under a minute.

Backups are created at theme version upgrades and theme restores — so for
day-to-day publishes, your safety net is the preview step, not rollback after.

## Base themes you can fork from

* Default — clean, neutral starting point. Best for most.
* Classic — traditional storefront layout with a generous hero.
* Nebula — dark-mode-first.
* Pulse — bold, marketing-style.

Start from Default if you're not sure — most customizations work cleanly on top of it.

## Sample prompts that work

```text theme={"system"}
Inspect my theme and tell me which file controls the homepage hero.
Don't change anything yet.
```

```text theme={"system"}
Change only the hero headline and CTA button color.
Keep the rest of the page identical.
```

```text theme={"system"}
Create a new /about page in the same visual style as the current theme.
Then validate and open a preview.
```

```text theme={"system"}
Add a testimonials section to the homepage, three cards on desktop,
stacked on mobile. Match the existing feature-section style.
Don't publish yet.
```

## What to read next

<CardGroup cols={2}>
  <Card title="Tutorial: AI theme walkthrough" icon="wand-magic-sparkles" iconType="duotone" href="/developers/tutorials/theme-with-ai">
    Concrete end-to-end walkthrough with Claude Code.
  </Card>

  <Card title="Quickstart" icon="rocket" href="/themes/quickstart">
    Pull a hosted theme locally before you start customizing it.
  </Card>

  <Card title="AI Theme Workflows" icon="sparkles" href="/themes/ai-workflows">
    More advanced CLI and MCP patterns.
  </Card>

  <Card title="Editing Themes" icon="sliders" href="/themes/editing">
    The unified workflow reference across dashboard, CLI, Dev API, and MCP.
  </Card>
</CardGroup>