PlayBrick

WordPress plugin that bridges design (Figma / HTML / images) and Bricks Builder.

On activation it creates a local dev scaffold. You build components there, then export optimized assets for production with one command.

Installation

1. Clone or download the plugin into wp-content/plugins/playbrick/
2. Activate it from Plugins → Installed Plugins
3. On activation the plugin creates wp-content/playground/ with the full scaffold

wp-content/plugins/playbrick/   ← the plugin (this repo)
wp-content/playground/          ← created on activation (your work goes here)
  ├── src/                      ← reference material only (Figma exports, screenshots, base HTML)
  ├── bricks/
  │   ├── base/                 ← variables.css · reset.css · global.css
  │   ├── components/           ← Bricks-ready CSS/JS + preview HTML
  │   └── sections/             ← page sections + Bricks-ready HTML previews
  ├── dev.css                   ← CSS entry point (@import chain)
  ├── dev.js                    ← JS entry point (IIFEs)
  ├── build.js                  ← production build script
  ├── package.json
  └── playbrick.config.js       ← local config (generated by the plugin)

Reference files in src/ are not built or shipped to production — only the bricks/ tree is processed by the build step.

Settings

Go to Settings → PlayBrick:

Development workflow

src/ (references)  →  bricks/ (build)  →  dev.css/dev.js  →  Bricks Builder

Reference files in src/ are not included in the production build. Author Bricks-ready CSS, JS, and preview HTML in bricks/components/ and bricks/sections/.

1. Drop Figma exports, screenshots, or reference HTML into src/
2. Build components in bricks/components/ and sections in bricks/sections/
3. Add @import entries to dev.css and IIFEs to dev.js
4. Open the HTML preview in your browser to verify before going to Bricks
5. In Bricks, apply the CSS class to the outermost Section element and set its padding to 0

Build commands (run from playground/)

corepack enable     # if pnpm is not available in this shell
pnpm install        # first time only
pnpm run watch      # dev mode → writes dev.built.css in the playground and refreshes Bricks
pnpm run build      # production → writes minified files to the output directory

In Tailwind mode, each build first exports CSS classes stored in Bricks Builder to .playbrick/bricks-sources.html and .playbrick/bricks-sources.txt, plus global-class Custom CSS to .playbrick/bricks-custom.css. Bricks Style Manager variables and color palette tokens are exported to .playbrick/bricks-theme.css as Tailwind @theme inline tokens. Do not edit Bricks-generated files under wp-content/uploads/bricks/css; Bricks Style Manager is the source of truth, and PlayBrick mirrors those variables into Tailwind. For example, Bricks variables like --space-m, --text-xl, --color-primary, and --card-radius become Tailwind utilities such as p-m, text-xl, bg-primary, and rounded-card for use in @apply. Builds also write .playbrick/tailwind-utilities.json so the CSS Panel can autocomplete those project utilities. While pnpm run watch is running, PlayBrick also checks Bricks for class changes, rebuilds when generated sources change, and updates the loaded dev.built.css link in the browser and same-origin Bricks canvas iframes through playbrick.reload.json.

PlayBrick CSS panel

When Bricks Builder is open, PlayBrick adds a small CSS panel button to the builder header. The panel supports both the active Bricks global class and the active Bricks element:

The panel shows how many visual controls were translated and lists unsupported settings so the mapping can grow safely over time. It keeps visual-control CSS and Custom CSS separate. Do not duplicate generated visual styles into _cssCustom; that would create two competing sources of truth.

Use Apply to visual to map simple custom CSS declarations back into the active target's Bricks visual controls. Supported declarations are moved into the target settings; unsupported declarations remain in _cssCustom. Supported mappings cover common layout, spacing, typography, background, border, border radius, and box shadow declarations.

The Custom CSS editor includes lightweight autocomplete suggestions loaded from assets/css-completions.json, plus generated project utilities from .playbrick/tailwind-utilities.json, without requiring Monaco, CodeMirror, or a plugin build step.

See the PlayBrick user guide for the complete workflow, styling levels, token conventions, responsive behavior, and troubleshooting. See the PlayBrick roadmap for future improvements and architectural guardrails.

Languages: English user guide · Guía de usuario en español · English roadmap · Hoja de ruta en español

Going to production

1. Run pnpm run build from the playground folder
2. In Settings → PlayBrick, switch Environment to Production
3. WordPress now serves the minified files — theme updates won't affect this

Child theme enqueue (advanced)

Some projects — such as those using snn-brx-child-theme — need the child theme to control exactly when and how PlayBrick assets are loaded. PlayBrick supports this as an explicit strategy.

1. In Settings → PlayBrick, set Enqueue strategy to Child theme.
2. Fill in Child theme path (absolute path) and Enqueue file (relative to the theme, e.g. functions.php or includes/features/enqueue-scripts.php).
3. Save the settings.
4. Click Generate child-theme enqueue. PlayBrick writes the enqueue hook into the selected file.
5. While Child theme is selected, the plugin will not enqueue any assets, so there is no double enqueue.

To switch back to plugin-managed enqueue, change Enqueue strategy to Plugin and save. If a legacy includes/playbrick-enqueue.php file from an old setup run is still present, the settings page will warn you so you can remove it.

CSS patterns

Self-centering section (required on every section)

.my-section {
  width: 100%;                         /* prevents shrinking in Bricks flex containers */
  max-width: var(--container-max);
  margin: var(--space-section) auto 0;
  padding: var(--space-2xl) var(--space-md-plus);
  box-sizing: border-box;
}

Full-bleed background (SVG / color spans full viewport)

.my-section-bg {
  position: absolute !important;       /* !important — Bricks overrides brxe-svg */
  top: 0 !important;
  bottom: 0 !important;
  left: 50% !important;
  right: auto !important;
  transform: translateX(-50%);
  width: 100vw !important;
  height: 100% !important;
  z-index: 0;
  pointer-events: none;
}

Entrance animation (IntersectionObserver)

.my-element {
  opacity: 0;
  transform: translateY(24px);
  transition: opacity var(--duration-slow) var(--ease-out-expo),
              transform var(--duration-slow) var(--ease-out-expo);
}
.my-section.is-visible .my-element { opacity: 1; transform: none; }

@media (prefers-reduced-motion: reduce) {
  .my-element { opacity: 1 !important; transform: none !important; transition: none !important; }
}

(function () {
  var section = document.querySelector('.my-section');
  if (!section) return;
  var obs = new IntersectionObserver(function (entries) {
    entries.forEach(function (e) {
      if (e.isIntersecting) { section.classList.add('is-visible'); obs.unobserve(section); }
    });
  }, { threshold: 0.15, rootMargin: '0px 0px -60px 0px' });
  obs.observe(section);
})();

Bricks gotchas