WordPress Best Practices: Advanced Custom Fields & Atomic Design

In a previous post, we discussed our development of the Clarity Kit, which is our answer to the recurring challenges of updating and managing WordPress sites.

In a nutshell, we wanted to make sure everyone involved in a complex, CMS-based site can do their jobs without stepping on their colleagues’ toes:

  • Content editors can move page elements around easily without developer assistance, and no longer must style individual elements using HTML.
  • Designers can create a great-looking site with the assurance that the design won’t be compromised by a cascade of small-scale changes.
  • Developers don’t have to get bogged down in rebuilding pages every time a change is requested, and they don’t have to constantly clean up messy code that results from WYSIWYG editing tools.

In this post, we’ll pull back the curtain a bit on how we built the Clarity Kit, so you can apply the same principles to your own designs.

WordPress meet Atomic Design

The Clarity Kit is built using Atomic Design principles, the systems design approach developed by Brad Frost. Atomic Design is a way of applying a hierarchical logic to build systems of design components. The original naming convention for Atomic Design is loosely based on chemistry and biology—so the smallest pieces, which are HTML elements like buttons and fields, are called atoms. One level up are “molecules,” which combine atoms together—such as a form with a field, a title, and a button.

We liked the systems design approach, but thought the naming convention was limiting, so we updated it to the following:

  • Element: An HTML element such as an image or link
  • Group: A collection of elements, such as a CTA with a link and an icon
  • Component: A collection of groups, such as a navigation element or card
  • Module: A collection of components and groups that will span a page, like a blade or section
  • Layout: A collection of modules that will be re-used, such as a product page

For content editors, modules are the heart of the Clarity Kit. They are what is selected in the WordPress admin to compose a page. Modules can be combined in any order, which supports a high level of flexibility in page composition, but also limits how much customization can be applied, which maintains design fidelity and coherence. This is the best of all worlds, a system that allows flexibility while maintaining design integrity as the site grows and content is updated and added.

Harnessing the power of Advanced Custom Fields

On a technical level, our standard Clarity Kit implementation defines a module as a combination of Advanced Custom Field (ACF) groups and WordPress PHP templates. ACF is one of the most widely used plugins in the WordPress ecosystem and forms the backbone of the Clarity Kit. With default ACF, templates are the basic building block, but there is no defined naming convention or directory structure. There is also no inherent hierarchy to the ACF field groups. We’ve upgraded this to follow Atomic Design principles, which keeps the codebase structured and extensible.

The WordPress templates directory is divided into elements, groups, components, and modules. Each of these templates has an associated ACF field group. So, for example, a component such as a card would have an ACF field group ‘card’.

Card example

The card component is cloned into an ACF module field group such as ‘cards grid’. The field groups are also organized using Atomic Design principles, following a naming convention that tracks to the hierarchy of templates.

In comparison to many page builders, there are substantial development benefits to this modular approach. Chief among them is direct access to the templates, which makes external integrations straightforward to accomplish. Need to integrate with your Salesforce account or inventory system? You’re working in standard WordPress templates using PHP and HTML, so any integration supported through the API will be possible.

WordPress Page Builder Drawbacks

Another drawback of many page builders is the use of custom, tool-specific CSS frameworks.  This is problematic if your company has already developed an internal CSS framework or standardized on one of the popular frameworks. The default Clarity Kit implementation uses Bootstrap but can be modified to use other popular or internal frameworks.

The module system is a great solution for sites with varied and growing content requirements, but some pages are ultimately one-offs that will not be re-used throughout the site. For these pages, we take a more standard approach to WordPress development and create custom page templates. The combination of custom page templates and the module system is the secret sauce that helps Fell Swoop WordPress projects offer clients a high degree of flexibility, maintainability, and design integrity.

For examples, take a look at the websites of PCC Community Markets and Juno Therapeutics. These are sites with wildly differing requirements and quite distinct looks. What they share is that, behind the scenes, the people who are updating and maintaining them are focusing a lot less on plumbing and a lot more on using their creativity to deliver a great user experience.

Waiting for Godot, er… Gutenberg

The new WordPress editing experience, Gutenberg, has been in development for years. And while we’re generally encouraged by its intent, its still in beta form so our testing of how well it aligns with our Clarity Kit approach is incomplete. We’ll circle back soon on our findings.

Want to learn more? Give us a shout.


Like what you see?

We’re always looking for interesting challenges and ways to provide value.
Contact us today and let’s talk about what we can do for you newbusiness@fellswoop.com