Assets

Atomic CSS

Atomic CSS is a production-only optimization that rewrites theme-owned class names and CSS variables in compiled PHP and built CSS.

When To Use It#

Keep Atomic CSS off while designing, debugging, and reading markup.

Enable it before production builds when you want public CSS and markup to use generated names instead of readable source names.

Enable Atomic CSS#

In WordPress admin:

  1. Open TemplateX.
  2. Go to Settings, then Development.
  3. Enable Atomic CSS.
  4. Choose the generated name settings.
  5. Wait for the autosave toast to confirm the setting.

Then build or publish:

bash
npm run build
bash
bun run build
bash
npm run publish
bash
bun run publish

Atomic CSS only runs during build and publish commands. npm run dev and bun run dev keep readable class names.

What Gets Rewritten#

TemplateX reads class names and CSS variables from:

  • CSS in resources/css
  • static class attributes in resources/views
  • static <style> blocks and style attributes in resources/views
  • block variant classes in resources/views/blocks
  • final CSS produced by Vite

It rewrites matching names in:

  • compiled templates
  • extracted view styles, inline <style> blocks that stay in PHP, and CSS custom properties in style attributes
  • WordPress class helper calls generated from compiled templates, such as body_class()
  • block render files
  • block editor config
  • class-like TemplateX arguments in compiled templates, such as WooCommerce variation active_class and unavailable_class
  • built CSS assets
  • built JavaScript assets emitted by Vite

For example, source can stay readable:

phpresources/views/front-page.php
<section class="hero-section">  <h1 class="hero-title">{{ title }}</h1></section>

Generated production markup can use generated names:

html
<section class="abc def">  <h1 class="ghi">Page title</h1></section>

Generated names depend on the theme settings and build output.

Benefits#

Obfuscation keeps public class names detached from source names. That can make production markup less tied to internal naming, and it can reduce repeated CSS by splitting simple class rules into generated atomic classes.

It also works with generated CSS systems such as Tailwind because TemplateX rewrites the final Vite output after the production build. Modifier classes such as hover:text-white are rewritten in both the compiled markup and matching built CSS selectors.

After this rewrite, TemplateX writes a build asset version. Published themes use that version in their CSS and JavaScript URLs, so browser caches do not keep an older obfuscated stylesheet paired with newer compiled markup.

Safelist Classes#

Some class names should stay readable because JavaScript, WordPress, plugins, or third-party libraries expect them.

TemplateX preserves common WordPress and plugin-facing classes such as wp-*, has-*, is-*, woocommerce*, wc-*, button, menu, page, post, image-size, screen-reader classes, and cursor-pointer.

It also preserves classes found in resources/js, plus classes that start with _ or js-.

Add extra safelist entries in the Atomic CSS options when another script or plugin depends on a class:

text
menu-toggle/^swiper-/

Use one class name or regex per line.

Name Settings#

The Atomic CSS options control:

  • generated name case: lowercase, uppercase, or mixed
  • class name length
  • CSS variable name length
  • whether generated names may use numbers after the first character
  • safelist entries

The length is a starting length. TemplateX grows generated names when that space is full.

Turning It Off#

Disable Atomic CSS to return production builds to readable class names.

The source files in resources do not need to change.