/design-site

description: Design a WordPress site, starting with a clear design direction and style tokens, then intial page layouts, followed by a full custom theme build with content pages deployed to a local Studio site
argument-hint: "<site description>"
disable-model-invocation: true

Design Site — Orchestrator

You are a workflow orchestrator. Delegate heavy creative work to Task() subagents that read reference files at execution time. You do NOT hold design system knowledge — the references do.

Reference Paths

• `${CLAUDE_PLUGIN_ROOT}/references/design-system-core.md` — shared design principles, aesthetics, rules
• `${CLAUDE_PLUGIN_ROOT}/references/design-system-phase2.md` — style tiles, embellishments, token extraction
• `${CLAUDE_PLUGIN_ROOT}/references/design-system-phase3.md` — page layout composition, grid math, visual richness
• `${CLAUDE_PLUGIN_ROOT}/references/wordpress-block-theming.md` — WordPress theme architecture, block markup
• `${CLAUDE_PLUGIN_ROOT}/references/gallery.md` — gallery mu-plugin setup, gallery.json schema

**Already in your context** (auto-loaded, do NOT read or load these — they're already here): `site-specification`

Path Conventions

All design outputs: `<site-path>/design/`. Theme files: `<site-path>/wp-content/themes/<slug>/`. `<site-path>` is set in Phase 0.5. Use absolute paths in all tool calls.

Key subdirectories: `design/{import,inspiration/screenshots,styles,pages,approved}` plus `design-tokens.json`, `design-package.json`, `site-spec.json`, `gallery.json` at the design root. Gallery is served at `http://<site-url>/?design-gallery`.

Trigger

User runs `/design-site` with a site description, or asks to design/build/make a WordPress site.

Workflow

0.5 Studio Setup → 0 New/Redesign? → 1 Brief + Directions → 2 Style Tiles (Task) → 3 Page Design (Task) → 4 Full Mockup (Task) → 5 WP Build (Task)

---

Phase 0.5: Studio Environment Setup

Before any design work begins, confirm that WordPress Studio is installed, the CLI is active, and establish the site path that all subsequent phases will use.

1. Run `studio site list` (Bash) to get all existing site paths. 2. **If the command fails** (non-zero exit code, "command not found", or connection error): Studio is either not installed or its CLI is not enabled. Tell the user:

"It looks like either WordPress Studio is not installed, or the CLI is not turned on.

• **To install WordPress Studio:** <https://developer.wordpress.com/studio/>
• **To enable the CLI:** <https://developer.wordpress.com/docs/developer-tools/studio/cli/>

Once Studio is installed and the CLI is enabled, run `/design-site` again."

**Stop here** — do not proceed with the rest of the workflow.

3. **If the command succeeds**, derive the Studio home folder:

• If sites exist, extract the common parent directory from their paths (e.g., if sites are at `~/Studio/my-site` and `~/Studio/another`, the Studio home is `~/Studio`)
• If no sites exist yet, default to `~/Studio`

4. **Resolve the Studio home to an absolute path** (expand `~`) and store it as `STUDIO_HOME` 5. **Check the current working directory** against `STUDIO_HOME`:

• If the current working directory **is** `STUDIO_HOME` (or a subdirectory of it): proceed — the agent is in the right place
• Note that in MacOS dir names are case-insensitive, so treat `~/studio` and `~/Studio` as the same path
• If the current working directory is **not** within `STUDIO_HOME`: tell the user:

"It looks like you're running Claude from `<current-dir>`, but your Studio sites live in `<STUDIO_HOME>`.

You have two options: 1. **Re-run Claude from the Studio folder** — `cd <STUDIO_HOME>` and start a new session 2. **Tell me the path** — if your Studio sites are in a different location, let me know and I'll use that

Which would you prefer?"

Wait for the user's response. If they provide a path, validate it exists and update `STUDIO_HOME` accordingly. If they choose to re-run, stop here.

6. Ask the user: use an existing Studio site or create a new one? 7. If **new**: derive a theme slug from the site name (kebab-case, validate: `^[a-z0-9-]+$`), then:

   studio site create --path <STUDIO_HOME>/<theme-slug> --name "<site-name>" --skip-browser

8. If **existing**: use the selected site's path; run `studio site start --path <site-path>` if the site is not already running

Store `<site-path>` for all subsequent phases. Use `STUDIO_HOME` and `<site-path>` in all paths from this point forward.

9. **Install gallery mu-plugin:**

   mkdir -p <site-path>/wp-content/mu-plugins
   cp ${CLAUDE_PLUGIN_ROOT}/templates/design-gallery.php <site-path>/wp-content/mu-plugins/

10. **Get site URL:** `studio site status --path <site-path>` — store the URL as `<site-url>` for gallery access.

---

Phase 0: New or Redesign?

**Goal:** Determine if this is a new site or a redesign of an existing one.

**Skill:** `content-import`

Auto-Detection

Check `$ARGUMENTS` for redesign signals:

• **Keywords**: redesign, redo, refresh, rebuild, revamp, remake, overhaul, update the look, new design for
• **URLs**: any `http://` or `https://` URL that looks like an existing site (not a reference/inspiration URL)

If redesign is detected, proceed with content import. If not, skip directly to Phase 1.

Redesign Workflow

1. **Confirm intent**: "It sounds like you want to redesign an existing site. I'll analyze [URL/description] and use your existing content as the foundation. The old design goes away — your content gets a fresh look."

2. **Gather content**: Use the `content-import` skill:

• If the user provides a URL, scrape it via WebFetch
• If the user provides a WordPress XML export, parse it
• If neither, ask: "Can you share the site URL or a WordPress XML export? I'll pull your existing content from there."

3. **Write content summary**: Save to `<site-path>/design/import/content-summary.json`