This episode is a recording of a November 2023 WordPress Accessibility Meetup where Reed Piernock of Georgetown University demonstrates how pattern library systems work, how themes and blocks can be built using shared components, and how accessibility testing is an integral part of their process. If you want to watch a video recording from the meetup, you may do so on the Equalize Digital website: Component Pattern Libraries for an Accessible WordPress Experience: Reed Piernock.
WordPress Accessibility Meetups take place via Zoom webinars twice a month, and anyone can attend. Learn more about WordPress Accessibility Meetup and see upcoming events.
ListenMentioned in This Episode
Transcript
>>CHRIS HINDS: Welcome to episode 047 of the Accessibility Craft Podcast, where we explore the art of creating accessible websites while trying out interesting craft beverages. This podcast is brought to you by the team at Equalize Digital, a WordPress accessibility company and the proud creators of the Accessibility Checker plugin.
This episode is a recording of a November 2023 WordPress Accessibility Meetup where Reed Piernock of Georgetown University demonstrates how pattern library systems work, how themes and blocks can be built using shared components, and how accessibility testing is an integral part of their process. WordPress Accessibility Meetups take place via Zoom webinars twice a month, and anyone can attend. For show notes, a full transcript, and additional information about meetups, go to AccessibilityCraft.com/047.
And now, on to the show.
>> AMBER HINDS: So I am very excited to introduce Reed. I’m going to pop them up here so you can see Reed. Reed is a principal developer on the web services team at Georgetown University, and is on the board of directors of WPCampus.
I’m actually wearing my WPCampus t-shirt. If you’ve not heard of WPCampus, it is a phenomenal nonprofit organization that has a Slack group, and runs education both in webinar format, occasionally, and also in live conferences in person for Higher Ed WordPress.
Reed works on the front-of-the-front-end code to create sites that work well across all devices, for all audiences. Reed is passionate about usability and accessibility, and earned degrees in digital media, web accessibility, and communication, culture, and technology.
Welcome, Reed. We’re really excited to have you.
>> REED PIERNOCK: Hello. Thank you so much. I’m excited to be here. I’ve attended a few of these before, but this is my first time speaking, so I’m pretty excited about that.
If there are any questions, if people could hold them until the end, except if there’s something, like, you don’t understand what I said or you need clarification, but other than that, we’ll get to the Q&A and discussion and everything after my last slide.
>> AMBER: Yes. I’ll just chime in before I go off screen. If people could please use the Q&A module in Zoom, it’s a little bit easier for me to track than if they’re in the chat, so if you are able to use that, that is most ideal. I will watch those, and if needed, I’ll chime in, but we’ll answer them [inaudible].
So thanks, Reed. I’ll let you take it away.
>> REED: OK, thanks, especially because since I’m doing this, I can’t really see chat.
As Amber said, my name is Reed. I’m a principal web developer. I work at Georgetown University. My pronouns are they/them.
My talk today is, “Component Pattern Libraries for an Accessible WordPress Experience.”
I’m very excited about this. As much as I work in WordPress, I also really love static site generators, and putting the two together to make a style guide to work with WordPress themes is something really neat.
We’re going to get started first with pattern libraries and style guides. Things that I’m going to go over include: “Why a style guide is beneficial.” I’ll do a super, super high-level overview of WCAG. We’ll go over installing and setting up KSS-node, which is what I use most for creating the pattern libraries and style guides. A brief overview as well of Twig files and CSS Comments, and then putting it all together by integrating the pattern library components with WordPress themes and WordPress blocks.
A few things that I’m not going to go over, but we could talk maybe later and when we get to discussion. I’m not going to talk about any file structure. People might use a BEM methodology or atomic to organize their files and their styles, but what I’m going to talk about can be CSS agnostic, so whether you’re using Sass, Less, Tailwind, even just plain Vanilla CSS, all of these can still apply.
Not going to get into the specifics of WCAG Success Criteria. I’m just going to go over it briefly, and then talk about how the pattern library can help with that.
I’m not going to talk about managing node projects. Even with setting this up slightly to include node, I’m not going to go over any type of node project itself.
I’ll explain how the pattern library components can be used in the themes and the blocks, but I’m not going to go into super specifics about creating the themes and blocks.
So the two main things here are on screen. Style guide is the document that lists all of the components, and the pattern library is the code that creates those components, so this solves some of the issues that people might have with their websites, where especially if you’re using a WordPress theme, you may not remember where you put something. You may repeat code because two things might look similar, so then you copy and paste instead of combining them, and that could lead to inconsistency, and trouble with maintainability.
If you have too many components, it could be confusing for developers as well as people that use the website, and then especially with Custom Gutenberg Blocks, one way of coding them is static, meaning everything is in the JavaScript when you build it. When you use the code, it outputs static HTML, but in order to have the pattern library components integrate with that, use dynamic blocks instead, which uses, in here, Twig and PHP and JavaScript to make some of those, which can then be updated basically on the fly, and you don’t have trouble with all those deprecations that you might have when you try to update the HTML output.
With the style guide, we can call that the source of truth in one way. This is the document where everything is listed. These are the components that you have, and it could be as small as a link, or it could be as large as an entire page template, so all of those things are used to create components that might then build into other components.
The pattern library is a sustainable way of coding the source of truth. That way, because you know where all of these components are, you could go to the style guide and check the page that is for link.
If you need to update link styles, you can do it in one place, and it will propagate to everything that you have that uses a link.
Even though I’m going to go over KSS-node as what I use most often for my style guides and pattern library, there are a lot of other tools that can do similar things, and some of the approaches that I’m going over could apply to those as well. Stuff like Pattern Lab , Storybook, Fractal. Those are all different types of things that can create design systems, style guides, or pattern libraries.
With KSS-node, the reason I like it is because I work also so often with WordPress themes. KSS-node offers different types of templating languages, so you can choose the one that works best for your project, and WordPress themes are written with Twig, and I can change the pattern library to use Twig files instead of plain HTML or, Nunjucks, Handlebars, any other type of templating language.
First, I can go over some more of the benefits more than I just explained. On screen is title “benefits,” and underneath that is an emoji of a person sitting with a laptop with the text web team, and then another emoji of an artist with a little paintbrush and palette, and says “content creators.”
So all of this is beneficial for what we want to accomplish in terms of accessibility. It’s most often used when you have the web team and the content creators not explicitly working together. You might be working together to create the websites, but the web team might either create the WordPress themes to hand off to an external client. Or create those themes for websites, and then the content creators could be somewhere else in your organization.
In my everyday job, it’s a university setting.
So the web team are the people that create the components that are used in the themes and blocks. The web team also is the one to interpret the Web Content Accessibility Guidelines to make sure that their code is adhering to success criteria.
The web team also iterates on components for the design or functionality, and then also fixes bugs anywhere that comes up in the components or the themes.
The content creators are the people that actually produce the content for the websites. These people could work in teams such as site architecture, content strategy, copywriters, graphic designers, video or podcast production.
What they do best is create content, and a lot of those people may not understand understand HTML, they may not understand accessibility guidelines. All they understand is their area of expertise, so if the web team can create these patterns for components and ensure their accessibility, the content creators can then ensure that the content they have is accessible.
On screen are the four principles of accessibility: perceivable, operable, understandable, and robust. This is from the introduction to “Understanding WCAG.”
From their website and their documentation, perceivable means that users must be able to perceive the information being presented. It can’t be invisible to all their senses.
Operable means that users must be able to operate the interface, that the interface cannot require interaction that a user cannot perform.
“Must be understandable,” meaning the users must be able to understand the information, as well as the operation of the user interface, and the content and operation cannot be beyond their understanding.
Robust means that users must be able to access the content as technologies advance. As technologies and user agents evolve, the content should remain accessible.
On screen, the first rule of ARIA is don’t use ARIA. This is from the W3C. If you can use a native HTML element or attribute with the semantics and behavior you require already built in instead of repurposing an element and adding an ARIA role, state, or property to make it accessible, then do so.
This basically means that HTML by itself is accessible. If you are writing code such as paragraph, heading, list, and you’re putting them in a good order and understandable way, then you don’t always need to add any ARIA attributes.
ARIA is Accessible Rich Internet Applications, and there are many times where code can get bloated by using too much ARIA, too many ARIA labels, too many roles of elements being overridden, so if you can use plain HTML, then just do that instead.
So setting up a pattern library. On screen here, I’m going to briefly go over, right here, the sample directory structure.
So on screen, I have an illustration of what a sample directory structure inside a theme could look like. There are five different folders or directories under that. All of these may or may not be needed, as some of them are optional.
The builder includes the scripts and the templates that build the style guide. That’s not the pattern library. It’s the builder that will output the documentation for what is in your pattern library.
The style guide directory is the one that actually holds that documentation, the generated output.
The source folder, it holds your CSS, your Twig files, any of that content that you need to build your websites.
Dist, D-I-S-T, that is everything that is compiled, such as the output CSS. You might have output JavaScript. You may have images or other media that is stored in that folder.
Config: Any configuration files that you might need for your project.
I am going to show an example of a config that is used for the KSS-node to build the style guide so you don’t have to type it out every time you want to build it, some of these could go into other directories. Especially with dist, your assets could go inside your WordPress theme itself and not here.
WordPress themes require to have a style.css file, and that includes the theme info such as the name, the version, the organization.
If you have any other style sheets that you are on queuing or pulling into your templates, those need to be at the root of your theme so it would go directly under sample WordPress theme. Anything that is beyond what you are going to have in your Style CSS.
>> STEVE JONES: This episode of Accessibility Craft is sponsored by Equalize Digital Accessibility Checker, the WordPress plugin that helps you find accessibility problems before you hit publish.
A WordPress native tool, Accessibility Checker provides reports directly on the post edit screen. Reports are comprehensive enough for an accessibility professional or developer, but easy enough for a content creator to understand.
Accessibility Checker is an ideal tool to audit existing WordPress websites find, accessibility problems during new builds, or monitor accessibility and remind content creators of accessibility best practices on an ongoing basis. Scans run on your server, so there are no per page fees or external API connections. GDPR and privacy compliant, real time accessibility scanning.
Scan unlimited posts and pages with Accessibility Checker free. Upgrade to a paid version of Accessibility Checker to scan custom post types and password protected sites, view site wide open issue reports and more.
Download Accessibility Checker free today at equalizedigital.com/accessibility-checker. Use coupon code accessibilitycraft to save 10% on any paid plan.
>> REED: On screen, first is the heading for this slide: “Install packages and add scripts.” From the “command” line, to install the KSS-node that we’ll build, “npm install dash dash save dash dev Sass and KSS.”
I’m going to use Sass because with that, it’s easier to separate each of your components into different files, and KSS is the package used to create the style guide.
In your sites package dot JSON file, all I have on screen here are two scripts: one to build the CSS, and one to build the KSS.
At a minimum for this, you need some sort of CSS file, whether it’s compiled from Sass or another, like Less, and then the KSS for the style guide. Those are your minimums.
The first thing to do is to copy the base builder template. On screen, the installed location is under the node modules, KSS, builder, Twig directory. You’ll find under there your builder files and the scripts needed to do the building. You copy those from that folder into your project location into the builder Twig directory.
There are different ways to go about this. You can copy-paste. You could use a script that will move it from one location to the other, but those are the files that you’ll need for this.
Again, I mentioned Twig because that is the templating language used in WordPress themes. The default for KSS, I believe, is Handlebars, but I use Twig for all of that, especially working with WordPress.
If you do work with another CMS, a lot of them are moving to Twig, but most, in my experience, is with WordPress.
On screen, create the pattern library directories. In each of the directories, I’m going to list that you will have an index.scss file in each of the directories, and these will hold all of the comments that will create the style guide later.
We’re going to start with base, color, text, link, card, and layout. You can organize these however your project best works or for whatever theme you’re using. You might have different files. I mentioned it could be Vanilla CSS, Less, Tailwind. As long as there’s an ability to add comments into the style sheet files, that’s all you need, and then we’ll use those and we’ll create namespaces for the directories that we have.
On screen, how to set up the builder configuration. The config, kss.json, it tells the builder where the information is for you to grab those patterns. You’ll need the title of your project, the directory of the source, the directory of the destination, the directory of the builder, and the directory of your CSS.
The source, destination, and builder directories are all relative to where the config file is in your folder structure.
The CSS file is relative to the generated pages in the output style guide.
Last in this JSON is a namespace, and because we’ll reference Twig from the pattern library, and the custom blocks, and the custom themes, it’s easier to give them a namespace to call those.
On screen, I’ve defined color, text, link, card, form, and layout as the namespaces for our project.
Now we’re going to get ready to add the patterns and components, so first, we’re going to talk about color. It is our first style guide entry.
On screen is a screenshot of the brand colors page in the style guide with a heading named colors. The colors listed are eerie black, which is a dark black, maize Crayola, a medium yellow, Gainesboro, a light gray, alabaster, an ivory white, and jet, a dark gray. The colors are laid out in a grid-like layout, and each grid item includes a representation of the color, its description, its color code, and its property name.
When the style guide is generated, the comments from the CSS are used to create the pages, so the builder will loop through all of the colors that you’ve input to output this page with the information about the colors.
On screen is an example of color style sheet. The beginning has plain CSS Comments that are preceded with two forward slashes. Empty lines between comments sections also must have a slash.
The first line here is brand colors. That is the name of your pattern. Beneath that, color is followed by a colon, and that tells the style guide that these are the colors for your website.
Beneath that is the weight of the page, and will determine the hierarchy structure of your style guide.
Then last in the comment section is style guide, and here it’s called color.
After the comments, that is just plain CSS right here. It isn’t a Sass file, but right here it is just root, and it has CSS custom properties for primary, secondary, tertiary background and foreground colors.
On screen, text heading. A screenshot of the text page in the style guide with a heading named text, and a subheading named heading.
An example section illustrates how that heading would display on websites, and below the example section is the Twig code used to create the pattern for the heading component.
Some sections of your style guide may have parents and children, so here, text is the parent category, and then beneath that is heading, and you may have other children of text, such as lists or paragraphs. Those comments from the previous slide tell the style-guide builder where those go and how the hierarchy structure is laid out.
On screen is an example of the text style sheet. As in the last one, the first line is the name of the pattern. Here it’s “text,” and then a “wait” for setting up that hierarchy, and then the style guide is called text.
Beneath that, still CSS Comments, again, proceeded with two slashes. Heading is our name of the subsection. It has a small description after it, which says, “heading content divides the header of a section.”
Here it’s still a little different from our previous in that there’s a new markup property in the comment. It lists heading.twig. It tells me style guide builder what code we want to use to generate with pattern.
Beneath that is another style guide. This has text as the parent, and then dot heading as the child or the subsection.
On screen is heading markup, and this is that heading.twig file that I just mentioned. There is both Twig and HTML code here, and the Twig files actually create what the patterns are. Right here, we just have the most basic attributes that can accept a value from any other file that may include this Twig file.
There’s not anything pretty fancy here. First, we have a set declaration that is a Twig function, where the variable is heading level, and we’re going to use a heading level that’s passed into that variable, or we’re going to have a default of two. Since your site might have title somewhere else, like the page title or the site title would probably be your H1, anything else we can default to an H2. That can then be updated whenever this is called from somewhere else so we can have a heading three, or four, et cetera.
So we can put that attribute heading level in the header. It has a class of text heading, and then between the opening and closing H tags is another attribute called heading text, and that’s whatever text is going to be passed in through this pattern.
When your style guide is built, it needs some sort of sample content to use to put on the screen. On screen here is an example for heading JSON file, and we’re updating that attribute from the previous slide where we put the heading text in between the opening and closing.
We have an example text here. I use a generator that makes it seem like it’s fake academic papers, so a lot of the sample content here may seem weirdly, vaguely, fake-ly academic. Here, I set the heading text to neodialectic conceptual theory.
On screen, we have another pattern. This one is link. It’s a screenshot of the link page in the style guide, and the heading is link. An example section illustrates how the links would display on the website, including the default styling, the hover, and the focus states.
Below the example section is the Twig code used to create the pattern. What we have here are the name of the pattern, the description, as we did with the other patterns of color and heading, but here, we’re going to add modifiers, and these modifiers, the link, at least, can be the other focus states, the hover states. We can set those again later. We can pass anything through there using whatever modifiers you need. It may be states, it may be different class names.
On screen is an example of a link style sheet. In the beginning, here is the comments that will generate in the style guide. The first is link, which is the heading. Below that, is a short description of what a link is that makes connections between two different resources.
Below that, where you can add your modifiers, this is the hover state and the focus state that I’m illustrating here. The same with the heading, it points to the markup for that, which is link.twig. It gives it a weight of three to set it up in that hierarchy structure and calls it “link” in the style guide. Below that, any CSS or styles that you want to apply to the A element goes there.
On screen is an example of the link markup. This is, again, the A element that uses, for link, have a class name of text link. We have an attribute for modifier class, and then an href that will be the link URL, and then between the opening and closing A tag, we have our attribute for link text, where those modifiers from the style guide modifier section will go.
When your style guide is created, in order to display additional states, it will create kind of fake placeholder CSS classes, because you may want to display your focus state and what that looks like on a webpage and not have to require anybody using the documentation to actually get to focus it.
We have another JSON file for link with example attributes here. Again, “Neodialectic conceptual theory” is our link text, and our link URL is “Example.com.”
When you create the JSON files that will generate that sample content in your style guide, that file name is the same as your Twig file.
For link, the file name is link.twig, and so our JSON file, it is link.json.
Now, once you have a bunch of patterns or components put together: headings, links, text, whatever your base elements are, we can now start putting it all together to create larger components.
On screen is a screenshot of the card page in a style guide with a heading of card. An example section illustrates how the card would display on a website. This card includes heading, paragraph, and link patterns.
Below the example section is the Twig code used to create the pattern for this component. This is where, like I mentioned, things start coming together now, and patterns can include other patterns, and that’s where all of the magic happens, where all the neat stuff starts to happen.
On screen is a sample style sheet for a card. Everything here is the same in the CSS file. Comments at the top for the pattern name, description, markup, weight, and style guide name, with all of your CSS below that, and this can be anything you need, and it’s the same way to set up the style sheet as any other pattern we’ve done already.
Now, the difference here is with the markup for this pattern that uses other patterns.
On screen is an example of what card markup could look like. It is a div with a class of card, and inside the opening and closing of the div tag, we have an “include” for text heading, an “include” for paragraph, and an “include” for link.
The includes use the namespace that we defined earlier, so text for heading, and text for paragraph, and then link is its own namespace.
In the includes, there’s a section that’s with braces after that, and that’s inside where you can set different attributes, so for the card, the heading, we’re always going to call it a heading three, and then the heading text that we’re sending to the heading pattern is being pulled in from what is then called the card heading, so those are specific attributes for the card pattern, but those attributes can be passed to the other patterns’ attributes.
On screen is an example of JSON for the card. That includes the card heading, card description, card link text, and card link URL, and these are, again, the key value attributes that are passed in through the patterns. Here, they are specifically prefaced with card, but then in the pattern, they are passed through to the patterns that are included in the pattern.
I’m going to say “pattern” a lot more as we go on. [chuckles]
So once you have all of these things put together, then you see even more things being put together.
Not going to go in in-depth over every single pattern that you could put on your website, that could take forever, but here on screen is an example of layout. It’s a screenshot of an example of the layout. It includes a global header, navigation, search form, main content, and global footer. The title is “Dialectic narrative.”
There are three navigation links in the nav bar, and in the content section is a card grid that has three different cards in it.
Once you have patterns set up, then it gets easier and easier to create more complex patterns because they build over the smaller ones that you’ve already put together.
Here, we have the example of the link used, then, inside a card, and then the card is used inside of a card grid. The card grid is used inside of the main content, and the main content is used inside the layout. Everything builds on top of each other. You can put these together in any way you need.
So what does this have to do with WordPress, then, if I’m talking about style guides? On screen, fitting in it with WordPress, custom themes and custom blocks, Custom Gutenberg.
The custom themes are using the larger component chunks, like the layouts, your site header, your site footer, major pieces like navigation.
Custom blocks are still called Gutenberg in the plugin, but now usually just called the blocks editor in WordPress. These include things like all of the smaller component pieces, like the links, icons, buttons, paragraphs, headings, all of these.
A review of the benefits here. When the web team needs to work with various content creators that may not know HTML or understand, or want to understand, you can front-load a lot of this work in the beginning to make building the patterns easier as you go on, and they build and build and build on top of each other. This makes it more maintainable. You no longer would need to make changes in multiple files for things that look similar.
If four different WordPress custom blocks are using a link call out, then you can change that in one place, and it trickles down to everything else below it.
Related to that, if you do find an accessibility issue with, for example, that card pattern that I went over earlier, then you could just fix the components inside, like, you could fix the individual components there, and then the pattern would get those fixes, again, trickling down because everything’s built on top of each other, and because of that, there are fewer risk of bugs, your styles are consistent, you know which patterns are used where, and it’s easier to be able to spot accessibility issues in the themes and the blocks, and then again, that leaves the content creators to focus on content, and not the skin, or the theme, or any of the HTML code.
On screen, adding theme templates. Themes in WordPress are written with Twig from the Timber documentation. With Timber, you write your HTML with the Twig template engine. This cleans up your theme code. Your PHP file can focus on providing the data and logic, and your Twig files can focus 100% on the HTML and display, meaning the PHP files are for your functionality, and the Twig files are for your templating.
This separates them to make them easier to maintain, and they don’t co-mingle, or are similar to different other languages, like you may not write inline style sheets, you pull your styles out. That’s why we no longer use things like the center tag. All of those got separated from HTML into CSS, and again, here we can split that out, have the functionality in the PHP, and the templating HTML in the Twig.
On screen is an example of code for the Timber context. The context is a list of all of the variables that WordPress can expose, and then that can be passed through to the templates and the theme.
Here, I have an example of the context setting the site title and the site link using site.name and site.url, and then these can render into the index.twig all inside that context.
This is a little different from other ways of doing WordPress theming, where you might use, like, get blog name or get blog URL. You only need to do that here by just putting in where that is in the context and using those Twig and Timber variables.
Some of the neat variables that you can use in the Timber context, these are probably the most often used ones.
For something like featured image in the WordPress editor, you can select a featured image that will be for your page or your post, and here, you can get that information with post.thumbnail.source and post.thumbnail.alt. There are other attributes you can get there like the height and the width, but “source” and “alt,” those are the ones that you really need.
Post.title for your page. Post.author.name if you have a blog or you have documentation that’s written by different authors or content creators, and then the post.postdate.
On screen is a base template example. This is HTML with a very basic default page structure, including the doc type, then the opening and closing HTML tags. Inside that is the head and the body. Inside the head, you have your title, and then in the body here between the opening and closing body tags is where I’ve put different includes for the Twig files from the pattern library.
So I’m including the layout header and the layout nav, and then there is a block section, I’ve called it main content, and in between that is the post.content, and that will be the content of the page that you will write in the WordPress editor, and at the bottom before the ending, body, tag, including the layout footer.
So you probably have different templates for your WordPress themes. You may have a different one for a news article or a post than you would for a page.
Here on screen, I have an example of a single post template, because we already have a decent template in place that we called index.twig, we can extend that instead of copying and pasting, or rewriting and putting things all over the place. We can use this to extend it.
For the post, it extends the template.
I have a typo. I’ve called it index, and here I’ve called it base. My apologies.
We have the opening and closing of the block. Now these aren’t HTML tags. These are Twig tags that specify a different block on the page, which you may include other content or override that later from the extends.
So here on the index page inside the block main content, which is just a reference to the post.content for the content of the page, when you extend it, you put that block there and can write anything else that you need to inside that block that will override the other template.
We only had post content, and here we also want to include a featured image, a heading. You might have a byline that uses the date and name of the author, and so it uses the same structure as all of the other pages on your site, and then customizes it just for what you need in one certain area.
Here, I’m also calling the post.id from the context. This is helpful here because WordPress will put an ID for every page and post that you have in your site, and from there, you can use that wherever you need to.
Here, I’ve put it inside an ARIA labelledby on the article tag, so because this is a post and it’s an article, we want to make sure that region is appropriately named, but instead of putting the ARIA label and repeating whatever the page title is, we can set up that heading to have an ID of title with the post ID in it, and then use the ARIA labelledby instead on the article tag.
Here on screen is an example of the page post template. Now, if you’re not terribly familiar with WordPress themes, it can be confusing because there’s a post and there’s a page post.
Posts are the things most used for news articles. Here, a page is a page that will remain static. It doesn’t have a date associated with it. It could be, like, “about” or “contact us.”
The example here is also extending the base template, and then, again, inside the block for the main content overrides whatever we needed from the other, so your page might not necessarily need to have a featured image or an article byline, so we only have to include what we want here, and that’s the heading, with the page title, and the post content.
If you’re starting to notice these things extending from each other and including other pieces, that’s where all of the patterns for the components really come in handy, but you can spot those accessibility issues and fix them in one place.
So if we find an issue with the global site heading, and there’s an image logo used for the site title and that doesn’t have any type of alternative text on it, whether it’s the alt of the image or some sort of label or actual “text” text, then we could just fix it in that one place and not have to go through every page template and update it one by one, line by line. We can fix it in one area. It’s included in other component patterns, and then those make up the big pattern for the templates.
We’ve talked about themes, and now we’ll talk about custom blocks.
On screen is a little bit from the documentation for WordPress Gutenberg. “Experience the flexibility that blocks allow, whether you’re building your first site or write code for a living. Blocks allow you to build your own custom posts and pages without any coding knowledge,” and that is also where this comes in a little easier, because your content creators don’t need to know HTML. Their focus is on content, could be copy, could be images, could be video, but whatever that content is, they can focus on making that accessible, and they don’t need to know any HTML. They don’t need to know success criteria. They don’t need to know anything about ARIA labels. All they need to know is their content, and then that allows the web team to create whatever code is necessary, and using those patterns again, we’ll create the dynamic HTML for the custom blocks.
On screen, I have the screenshot for the card. Again, the card pattern can be used to create the card custom block. It has a heading of card, an example section illustrating how the card would display on the website, and then a sample of the Twig code below that.
So the devs can create a block, which then the content creators will insert on their pages. We can use that to control accessibility in ways that some WordPress Core Blocks don’t allow or don’t offer. We can then provide content creators with patterns with those blocks so that they don’t have to get overwhelmed if they are confronted with a blank page and are unsure where to start, and so if we provide those blocks in the forms of either the blocks themselves or block patterns in WordPress, they only need to fill out the content fields, like the heading, the description, and the call to action.
I want to make sure that you know I am not a block developer. I work on the dynamic pieces, the patterns that create the blocks, but I work with other developers who do all of the functionality of the blocks, so other developers will create those input fields for the heading text or the little pop-ups for you to add the image from the block toolbar. Using that, I will then create, like, the skin for the blocks, and that is the patterns that we put in that library.
So on screen, it’s using Timber again to call the pattern library to fetch the card pattern. Any of the variables that are set in the functionality of the block can then be passed through to the variables from the pattern.
In the block, you might have class name, heading, description, link, and URL, which will then get passed to the pattern as modifier, class, card heading, card description, card link text, and card link URL. You can save those attributes there, and it’s only included when the block pattern is called.
So go forth and build all the things. I have a repository that includes a sample of a style guide, and I have a demo website for the style guide.
This talk is also available on my website. If those links are needed, Amber or Paola can get those to attendees later. I’ll put my email in the chat when I’m done sharing my screen, but you can contact me at “Code@readcodes.com.”
If there’s anything else, then we’ll go over it in the Q&A or discussion.
Thank you.
>> AMBER: Sorry, sometimes it takes me a little while to find that spotlight button myself.
Thank you so much for that talk. I had never heard of Timber before, so then I went down a little rabbit hole while I was listening to you, because I clicked the link in your slide to go to the Timber thing.
I’m curious, could you share a little bit more about that? Would you call it a theme framework? It’s like a starter that people can use to build custom themes?
>> REED: It’s not really a starter, but it is kind of a framework or a wrapper that can help you find all of those WordPress variables, because sometimes you may not know the actual WordPress function for something. I’m pretty sure that it’s something like “get blog name” or something like that, but if you don’t have all of that handy, it’s so much easier to write something like site.name, and then you know that’s the name of your site.
So that’s where Timber can really come in handy, and then Timber uses Twig as the templating engine, so it’s real handy with using that in WordPress themes.
>> AMBER: Yes, that’s neat. I posted a message for our devs and I was, like, “Have you heard this?”
[laughter]
So that’s really cool.
Everyone, feel free if you have any questions to put them in the Q&A module and we’ll go through them.
Billius [phonetic] asked: “Will this approach work on Django, or is it exclusively for WordPress themes?”
>> REED: I’ve not used Django, but a lot of what I went over can apply to other themes or content management systems.
I know Drupal is using Twig or you can use Twig and Drupal. I haven’t used Drupal in years, but… Oh, it’s there. Kraft, I think, uses Twig as well, so a lot of these can also apply to other projects or other content management systems.
Also, you could always create a style guide that is separate from your theme. We use it with the theme, because if you have it in one place, you can just call it in. It’s so much easier that way, but you could have them separate and then just do your theming in a different way.
>> AMBER: Yes. There was actually a question that I was going to ask you, which is, how do you decide what components belong in the theme versus in maybe a separate plugin? Because I know we’ve had some discussions about that internally.
When we’re making really custom blocks for things, we debate, “Does this belong in the theme?” Or is it something that we think even if they change their theme four or five-plus years from now or whenever that they might still need this, and therefore, it should be its own thing.
Have you had conversations or thought about how components could fit, whether theme or plugin-based?
Yes, because some of them would work in both. If you have a call to action, but it’s just a link, and it might look the same whether you have it in the navigation or it might look the same whether it’s in like a call out or one of those card blocks I showed, those could be in both places. It could be in the theme and in the block.
With the block if you separate your block plugin from your theme, then you could have different themes use the same blocks, and all of those things can still use the same pattern library because the Twig itself is the same and will have that same output on the HTML of the front-end.
So if you have theme A and theme B, and both of those use the same block plugin C, all that would be different is the style sheet itself. Everything else can stay the same and they would just get styled differently.
Sometimes it’s a matter of choice where you want to put those things. I haven’t done any of it yet, but there are now block themes that might benefit from having the blocks inside the theme instead of a separate plugin.
It’s kind of iffy and it’s a bit of a gray area, so I would say it depends. [chuckles]
>> AMBER: Yes. Yes. I think it’s so hard because we talk about and we frequently build custom blocks that are in a theme, but then it’s, like, well, if they decide to re-theme later on the downside of Gutenberg or the blog editor, those blocks will stop working, unless they’re going to have to be migrated to a new theme or migrated into a plugin or something like that. Or they’re, like, you know, “We don’t want those blocks in that layout anyway.” But then they have to go through their content editor and replace them all, which could be bad if it’s on a lot of pages or posts.
>> REED: Yes, and I think one of the good things with this is, if you have a separate block plugin, then that could call the pattern library itself, and then your theme could be something completely different.
The style sheets, like I said, themes will have different style sheets, but with the block, you can have it use those patterns, and hopefully, if they’re just changing themes, all it has to do is basically update the styles for those blocks, and then the content can stay the same. You don’t have to migrate.
>> AMBER: Yes. It sort of seems like that’s the direction WordPress Core is hoping to go, which is that the theme will do bare-bones styling and that is it, and even things like padding and margin and layout and font size and everything is going to be controlled at the block level, not necessarily on the theme.
>> REED: Yes.
>> AMBER: Do you see any downsides to that?
>> REED: Some of it is, if you want to use the same block on a few different pages, then in the editor, you might need to update all of those things separately.
Like on your “about” page, if you have that call to action, and you use the style in the editor to say, “Oh, I want this to be red, and I want it to have white text, and I want it to have a border around it with this much padding,” but on your contact page, you want it to be blue, but then later date, you decide you want all of your buttons to be purple, then you have to go through all your pages to do that if you’re doing it in the editor itself, so if your theme has that style sheet, or your patterns, or your blocks have that style sheet, it could be a little easier.
>> AMBER: Yes, it scales better for editing.
Daniel had asked: “Did you say that the KSS-node would work with Nunjucks or something else other than Twig?
>> REED: Yes. I’ve used it so far with Twig, Handlebars, and Nunjucks. I think there are a few other templating languages that you can use as well, but those are the ones that I’ve definitely used with it. Twig most often though.
>> AMBER: OK. Do you have any tips for anyone who is just getting started with that? I noticed, like, the Timber website has a course and some other resources. Is that the best thing to also learn about Twigs, or are there other resources that you’d recommend?
>> REED: It’s a lot because there’s a few different moving parts here, and so it depends on where your expertise is as well. Like if you’re a block developer versus a designer, you might want different resources to look up, so for things like design systems that are created with components and patterns, and then generates the style guide, looking up something with design system or atomic design, that could help with that.
Then if you want to get into the code bits of it, I don’t think you necessarily have to learn all of Timber as long as, depending on what you need. If all you’re doing is the patterns or the layouts, then you probably just need to know what some of those variables are, like site.name, especially if you’re working with other developers that do a lot more of the back-end or a lot more of the block development. Everything else is pretty much plain CSS or Sass, however you want to write it, and all of the style guide stuff goes in comments, and the documentation for KSS-node is pretty good, but similarly, there are other systems you might decide work better.
Fractal, I think, is one that other people have used, and Storybook, but this is the one I use most often.
>> AMBER: Yes. I don’t see any other comments or questions from attendees.
I think my last question that I sort of thought of while you were talking was, are there certain components or good ways that you’ve used to identify what should be its own component versus part of a larger component? Or, like, a list you could recommend or reference on… You know, like USWDS, it’s like accordion, like all of these different things that it’s like, “This is a component.” “This is a component,” and I know sometimes we have discussions about, like, “Is a small thing a component that gets repeated as part of a bigger thing or across multiple? Or are all the bigger things their own components?”
>> REED: Yes. That is another thing where I’m, like, “It depends.” [chuckles] You may have different needs for certain things. You know, a button is probably one of the more common types of components that I’ve seen. You might consider something like the search bar its own component, which uses a button. Or you might consider, like, that card its own component, which uses a link styled like a button, so you have decide if those are things, like, you want those “buttons” to be the same across your site. Or they might just be an actual button tag or an A tag that you style that way, and you don’t need any other functionality. Then I’d say it could just be a plain HTML and not its own component, but that really depends.
I hate saying “it depends,” but it all comes down to your needs or your team’s needs.
>> AMBER: Yes, and just how much you want to be able to repeat or reduce repeat work, right?
>> REED: Yes, so like that card pattern. In our themes, we have things like an information grid, news items, related content, and all of those use that same type of card-in-a-grid layout, but they’re all their own blocks, yet they use a lot of the same components.
So if we decide, “Oh, we want to use this thing instead,” then it can trickle down from the card component to everything that uses that card component.
>> AMBER: Yes, so you only have to change the size of the H2 and the style of the link one time. [chuckles] You don’t have to go change it on five different things that use it.
>> REED: Eight different CSS files, forget one, have bugs. [chuckles] Yes.
>> AMBER: Do you feel like adopting this reduces the amount of time that you have on QA?
>> REED: It [chuckles] also depends. In my team at work, we have several different layers of QA, and we will send it for a design QA, an accessibility QA, functionality QA on each individual thing, so if there is a new pattern for a new component in a new block, that goes through all of those things, and then once we get to a point where we’ve merged, and so we might have like four different things we’ve worked on in a week, and they’ve all been QA’d three times each individually, once all of those things are merged and are ready to be deployed, then we do another round of QA with a visual regression tool, and another bit of functionality testing will sign off.
So it does help in some ways, because if you’re familiar with something… You know, I mentioned the news items. If someone is familiar with the way a news block works, and then we have a related content block that has the same patterns, you could notice it and be like, “This doesn’t look right.” Or, “This functions differently,” and it will cut down on some things.
If your card pattern itself is accessible, then most likely, your news and your related content will also be accessible because they’re using the same components from the card pattern.
>> AMBER: Yes, so it could reduce it a little bit, but you still have to do lots of testing.
>> REED: We still do lots of testing. [chuckles]
>> AMBER: I know. [chuckles] Accessibility testing, I think, is always a multi-layered approach, and that is the right way to approach it to make sure that it’s working for everyone on all their devices.
>> REED: Yes.
>> AMBER: I really appreciate you taking the time to present, Reed. This has been a really interesting and educational talk, and I really appreciate it.
There’s tons of great links, so we will make sure to include the links to the slides with the recap.
Thank you, everyone, for tuning in, and if you’re in the US, happy Thanksgiving.
Thank you, Reed.
>> REED: Thank you so much for having me. Bye.
>> CHRIS: Thanks for listening to Accessibility Craft. If you enjoyed this episode, please subscribe in your podcast app to get notified when future episodes release. You can find Accessibility Craft on Apple podcasts, Google podcasts, Spotify, and more. And if building accessibility awareness is important to you, please consider rating Accessibility Craft five stars on Apple podcasts. Accessibility Craft is produced by Equalize Digital and hosted by Amber Hinds, Chris Hinds, and Steve Jones. Steve Jones composed our theme music. Learn how we helped make 1000s of WordPress websites more accessible at equalizedigital.com.