The Purpose and Cautions of Adjusting Gutenberg (Block Editor) with CSS

When entering articles with WordPress’s Gutenberg (block editor), have you ever felt that the appearance in the editor looks completely different from the published site?

For example, the line spacing looked readable in the editor, but it appears cramped after publishing. Or the design of headings and buttons differs from the production site, making it hard to picture the final outcome.

These “preview vs. production mismatches” cause rework and additional fixes after publication.

  • The goal is to narrow the style gap between the editor and the production site. The closer the appearance is while writing, the less mismatch and rework you’ll have after publishing.
  • Don’t overdo it: limit the scope so you don’t affect the admin UI itself (sidebar, toolbar).
  • There are two main approaches
    1. Use editor-style.css to load CSS dedicated to the editor
    2. Load only in the admin with admin_enqueue_scripts / enqueue_block_editor_assets

Terminology note: “Block Editor” = Gutenberg. The main content area in the post screen is built with React and wrapped with dedicated class names.

Enable editor CSS (editor-style.css and add_theme_support settings)

Search intent: Learn the basic setup for editor-only CSS.

1) Declare support in functions.php

// Enable editor styles in the theme
add_action('after_setup_theme', function () {
  // Declare the use of editor styles
  add_theme_support('editor-styles');
  // File to load (theme root or any path)
  add_editor_style('css/editor-style.css'); // Example: /wp-content/themes/your-theme/css/editor-style.css
});

2) Create editor-style.css

Minimal example (scoped based on “Frequently used selectors” below):

/* Example editor-style.css */
.editor-styles-wrapper {
  font-family: "Noto Sans JP", system-ui, -apple-system, "Segoe UI", sans-serif;
  line-height: 1.8;
  color: #222;
}

.editor-styles-wrapper p {
  margin: 0 0 1.2em;
}

.editor-styles-wrapper .wp-block-heading h2 {
  font-size: clamp(20px, 2.4vw, 28px);
  margin: 1.2em 0 0.6em;
}

Notes:

  • If you don’t declare add_theme_support('editor-styles'), add_editor_style() won’t take effect.
  • editor-style.css is for the content preview area in the admin only. It’s safer to manage it separately from the production theme CSS.

Load CSS only in the admin (how to use admin_enqueue_scripts)

Search intent: editor-style.css isn’t enough / you want to add CSS conditionally.

enqueue_block_editor_assets (reliable for block editor only)

add_action('enqueue_block_editor_assets', function () {
  // Load only in the block editor (not loaded in the classic editor)
  wp_enqueue_style(
    'my-editor-extra',
    get_template_directory_uri() . '/css/editor-extra.css',
    [],
    filemtime(get_template_directory() . '/css/editor-extra.css')
  );
});

admin_enqueue_scripts (entire admin → safely narrow down)

add_action('admin_enqueue_scripts', function ($hook) {
  // Only the block editor screen for posts/pages
  // e.g., post.php (edit), post-new.php (new)
  if ($hook === 'post.php' || $hook === 'post-new.php') {
    // Strictly check whether it is the block editor
    $screen = get_current_screen();
    if ($screen && method_exists($screen, 'is_block_editor') && $screen->is_block_editor()) {
      wp_enqueue_style(
        'my-editor-scope',
        get_template_directory_uri() . '/css/editor-scope.css',
        [],
        filemtime(get_template_directory() . '/css/editor-scope.css')
      );
    }
  }
});

Notes:

  • Limit extra CSS to fine-tuning for the editor without overriding the production theme CSS to reduce accidents.
  • If you frequently tweak small adjustments, splitting into something like editor-extra.css improves maintainability.

Understand frequently used selectors (.editor-styles-wrapper / .block-editor / .wp-block, etc.)

Search intent: Learn which classes are safe and effective to target.

  • .editor-styles-wrapper
    Wraps the entire content area within the editor. Start by scoping here to avoid contaminating the admin UI. .editor-styles-wrapper .wp-block { max-width: 720px; } /* Visual guide for content width */
  • .block-editor / .block-editor-writing-flow
    For the internal structure of the Gutenberg editor. Since it also includes UI-side classes, prioritize .editor-styles-wrapper for styling the content appearance.
  • .wp-block
    The base for all blocks. Individual blocks include .wp-block-paragraph, .wp-block-heading, .wp-block-button, etc. .editor-styles-wrapper .wp-block-paragraph { /* Paragraph block */ } .editor-styles-wrapper .wp-block-heading { /* Heading block */ } .editor-styles-wrapper .wp-block-button .wp-block-button__link { /* Button */ }
  • Utilities
    • Images: .wp-block-image img
    • Lists: .wp-block-list li
    • Quotes: .wp-block-quote
    • Tables: .wp-block-table table

First, make it a habit to always place .editor-styles-wrapper at the top level—this is the safest approach.

Adjust with concrete examples: polish previews for headings, paragraphs, and buttons

Search intent: Learn practical CSS you can use right away.

Headings

/* Unify hierarchy and spacing for headings */
.editor-styles-wrapper .wp-block-heading h1 { font-size: clamp(26px, 3.2vw, 34px); margin: 1.4em 0 .6em; }
.editor-styles-wrapper .wp-block-heading h2 { font-size: clamp(22px, 2.6vw, 28px); margin: 1.3em 0 .6em; }
.editor-styles-wrapper .wp-block-heading h3 { font-size: clamp(18px, 2.2vw, 22px); margin: 1.2em 0 .5em; }

/* Underline variation (site-like preview) */
.editor-styles-wrapper .wp-block-heading h2.is-style-underline,
.editor-styles-wrapper .wp-block-heading h3.is-style-underline {
  border-bottom: 2px solid currentColor;
  padding-bottom: .25em;
}

Paragraphs

/* Comfortable measure and line-height */
.editor-styles-wrapper {
  --measure: 72ch; /* Maximum text width */
}
.editor-styles-wrapper .wp-block-paragraph {
  max-width: var(--measure);
  line-height: 1.9;
  letter-spacing: .02em;
}

/* Emphasis appearance */
.editor-styles-wrapper em  { background: linear-gradient(transparent 60%, #fff2a8 0); }
.editor-styles-wrapper strong { font-weight: 700; }

Buttons

/* Make the default look of block buttons closer to production */
.editor-styles-wrapper .wp-block-button .wp-block-button__link {
  display: inline-block;
  padding: .8em 1.2em;
  border-radius: 9999px;
  text-decoration: none;
  font-weight: 700;
  transition: transform .06s ease, box-shadow .2s ease;
  box-shadow: 0 2px 8px rgba(0,0,0,.08);
}

/* Outline style (transparent) */
.editor-styles-wrapper .wp-block-button.is-style-outline .wp-block-button__link {
  background: transparent;
  border: 2px solid currentColor;
}

/* Hover feedback */
.editor-styles-wrapper .wp-block-button .wp-block-button__link:hover {
  transform: translateY(-1px);
  box-shadow: 0 6px 18px rgba(0,0,0,.12);
}

Notes:

  • .is-style-* classes are added by the “Styles” feature (right sidebar) in the editor. Add more to match your site’s design.

Support responsive and dark mode (with media queries and prefers-color-scheme)

Search intent: CSS that won’t break during preview on mobile or in dark theme.

Responsive (when the width is narrow)

/* Fine-tune type sizes and spacing at 600px and below */
@media (max-width: 600px) {
  .editor-styles-wrapper { line-height: 1.85; }
  .editor-styles-wrapper .wp-block-heading h1 { font-size: 24px; }
  .editor-styles-wrapper .wp-block-heading h2 { font-size: 21px; }
  .editor-styles-wrapper .wp-block-paragraph { letter-spacing: .01em; }
  .editor-styles-wrapper .wp-block { max-width: 92%; }
}

Dark mode (follow OS settings)

@media (prefers-color-scheme: dark) {
  .editor-styles-wrapper {
    color: #e9e9e9;
    background: #121212; /* Example: darken the editor content area only */
  }
  .editor-styles-wrapper a { color: #8ecbff; }
  .editor-styles-wrapper .wp-block-button .wp-block-button__link {
    box-shadow: 0 2px 10px rgba(0,0,0,.5);
  }
  .editor-styles-wrapper .wp-block-quote {
    border-left: 4px solid #4aa3ff;
    background: rgba(255,255,255,.04);
  }
}

Notes:

  • To avoid darkening the entire admin interface, change colors only within the content area (.editor-styles-wrapper).

Checklist when styles don’t apply (cache, priority, and handling !important)

Search intent: Learn how to troubleshoot when CSS doesn’t take effect.

  1. File paths and load order
    • Did you add add_theme_support('editor-styles')?
    • Is the path correct for add_editor_style('css/editor-style.css')?
    • For additional CSS, loading it later via enqueue_block_editor_assets makes overriding easier.
  2. Cache
    • Clear browser cache / server cache plugins.
    • Set the 4th argument (version) of wp_enqueue_style() to filemtime() for cache busting.
    wp_enqueue_style('my-editor-extra', get_template_directory_uri() . '/css/editor-extra.css', [], filemtime(get_template_directory() . '/css/editor-extra.css') );
  3. Selector scope and specificity
    • Are you prefixing with .editor-styles-wrapper?
    • If there’s strong competition, increase selector granularity (e.g., .editor-styles-wrapper .wp-block-button .wp-block-button__link).
    • Use !important only as a last resort—overuse makes maintenance difficult.
  4. Confirm the target screen
    • Are you actually using the block editor (not the classic editor)?
    • If using admin_enqueue_scripts, check whether you’re reaching it with $hook or get_current_screen()->is_block_editor().
  5. Conflicts with theme JSON
    • When using theme.json alongside, it may conflict with editor-generated styles. Try solving with CSS first; if needed, consider shifting to theme.json-based design tokens.
  6. Overrides from plugins
    • Design-related plugins may inject CSS with high priority. In Chrome DevTools, check “which CSS wins.”

Finishing template (starter you can use as-is)

functions.php

add_action('after_setup_theme', function () {
  add_theme_support('editor-styles');
  add_editor_style('css/editor-style.css');
});

add_action('enqueue_block_editor_assets', function () {
  wp_enqueue_style(
    'my-editor-extra',
    get_template_directory_uri() . '/css/editor-extra.css',
    [],
    filemtime(get_template_directory() . '/css/editor-extra.css')
  );
});

css/editor-style.css (excerpt)

.editor-styles-wrapper {
  font-family: "Noto Sans JP", system-ui, -apple-system, "Segoe UI", sans-serif;
  line-height: 1.9;
  color: #222;
}

.editor-styles-wrapper .wp-block { max-width: 720px; }
.editor-styles-wrapper .wp-block-paragraph { max-width: 72ch; margin: 0 0 1.2em; }
.editor-styles-wrapper .wp-block-heading h2 { font-size: clamp(22px, 2.6vw, 28px); }

/* Buttons */
.editor-styles-wrapper .wp-block-button .wp-block-button__link {
  display: inline-block; padding: .8em 1.2em; border-radius: 9999px; font-weight: 700;
  transition: transform .06s ease, box-shadow .2s ease; box-shadow: 0 2px 8px rgba(0,0,0,.08);
}
.editor-styles-wrapper .wp-block-button .wp-block-button__link:hover {
  transform: translateY(-1px); box-shadow: 0 6px 18px rgba(0,0,0,.12);
}

/* Responsive & Dark */
@media (max-width: 600px) {
  .editor-styles-wrapper .wp-block { max-width: 92%; }
}
@media (prefers-color-scheme: dark) {
  .editor-styles-wrapper { color: #e9e9e9; background: #121212; }
}

As needed, parameterize according to your live site’s type, color, and spacing rules (e.g., --color-primary) so you can manage both production and editor with the same tokens. I can also help with rewrites or additions.