Creating a Design System for WordPress

A good design system leads to an aesthetically pleasing product. It saves time and money by making it easy to implement and scale. WordPress makes it easy to implement a design system by giving developers ready-to-use tools and techniques to implement things such as:

1. Styles guides
2. Pattern libraries
3. Component libraries

In this section, we shall mainly look at creating style guides for WordPress which are easily translatable into code.

For the sake of cohesion with WordPress, we shall use the term ‘block’ instead of component from here on.

Creating a style guide using theme.json

The equivalent of a visual style guide in WordPress is a file called theme.json. It is commonly used to:

• Define global styles and settings for the theme
• Control block-level defaults and variations
• Set up color palettes
• Set up typography
• Set up layout properties and spacing presets
• Set up site-wide CSS

Defining global styles and settings

Most commonly, the theme.json file is used to set up styles and settings that are shared across the website. It lets developers create a define-once-use-anywhere configuration that users can choose from when using text, images, sections, etc.

Setting up typography using theme.json

Theme.json supports extensive typography configurations. Using this file, developers can configure font families, font sizes, line heights, and weights to be used across the website or on certain blocks.

Figure 2.1 shows an example of two font size variations and their code-equivalent. 

Establishing color schemes using theme.json

Colors give life to the design and the theme.json file ensures that developers can codify the colors that a designer has selected. We can add as many variations as possible, such as primary, secondary, tertiary, accent, and functional colors. We can also add gradients and duotone filters using the theme.json file.

Figure 2.2 shows different types of colors and their code-equivalent. 

Configuring layouts using theme.json

In the theme.json, we can also define the basic layout configurations such content width, wide width, and default block alignments. These layouts can be used globally as well as for an individual block.

Figure 2.3 shows how these settings look on the editor side. These settings can be accessed using Site Editor > Styles > Layout.

Defining spacing presets using theme.json

Using theme.json, we can define different types of spacing we want to use in our theme. These spacings can be inter-component and intra-component. For example, in Figure 2.4, we can see three spacing variants being used between three different headings (inter-component). 

We can also define margin and padding presets to be used in the design. This makes it easier for the user to quickly and consistently add spacing, margin, and padding.

Customizing block defaults and variants using theme.json

Often, we want the blocks (core and custom; read more about core blocks here) to look a certain way. For this reason, we may want to modify their default appearance or add additional variations. This can be achieved using the theme.json. 

We can:

• Set default styles for core blocks (paragraph, heading, list, etc.)
• Define custom styles for theme-specific blocks
• Create block variations for common use cases
• Configure default block spacing, margin, padding, and alignment

In Figure 2.5, we can see that we have two variations for the core button block: fill and outline, and the code-equivalent. We have modified the fill variant to have the “Heading” font family and letter spacing of 0.2rem. On the other hand, the outline variant retains the default font family but has a border width of 1px.

Creating a WordPress-friendly Design System

A design system that can be easily translated into a WordPress block-based site not only ensures beautiful and consistent experiences, but also saves a lot of effort and time during development.

Let us understand how we can combine WordPress blocks and some fundamental design philosophies to create efficient and effective design systems for WordPress Block Editor.

Understanding core blocks in WordPress Block Editor

WordPress ships with a variety of blocks, called core blocks. There are more than 100 core blocks available for the user to choose from and more blocks can be added using plugins (block libraries) and by developing custom blocks.

Core blocks can be modified in two ways:

1. Logical modifications (extensions)
2. Stylistic modifications (customizations and variations)

As designers, we may wish to change both. Hence, it is important to understand what WordPress ships with natively. This reduces development time and effort.

Following are some of the commonly used blocks:

Heading

Heading blocks can be used to add headings (obviously) ranging from H1 – H6 levels. Each of these levels corresponds to the HTML heading element (h1-h6).

Figure 2.6 shows the default heading styles that ship with the Twenty Twenty Four theme.

Some common modifications for heading block are (but not limited to):

1. Font family
2. Font size
3. Font weight
4. Font color

Paragraph

Paragraph blocks can be used to add normal text to the website. Figure 2.7 shows a default paragraph block. 

A paragraph block supports rich text formatting, so users can format text, add links, etc. 

Following are the common considerations:

1. Font family
2. Font sizes
3. Link (Anchor) design
4. Font weight

Image

Button

Creating modular design elements for WordPress

• Create a library of reusable components and patterns
• Design with block-based structure in mind
• Develop a system of micro-components that can be combined into larger patterns
• Consider how components can be nested and reused across different contexts

Achieving consistency in WordPress design systems

Consistency is important for any design system. A big advantage of a consistent system is that a major part of the UI work is already solved. It can simply be handed over to new developers and designers and they can continue working with utmost efficiency.

There may be a few inconsistencies here and there to spice the design up a bit, but holistically, a design should be consistent, not only within itself but also with standard guidelines and design principles.

We recommend the following guidelines to achieve consistency:

• Ensure cohesive styling across various page types (home, archive, single post, etc.)
• Use global styles to maintain consistency in typography, colors, and spacing
• Design flexible templates that can accommodate different content types
• Create a set of reusable block patterns for common page sections
• Keep the set of configurations limited

Balancing flexibility and brand consistency

• Allow for customization while maintaining brand identity
• Use locking options to prevent unwanted changes to crucial brand elements
• Provide a range of pre-designed variations that align with brand guidelines
• Create clear documentation on how to use customization options within brand parameters

Nomenclature and organization in WordPress design systems

For a design system, it is crucial to establish a clear naming convention in the design system. A well-defined nomenclature helps designers and developers use consistent terminology across design and codebase. It also helps developers organize theme.json sections logically.

The key to having a good naming system is to document the purpose and usage of each token. For WordPress, we recommend using kebab-case. Usually, we follow the category-concept/property-variant naming convention.

Following are the common set of guidelines to follow while naming the tokens:

Be descriptive

Use informative names, reflecting the purpose of the token. Avoid using generic names such as “color1”.
Bad: xs-h (does not reflect the purpose; no information at all)
Good: gap-horizontal-xs (provides all the information needed)

Maintain consistency

Even if you prefer a different naming convention, it is important to keep the token names consistent throughout the design system.
Bad: color-form-green / color-error (there’s no consistency across the concept in which the token is to be used)
Good: color-feedback-success / color-feedback-error (indicates the concept very clearly)

Make it scalable

Consider how your names scale as your design system grows. Avoid using names that are specific to a project or component.
Bad: rtcamp-rtblock-bggradient (can only be used for  rtblock)
Good: background-gradient (can be used across the project)

To learn more about tokens and how to name them, you can check out this article. 

Designing layouts in WordPress Block Editor

Designing layouts for Gutenberg-based themes can be make-or-break. It is important to know the built-in layout blocks to aid your design thinking.

Built-in Layout Blocks

It is good to know the layout blocks which ship with the block editor. These blocks can be used to create a variety of layouts. Following are the default layout blocks which can be used in your design:

Group

The Group block is used to combine multiple blocks inside one container so that you can set container-level properties such as background color, padding, and margins. It also supports block spacing, and can be used to organize different sections.

Figure 2.10 shows a group block which groups together an image and a quote. You may observe that there is a padding within the section and a background color.

Stack

The stack block can be used to align its children (inner blocks) vertically.

Figure 2.11 shows a stack with two Quote blocks.

Row

The row block is a variation of the stack block with its children aligned horizontally.

Figure 2.12 shows a row with two Quote blocks.

Grid

Grid block offers fixed width columns and multiple rows arranged in a traditional grid layout with usual functionality such as column and row spanning.

Figure 2.13 shows an auto-arranged grid block without any column spanning.

Columns

The columns block can be used to display content in multiple columns. There are multiple default layout options available such as 50/50, 33/33/33, 25/50/25, etc. It is possible to set the column widths manually.

Figure 2.14 shows columns block with 33/66 layout.

Content Adaptability

Creating layouts that adapt gracefully to different content types is crucial for WordPress block themes. Let’s explore how to achieve this effectively.

Design Flexible Grids

When designing grids, consider both minimum and maximum content scenarios. Figure 2.15 shows how a three-column grid adapts when:

• One column has minimal content
• Another has extensive content
• The third has average-length content

The key is to establish rules for:

• Minimum column heights
• Content overflow handling
• Equal height columns vs variable height
• Grid gap consistency

For example, a services grid might need equal heights to maintain visual harmony, while a blog post grid could allow variable heights for content flexibility.

Using Blocks for Complex Arrangements

The combination of Group and other layout blocks offers sophisticated layout control in WordPress. Each layout block serves distinct purposes and can be nested strategically to achieve complex designs.

Group Block Combinations

• Nest Groups for layered backgrounds and overlays
• Create card-like components with consistent padding
• Build hero sections with overlapping elements
• Establish content width constraints within full-width sections

Stack Block Applications

• Organize related content vertically with consistent spacing
• Create feature lists with aligned elements
• Build form layouts with uniform spacing
• Structure article content with predictable vertical rhythm

Row Block Usage

• Arrange elements horizontally with flexible spacing
• Create inline navigation elements
• Build pricing comparison tables
• Design feature highlights with icons

Grid Block Implementation

• Display product galleries or portfolios
• Create masonry-style layouts
• Design team member showcases
• Structure dashboard-like interfaces

Cover Block Integration

• Layer text over background media
• Create parallax-style sections
• Build full-screen hero areas
• Design promotional banners

Advanced Combinations

• Stack + Group: Create sectioned content with consistent spacing
• Grid + Cover: Build media-rich galleries with overlaid captions
• Row + Stack: Design hybrid navigation patterns
• Multiple Groups: Create depth through layered backgrounds

When combining blocks, consider:

• Block nesting depth limitations
• Performance impact of complex arrangements
• Maintainability for content editors
• Responsive behavior of nested structures

The key to successful complex arrangements is understanding each block’s strengths and combining them purposefully rather than arbitrarily nesting blocks.

Vertical Rhythm System

Establishing consistent vertical rhythm requires:

1. A base spacing unit (commonly 8px or 16px)
2. Spacing scale multiples (1x, 2x, 3x, etc.)
3. Standard spacer blocks at common heights
4. Consistent use of margins and padding

For example:

• Small spacing (1x): Between related elements
• Medium spacing (2x): Between different elements
• Large spacing (4x): Between major sections

Design tokens in the system

There are a lot of commonalities between a designer’s design system and developer’s theme.json. Knowing what all could be defined in your design system which developers can readily use saves time and effort.

Color palette

The theme.json supports as many colors as the design system needs, but this does not mean we can bloat it with colors that are not used or that should not be in the file.

Following is the list of color definitions a design system should have: 

1. Primary, secondary, tertiary and accent colors
2. Text and background color combinations
3. Feedback colors: info, success, warning, error

An important consideration while designing the palette is to keep the colors (and color combinations) accessible. A designer should aim for WCAG Compliance of at least AA. Also, WordPress supports gradients in the theme.json file, so feel free to add gradients to the design system.

One of my favorite examples for a styled system palette is Chakra UI’s default color palette. Figure 2.16 shows the gray swatch ranging from 50 (lightest) to 900 (darkest). 

Typography

WordPress’ theme.json also supports typography. We can add font sizes, font weights, font families, etc. 

Following are the typography-related settings a design system should have and theme.json supports.

1. Heading and body text styles
2. Font size and line height scales
3. Font weight variations
4. Special typography styles (e.g., for quotes, captions)
5. Responsive typography settings (see: Handling Responsive Designs)

Some users may be accessing the website in languages like Arabic, therefore it may also important to add support for text directionality, i.e. RTL / LTR.

Figure 2.17 shows a simple typography scale ranging from small (S) to extra large (XXL). You may notice that we are not using pixels (px) but instead we use rem (16px = 1rem); however, this is not a requirement for theme.json, it supports all the units.

Spacing

For consistent spacing, a design system needs consistent spacing. WordPress also supports spacing tokens in the theme.json.

We can add following tokens in our design system:

1. Spacing values
2. Margin and padding values
3. Inter-block gap

A designer should aim to have consistent spacing throughout the design system. Spacing scale can either be additive or multiplicative. We can define the addition/multiplication factor, the medium value, number of steps, and unit.

In Figure 2.18, you can see a multiplicative spacing scale. The scale values are: 0rem, 0.13rem, 0.25rem, 0.5rem, 1rem, 2rem, 4rem, 8rem.

In Figure 2.19, you can see an additive scale. The scale values are: 0rem, 1rem, 3rem, 5rem, 7rem, 9rem, 11rem, 13rem.