Preview vs Reality: The Block Editor's Identity Crisis

"This looks nothing like what I built in the editor."

The client's content manager was sharing her screen, showing me a beautifully crafted page layout in Twill's block editor alongside the completely different-looking frontend that had just gone live. The spacing was wrong, the typography didn't match, and the carefully arranged visual hierarchy had been flattened into a generic blog post layout.

"Did something break during deployment?" she asked.

I stared at both versions—the polished preview in our editor and the bland reality on the live site—and realized we'd built a CMS with multiple personality disorder.

The WYSIWYG Lie We Told Ourselves

When we designed Twill's block editor, we made a decision that felt obviously correct: make the editing experience look as much like the final output as possible. WYSIWYG (What You See Is What You Get) was the gold standard, right? Content creators should be able to see exactly what they're building while they build it.

So we invested heavily in making our editor previews beautiful. Rich typography, accurate spacing, proper image sizing, color-accurate backgrounds. The editing experience felt sophisticated and professional—like using a high-end design tool instead of a traditional CMS.

The problem was that we were showing people a fiction.

The editor preview was rendering content using our carefully crafted admin CSS, optimized for the editing experience. But the frontend was using completely different stylesheets, optimized for performance, accessibility, and responsive behavior across dozens of devices and browsers.

Those two CSS systems had different priorities, different constraints, and—inevitably—different visual results.

The GitHub Issues That Revealed the Truth

Within six months, our most persistent support requests all had the same theme:

"Block editor preview doesn't match frontend output" (Issue #124)

"Typography in editor vs site is inconsistent" (Issue #201)

"Image sizing works in preview but breaks on mobile" (Issue #289)

"Editor shows perfect spacing but frontend is cramped" (Issue #367)

Each ticket was a small tragedy of broken expectations. Content creators would spend hours perfecting a layout in the editor, only to discover that the live site looked completely different. They'd adjust content based on how it appeared in our preview, making decisions that were wrong for the actual user experience.

The worst part was that both versions were "correct" within their own contexts. The editor preview accurately reflected how content would look with admin CSS. The frontend accurately reflected how content would look with production CSS. They were just two completely different visual systems pretending to be the same thing.

The Nike Reality Check

The breaking point came during a major campaign launch for Nike. Their creative team had built an elaborate landing page using Twill's block editor, carefully balancing image sizes, text positioning, and white space to create a specific visual narrative.

The preview looked stunning—magazine-quality layout, perfect typography hierarchy, images that told a cohesive brand story.

Then we deployed to production.

The frontend used Nike's design system, which had different font stacks, different spacing scales, different responsive breakpoints, and different image optimization settings. What looked like a carefully crafted visual story in the editor became a generic content dump on the live site.

"This isn't what we designed," their creative director said during our post-launch review. "We spent weeks perfecting this in your editor, but none of that work translated to the actual website."

She was right. We'd given them a design tool that couldn't actually control the design. We'd shown them a preview that bore no resemblance to reality.

The Impossible Balance

The core problem was that we were trying to serve two masters with incompatible needs:

Content creators wanted predictability: When they arranged content in the editor, they wanted to know how it would look to end users. They needed to make decisions about content hierarchy, image selection, and text flow based on visual feedback.

Developers needed flexibility: Frontend implementations had to work across devices, meet accessibility standards, integrate with existing design systems, and perform well under real-world conditions.

These requirements were fundamentally at odds. A preview that accurately reflected responsive behavior would be too complex for content editing. A preview optimized for content creation couldn't accurately represent frontend constraints.

Our attempts to split the difference satisfied neither group. Content creators couldn't trust the preview to make good content decisions. Developers had to constantly debug why editor layouts broke on the frontend.

The Configuration Nightmare

Our first fix was to make editor styling configurable. Let developers import their frontend CSS into the editor preview so the two would match perfectly.

This created new problems:

Performance disaster: Frontend CSS was optimized for public sites, not editing interfaces. Loading it in the admin made the editor slow and bloated.

Responsive chaos: Frontend CSS assumed specific viewport sizes and device contexts that didn't exist in the editing interface. Mobile-first CSS broke desktop editing workflows.

Conflicting styles: Admin interface styles clashed with frontend styles, creating visual bugs and broken layouts in the editor itself.

Maintenance nightmare: Every frontend CSS change required testing in both the public site and the admin editor, doubling the QA overhead.

The OpenAI project made this painfully clear. Their design system was built for high-performance public pages, not content editing interfaces. When we tried to use their CSS for editor previews, the editing experience became so slow and buggy that content creation was nearly impossible.

The Mental Model Shift

The solution came from changing what we were trying to accomplish. Instead of making the editor look exactly like the frontend, we focused on giving content creators the information they needed to make good decisions.

Content structure over visual design: The editor preview showed content hierarchy, relative sizing, and layout relationships without trying to match exact typography or colors.

Responsive indicators: Instead of showing how content would look on every device, we added simple indicators for content that might have responsive behavior.

Frontend preview integration: Built tools that let content creators easily preview their work on the actual frontend without leaving the editing workflow.

Layout validation: Added warnings when content arrangements were likely to cause problems on the frontend (like text that would be too long for mobile, or images that wouldn't work at different aspect ratios).

Style-agnostic editing: Designed editor interfaces that focused on content relationships rather than visual styling, so creators could build effective layouts regardless of how they'd be styled.

What Actually Worked

Honest previews: We stopped pretending the editor could show exactly what the frontend would look like. Instead, we showed a consistent, functional representation that helped creators understand content structure and flow.

Quick frontend access: Added one-click preview links that opened content in the actual frontend context, so creators could see real results without leaving their workflow.

Layout guidance: Built tools that warned about potential responsive issues, content length problems, or styling conflicts before they became frontend problems.

Template consistency: Created block templates that worked reliably across different design systems instead of trying to make every custom layout perfectly previewable.

Content-first design: Encouraged content creators to focus on information hierarchy and user needs rather than pixel-perfect visual control.

The Lesson About False Promises

The block editor identity crisis taught me that WYSIWYG is often a lie, especially in systems where content and presentation are truly separated. The goal shouldn't be to make editing look exactly like the final output—it should be to give content creators the information they need to build effective user experiences.

Users don't need perfect visual previews. They need reliable feedback about whether their content decisions are working. They need to understand how their choices affect the final user experience, even if they can't control every visual detail.

The most dangerous kind of preview is the beautiful one that bears no resemblance to reality. It encourages content creators to make decisions based on false information, leading to frustration when their carefully crafted layouts fall apart in production.

These days, when clients ask about Twill's preview capabilities, we're upfront about what the editor can and can't show them. We demo the actual frontend preview workflow, not just the editor interface. We talk about the difference between content structure and visual styling.

It makes for less impressive demos, but much better content creation experiences. Because the goal isn't to show people a beautiful lie—it's to give them useful tools for creating content that works well for their actual users.

The best editor preview isn't the most visually accurate one. It's the one that helps content creators make decisions that improve the real user experience, even when they can't see exactly what that experience will look like.