Style Variations

Style Variations

A style variation is a whole-theme override the user can switch to from Site Editor → Styles. Obel ships three:

• dark.json — inverts base/contrast for dark mode
• editorial.json — serif body, narrower content, magazine-style layout
• high-contrast.json — WCAG-leaning palette, always-underlined links, thicker button borders

How variations work

A variation is just a JSON file in styles/ that uses the same schema as theme.json, but only overrides the keys you want to change. WordPress merges the variation on top of theme.json at runtime.

Anatomy of a variation:

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 3,
  "title": "Dark",
  "settings": {
    "color": {
      "palette": [
        { "slug": "base", "name": "Base", "color": "#1A1A1A" },
        { "slug": "contrast", "name": "Contrast", "color": "#FAFAF7" },
        { "slug": "accent", "name": "Accent", "color": "#E89E5B" }
      ]
    }
  },
  "styles": {
    "color": {
      "background": "var(--wp--preset--color--base)",
      "text": "var(--wp--preset--color--contrast)"
    }
  }
}

The title field is what appears in the Styles picker. Leave it blank or omit it and the file shows up with no label.

Anatomy of the three included variations

dark.json

The simplest possible dark mode: swap base and contrast, soften subtle and muted for dark backgrounds, brighten accent slightly so it remains readable on dark.

The whole file is ~80 lines. Most of it is the color palette.

editorial.json

Designed for content-first sites (publications, journals, longform brands).

• Switches body to serif instead of sans
• Tightens contentSize to 640px for narrower reading columns
• Uses larger lineHeight for body
• Adjusts heading typography (italic h1, tighter tracking)
• Slightly warmer color palette

high-contrast.json

Built with accessibility in mind:

• Pure black on pure white (or near-pure)
• Always-underlined links (instead of underline-on-hover)
• Thicker button borders (2px via the thick border-width token)
• Higher-saturation accent for clear focus indication

Creating your own variation

1. Copy _examples/style-variation.json.txt to styles/your-name.json.
2. Set the title field at the top.
3. Override only what you want to change.

The variation appears in Site Editor → Styles automatically. No registration needed. No PHP code.

Common variation patterns

A holiday or seasonal variation

Just overrides accent and maybe accent-soft:

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 3,
  "title": "Holiday",
  "settings": {
    "color": {
      "palette": [
        { "slug": "accent", "name": "Accent", "color": "#C53030" },
        { "slug": "accent-soft", "name": "Accent soft", "color": "#FED7D7" }
      ]
    }
  }
}

A "compact" variation (denser layout)

Overrides spacing scale to be tighter:

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 3,
  "title": "Compact",
  "settings": {
    "spacing": {
      "spacingSizes": [
        { "slug": "md", "name": "Medium", "size": "clamp(0.75rem, 0.5vw + 0.5rem, 1rem)" },
        { "slug": "lg", "name": "Large", "size": "clamp(1rem, 1vw + 0.75rem, 1.5rem)" }
      ]
    }
  }
}

A rebrand variation (whole new look)

Override color.palette, typography.fontFamilies, and possibly a few styles.elements.* rules. See styles/editorial.json for a full-featured example.

Tips

• Mirror palette slugs. Every variation should define every color slug from the base theme.json. If the base has 16 colors and your variation has 14, the missing 2 fall back to the base values, which can produce unexpected combinations.
• Don't override styles.blocks.* unless necessary. Block-level overrides are tightly coupled to the block markup. If you override core/button in a variation, every change to core/button styling in theme.json has to be mirrored in every variation. Keep variations to global tokens and element-level styles.
• Test in the Site Editor. Switch between variations in Site Editor → Styles to verify each one looks intentional. The user will switch between them; you don't get to pick.

How users switch between variations

In the WordPress admin, go to Site Editor → Styles. The "Browse styles" panel lists all available variations. Clicking one applies it sitewide. WordPress remembers the choice.

Variations are not per-page. They're sitewide. If you want a per-page look (e.g. a different header on the landing page), that's a custom page template (e.g. page-landing.html), not a variation.