Live Q & A: Design Systems and theme.json

One of the key challenges of running a site or series of sites at scale is ensuring design consistency and compliance with a design system. During this show, David Bowman, principal designer and Alec Geatches, JavaScript Developer, both at WordPress VIP will demonstrate the process to export the design system tokens from Figma and import to WordPress. Joni Halabi, Georgetown University, shared how her team at the university works within a different design system. The Panel also discussed WordPress as an enterprise-ready software and Gutenberg being a design system in the making. The show was hosted by Birgit Pauli-Haack, curator of the Gutenberg Times.

Shared Resources:



Birgit Pauli-Haack: Welcome, welcome to the 35th Gutenberg Times Live Q and A. Sorry. My name is Birgit Pauli-Haack, and I’m your host tonight, or this morning, depending on where you are. Thank you all for watching. It’s great to have you all. And today’s show, we will discuss how companies and institutions can organize the WordPress sites around established design systems in general. And then how to do this with Figma and WordPress theme.json. The folks of WordPress VIP team build a plugin for the workflow and we will see a demo of it. And later we’ll also hear how Georgetown University works with the design system. And then we’ll answer all your questions as well as mine. It’s the little privilege that I have.

So I’m thrilled to have these three experts on the show for you. It’s David Bowman, principal designer at WordPress VIP, and then we have Joni Halabi, senior developer at Georgetown University, and Alec Geatches, also JavaScript developer at WordPress VIP.

Alec Geatches: Hi.

Birgit Pauli-Haack: Hi, everybody. Glad you joined me here on this little show. We do proper introduction of course, in a minute. I have just a few housekeeping notes. The questions for those who are watching on YouTube, on the right hand side, you have a chat window, that’s where you can put your questions and also your comments. And then here on Zoom, we have the Q and A bubble on the bottom and the chat bubble to share your thoughts and questions. And please, please be kind, even if you disagree. This is a family friendly endeavor. And with that out of the way… I need to group… Yeah, so we’ll get into introductions. I have two questions for each of you. From where are you calling in today and what is your day job like? So David, do you want to start and then Alec and then Joni?


David Bowman: Sure. I’m calling in from northern Utah where I work from home here. And my day job, I’m a principal designer at WordPress VIP. That’s my background. I’m a graphic designer by trade, but have gotten into product design and web development via WordPress over the years. And now I work at WordPress VIP, focusing mostly on design systems and on how we can increase enterprises and big organizations to adopt Gutenberg and block theming, which I’m super stoked about.

Birgit Pauli-Haack: Yeah.

David Bowman: And I’ll pass… Should I pass to someone? I’ll pass to Joni.

Birgit Pauli-Haack: Yeah.

Joni Halabi: Oh, thanks. Hi everybody, my name is Joni Halabi. I’m calling in from the United States in the DC metro area. My day job, I am a senior web developer at Georgetown University, mostly working on WordPress customizations. And my specialty is custom block creation, so that is probably 80% of what I do.

Birgit Pauli-Haack: Mm-hmm. Excellent. And it’s up to you, Alec.

Alec Geatches: Hi, I’m Alec. I’m calling in from the States as well. I’m in Colorado. I work at WordPress VIP along with David, and I’m a developer. I’ve been a web developer for 10-plus years. Right now I’m working on a team that’s been focused on making the Gutenberg editor work better for enterprising companies. So that’s some of the stuff we’re talking about today, like design systems, how to integrate those with WordPress, editor curation, locking down the editor, things like that. And my team’s also done some work with decoupled slash headless WordPress as well.

Birgit Pauli-Haack: Awesome. Awesome. So cutting edge right there. Joni, and you also published on the developer blog about the difference between static blocks and dynamic blocks. And I think that was very helpful to a lot of developers who started out with Gutenberg development. Thank you so much for doing that.

Joni Halabi: Thank you.

Birgit Pauli-Haack: And Dynamic Blocks will get a little bit more promotion with the interactivity API, but that’s a different show. But that’s coming with 6.4, not 6.3, 6.4. So let’s get into the show. 

Finding and Working with Design Systems

For someone who’s a little bit not so in these big systems, what are design systems and how would you connect them? How do you find them and how do you work with them?

Alec Geatches: David was the first one to explain this to me, so I would defer to David.

David Bowman: I’ll try to be brief. I have a tendency to ramble and get lost in my thoughts when I’m talking about design systems, but the textbook definition that I give everybody is that a design system, the purpose of it, is in a classical sense to speed application development. So it makes it easier for designers and developers to work together to build some software application. And there are three parts to it. There’s code, there’s code. So it’s usually a set of reusable components and styles and things. Usually lives in a package that developers pull into their project. There is a UI kit. In our case at WordPress VIP, that’s a big Figma library, a bunch of Figma files with components and styles and things that mirrors what exists in code. And then there’s documentation to explain how everything works together. Because it’s inherently complex, a lot of it needs explaining. We do our best to just make it all smooth and seamless, but at the end of the day, a lot of stuff needs to be explained, so there’s always a documentation component.

Those are the three bits. Classically meant for just speeding application development. I think what we’ll talk about today, and why I’m so excited about Gutenberg is that I think that Gutenberg adds content creators and page builders into the design system equation. So when you’re building a WordPress theme, you’re not really building a website. If you’re building a block theme, you’re building a tool that someone else is going to use to actually build the website. And so you have to include the content creator in the design system club, which I think Gutenberg blocks do pretty effectively. But yeah, that’s, I guess, how WordPress makes it a little different. That’s my answer. If you ask anyone, everyone has different opinions, but that’s mine.

Birgit Pauli-Haack: Yeah. Alec, Joni, do you have a different opinion? Do you want to add something to it?

Joni Halabi: Yeah, so at Georgetown, we’re building our own system of websites. We support just about 400 websites on our WordPress systems, and they fall under one of two different themes. But we built this design system… It’s a homegrown system that is inspired by atomic design, but we’re not using those atomic terms. So we came up with our own terms. So we have foundational elements, and then we have those come together to make blocks and those will come together to make page templates and so on and so on. And one of our goals at Georgetown is to really lock down our design system to be super, super hyper specific to the university because we have some very strict visual identity guidelines. We strive to adhere to WCAG 2.1, AA standards for accessibility. And we have a whole host of just interactivity opinions that we want to at least try to enforce across all of our websites.

So what we do on my team, I’m part of the web services team there, we are creating this system that’s going to be used by individuals across the university who are in charge of their own websites. And some of these people, they are pretty well versed in web technologies and some of them, they have day jobs, and this is something that they do on the side. And it’s part of that infamous, other duties as prescribed, sentence that we all see in our job descriptions. So we might have somebody working on their website for their office, and they don’t know HTML, so we’re trying to make things as easy as possible with our design systems.

Figma and Theme.json

Birgit Pauli-Haack: Yeah. But what you did on WordPress VIP was also to… You said the word Figma, which is a design system by itself where you can build them, and then you bridged it to… Because WordPress block themes have this theme.json, which is pretty much a machine readable code of design styles and settings pretty much. And how to get it from the Figma into a block theme or theme.json, so you can spin up new sites. Is that how I explained that right?

David Bowman: Pretty much, yeah. I think the way that, and I have a demo that I’ll show of exactly how this works, but the way that our design system workflow works, I think we’re similar to how you guys run, Joni, but at a much smaller scale, because we’re a company, but we only maintain really two marketing sites right now, some documentation sites, so it’s a much smaller footprint. But we know that there are organizations like Georgetown and like every other enterprise company out there that runs a significant web presence where they’ve got just a ton of stuff. There’s all sorts, and it’s all different. Everyone has their own special needs. And at the end of the day, something you said, Joni, that really struck me, was that at the end of the day, the people that are actually pulling the levers on the website might as well be bloggers.

They’re not some developer. A lot of times they’re doing it and they don’t want to, because they don’t have a lot of time, and they just want it to be easy. And that’s actually why I think WordPress is most viable as an enterprise product. I think WordPress is perfect for this, because it’s designed for bloggers, it’s designed to be easy, and at the end of the day, everyone at work, that’s what they are. They’re not all a bunch of fancy web experts. And Gutenberg really provides a way for us to deliver that design system to them in a way that they can actually make use of it. And I guess the way that we do that, our flow is that our designers make stuff in Figma. We are designing our blocks, we’re designing our page layouts, we design, pick our colors, design all sorts of things.

And then a large portion of that gets exported from Figma as something called design tokens, which is a fancy term in the design system world, and it’s a variable. You can basically think of it as a variable. If you want to be philosophical about it, it’s a design decision represented in a little piece of code, and it’s something like, “My brand color is red.” That’s how you would say it in words. And a bunch of those get exported from Figma to a code base in GitHub where we store our design system. And then that gets further exported from the design system down into theme.json in our WordPress applications. And the introduction of theme.json, is like, I can’t overstate how revolutionary that was for WordPress applications.

I say all the time that Gutenberg is a design system, and it hasn’t realized it yet. It’s in its teenage years, it’s still coming of age and finding itself, and give it another five years and it’s going to realize what it is, it’s design system. And that theme.json file is the config for your design system and gives you a landing place for all of those design decisions that you’ve made. And because it’s all nice in code in a nice little json file, you can automate all that.

And that’s my litmus test for whether something is a, quote, real design system or not, is that if at any point of the step from designer thinks of something, developer builds it, content creator uses it, anywhere along that chain, if you have to rely on a human API to make sure something works, like if someone has to copy paste something or refer to a style guide or copy stuff out of an inspect mode and Figma, then it’s not a real design system. If you want to be real hard-nosed about it. But the goal is all the robots do the work for you, but theme.json lets you do that.

Joni Halabi: Yeah. If I can interject. To piggyback off of that. Theme.json was such a game changer for us, because… I alluded to this before, we really want to lock down our designs and out of the box WordPress, it gives you so many options in terms of color palettes and typography settings. I personally love that for a one-off site that is not affiliated with Georgetown. If I were to go and build a site, having that many options is great. Within the Georgetown universe, we don’t want that. We don’t want that. So being able to say, “I want to turn off custom palettes. I want to restrict the palettes to just our approved colors. I don’t want people to mess with the typography settings.” You get two choices for sizes. It has been absolutely wonderful. As soon as we saw that come into Core, we added it to our theme, and it was love, just love.

Theme.json or Classic Theme

Birgit Pauli-Haack: Are you using theme.json on a classic theme, or are you moving into block themes as well? So gradually?

Joni Halabi: So we’re currently using it on a classic theme, and this is a much longer story and probably a different talk. I did an experiment to see how easy it was to convert that classic theme into a block theme and also incorporate our design system, which uses external twig templates into that block theme. And it was an amazing experiment and a very complicated experiment, and I just spoke about that at a conference last week. So if anybody’s interested, you can follow me. I’m sure the video will be up in a month or so.

David Bowman: Oh, I want to watch that video. Absolutely. I want to watch that video.

Joni Halabi: Yeah.

David Bowman: It’s a real journey whenever someone embarks on that task. That’s a real quest.

Birgit Pauli-Haack: Yeah. I will do a switch from my site from a classic theme to a block thing I haven’t migrated yet. Although I’m talking with people about block themes since 2020, the first time about it, but I still haven’t done the switch yet. But talking about videos, I think, David, you have a demo for us, and I think that’s now a good place to play that and to talk about it afterwards.

Website Demo

David Bowman: Awesome. I will play this demo and… Yeah, it’s a… Oh, hang on, I got to share my sound. Can’t forget that one. Yeah, let’s play. It’s pretty casual demo, but it gives you a little taste of how we’re using this stuff on our websites with our WordPress theme and how we use blocks. Let’s start from the beginning. Here we go.

Hi, I wanted to give a quick demo to show you how we integrate Figma with our WordPress theme and how we use blocks as an extension of our design system. So here we are in Figma, and the foundation of our design system is our design tokens. And these mainly manifest in Figma as color and type styles, but we use a lot of other tokens in production for things like spacing, border radius. You use design tokens for all sorts of things. They have a lot of uses.

So using a common token structure between our applications is a big part of how our design system works smoothly and has good interoperability. And this here, what we’re looking at is the file that manages all the color and type styles that we use across our designs. And to link all these things up to our tokens and ultimately to our WordPress theme, our tokens live in GitHub, we use this plugin here called Token Studio. And this is a community created plugin, and it provides two main things for us. It gives us a way to push design changes from Figma here to GitHub, and it also gives us a way to manage design tokens that Figma doesn’t support right now. And it lets us do that within our design tool where we’re working on these things, and that makes the code a lot more accessible to designers.

So to demonstrate how all of this works, I’m going to show you how we can swap themes, and then I’ll show you what that looks like on the front end of an application and then what that looks like in the block editor. So we use themes and there’s a lot to this plugin. There’s videos, there’s documentation, there’s a lot going on here. There’s a lot going on here, but right now, this is the file that manages the styles for, and I’m going to go ahead and swap it for the token set for our other application, which you can see you swap it and it swaps out all the colors. So colors is the easiest place to see this change happening.

So there you go. So we’ve effectively swapped everything for a different set of tokens. So if we were to publish this library, it would update all of our designs with new values. So you can see how that switching works. And likewise, if a designer were to make a change to one of these, say they want to make the background color something else, they could make that change here, and then go ahead and push it up to GitHub. And from there we go to our tool, to the Design Bridge tool to get the tokens from the standard format in which they’re stored out into our WordPress theme. So I will show you that next.

So here we are. This is our design system repository that houses all of our tokens and then all the components of our design system for our React application, for our dashboard. So in terms of WordPress or WordPress applications, this just houses the tokens. Everything else in terms of components and things are the Gutenberg blocks. That’s all coming from WordPress Core, and then any custom block plugins that we’ve made. So what you’re looking at here, is this is how all of our design tokens are saved. So yeah, it’s a standard format. The W3C is working on a new web standard for design tokens, and this is what Token Studio outputs to GitHub. And you see that we’re able to alias between tokens. We have a core set that has all of our underlying color palettes and type scales and things, and we, from all those raw values, curate the values that are going to get used in our WordPress applications.

So you can see here our body one short style are these attributes that then get applied as CSS in our WordPress application. So this is how they’re stored. And in order to get things from here into theme.json, where they can be applied to our blocks, into our global styles, we created a tool called the Design Bridge. So I’m going to go ahead and I’m going to run it. It doesn’t look like a whole lot, but I’ll show you what it does on the other side. So it runs in the command line right now. And we did that so that people can automate this, you can work it into an existing dev workflow to just make it more flexible. It could run as a GitHub action. You can do a lot to automate this process.

But for right now, I’m going to do it manually. And all it does, is it takes two arguments. So it takes the token path, which is the path to where the tokens live, which is right here, what we’re looking at. And then it takes the path to the theme where it will look for a theme.json file, and then you pass it the value of a token theme. So these are things that Token Studio creates to tell it what token files to activate basically. And then you choose whether you want it to overwrite your existing theme.json file or not. And we’ll go ahead and hit enter. It will do its magic, and then it will tell you that it’s done. Say, “Hey, we did it.” So next we’ll pop over to pop to our WordPress application and see what that looks like.

So here we are in our theme.json file, and what our tool does, is it outputs all of our design tokens as variables in the custom object in theme.json. So if you’ve done any amount of theme.json work and working with global styles, you’ll know there’s this little custom object that sits inside of the settings object in theme.json. And this is just a blank thing that you can put whatever you want in. And everything that you put in here will be exposed to CSS variables along with any global styles that you are adding. So this has just been reformatted and output here into theme.json. And the format’s very similar. It’s not exactly the standard format, but it is pretty close. But it does go ahead and output the design system, essentially.

And so what this does is it exposes it in a predictable way in the DOM as CSS variables that are named according to the standard way that Gutenberg names all of its CSS variables. And that means that you can reference them in block development and you can point all of your blocks and all the work you’re doing to style your theme. You can point it at a constant set of variables that can be swapped out exactly the same way that we swapped out the styles and Figma, like I just showed you, you can do the same thing on a WordPress application.

Yeah, so I’ll show you what that looks like now. All right. So here we are. This is This is the website for our content analytics product at WordPress VIP. And this is one of the two web applications right now that we have running on our theme that is set up to integrate with our tool here. And as you can see, it looks all green and looks branded appropriately. And I’m going to go ahead and swap the tokens and you can see what happens when it does that. So I’m going to go ahead and run our sync and do it. And there you go. You can see what happens is it changes, you see font styles, you see colors changing. It’s not a huge change, because we haven’t designed it to be very divergent between the brands, but you do see the front end styles get swapped out and it works pretty well and makes it pretty easy to manage a multi-brand system of WordPress applications. And so next, let’s look at what this looks like in the block editor.

Okay, so now we’re in a local dev site here, and this for me is really where the magic and the value of this really happens. So this is a sample page and we’ve got this set up with our styles. We’ve got this set up to be pulling from the global styles we’ve defined, all the block styles we’ve defined. You can see in here we’ve got our pallets defined for this particular brand,, and these are coming from theme.json. And so if we go ahead and run the same sync… I’m going to run the sync and then refresh the page here. You can see what happens if I swap the theme from back to WPVIP. And looks like that sink is done. I’m going to refresh. And you see everything changed. Everything goes gold. You get the brand colors from VIP. And this stuff is achievable with CSS. You can swap out CSS styles, you can point at a different style sheet.

But I think what makes the integration in theme.json super valuable is that you get all of your block options are updated as well, because all of these are also coming from theme.json. So not only are you getting front end style updates, but you’re getting updates in interactivity in the backend, which is great. That’s really what you want to be able to make a good user experience and to be able to manage multiple user experiences and have it all get integrated easily with your design tooling. So yeah, there you go. That’s the high level, a lot of detail to talk about, but this is the quick rundown of what the tool can do.

Birgit Pauli-Haack: Excellent. Excellent.

David Bowman: There you go.

Birgit Pauli-Haack: Well, thank you so much for the demo. It’s kind of whose head is spinning, but I really love that flow from the designers work here, and then you can just write some script or run some scripts and then you have it all in the theme already. Does it also work backwards, or is it only one direction?


David Bowman: It’s bidirectional. What it does is it sets up… Our GitHub repo, our design system repo is the actual source of truth. And so that means that a developer can use an IDE to edit that code file and save it. Or a designer can use Figma to edit that same file and save it and its version controlled with Git and they can both pull down each other’s changes and it brings designers into an actual dev workflow on a design system. At least for the tokens. Just for the tokens.

Birgit Pauli-Haack: Just for the tokens, yeah. We don’t have any questions from the audience right now, but Joni, do you have any questions? Or David and Alec?

Joni Halabi: I don’t know where to start. 

Birgit Pauli-Haack: Are you muted or… No.

Opinions using WordPress

Joni Halabi: I was at a loss for words. It was a very cool demo. I’m very excited by that switch where both the front end and the block options change, because that’s something that could… So at Georgetown we have two different themes and they look pretty different. They’re similar in terms of colors, but not exactly the same, slightly different fonts, slightly different colors. And to be able to have the ability to switch between the two… Because we have a lot of sites who are wanting one theme over the other.

Birgit Pauli-Haack: Yeah.

David Bowman: I mean I have questions for you. I am extremely curious about… Because like I said, everyone does this their own way. Every organization that I know that has a design system… I think there’s a reason that every big company out there has made their own. Google made one, Amazon made one, Salesforce. They all make their own because they all do it differently. And so I guess, is WordPress your primary user facing surface that you’re maintaining or do you have other stuff? Do you have React applications or is it pretty much just WordPress sites?

Joni Halabi: For our team, it’s pretty much just WordPress sites. The history of our team, we’ve actually worked with a number of CMSs. I think this might be our fourth or fifth overall, but WordPress is our primary UI just because it’s a very easy UI, especially for those content editors who don’t have a ton of experience, it’s easy for them to pick up. And I feel like it’s gotten easier. I’m hoping it’s gotten easier since the classic editor. But yeah, I mean in the future, one of the big reasons why we created our own design system, we call it our pattern library, and the reason why that pattern library is external is in the future, if we do have some external application that we want to hook into or we have a piece of software like an LMS or something that will let us customize the front end, we can say, “Hey, you can go grab this twig file and there’s your custom header, or here’s your custom footer, or here is the color palette that we want this to use.”

We wanted something that was a little bit more universal and not necessarily in WordPress. So we built this pattern library. Actually my colleague was the one who really architected the entire thing. It’s built-in kss-node and it’s really slick. We can take those styles and take those twig files and import them into our WordPress build, but we also have a front end interface for this pattern library that includes documentation and different variations on patterns and such so that somebody who just wants to see all of these different foundational elements or what a block looks like, they can do that with a front end that isn’t necessarily associated with our WordPress installation.

David Bowman: That’s super interesting, because it sounds like you guys are doing the part of the integration that has terrified me up until now. I think design tokens are… Well, not easy, but it’s easier. They’re just little variables. They’re little bits of data that you can pass back and forth, and it’s a mapping exercise to get it to go to the right place. But when it comes to actually having… Like if you look at another design system, there’s their tokens, and then they have their components and all of those components, when we started working on design system integration stuff, I went under the assumption that the WordPress Core blocks are your component library. That if you’re integrating with WordPress, you get a component library and you should think of it as another framework that you support.

So Google material supports React and View, and if your design system supports library A also supports Gutenberg. And Gutenberg is very opinionated about what blocks it has and how you use them. And so I took all that for just for granted. I was like, “Cool, we’re going to assume core blocks and go from there and then build some custom stuff.” But it sounds like you’ve gotten much further than that. You have this whole… You got a whole thing run in to put all the core blocks together. Are you using Core blocks? What are you… I guess, tell me more about this.

Using Core Blocks

Joni Halabi: Yeah, so that, that’s actually the core part of my job. So we are using Core blocks because it was very important for us to be able to maintain that basic, basic blocks, so header list, paragraph image, things like that. But we’ve also taken away access of some of the blocks that we don’t necessarily want our content editors using. So a lot of the full site editing focused blocks, so like page title query. I’ve said this before, we like lock things down. So we’ve locked those down. And to replace those blocks, we’ve actually created a number of custom blocks.

So our custom blocks will give our content editors the ability to grab posts by category, which, yes, there’s a core block for that, but we also really, really wanted control over the markup for that scenario. We have a bunch of blocks that will allow you to have an image and text next to each other or video and text next to each other. And again, for us, it’s a control issue. We really want control over that markup. So all of the blocks that I’ve written to be custom for installation, they are dynamic blocks. And the beauty of the dynamic block is it makes it really, really easy to hook those dynamic blocks. We just take the render function in PHP, we hook that via timber to our twig files from the external pattern library. So we have one block we call premo with image.

So it’s an image next to some text and maybe a call to action link. And what I’m doing in that render function is I’m just taking all of that information, the image object information, the text, the link, and I’m sending it as an array, just an array of parameters to my twig file in the pattern library. And the pattern library does the rest on the front end. So it means if we ever want to switch out the front end, if we discover, “Hey, we have an accessibility bug. Our CTA link isn’t really accessible, we need to change the Aria label on it, or we need to change the color contrast on this button,” we can do that within the pattern library. And WordPress is unaffected by it, so we don’t have to worry about things like deprecation errors. We don’t have to worry about having people go in and update their page to a new version of the block or anything like that. It just automatically happens as we make those changes to our pattern library.

David Bowman: That sounds awesome. I have so many questions, but I’m talking a lot. Alec, do you have any thoughts?


Birgit Pauli-Haack: Before you get to your questions, I have a small clarification, when you talk about patterns, you are not talking about WordPress patterns, or are you?

Joni Halabi: I am not. No, sorry, I am talking about design patterns. We’re still struggling with terminology because pattern is a very loaded word. It could be WordPress patterns, it could be design patterns. Block is another big one that we struggle with because there’s WordPress blocks, but then there’s also blocks of information and blocks of HTML. And so thank you for…

David Bowman: Even theme means like 10 things in different contexts.

Birgit Pauli-Haack: Yeah. When you talk about Figma themes, it’s like, “Oh yeah, those are totally different than WordPress themes.”

David Bowman: Everyone’s got a theme. There’s a lot. You got to really keep your theme straight.

Birgit Pauli-Haack: Yeah. So we got one question, and thank you Alec, for answering that, from Bridget Vessel. Is that the best place to get the links? And she linked to a page on WordPress VIP, and then Alec had added two additional links there. And I will put those also in the show notes after the show.

Alec Geatches: Okay, yeah, I can talk about that a little bit if that’s okay.

Birgit Pauli-Haack: Yeah, please do.

Alec Geatches: So when we first designed this with David, we wanted to be able to… If you watched what David was doing, have no idea what happened or you just want to try it yourself, we have this long readme, or it’s in our design system bridge repository, but it’s a whole walkthrough. We have a little tiny material UI, basic design system, Figma document. You can clone that. You can see how the Figma tokens plugin that David was using, connects to it and how the token sync. And then you can use our tool to pull down those tokens and sync it up with a theme.json and then you can like, “Oh look, the color changed as I made a change in Figma, synced it, now it’s in WordPress,” and see how all of those links work together. The secret sauce in that is that custom section in theme.json. So that’s where you can dump all of your CSS variables, mostly colors, typography, things like that, units, and then you can just re-reference those in other parts of your theme.json.

So like your palette, you can say, “Give me the primary color.” And then in Figma, you can change your primary color. It gets synced to the same spot. Then your block pulls in a different primary color for its options. It’s all magical, but it’s really based off of that custom section. And what the design system bridge does, is it reads all that json, puts it in a format that’s comfortable for CSS and for WordPress using Style Dictionary, which is this Amazon product. It’s basically used for design tokens for this exact purpose or similar, where you have some design constructs, you want to put them in a different format. So we have some transforms in there. It’s like add some pixel units here. It’s really basic stuff. For the most part, we take that json, modify it a bit, put it right in the theme.json custom list, and from there it just works. Anyways, check out the tutorial I linked. We can put that in the show notes for a walkthrough, it’s really simple. You might not learn a lot from it, but it can at least show you the full end-to-end process.

Birgit Pauli-Haack: Well, thank you.

David Bowman: As soon as you implement it, as soon as you use it a couple of times, it feels really good. Changing something in Figma and then watching it update in WordPress theme. It’s pretty cool.

Changing Design Practices – How to Start

Birgit Pauli-Haack: Yeah, I can imagine how that… Amazing. So we get from an attendee, we have a developer who’s deep in the Gutenberg ecosystem and he has a question about how would you go about inspiring hesitant designers to a) embrace things like the site editor style book, and b) adapt their existing, if applicable, design systems like Figma, XD and whatever those two become post-acquisition, to work more in what Gutenberg already provides. I’m struggling to achieve internal buy-in to change design practices, even though I have full internal buy-in from ownership for Gutenberg and block-based theming. That’s the loaded question, right? The million dollar question. So, thank you for that question. That’s a really good one. Yeah. Who wants to take it on first? You all work with developers.

David Bowman: It’s a good question.

Birgit Pauli-Haack: Yeah. So how do you embrace things like site editor style book?

David Bowman: I guess I would, maybe this isn’t an answer to the question, I’ve been talking a lot again, but I’ll just say this quickly. As a designer who went on this journey who was like, “I got to use Gutenberg, let’s figure it out,” and having to go through that process, a couple of things were really helpful to me. The first one was to maybe as a non-starter for some people, but just get into block theme development. Block theme development is not hard. And I think that one of the best things about block themes is that the code of a WordPress theme includes very little PHP now, it includes very little JavaScript by default. And if you want to start doing things like getting custom styles and really doing things, it’s pretty simple. And the meat of their block theme development, so much of it is happening in json files and block markup files that are HTML, that it’s very accessible.

And so if you’re a designer that is wanting to understand Gutenberg, just go build a block theme. Go really get in there and try and figure it out, because doing that, you’ll see that there are a lot of places where you can really integrate it with what you already have. So theme.json, getting tokens out of Figma and into theme.json is… Just that is a really big step. And that’s the other piece of advice I would give is to just focus on small things. Just because Gutenberg is so opinionated and truly has not realized that it’s a design system yet.

There’s a lot of the dynamic blocks, static blocks, there’s a lot, there’s a lot of pitfalls, but if you can focus on the small things, like getting global styles hooked up to your existing design styles, you’ll get a long way. At least that was my experience, is that just doing those things, I was like, “Oh, cool, I can actually really craft this experience in the editor and I can craft the front end and I can influence it as a designer without having to go bug a developer to make a PR for me.” Often I can just go and change it. I can go change my Figma files and that was pretty rad. That was longer than I wanted it to be, but that was my answer.

Joni Halabi: Yeah, I would definitely echo that. But I think it almost feels like there is a social aspect to this question as well. And I would want to dig deeper into why the designers are hesitant about getting their hands in there. It almost seems like, are they feeling overwhelmed? Are they feeling like they don’t have the technical chops for it? I would start to have those conversations with the designers and maybe developers and designers can get into a room, virtual or physical, however you all work, and just see where that pain point is. Sometimes I know personally when I feel like oh my goodness, something is really difficult, something is just mentally blocking me from starting that task, it might be easier to talk it out or to have somebody hold my hand, at least for the first couple of steps, and maybe that will give them the inspiration to just jump in.

Create Block Theme

Birgit Pauli-Haack: And yeah, I understand that not everybody who gets into a car knows how to drive it. You need somebody to show it to you. Or another metaphor is if books would help or documentation would help, there wouldn’t be universities attached to libraries. So what I shared in the chat window was two links. One is to a course on learn.WordPress. That is develop your first low-code block theme. So to get a scaffolding and use the tools that are in the site editor, and they have been really expanding and they will be with 6.3. I don’t know if you are watching here and you want to see what’s coming, 6.3, there was a product walkthrough last night and it will be published on news on WordPress. And then the other link that I shared is just a tag of other courses on how to use the site editor.

I think it really helps to know how a content creator is going to use the site editor as well to help with the design and what would be needed. Of course, that’s the beginning. So the theme team, WordPress theme team, also developed a plugin. It’s called Create block theme plugin, which also lets you then create style variation, create patterns, as well as export the theme from the site so you can upload it to another site. That’s helping with the workflow of block themes development. And I’m sure I’m going to get the link when I’m doing it live and talking. That’s never a good thing.

David Bowman: It’s easy to search for. Create block theme.

Birgit Pauli-Haack: Create block theme.

David Bowman: It’s a good one.

Birgit Pauli-Haack: Yeah, and it has its active development and the designers that are actually creating themes for the repository, they’re start out with that plugin and then do some modifications later on if they needed to. But it’s very good to create some.

David Bowman: I would add maybe one little note to the create block theme thing, which is that… So the site editor and tools like create block theme, it’s rapidly getting so much better to the point that their goal is to have the site editor be a design tool so that you can sit down and craft a theme and be able to use it like a design tool. And it’s going to get there and it’s getting there pretty quickly. But I would, maybe this is a spicy hot take for me, is that I would not think of WordPress as a no-code solution. There are definitely, if you need that and you want to use WordPress, there’s options for you. But as just a designer being like, “Hey, I want to make a website. I need a no-code solution to make a website,” there’s stuff out there that’s really good that’s not WordPress.

And I think you give up a lot when you go with those, but you do get no-code. But what WordPress has, that some of these other things don’t, is that the code that you need to make a WordPress theme, it’s really easy, and it might not be fully, “no-code,” but it is very accessible code. And if you have ever, ever, ever made a website ever, like in college, ever, if you’ve ever done it, you can figure out how to do a block theme. And in addition to really digging into the site editor, go read the docs on theme.json. If you go read the docs on theme.json, you’ll be like, “Oh, it’s just a json file.” And you can go and find yourself developing, quote, block themes before you know it. And that’s pretty rad.

Birgit Pauli-Haack: Yeah, I like that analogy. There was this idea that block development raises the bar for entry. Because with the JavaScript and the React and the build tool and all that, the theme.json, got us back to the tinkering kind. We want to, “Oh, I want to make this border bigger, or I want to make that color more red. And I go into the theme.json and I just change it and boom, it’s done.” So it really is a good way to get your hands dirty again, with a little bit of code. We got some more information from our developer and they said, “Thank you all. I’m not certain my design colleagues will feel comfortable diving into WordPress themselves based on our experience together. I myself am very comfortable with coding block themes, SCSS under the hood and such, and how once I’m done, we set up the theme.json, that the process is largely no-code. It’s a whole new world.”

Primer – Getting Started

As a more overarching question for David and all, Figma or otherwise, what would be a good primer to share with my designers who I think are intimidated by development’s expectations. Now that I’m working exclusively in Gutenberg, I’m suspicious that there isn’t a robust design system in place on their end. And the question I ask when it comes to populating my theme.json are challenging their current practices. Is there a good getting started with web design systems resource you would recommend to them? And I give it back to David or Alec or Joni?

David Bowman: That’s a good question and I’ll tell you what resources I used when I was doing this, because I think a lot of, “web designers,” nowadays you learn… If you’re as old as me and learn to doing stuff in Photoshop and you’re used to… Design systems is a relatively new thing. And it is made designing things for the web more technical, but it’s also made it a lot more efficient and you hand off to devs easier. There’s a lot of benefits to it. And the way that I got into design systems was by honestly mostly by checking out existing design systems. And the big guys like IBM Carbon was very influential for me. Google material is ubiquitous in our lives. If you go check out the documentation sites for these big design systems, they really lay it out very nicely, because they’ve got whole teams supporting them.

And so they’re like, “Here, this is our design system. Here’s our Figma files that you use. Here’s this.” They’re all open source and you can download and play with them and build stuff with them. That can be a lot. If you’re really interested in getting into design systems, that’s a great place to start. If it’s too much, honestly Figma. If you’re not already using Figma, you should probably be using Figma. And Figma, with their latest releases at their config conference just a few weeks ago, introduced variables into Figma. They introduced modes into Figma. And so they now natively support some really fundamental design system concepts and have a bunch of really great little tutorial files that you can go play with, and this is how it works. You change from light mode to dark mode. And it’s mirroring how it’s going to work in code and point them at those. If they’re not Figma people then tell them to get into Figma. Hopefully Adobe XD just dies a slow death and they just, which I think is their plan.

Alec Geatches: Yeah, I’d also say searching Figma templates or just the word design systems or the words you can find a whole bunch, everything from these huge ones with 10 pages of buttons and things to just a little baby one that’s just a color palette and then you can take one and change it up. And that’s how I learned about them and got a hands-on knowledge.

Birgit Pauli-Haack: Joni, do you have any input?

Joni Halabi: I was just going to say, I’m a developer. Everything I suggest is going to be code, so you probably don’t want to take a suggestion from me, but Figma looks amazing.

David Bowman: Figma’s great.

VIP Plugins

Birgit Pauli-Haack: Awesome. So I’m really glad that we all got together today. We’re leading up on the hour. I have two questions for you. I know VIP is also working on two other plugins. Do you want to talk about it Alec, briefly, so we can wet the…

Alec Geatches: The first one still internal beta, so I don’t have a good link for it, but it’s super relevant to what we’ve been talking about, what Joni was talking about. Just locking things down. David posted here. Let me find that link real quick. I had that ready. A great issue in the Gutenberg repository last year and it was talking about theme.json. It’s great for design systems, but it loses the scope of these higher level design system things like if you embed this block in a hero, how does it look different now? Usually that’s part of a design system. These typography options are available here but not here. And theme.json just has a flat block structure. Every block has these settings when you design them that way in theme.json. Where was I going with this?

We’re working on a plug in that is looking to extend Gutenberg and the way that David is talking about, but also have a very allow list approach to everything which blocks you have, which roles get access to them, which block settings you have, things like that. So we want to make this super enterprise focused, because Gutenberg gives you the ability to just do crazy things. Even if you lock it down to a design system, you still get a lot of options for a lot of things and it’s very hard to get those all out if you’re running 40 websites for other people. So we’re working on a plugin that…

Birgit Pauli-Haack: Or 400.

Alec Geatches: Yeah, yeah. Or 4,000 or yeah. WordPress goes crazy. So yeah, we’ll have more information when that becomes public or when we talk about it more. But anyways, we’ve been heads deep in this trying to work with Gutenberg to allow these enterprise things, because Gutenberg is meant to be customizable. We don’t want to be customizable at all, want everyone’s job to be easy and not have that many typography options. And so the other plugin that we’re working on…

Yeah, just have good options and not that many of them. And the other thing that we worked on, this is released now, it’s called the block data API. This is a headless or decoupled thing, but there’s this issue with the way that post work in Gutenberg that make it tricky to use sometimes in like a node. If you have a node front end and you want to consume that, pretty much for a post, if you use the rest API, you just get a big blob of HTML. And it’s got class names in it and sometimes it’s got styling in it and there’s not a lot you can do with it other than just put it on the page and try to supply enough styles so that it looks decent.

But it can be hard to map onto custom components and things. There are ways to do it, but it’s pretty tricky. So we added this block data API. If you just search that in Google, you’ll find it. Check it out, look at the first GIF. It explains how it works, but it’s just we read through the HTML, parse it into json, and then pass that back. So you just get a bunch of json that you can map onto your own custom components instead of just having to rely on HTML string somewhere. So that’s pretty cool. We just released it for the first time this year. We’ve got one customer who will be launching it soon. I don’t think I can say any more specific on either part of that, but pretty cool.

David Bowman: It’s going to be big.

Alec Geatches: I’m excited about that.

David Bowman: It’s going to be cool.

Alec Geatches: Yep. Anyway, so those are the two main things our team’s been working on.

Birgit Pauli-Haack: Yeah, so there are quite a few enterprise companies who actually use WordPress as a content creation tool, but not on the front end, because they need other data match up with things. So yeah, the headless is the way that they go via the rest API. So that block data API is probably going to be embraced by quite a few agencies as well and not just the clients of VIP.

Alec Geatches: Yeah, hopefully.

Contact Info

Birgit Pauli-Haack: Yeah, we do. So we have three minutes to go. If the viewers want to get in touch with you, what’s a good place to reach you? Joni? Or do you have anything else that you couldn’t talk about but you want everybody to know?

Joni Halabi: Yeah, if folks want to reach me, you can find my contact info on my website. It’s I’m also @jonihalabi on most socials.

Birgit Pauli-Haack: All right. Thank you. Alec and David?

Alec Geatches: David, go for it.

David Bowman: Alec.

Birgit Pauli-Haack: You’re too nice.

Alec Geatches: I’m going to be quiet.

David Bowman: So find me on LinkedIn if you want to talk WordPress stuff. That’s probably the best place to find me to talk about WordPress things. I’m also social media. You find me at hanging out in the Gutenberg GitHub repository sometimes. And yeah, I also, I blog with my family at about, totally not related to WordPress, but you can find me there. It’s mostly about national parks and travel stuff.

Birgit Pauli-Haack: Oh, wonderful.

David Bowman: But yeah, that’s how you find me. There’s a few different ways if you really want to track me down.

Alec Geatches: I’ve searched my name, Alec Geatches. I think I’m the only one so far. So you’ll find me there. You can email me at

Birgit Pauli-Haack: Excellent. Well thank you so much, and I think we are right at the hour. Very punctual. Yeah, it’s a German show. Well, thank you, all three of you, for spending the time with me and explaining all this good design systems and how you work with WordPress. I learned a lot about it, and I’m sure the viewers learned a lot too. Thank you so much for coming and I hope you have a wonderful weekend. It’s Friday night, or Friday morning, depending on where you are. Thanks everybody, and goodbye.

David Bowman: Thanks, everyone.

Birgit Pauli-Haack: And we got a thank you from our anonymous developer. We use CD and with a pending acquisition of Figma by Adobe, I’m cautiously giddy and design system distraught. So here’s hoping. All right. That’s a good way to end it. Thank you all so much.

David Bowman: Take the plunge.

Birgit Pauli-Haack: You take care, and I’ll end it here.