6 Principles to follow when building scalable websites with Gutenberg

When we start envisioning a website, we’re faced with several decisions. What’s its purpose? What does it have to say? What does it look like? How does content appear?

These questions are a high-level look at the craft of web experiences. One of the key decisions we make early on, as developers, is the tech stack that drives the website. For marketing and primarily content-driven websites, we have to choose a content management system (CMS). This is an endeavor hard enough on its own, and we’ve learned a few things about it if you want to check out our CMS decision process.

9 Factors to consider when choosing the right CMS [2024]
It's not about choosing the 'best' CMS out there, but the one that fits your needs.

WordPress is one of the most popular CMS choices. Its open-source nature, large community, thriving plugin ecosystem, and comprehensive documentation make it a good choice for beginners and pros alike. One of the main differentiators of WordPress as a platform for marketing websites is Gutenberg.

Gutenberg is a Block editor experience that affords content editors the freedom to assemble, customize, and tweak their content. It’s akin to a website builder, built natively within WordPress.

Gutenberg and Blocks

When developers build marketing websites for a client or a project, the marketing team’s range of motion is usually quite limited: content editors are allowed to change URLs, text, and post content inside of a few, restricted fields.

While this is a good approach to ensure consistency and limit the potential for site-breaking events, it’s restrictive.

Content editors can’t easily add a new section to a website - not at least without requiring some design and development work beforehand. This means that, for example, adding a new banner with a call to action over the weekend is unfeasible - a scenario that’s likely to happen, eventually.

Marketing teams like the flexibility of WordPress to craft and publish content - why not have the same degree of freedom with the website itself?

Blocks are a game-changer when we think of scenarios like these.

Simply put, Blocks are the pieces of content that editors work with to build posts, sections, and pages. They are designed and developed beforehand to let editors work with them independently. Marketing teams can grab Blocks, infuse them with content, and change them according to their needs (including styling choices!).

While having specialized teams design and implement core Blocks is still a necessity, this means that marketing teams spend fewer hours requesting changes to their website, and make better use of their time by shipping the features they need immediately.

From a developer’s perspective

Blocks are the natural evolution of standard WordPress templates.

Traditionally, a WordPress-driven website entails a collection of templates that are designed and developed to expose a few features that are controllable by content editors - as we’ve seen earlier, only a few fields, usually.

This is fine for a website that doesn’t need to grow too much. However, things get more interesting from a scalability perspective. While a fixed paradigm can be replicated across several pages, it’s not easily adaptable to accommodate changes. It’s often hard to extend with new sections, layouts, and content types. It cuts editing freedom for marketing teams.

Blocks, however, allow all this freedom, and then some. As they are built from the ground up by developers, they can be tailored to a website’s design, business logic, and specific needs that the marketing team may have. They can be either as restricted as a standard WordPress template, or as flexible as to allow editors to change their content, layout, colors, typography, etc.

It’s the developer’s job to adapt a design system’s artifacts into Gutenberg.

Developers author new Blocks, which are comprised of a front-end interface (what is displayed on the shipped website), and an Editor interface (the controls that the marketing team interacts with on the WordPress back-office).

As Gutenberg uses React for its Editor interface, developers can leverage modern JavaScript web development techniques with the tried-and-true WordPress PHP approach for the front-end portion of the Block. This process is left to the development team’s judgment about the project’s requirements.

Our latest WordPress-driven marketing website for Veza allowed us to collect our thoughts about how to design and implement a stellar Editor experience for marketing teams - or at least one that doesn’t limit their freedom. Check out our Veza website case study to learn more about how WordPress and Gutenberg were a major asset.

From the Veza website project, we derived six principles to craft Gutenberg Blocks to empower marketing teams with the freedom to build flexible, customizable, and scalable websites. 👇

1. Composable

A Block may be something as simple as a heading, or as complex as a grid of cards with images, links, and other sources of content. WordPress already comes with a healthy set of Blocks that cover the basics.

As Blocks can contain other sub-Blocks, it’s interesting to assemble them in different arrangements to create elements of a website’s design system on a page. However, if the developer had to build every single item of a section by hand, websites would take years to develop.

Composability is the idea of reusing what WordPress already offers out of the box.

While some custom logic may be required to build a custom Block - for example, a card that shows a location for an event or the author’s picture for a blog post - the developer doesn’t need to code headings, paragraphs, images, etc.

By reusing standard WordPress Blocks, developers are assured of a few things:

2. Contextual

One issue with customizable content is preserving the original design intent, carefully thought of and codified into a design system by design teams that work on website projects.

When content editors are tasked with authoring content and also deciding how it looks, we face issues, such as the look and feel potentially becoming compromised. Some pieces may not fit in correctly with others, leading to website-breaking situations where marketers just want to assemble some content and don’t have the freedom to do it properly.

Block-driven websites afford developers an excellent opportunity to conspire for content editors’ success - to make Blocks work correctly in their context.

Let’s take a look at the previous card example. Should content editors know exactly when a card has to show a post author’s picture and personal bio? Or that a button inside a banner should have a specific background? It’s not realistic to place these expectations on the editors, yet a lot of websites add this overhead to marketing teams by creating more decision paths.

Developers can simplify editors’ lives by using context when developing Blocks. If a given set of rules is present in the website’s design system, the developer makes the behavior work within the Block. If a card only shows certain fields for a given category, don’t make the content editor have to worry about this and ensure that the proper content is shown.

Some advantages include:

3. Customizable

On one hand, we want editors to be able to do their job without thinking too much about the design system, on the other hand, there are scenarios where an “escape hatch” is desirable.

Marketeers need the freedom to, sometimes, customize a Block visually. What can be changed?

WordPress allows a surprising amount of freedom - colors, typography, spacing, Flexbox-based layouts (for marketing teams with CSS chops), and even full gradients. As Gutenberg lets developers build custom interfaces to control the Block’s behavior on the site editor, having these features available at no extra development cost is a significant time-saver when building customizable components.

Developers can enable customization features selectively. This is important to ensure that some degree of cohesion is respected. Some marketing teams have designers and branding experts who can work these features into beautiful content. Other teams just need to be able to change between pre-selected colors to whip up something that looks presentable.

As the saying goes, “With great power comes great responsibility”.

4. User-Centric

Some Blocks are more complicated than others. Developers can build an editing experience that makes content authoring a breeze by making use of wizards and micro-tutorials which enhance the editor experience.

Instead of, for example, exposing several fields for a given Block and letting the user poke around to make it work (on a mere trial and error basis), a better approach is to guide the user step-by-step through the Block creation process.

Adding a block to the page with a built-in wizard to help the editor assemble complex behaviors.

Gutenberg makes developing these interfaces easier by using its own internal React component library, which has all the primitives needed to let developers build supporting user interfaces to aid a Block’s creation process with surprising speed and ease.

The content editor only has to follow through a few steps. The code behind the scenes works to set up the block correctly, which saves the editor precious configuration time. The complexity of configuring a more complex Block is abstracted away to the background, allowing once again more focus on delivering and shipping, which all marketing websites benefit from.

5. Self-explanatory

Another way of lending a helping hand to the content editors is by providing highly contextual and relevant information.

Say, if a Block is only displayed on the website’s front end if a certain set of conditions is met, there’s an opportunity to inform the user that, if those conditions aren’t met, nothing will happen. Nothing is more frustrating than expecting something to happen and not getting any useful feedback when it doesn’t happen.

Developers can build Blocks that make use of warnings, callouts, informative bullet points, and other kinds of interfaces that augment the editor experience. Gutenberg also lets developers make this self-explanatory information appear only when needed, as it is dynamic and responsive to user input. If, for example, only five posts are allowed to be visible on a given list, the user will be notified of this once the limit is reached. However, if there is no need to display a warning or overload the user with information, nothing appears.

This is a wonderful way to make the editor experience easier to understand and more intuitive for editors:

6. Bespoke

Last but not least, Gutenberg Blocks empower developers with the freedom to build entirely custom business logic and bespoke features for specific use cases.

Some features represent tremendous effort from designers and developers alike: animations, interactive visuals, and complex visual information arrangements are the usual suspects. These kinds of creative development tasks take up the most time in website projects. While they add tremendous amounts of value to a website, they also come with a significant caveat: most of the time, they’re not easy to tweak and customize in response to emerging needs.

For example, animated content that involves text is usually a place where marketing teams need the freedom to tweak, improve, and refine the copy. Usually, this means there’s a dependency on the development team anytime changes are needed - from changing custom code to shipping a new website version, thus reducing the marketing team’s independence.

It should be noted that developers can implement interfaces to make these edits possible, at the cost of a significant expense in complexity and time.

Gutenberg, with its built-in controls and modern JS-powered techniques, makes this job far easier for developers. Block controls let editors do things like tweak an animation’s copy, an organization chart’s connections and content, or switch up an infographic’s set of data - while making the interface markedly easier to build for developers.

Building bespoke Blocks brings bountiful benefits:


Gutenberg is an excellent platform to build customized, atomic websites that embody scalability, flexibility, and customizability.

Blocks represent a paradigm shift towards making marketing teams’ lives easier by letting them do their job with fewer dependencies. From a development standpoint, Blocks represent an opportunity to make websites that are more helpful to their maintainers, more flexible to change and client needs, and more scalable than ever before.

When translating design systems into code, developers have several decisions to make that will affect the editor experience in several ways. Our responsibility is to build stellar editor experiences.

These six principles are a starting point derived from our experience, to be expanded and iterated upon as the needs of marketing teams evolve. By focusing on ease of use, speed, and scalability, Gutenberg empowers WordPress website developers to ship websites faster.

In turn, marketing teams appreciate the freedom and manage websites more expertly, unencumbered by dependencies on designers and developers alike. Our work shines brighter from this collaboration. ✨

João P. Marques
Creative Developer