Style variations are one of the most commercially powerful features in the block theme ecosystem. A single theme can ship with five, ten, or even twenty completely distinct visual personalities, different color palettes, font stacks, spacing rhythms, and block-level treatments, all selectable from the Site Editor in two clicks. For theme developers, this means one codebase, multiple market segments, and dramatically shorter time to market for new design packages. For end users, it means meaningful design choices without touching a line of code.
This guide covers the full lifecycle of style variations in block themes: the JSON file structure, how WordPress discovers and loads them, how to override colors, typography, and spacing per variation, how to style individual blocks differently per variation, how to preview your work in the Site Editor during development, and how to position style variations as a genuine selling point when distributing commercial block themes.
What Style Variations Are and How WordPress Loads Them
A style variation is a partial or complete override of a theme’s theme.json settings and styles. It lives in a dedicated styles/ directory inside the theme root as a standalone JSON file. When a user activates a variation in the Site Editor, WordPress merges that variation’s JSON on top of the base theme.json, with the variation winning on any property both files define.
WordPress first introduced style variations in version 6.0 alongside the Twenty Twenty-Three theme, which shipped with a set of well-designed variations that demonstrated the feature’s potential. The underlying mechanism is the Theme JSON API, specifically the WP_Theme_JSON_Resolver class, which assembles the final style data by layering: WordPress core defaults → theme base theme.json → active style variation → user customizations from the Site Editor.
Each layer can override or extend the layer below it. A style variation does not need to be a complete theme.json replica, it only needs to contain the values it wants to change. If your base theme defines ten colors and a variation only changes two of them, the variation file only needs those two color entries. Everything else inherits from the base.
The Discovery Mechanism
WordPress scans the styles/ directory inside the active theme folder for any .json files. Each file it finds is registered as an available style variation. The title field inside the JSON is what appears in the Site Editor UI. If no title is present, WordPress falls back to the filename (minus the extension).
Child themes can also provide style variations. When a child theme is active, WordPress scans both the child theme’s styles/ directory and the parent theme’s styles/ directory. Child theme variations appear alongside parent theme variations in the Site Editor, giving child theme developers a clean extension path.
File Structure: Anatomy of a Style Variation JSON
A style variation file follows the same schema as theme.json. It must include a schema declaration and a version number. Beyond that, only include the settings and styles you intend to override. Below is a complete, production-ready example of a “Dark Professional” variation that overrides the full color palette, gradients, and global typography styles:
A few things to notice in this structure. The "title" field is the display name in the Site Editor. The settings section redefines the entire color palette, because palette definitions do not merge at the item level, defining a new palette replaces the base palette in full for this variation. The styles section applies those palette colors globally and redefines element-level typography. The elements block under styles lets you target semantic elements (links, headings, buttons) with variation-specific values.
Recommended File Naming Conventions
WordPress does not enforce a naming convention for variation files, but these guidelines will save you maintenance headaches as your theme grows:
- Use lowercase kebab-case:
dark-professional.json, notDarkProfessional.json - Name files descriptively for the variation’s personality, not its technical content:
warm-sunrise.jsoncommunicates the mood better thanorange-palette.json - If you offer themed groups (light/dark pairs, seasonal sets), prefix them:
light-classic.json,dark-classic.json - Avoid version numbers in filenames, the title field handles versioning for the UI
Overriding Colors Per Variation
Color is the most common, and most impactful, thing to change per variation. The palette you define under settings.color.palette in a variation completely replaces the base palette. This is intentional: if WordPress merged palettes at the slug level, users could end up with a mix of base and variation colors in the editor, which would be confusing.
The recommended pattern for commercially distributed themes is to use semantic color slugs in your base theme, slugs like base, base-2, contrast, contrast-2, accent, and accent-2 rather than descriptive names like blue or light-gray. When your slugs are semantic, every block that references var(--wp--preset--color--accent) automatically picks up the variation’s accent color without you touching any template or pattern code.
Here is a warm-toned color variation that reuses the same semantic slugs from the base theme:
Because both the base theme and this variation use the same slug names, every block pattern, template part, and user-created content that references has-accent-color or has-base-background-color classes will automatically render in the warm color scheme when this variation is active. No patterns need to be updated, no templates need to be duplicated. This is the power of semantic slugs done right.
Gradients and Duotone Per Variation
Gradients follow the same replacement behavior as palettes. Define settings.color.gradients in your variation to provide variation-specific gradients. Duotone presets, defined under settings.color.duotone, work the same way. If your base theme offers a set of photography-oriented duotones, a variation targeting a corporate audience might replace them with brand-aligned monochrome duotones.
Overriding Typography Per Variation
Typography changes, switching font families, adjusting the type scale, modifying line heights, are where style variations can dramatically alter a theme’s character. A theme that ships in a clean geometric sans-serif can feel like an entirely different product when a variation switches it to a classical serif stack.
The typography variation below demonstrates a full font family swap with fluid font sizes using CSS clamp() functions, a common pattern in modern block themes:
Several important details in this example. The fontFace array inside each font family entry handles @font-face declaration, WordPress generates these rules automatically from the data you provide. The fontWeight and fontStyle values can be ranges (like "400 700") to load variable fonts efficiently. The font sizes use clamp() with viewport-relative units, which gives you fluid typography that scales smoothly between viewport widths without JavaScript or additional CSS files.
Scoping Typography Changes to Headings
You do not have to replace the entire typography system in a variation. A variation can change only heading typography while leaving body text alone. To do this, define only the elements changes under styles without touching settings.typography at all. WordPress inherits the base theme’s font size and font family settings but applies your variation’s heading overrides on top.
This is particularly useful for themes that want to offer a “same layout, different mood” set of variations where body text stays consistent for readability but heading typography shifts the overall design personality.
Overriding Spacing Per Variation
Spacing is the least glamorous but most functionally significant dimension of style variations. A “compact” variation can make a theme feel tight and efficient, appropriate for news aggregators, dashboards, or dense editorial layouts. A “generous” variation with large block gaps and paddings can make the same theme feel luxurious and spacious, appropriate for portfolio sites, luxury brands, or long-form editorial.
WordPress generates CSS custom properties for spacing presets using the pattern --wp--preset--spacing--{slug}. When your base theme and all its block styles reference these tokens, changing the spacing scale in a variation cascades across the entire layout automatically:
The spacingScale object uses a multiplicative scale, each step multiplies the previous by the increment value, starting from mediumStep. You can override only the scale parameters or provide explicit spacingSizes entries for full control, the complete theme.json settings reference documents every available spacing property. The styles.blocks section then applies these tokens to specific core blocks like core/group, overriding their default padding for this variation.
Layout Width Variations
You can also override settings.layout per variation to change the content width and wide width. A variation targeting long-form writing might narrow the content width to 680px for improved readability. A variation for product-focused pages might widen to 1100px to give product grids more room. These layout width changes flow through to core blocks automatically via WordPress’s layout block support.
The most effective style variations do not change everything, they change the right things. Pick two or three dimensions that define the mood (color, typeface, spacing scale) and leave the structural decisions (layout widths, template architecture) consistent across variations.
Styling Individual Blocks Per Variation
Color, typography, and spacing changes affect the global canvas. But some of the most interesting variation-specific design decisions happen at the individual block level. The styles.blocks section of a variation file lets you target any registered block by its block name and apply variation-specific styles to it.
A “Minimal Ink” variation that strips visual embellishments from buttons, quotes, and images demonstrates this approach well:
Notice the use of pseudo-class selectors (the ":hover" key) inside block style definitions. WordPress 6.1 added support for interactive state styles directly in theme.json and variation files, which means you can define hover, focus, and active states for buttons and links without any additional CSS files. This keeps your variation’s complete visual contract inside the JSON, making it portable and maintainable.
Third-Party Block Support
The styles.blocks key works with any block that supports theme.json styling, not just core blocks. If a popular plugin registers its blocks with full theme.json support (using supports.color, supports.typography, supports.spacing in block.json), you can target those blocks by their full namespaced name in your variation files. Check the block’s block.json for its name field to confirm the exact namespace to use.
Previewing Style Variations in the Site Editor
WordPress includes a built-in preview workflow for style variations in the Site Editor. Understanding this workflow will save you significant development time and help you deliver a better experience to theme users who discover variations for the first time.
Accessing the Styles Panel
In the Site Editor (Appearance → Editor), click the Styles icon in the top-right toolbar, it is the half-filled circle. This opens the Styles panel. At the top of the panel, you see a grid of visual thumbnails, one per style variation. These thumbnails are automatically generated by WordPress from each variation’s color palette and typography settings. You do not need to provide preview images manually.
Clicking a variation thumbnail immediately applies it as a live preview across the entire editor canvas. You can navigate between templates and template parts to see how the variation affects different parts of your site. No changes are committed until you click Save. This non-destructive preview workflow is one of the most user-friendly aspects of the style variation system.
Development Iteration Cycle
When developing variations, use this cycle to iterate efficiently:
- Make a change to your variation JSON file in your code editor
- In the Site Editor, navigate away from the Styles panel and back to it, WordPress reloads variation data from the filesystem on each Styles panel open
- Click your variation thumbnail to preview the change
- If the change does not appear, check the browser’s network tab for the REST API call to
/wp/v2/global-styles/themes/{theme}/variationsto see what WordPress is returning - Repeat until the variation looks correct in the editor before testing on the front end
Local development environments with file watching (Local by Flywheel, wp-env, Lando) do not need a server restart between JSON edits, WordPress reads these files on every request when WP_DEBUG is true. In production-like setups with object caching enabled, you may need to flush the cache to pick up JSON file changes.
Validating the Generated CSS
WordPress generates inline CSS from your variation’s theme.json data. You can inspect this output by viewing the page source and looking for a style block with the ID global-styles-inline-css. This block contains all the custom properties and block-level overrides derived from your active variation. Reviewing it during development helps you catch issues like missing custom property references or unexpected value overrides.
Registering Variations Programmatically
Most use cases are served entirely by JSON files in the styles/ directory. But there are scenarios where you need to generate variation data dynamically, pulling brand palettes from a database, generating client-specific color schemes, or integrating with a design token management system. WordPress 6.5 introduced register_block_style_variation(), and the wp_theme_json_data_theme filter provides an earlier-compatible approach for dynamic overrides:
The filter approach shown here is most useful for agency or multi-tenant scenarios: a theme deployed across many client sites, each with its own brand colors stored in the database, where the “variation” is effectively just the client’s brand palette applied over your base theme. The REST endpoint example shows how to expose variation data to custom interfaces, useful if you’re building a theme customizer or an onboarding wizard that walks users through picking their design preset before they ever enter the Site Editor.
Style Variations as a Commercial Selling Point
The business case for shipping robust style variations with commercial block themes is stronger than most theme developers realize. Variations address a fundamental problem in the theme market: buyers want to see their specific aesthetic reflected in the product before they purchase, but no single theme can visually appeal to every design taste.
Reducing Perceived Risk for Buyers
When a potential buyer visits your theme’s demo page and sees eight different style variations selectable in real time, they no longer have to imagine how the theme might look in a different color or with a different typeface. They can see it. This dramatically reduces the “I like the layout but not the colors” objection that causes prospective buyers to abandon the purchase.
Themes on the WordPress.org theme directory that ship with multiple style variations consistently receive stronger “fits many use cases” feedback in reviews. Buyers who activated a non-default variation often mention it explicitly, because the discovery felt like a delightful surprise. That surprise is your product moment, design it deliberately.
Expanding Addressable Markets
A block theme built for creative agencies can include a “Corporate” variation with conservative colors and tight spacing that makes it viable for professional services firms. A theme built for bloggers can include an “E-commerce Ready” variation with stronger CTA button styles and a product-focused palette. Each variation extends your potential buyer pool without requiring a new theme.
The key constraint is coherence: every variation should use the same templates, patterns, and block structures. Variations that require different page layouts or navigation structures push toward child themes rather than style variations. Stay within the “same structure, different aesthetics” contract and your theme remains a single maintainable product.
Structuring Variations for Theme Sales Pages
On your theme’s sales or demo page, present variations as a gallery with named thumbnails rather than asking buyers to dig into the Site Editor. Several approaches work well:
- Named presets with live demos: Each variation gets its own demo URL (using WordPress’s
?wp_theme_previewparameter or a dedicated staging subdomain per variation) so buyers can browse the full site in each variation before purchasing - Category-based grouping: Group variations by use case (Creative, Professional, Minimal, Bold) rather than by aesthetic properties, this matches how buyers self-identify
- Default variation choice: Make your most commercially appealing variation the default in
theme.json, it is what buyers see when they first activate the theme before exploring the Styles panel - Feature variations in onboarding: If your theme includes a welcome/setup page (via the Patterns API or a custom settings page), surface variation selection as the first design choice in the onboarding flow
Variations as a Premium Upsell
A common commercial pattern: ship 3-4 variations in the free version of your theme and 10-15 in the pro version. The free variations demonstrate the concept and build buyer confidence. The pro variations, especially those targeting premium markets like luxury real estate, high-end hospitality, or enterprise software, justify the upgrade. Because variations are pure JSON with no PHP logic, the free/pro split is simply a matter of which JSON files you include in each package.
Common Mistakes and How to Avoid Them
Shipping style variations in production themes surfaces several recurring mistakes. Knowing them in advance saves debugging time.
Using Descriptive Instead of Semantic Color Slugs
The most common mistake is naming palette entries after their color value: "slug": "blue-700", "slug": "warm-gray". When a variation changes these to completely different colors, the slugs become misleading. Block patterns and user content that referenced has-blue-700-background-color now render with whatever non-blue color the variation assigned to that slug. Use semantic slugs (primary, accent, surface) from the start and you never encounter this problem.
Defining More Colors Than Users Can Meaningfully Distinguish
Large palettes (15+ colors) create noise in the color picker without adding design value. For a well-designed variation system, 6-8 semantic colors cover the vast majority of use cases: a base background, a secondary background, two foreground/contrast values, two accent values, and one or two semantic colors for status (success, warning). Each additional color beyond this set adds maintenance burden when creating new variations.
Forgetting User Customization Persistence
When a user customizes their site in the Site Editor and then activates a different style variation, their customizations are preserved and layered on top of the new variation. This is technically correct behavior but can produce unexpected results, a user who manually set their heading color to match the old variation’s accent color will see that override persist even after switching variations. The UX implication: document for your users that “resetting to variation defaults” clears their customizations, which is done via the reset icon in the Styles panel.
Not Testing Variations Against All Template Parts
Developers often test variations against the homepage template and assume everything looks correct. In practice, edge cases surface in less-visited templates: 404 pages, archive headers, search results, single post headers when a featured image is present, comment forms. Build a checklist of every template and template part in your theme and run each variation against the full checklist before shipping a release.
Building a Maintainable Multi-Variation Workflow
As your theme grows to include 8, 10, or 15 variations, ad-hoc JSON editing becomes error-prone. A structured workflow keeps the variation library manageable.
Use a Design Token Spreadsheet as the Source of Truth
Before writing any JSON, maintain a spreadsheet or Figma token document that defines every variation’s values across all dimensions: palette colors, gradient definitions, font families, type scale, spacing increments. This document becomes the canonical reference that the JSON files implement. When a variation needs updating, you update the reference document first, then translate it to JSON. This also simplifies client collaboration, clients can review a color palette table without needing to read JSON.
Validate JSON Files in CI
A malformed JSON file in your styles/ directory can silently cause WordPress to skip loading that variation or, in some cases, cause a PHP warning that degrades editor performance. Add JSON schema validation to your CI pipeline using ajv or a simple jq check against the official theme.json schema, the same $schema URL you reference in your variation files. Catch syntax errors before they reach a production site.
Version Your Variation Files
When you update a variation in a new theme release, users who have that variation active and have made Site Editor customizations may see unexpected changes. Follow a consistent deprecation policy: if a variation changes significantly enough to break existing customizations, rename it (add a version suffix) and keep the old version in the package for one major release cycle. Users who had the old version active retain it; new installs use the updated version.
Where Style Variations Fit in the Broader Block Theme Design System
Style variations are one layer of a broader block theme design system. They work best when the other layers are well designed too. Block patterns should reference only semantic color and spacing tokens, not hardcoded values, so they render correctly in every variation. Template parts should avoid inline styles. The base theme.json should establish a solid default that works on its own, with variations providing differentiation rather than compensating for base theme deficiencies.
The Block Theme Design Systems series on this site covers the full architecture: theme.json structure, block patterns, template design, and the role of variations within a cohesive design system. This article is Article 5 in that series, if you haven’t read the earlier pieces on design tokens, template hierarchy, and synced patterns, they provide context that makes the variation concepts here easier to apply.
Next Steps
Start building your variation library by auditing your current base theme.json. Are your color slugs semantic? Is your spacing system using tokens consistently? Is your typography referencing custom properties rather than raw values? A solid base is a prerequisite for variations that actually work. Once the base is token-driven, creating a new variation becomes as simple as writing a 40-line JSON file that reassigns the semantic tokens to new values, and your entire theme repaints itself.
The practical exercise: take your current theme’s color palette and create one dark variation and one high-contrast variation this week. Deploy them to a staging environment and navigate through every template and template part. The experience of seeing your entire site transform in two clicks is the clearest possible demonstration of why the block theme architecture is a step forward from the classic theme model, and why style variations are one of its most compelling features for both developers and end users.
Building Block Themes Seriously?
The full Block Theme Design Systems series walks through every layer of the architecture, from design tokens in theme.json to synced pattern strategy to the template hierarchy and beyond. Each article is written for developers who want to ship commercial-grade block themes, not just experiment with the Site Editor.