BreakColorUI Sync (WordPress)

BreakColorUI Sync is a WordPress plugin that connects a BreakColorUI project directly to your WordPress site. Once connected, the same Quick Access modal you'd see in the Chrome Extension is injected into the Breakdance and Oxygen page builders — but for everyone editing the site, not just the user who installed an extension.

When you save a change in the dashboard, the plugin gets it within seconds. No exporting CSS, no resyncing extensions, no clicking Copy & Paste a second time.

Plugin vs Chrome Extension

Both reach the same end goal — pick tokens directly inside the builder — but the plugin solves problems the extension can't.

You can install both — they don't conflict.

Installation

The plugin distributes a versioned ZIP through a Cloudflare Worker that proxies private GitHub releases. There are two paths:

Requirements: WordPress 6.0+, PHP 7.4+, a Breakdance- or Oxygen-powered site, and an account on breakcolorui.com with at least one project.

Connecting to your dashboard

The plugin uses a PKCE-style flow so you never paste an API key. The user clicks one button, picks a project, and the WordPress site is connected.

After the redirect lands, the settings page flips to a Connected card showing project name, sync mode (more on this below), and the time you connected. There's no key to remember — you can disconnect any time and the plugin auto-revokes the key on the dashboard side.

Sync mode: webhook+pull vs pull-only

When the dashboard claims your connection, it probes your webhook URL (/wp-json/breakcolorui/v1/webhook) with a HEAD request:

• Reachable (public site) → mode = webhook+pull → realtime updates
• Unreachable (localhost, NAT, behind a firewall) → mode = pull-only → updates on Sync now or every 10 minutes

The connected card shows a realtime or pull-only pill so you know which one your site got.

Real-time sync via webhook

When you save a change in the dashboard, the server sends a signed POST to every connected site running in webhook+pull mode:

POST  https://your-site.com/wp-json/breakcolorui/v1/webhook
Headers:
  X-BCUI-Signature: t=1729972800,v1=<hex>
  X-BCUI-Event: project.updated
  X-BCUI-Delivery: <uuid>
Body:
  { "event": "project.updated", "project_id": "...", ... }

The plugin verifies the HMAC-SHA256 signature against sha256(api_key), rejects deliveries older than 5 minutes (replay protection) and ignores duplicate delivery_id values for 15 minutes (idempotency). Once a webhook validates:

1. The local cache (transient, 10-minute TTL) is invalidated.
2. A wp_schedule_single_event pre-warms the cache 1 second later so the next editor opening Breakdance gets fresh data instantly.

The result: change a brand color in the dashboard, save, and the next refresh in Breakdance shows the new step values. No re-export, no re-publish.

Inside the builder

When the plugin is active and the site is connected, it injects a Quick Access modal identical to the Chrome Extension's — just enqueued by WordPress instead of a browser extension.

How to open the modal

Right-click — that's it. Like the Chrome extension, the modal is bound to your browser's right-click menu inside the Breakdance / Oxygen canvas.

Detection priority — Breakdance unit-input drag containers, spacing-specific selectors, typography selectors, color selectors, radius selectors. Each input type gets the matching token category.

Theme toggle

If the connected project is exported as Full System, the modal includes a sun/moon button to flip between light and dark previews. The choice is shared with the Chrome Extension (same localStorage key) so a user switching tools keeps their preference.

If the project exports Light Only or Dark Only, the toggle is hidden.

Excluded sections

The modal respects whatever you toggled in the Export tab. If a category is unchecked (say, Typography is off), the modal shows a "Not included in export" placeholder for that section instead of an empty box. Re-enable the section in the dashboard, save, and within seconds the placeholder turns into real tokens.

Auto-update

The plugin uses Plugin Update Checker (bundled in includes/plugin-update-checker/) to look for new versions. It polls a Cloudflare Worker — bcui-sync-updater.geralpixelhunter.workers.dev/info.json — that proxies a private GitHub release feed.

From a user's perspective:

• New versions appear under Plugins → Installed Plugins with the standard "Update available" notice
• WordPress shows the changelog in the View version details modal (rendered from the GitHub release notes)
• Clicking Update now downloads /download/plugin-vX.Y.Z from the Worker, which streams the ZIP from GitHub

You can override BCUI_SYNC_UPDATE_URL in wp-config.php if you ever need to point at a staging Worker (rare).

Security model

The plugin only ever calls one server endpoint with the key (GET /api/public/projects/{id}). That endpoint returns project tokens — no user data, no billing data, nothing else.

Troubleshooting

Advanced: pointing at a custom dashboard

The plugin defaults to https://breakcolorui.com. In dev / staging / local environments (anything wp_get_environment_type() reports as local, development, or staging), an extra Advanced settings disclosure appears on the settings page where you can point at a different host — e.g. http://localhost:3002 for local Next.js development.

The setting only appears outside production, so end users on a real site never see it. Override BCUI_SYNC_DEFAULT_API_URL in wp-config.php if you need to permanently retarget.

Next steps