Styling

Principle

One stylesheet system. The front end and the editor apply the same rules. Every path the theme loads is a file the production build emits.

Why

Note

add_editor_style() inlines a stylesheet and rewrites its selectors. WordPress’s own editor reset is unlayered, so it overrides rules that sit inside CSS @layer. Tailwind 4 emits @layer. Passing that file to add_editor_style() leaves the editor unstyled. enqueue_block_assets loads a normal <link> in the editor iframe and leaves the layers intact.

A second framework, brought in for one widget, weighs as much as the theme and adds a second set of names.

How

Block theme

Hand-written CSS against theme.json presets covers layout, type, and focus. The file stays in the tens of kilobytes. The front end enqueues it. add_editor_style() receives that same path. This holds only while the file contains no @layer.

functions.php

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

add_action( 'wp_enqueue_scripts', static function () {
  wp_enqueue_style(
    'theme',
    get_theme_file_uri( 'assets/css/theme.css' ),
    array(),
    wp_get_theme()->get( 'Version' )
  );
} );

Utility classes in PHP

A utility framework earns its place when most of the design is utility classes in PHP templates.

The build scans those templates so unused utilities drop out. There is no safelist kept in reserve. The front-end build and the editor build are separate. The editor build can skip the framework’s reset.

The editor file loads with enqueue_block_assets while is_admin() is true, not with add_editor_style(). TinyMCE, including rich-text fields from a fields plugin, receives the same URL on the mce_css filter.

add_editor_style() loads at most one extra file: small, unlayered, for rules that must survive selector rewriting. The production build writes that file. A theme that does not need the extra file does not reference it.

Production CSS is minified. One feature does not add a second library beside the system already in use.

How to check

Tip

Every add_editor_style() path exists after the production build. A missing path 404s in the editor.

grep -R -n -o -E "add_editor_style\(\s*'[^']+'" --include='*.php' . \
  | sed "s/.*add_editor_style[[:space:]]*([[:space:]]*'//;s/'.*//" \
  | while read -r path; do
      test -f "$path" || echo "missing $path"
    done
wc -c assets/css/*.css
grep -R -n '@layer' assets/css/*.css

wc runs on the built files. A block theme on theme.json stays under 50KB for the front-end file. A utility build stays under 100KB unless a new component accounts for the growth. @layer in a file passed to add_editor_style() is a failed check.

Avoid

Caution

add_editor_style() pointed at a path the production build does not emit.

add_editor_style() on a file that contains @layer.

outline: none or outline: 0 as the focus treatment. The outline goes only when :focus-visible draws a visible ring. See Accessibility.

A dependency stylesheet for one widget that is larger than the theme stylesheet.