How to Fix Gutenberg Editor Color Palette and Display Issues

Many WordPress users rely on custom color palettes in the Gutenberg editor to maintain brand consistency and streamline their design workflow. A common issue reported by the community is that the editor's color settings can sometimes be overridden, display incorrectly, or not appear at all. This guide will help you understand why these problems occur and how to resolve them.

Common Color Palette Issues

Based on community reports, the most frequent problems include:

• Custom color palettes defined via add_theme_support('editor-color-palette') being overridden by a Gutenberg plugin update.
• Selected colors not displaying in the editor but appearing correctly on the front end.
• The entire editor background turning an unexpected color, like grey.
• Specific blocks, like buttons or galleries, displaying incorrect background colors.
• Global styles, such as link colors, being overridden.

Why This Happens

The primary cause of these conflicts is the evolution of the WordPress theming system. The introduction of theme.json represents a significant shift in how themes manage global styles and settings.

• Backwards Compatibility Gap: While the Gutenberg team aims for backwards compatibility with the older add_theme_support() method, some updates can cause temporary conflicts where the plugin's settings take precedence.
• Theme.json Priority: If a theme introduces a theme.json file, it becomes the single source of truth for style definitions. Even if it doesn't define a color palette, its presence can change how the editor processes older methods.
• Plugin or Theme Conflicts: Another plugin or your theme's CSS might be enqueuing styles that override the editor's appearance.
• Editor Preferences: In some cases, a user may have accidentally enabled a feature like 'Spotlight mode,' which dims all blocks except the one being edited, making the editor background appear grey.

How to Fix It: Recommended Solutions

1. Migrate to theme.json (The Modern Best Practice)

The most robust long-term solution is to define your color palette in your theme's theme.json file. This is the method the Gutenberg team is actively developing and will ensure the best compatibility.

{
  "version": 2,
  "settings": {
    "color": {
      "palette": [
        {
          "name": "Primary",
          "slug": "primary",
          "color": "#0073aa"
        },
        {
          "name": "Secondary",
          "slug": "secondary",
          "color": "#000000"
        }
      ]
    }
  }
}

Place this file in your theme's root directory. If you are using a default theme like Twenty Twenty-Four that already has this file, you may need to create a child theme to safely add your customizations.

2. Check for Plugin and Theme Conflicts

Before making code changes, rule out conflicts. The recommended way to do this is by using the Health Check & Troubleshooting plugin.

1. Install and activate the Health Check plugin.
2. Go to Tools > Site Health > Troubleshooting and enable troubleshooting mode. This will disable all plugins for your user session only, leaving the site fully functional for visitors.
3. Switch to a default theme (e.g., Twenty Twenty-Four).
4. If the problem is resolved, reactivate your plugins one by one to identify the culprit.
5. Reactivate your theme last to see if it is the source of the conflict.

3. Verify Editor Preferences

If your editor has a grey background, check your preferences.

1. Click the three-dot menu (⋮) in the top-right corner of the editor.
2. Select Preferences.
3. Go to the Appearance tab.
4. Ensure that options like 'Spotlight mode' are turned off.

4. For Specific Block CSS Issues

For problems like a white border on a gallery block, you will likely need to add custom CSS to override default styles. Use your browser's inspector tool to identify the specific CSS class causing the issue and add corrective styles to your theme's 'Additional CSS' section or style sheet.

Conclusion

Color display issues in Gutenberg are often a result of the transition to the new theme.json system. The most effective solution is to adopt the modern standard. If the problem persists after migration, a thorough conflict check using the Health Check plugin is the best next step. For more details on implementing theme.json, you can refer to the official WordPress documentation.