WordPress block editor and headless mirroring

Superfunky uses WordPress as the editorial and design control plane while the headless storefront owns application routing and interactive commerce. This page explains which native block-theme settings cross that boundary, how they are delivered, and when a rebuild is required.

Rule of thumb: use the Site Editor and block editor for content and WordPress design tokens; use Layout Studio or source code for storefront application chrome and component behaviour.

Source of truth

• WordPress content: page and post blocks, rendered HTML, featured media, captions, alignment classes and safe inline style attributes.
• Site Editor: saved global styles from wp_global_styles, merged with the active theme’s theme.json.
• Control Center: storefront branding, layout, commerce presentation, custom CSS and operational settings.
• React storefront: routes, application components, checkout/account/community behaviour and hydration.
• Static build: the publish boundary that snapshots all public content and mirrored design data.

Site Editor settings mirrored to React

The backend reads WordPress global settings and styles through wp_get_global_settings() and wp_get_global_stylesheet(). The storefront receives a typed themeStyles payload and applies it before content becomes visible.

• Colour palette presets and their CSS custom properties.
• Font families, locally served font-face rules and font-size presets.
• Gradient presets and spacing-size presets.
• Global element typography for headings, paragraphs, links, buttons and captions.
• Content and wide layout sizes used by constrained, wide and full-width blocks.
• WordPress Additional CSS plus Control Center custom CSS.
• Core block-library and block-theme stylesheets, followed by Superfunky compatibility CSS.

Changes made in Appearance → Editor → Styles are therefore reflected in generated storefront pages after a successful storefront rebuild. The build emits one hashed WordPress stylesheet and loads it render-blocking to avoid a style flash.

Block editor content mirrored to React

• Core paragraphs, headings, lists, quotes, code, tables, separators and spacers.
• Groups, rows, stacks, grids, columns and mobile stacking.
• Wide/full alignment, constrained content, covers, media-and-text, galleries, images, captions and embeds.
• Button styles, WordPress preset classes, custom anchors and internal links.
• Reviewed Custom HTML styles and scripts when the corresponding content-script setting is enabled.
• Superfunky shortcodes, rendered by the same bounded shortcode registry used during static generation and hydration.

Rendered block HTML is sanitized without removing WordPress layout semantics. CMS links pointing to the backend are mapped to the public storefront when they represent content; admin, REST, GraphQL and media application URLs remain native.

What remains frontend-owned

• The React header, footer, drawers, search overlay, cart, account, checkout and community application templates.
• Layout Studio choices for application component placement, mobile navigation dimensions, overlay search and code controls.
• Interactive state, API calls, filters, pagination, product variation selection and authenticated actions.
• Provider-specific deployment settings and environment variables.

Site Editor template parts are used by the native WordPress preview path. They are not copied as arbitrary PHP templates into React. Headless header/footer links come from the assigned WordPress menus; their visual presentation comes from Layout Studio and Control Center settings.

Headers, footers, and navigation

• Assign menus to Header, Mobile and Footer locations in Appearance → Menus.
• Use absolute backend content URLs or root-relative public URLs; the storefront normalizes content links to the frontend origin.
• The configured WooCommerce shop page, privacy page, terms page and authentication pages are resolved through the shared special-page registry.
• Menu CSS classes can opt items into mega-menu and expanded descendant behaviour.

CSS, Tailwind, and style order

The public cascade is deterministic: WordPress block CSS, font faces, Site Editor global styles, Additional/Control Center CSS, then the block-compatibility layer. Static and hydrated CMS wrappers use the same utility classes so hydration does not reflow the page.

• Use WordPress preset controls when an editor should own the value.
• Use Additional CSS or Control Center custom CSS for reviewed site-wide overrides.
• Use the supported CMS Tailwind utility contract for content-authored utility classes.
• Change React source for application-component structure or utilities outside the CMS contract.

Scripts and plugin blocks

Core blocks that only need HTML and CSS work automatically. Third-party blocks that require PHP rendering, frontend JavaScript, plugin CSS or browser globals need an explicit compatibility path.

• Bundle reviewed behaviours in the storefront when possible.
• Enable trusted Custom HTML scripts only for the required post types.
• Scripts are made inert in server HTML, HTML entities are decoded, and execution happens through the contained CMS script runtime.
• One failing CMS script reports an error without stopping the rest of the page. HTML responses embedded as JavaScript are rejected.

Preview and publishing workflow

1. Edit blocks or Site Editor styles in WordPress.
2. Use WordPress Preview to inspect the mirrored native theme without publishing static files.
3. Publish the WordPress content when editorially ready.
4. Click Rebuild storefront in the top admin bar.
5. Wait for the deployment status badge to succeed, then verify the public URL in a private browser.

Artifact invalidation may happen automatically, but static-first public HTML changes only at the explicit storefront build boundary. Visitors keep the previous known-good deployment until the build succeeds.

Troubleshooting

The editor looks correct but the storefront does not

• Confirm the latest storefront rebuild succeeded and the public page uses the expected build timestamp.
• Check that the block uses core markup or has a reviewed plugin compatibility path.
• Inspect Additional CSS for backend-only selectors and fixed widths.
• Confirm the page’s static hydration and WordPress stylesheet assets return HTTP 200.

Styles shift during hydration

• Static and hydrated content wrappers must remain identical.
• Do not defer the hashed WordPress stylesheet.
• Ensure custom font files and CSS URLs are publicly reachable.
• Check for CMS scripts that rewrite layout after page readiness.

Internal links open the backend or wrong page

• Use normal WordPress page links instead of hard-coded admin URLs.
• Assign the real shop/legal/auth pages in WordPress and WooCommerce.
• Rebuild after changing special-page assignments or menu locations.

Acceptance checklist

• Desktop and mobile block editor previews match the public content structure.
• Home and representative pages retain their title, H1 and full-width sections.
• Header, mobile and footer menus point to the public frontend.
• Products, posts, authors and taxonomies keep their layout after hydration.
• Custom CSS and fonts load before the page is revealed.
• Shortcodes and trusted scripts work without console errors.
• A rebuild publishes Site Editor and block content changes; rollback restores the previous deployment.