/wp-variation

description: Generate a WordPress block theme style variation (styles/*.json) — dark mode, color palette swap, or font swap.

/wp-variation

**Purpose:** Generate a WordPress block theme style variation — a `styles/*.json` file that overrides color, typography, and spacing from the base `theme.json` to create an alternative theme aesthetic.

When to Use

Trigger this command when:

• The user wants a dark, light, high-contrast, seasonal, or brand-alternate version of their theme
• The user says "color scheme", "variant", "skin", "dark mode", "alternate palette"
• A design system has multiple brand expressions (e.g., marketing vs. product, seasonal themes)

**Do not** use this command for per-page or per-block style changes — style variations apply globally to the entire site.

Workflow

Step 1: Gather Variation Details

Ask (or infer from context):

| Question | Default if silent | |----------|-------------------| | Variation name (human-readable) | Required — always ask | | Variation slug (kebab-case file name) | Derived from name | | What to change: colors, typography, spacing, or all three? | Colors only (most common) | | Color palette overrides | Required if colors are changing | | Font overrides | Optional — only if changing fonts | | Spacing overrides | Optional — only if changing scale | | Is this a **global variation** (appears in Site Editor) or a **scoped variation** (Section Style on a Group block)? | Global variation |

**Global vs Scoped Variations:**

| | Global Style Variation | Section Style | |-|----------------------|---------------| | Applies to | Entire site | A single block instance | | File location | `styles/{{slug}}.json` | `styles.blocks.core/group.variations.{{slug}}` in theme.json | | Appears in | Site Editor → Styles → Browse styles | Block toolbar → Styles | | WordPress version | 6.0+ | 6.6+ |

If the user wants a variation for a single block (e.g., a "dark section" Group block), refer to `references/modern-blocks.md` — Section Styles section instead.

Step 2: State the Variation Plan

VARIATION PLAN: {{Variation Name}}
File: styles/{{slug}}.json
Changes:
  Colors:     {{list color palette changes}}
  Typography: {{list font changes, or "no changes"}}
  Spacing:    {{list spacing changes, or "no changes"}}
  Elements:   {{list element style changes}}

Step 3: Generate the Variation File

Style variations are **partial `theme.json` files** — they override only the keys they define. The rest inherits from the base `theme.json`.

**Minimum valid structure:**

{
    "$schema": "https://schemas.wp.org/trunk/theme.json",
    "version": 3,
    "title": "{{Variation Name}}",
    "slug": "{{variation-slug}}",
    "settings": {},
    "styles": {}
}

**Color-only variation (most common):**

{
    "$schema": "https://schemas.wp.org/trunk/theme.json",
    "version": 3,
    "title": "{{Variation Name}}",
    "slug": "{{variation-slug}}",
    "settings": {
        "color": {
            "palette": [
                {
                    "slug": "primary",
                    "color": "{{new-primary-color}}",
                    "name": "Primary"
                },
                {
                    "slug": "secondary",
                    "color": "{{new-secondary-color}}",
                    "name": "Secondary"
                },
                {
                    "slug": "foreground",
                    "color": "{{new-foreground-color}}",
                    "name": "Foreground"
                },
                {
                    "slug": "background",
                    "color": "{{new-background-color}}",
                    "name": "Background"
                },
                {
                    "slug": "surface",
                    "color": "{{new-surface-color}}",
                    "name": "Surface"
                }
            ]
        }
    },
    "styles": {
        "color": {
            "background": "var(--wp--preset--color--background)",
            "text": "var(--wp--preset--color--foreground)"
        },
        "elements": {
            "link": {
                "color": {
                    "text": "var(--wp--preset--color--primary)"
                },
                ":hover": {
                    "color": {
                        "text": "var(--wp--preset--color--secondary)"
                    }
                }
            },
            "button": {
                "color": {
                    "background": "var(--wp--preset--color--primary)",
                    "text": "var(--wp--preset--color--background)"
                },
                ":hover": {
                    "color": {
                        "background": "var(--wp--preset--color--secondary)",
                        "text": "var(--wp--preset--color--background)"
                    }
                }
            },
            "h1": { "color": { "text": "var(--wp--preset--color--foreground)" } },
            "h2": { "color": { "text": "var(--wp--preset--color--foreground)" } },
            "h3": { "color": { "text": "var(--wp--preset--color--foreground)" } }
        }
    }
}

**Dark mode variation:**

{
    "$schema": "https://schemas.wp.org/trunk/theme.json",
    "version": 3,
    "title": "Dark",
    "slug": "dark",
    "settings": {
        "color": {
            "palette": [
                { "slug": "background", "color": "#0F172A", "name": "Background" },
                { "slug": "surface",    "color": "#1E293B", "name": "Surface" },
                { "slug": "foreground", "color": "#F1F5F9", "name": "Foreground" },
                { "slug": "muted",      "color": "#94A3B8", "name": "Muted" },
                { "slug": "border",     "color": "#334155", "name": "Border" },
                { "slug": "primary",    "color": "#6366F1", "name": "Primary" },
                { "slug": "secondary",  "color": "#8B5CF6", "name": "Secondary" }
            ]
        }
    },
    "styles": {