046: Accessibility-First Dev Briefs, 2 Towns The Bad Apple


In this episode, we take a deep dive into accessibility-first development briefs, and how our own approach to establishing accessibility requirements on projects continues to evolve.

Mentioned in This Episode

Accessibility Notes

Accessibility is important to us and will be a big part of our test and debug process. We will be looking at the HTML output in your code to make sure it is semantic HTML.

I’m being upfront about this because it would be ideal if you code with accessibility in mind from the beginning – that will reduce the need for us to have extra rounds of revision or for you needing to recode things after the fact to meet standards, which is frustrating for all parties. 

Example expectations/things that we have asked developers to fix on past projects:

  • Buttons will be coded as buttons, not divs, spans, or a tags.
  • Everything interactive will be keyboard focusable. The whole website needs to be usable with a keyboard alone. Use your tab key to check this.
  • Every focusable element needs a visible focus outline (2px solid with a 2px offset that sufficiently contrasts from the background).
  • Lightboxes, popups, and modals manage focus well – I.e.:
    • When opened, focus moves to the lightbox.
    • There is no way to tab out of the lightbox without closing it
    • After closing a lightbox, focus returns to the element that triggered it
    • The escape key should close the element when pressed. 
    • Screen readers should announce if a modal has been opened.
  • Any “Read More” links will have an aria-label that includes the post title (I.e., aria-label=“Read More of Post XYZ”).
    • This applies to all ambiguous links (learn more, more, download, etc.)
    • You can use the Screen Reader Text Format plugin to add screen reader text in the block editor for ambiguous links in blocks.
  • There will be no empty links, buttons, or headings.
    • If a button or link contains an icon, the icon has a proper alt text or is hidden from screen readers, and there is an aria-label or hidden screen reader text communicating the button’s or link’s purpose.
    • If you code a custom ACF block to match the design, assume that any field could be left blank. As such, you must use conditionals when fetching meta or other information – don’t output empty tags or a heading with no content following it if a meta field is left empty in the admin.
  • Headings are used in the correct order (we can provide a view of the design that indicates the expected heading levels if you need this) – you will likely need to style heading levels multiple ways to fit the design.
  • Images should almost always be in tags – background images are only appropriate for true background images that are purely decorative. Here is an example:
    • The subtle helmet graphic on the header bottom right is decorative and should be a background image.
    • The photo of the building is not decorative and should be a foreground image with alt text.
  • All should get the alt out of the media library. If alt isn’t entered, then the alt attribute should be alt=”” Please don’t replace it with the image title because that is usually garbage.
    • In some cases, it may be appropriate to make the alt text of a featured image the post title. For example, a post about a company where the feature image is in the company’s logo. But please be very careful about hardcoding any alt text – air on the side of allowing the content creator to enter it.
  • If there is an item in the nav that is styled like a button, it needs to be added in the nav menu settings with the other nav items and then just styled with a class (don’t add it somewhere else such as in a widget area, etc.)
  • Any data tables (pricing tables, informational tables, etc.) need to be coded as actual HTML tables. It is almost never appropriate to use divs. If you want to use divs for a table, check with us first and note that you’ll need to add ARIA to it to indicate that it is a table.
  • Groups of posts should be coded in unordered lists, not divs, and should contain article tags in the li elements for each post.
  • When linking to a post with an image, heading, excerpt, etc. use one <a> tag wrapped around everything in the post block (rather than multiple links on every element.

Please use a tool like WAVE or our Accessibility Checker plugin to check your work and tab through it with your keyboard only. We do not launch websites with WAVE errors on them*, and you’ll save yourself time if you resolve WAVE errors before handing the site off to us for review.

* No WAVE errors does not include imported content. This specifically references any custom-built pages or blocks for this project.


>> CHRIS: Welcome to episode 46 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. 

In this episode, we take a deep dive into accessibility-first development briefs, and how our own approach to establishing accessibility requirements on projects continues to evolve. 

For show notes and a full transcript, go to “AccessibilityCraft.com/046.”

Now, onto the show. 

 >> AMBER: Hi, everybody. It’s Amber, and I’m here today with Chris. 

 >> CHRIS: Hey, everyone. 

 >> AMBER: And Steve. 

 >> STEVE: Hey, everybody. 

 >> AMBER: And we’re going to be talking about writing dev briefs, or accessibility-first to dev briefs today, but we’re going to start with a beverage. 

 >> CHRIS: Yes. We are dipping back into the cider well, so to speak, so we sourced a cider called 2 Towns Ciderhouse: The Bad Apple. This is going to be an imperial-style cider fermented with local meadow farm honey, and then aged in Oregon White Oak. 

I was trying to find something that was going to be a little more dry, a little complex, and not just fermented apple juice with nothing else going on. It is very well regarded untapped, so hopefully we’re in for a treat here. 

 >> AMBER: And it says it’s a 10.5% alcohol per volume, so it’ll be very enjoyable. 

 >> CHRIS: It’s a good thing it’s a Friday afternoon. 


 >> AMBER: All right. This is a bottle opener bottle, right? 

 >> CHRIS: Yes. 

 >> AMBER: So shall we crack them open? 

 >> CHRIS: Let’s do it, and I brought a glass today too. I’m being extra fancy, so [crosstalk 00:02:06] pour here. 

 >> AMBER: I thought I heard somebody’s make a noise, but mine didn’t make like a… 

 >> STEVE: Mine didn’t make much of a noise either.

 >> AMBER: Yes, so not as carbonated. 

 >> STEVE: “Boldly crafted in Oregon” on the inside of the cap. 

 >> CHRIS: Oh, yes. 

 >> STEVE: Yes. 

 >> AMBER: So this bottle that we have, it’s more than a pint. 

 >> STEVE: Yes, it’s big.

 >> AMBER: 16.9 fluid ounces.

 >> STEVE: It’s big. 

 >> CHRIS: It’s got an extra ounce on there. 

 >> AMBER: Oh, I’m going to use my handy-dandy WordCamp Denver Organizer bottle opener that also keeps bottles fresh. 

 >> CHRIS: Yes. 

 >> AMBER: Because there’s no way I’m drinking this entire thing. 


By the way, we have just decided, everyone, that at the beginning of January, the next episode, we are going to have videos available on YouTube for these, too, so if you ever decide that you want to tune in and watch so you can see the beverages… We still describe them for people who listen .., and see our funny faces when we try them. 

 >> STEVE: Yes. That’s what I was going to say. Unfortunately, they have to see our faces, too, but… 


 >> AMBER: I mean, sometimes our faces are happy, so this bottle, as we said, it is large, so it is definitely bigger than a regular beer bottle, like, double the size, I guess, and it’s got a red and black label with a tree on it with a single apple, the bad apple.

 >> CHRIS: It’s the bad apple that’s left. 

 >> AMBER: And it is a nice golden color. 

 >> CHRIS: Yes, nice golden color, nice bubbles. They’re just kind of lazily floating up and sticking to the sides of my glass. 

 >> AMBER: It kind of looks like Champagne or like a sparkling wine to me.

 >> CHRIS: Yes, I was going to say it’s a little prosecco-y there. It’s kind of what the bubble pattern reminds me of. 

I love the nose on this. It’s very mineral-y, very tart. 

 >> STEVE: Smells like beer.

 >> AMBER: Really? It smells like apple to me. I don’t get beer. 

 >> STEVE: I get beer. 


 >> CHRIS: There’s definitely that yeasty smell. I’m going to take a sip. 

 >> AMBER: Yes, me too. All right, let’s see. 

Ooh, I like this. 

 >> CHRIS: Ooh. 

 >> STEVE: Oh, well, you get the apple there, big time.

 >> AMBER: Yes. It tastes like apple juice with a little bit of a kick. It’s got a really long neck. I don’t know if we can pick this up on the microphone, but, like…

 >> CHRIS: Is it, like, glugging a little bit? 

 >> STEVE: It’s, like, glug, glug, glug. [chuckles] 

 >> AMBER: Oh, yes. I couldn’t hear that on the microphone, but… 

 >> CHRIS: That’s part of the experience, I think. 


I got to say, I really enjoyed my first sip. It’s got that acidity. The bubbles aren’t overpowering. I taste a little bit of that white oak. Not that I can discern different oak flavors. My palate isn’t that developed, but I definitely get a little bit of that, like, this is sodden wood for a while kind of flavor. 

 >> AMBER: Well, hold on now. I’m really curious about that. 

 >> CHRIS: And it’s apple-y

 >> AMBER: What is it that you’re tasting that tastes like.., because when things are, like, oak flavored or whatever, I never know. Like, what would I want to look for in my mouth to, like… 

 >> CHRIS: So it comes from years of tasting, like, oaked versus un-oaked chardonnays for, like, when I was in restaurants and wine-tasting school, but basically, it’s if you get notes of caramel or vanilla, and not necessarily on the nose, but also on the palate, and there’s like a woody flavor, not to the extremity of chewing on a toothpick, but, you know, there is just this undertone if you kind of look for it underneath the apple. 

I’m getting a little bit of that woody complexity versus just it being like a stainless steel fermented apple drink that has never had any contact with any other element in nature, right?

 >> AMBER: OK, I think I get it. What I like about this is it’s not really sweet at all. I mean, it has a little sweetness, but it’s not… 

 >> STEVE: It’s a little sweet.

 >> AMBER: Well, I mean, yes. It’s not like a beer, like, there’s no bitter. When I think of apple juice, like, actual apple juice, it’s, like, so sweet, and when I saw the color of this as yellow as it is, I was a little nervous that it was going to be very apple juicy, and I guess I do kind of like if I take a sip and I hold it in my mouth, towards the end, I maybe get what you’re talking about where it’s like a little more woody or more organic, and that’s where in the apple juice, I’m like, “Too sweet,” and so it starts sweet, but then it ends dry, almost. 

 >> STEVE: Yes, yes, yes. 

 >> CHRIS: Yes. Just straight apple juice is always way too sweet for me.

 >> STEVE: It kind of has that, like, stickiness of apple juice on your lips, you know. 

 >> CHRIS: There’s definitely a little residual sugar in there. 

 >> STEVE: Yes, yes, yes. It’s not bad though. 

 >> CHRIS: Yes. Yes. 

 >> AMBER: I like it. I think I would get it again. Would you get it again, Steve? 

 >> STEVE: Yes, if you send me it again, I’ll… 


 >> AMBER: You’ll drink it? 


 >> CHRIS: [playfully] “Quiet, kids. Daddy’s having his apple juice.”

 >> STEVE: Yes. 


“It’s been a rough week, kids. Daddy needs his apple juice.” 


 >> AMBER: Well, OK, so I do want to ask, just a quick throwback because we’re recording this after Thanksgiving, did anyone’s children try the Turkey Gravy Soda? 

 >> STEVE: Yes. 

 >> AMBER: And what was the verdict? Did they think it was as horrible as we did, or did any of them surprisingly like it? 

 >> STEVE: Yes. We gave it to some family member. They didn’t like it. 


 >> AMBER: But was it amusing? 

 >> STEVE: Yes. I mean, it’s a novelty, you know, just to bring it and bring it out, you know. Everybody’s, like, “Ew, gross,” you know? 


 >> AMBER: Yes. Chris’ aunt and uncle and the cousins and some of our kids tried sips of it. I don’t think anyone drank an entire bottle [chuckles] or got anywhere close to it. 

 >> CHRIS: When I left at the end of the visit, there were still three bottles sitting on the counter, and I was thinking to myself, “I’m just going to leave those there.”

 >> AMBER: “We’ll let them throw them away.”

 >> CHRIS: “We’ll let them throw them away.”


 >> AMBER: I very much appreciate that we’re back to normal beverages [laughs] and not, you know, weirdly meat-flavored beverages, but every once in a while, it’s fun to be silly, I think.

 >> CHRIS: Yes. 

 >> STEVE: Yes. 

 >> CHRIS: Yes, you guys just do, like, a couple of year. I think that’s a good cadence. We had Hello Kitty earlier this year, and then we had the Turkey Soda. 

 >> AMBER: Well, I will pick Hello Kitty Soda over Turkey Soda any day. [laughs] 

 >> CHRIS: Yes. 

 >> AMBER: So I thought it would be fun to make this episode a little bit of a build in public, if you will, but we’ve been talking about how we need to, as we move into 2024, revise what our process looks like for writing dev notes. We’ve gone through quite a bit, and we’ve sometimes had some challenges about communicating what needs to be done from an accessibility perspective to the devs, and then getting it back? That way. Like, even when we thought we communicated, it didn’t always come back that way. 

I know we were talking about, maybe we should just chat about this and figure it out, and I was, like, “Why not do it in a podcast episode?” [chuckles] 

 >> CHRIS: Yes. 

 >> AMBER: So that’s what we’re going to talk about today.

 >> STEVE: Let’s do it. 

 >> AMBER: All right. 

 >> STEVE: Yes. 

 >> CHRIS: I know when we were initially focusing on this, we spent a lot of time thinking about, what are all the things that we can do before dev to try to make it so that whoever’s building it creates fewer accessibility problems in their work? Not necessarily always code, but things that we can look at in content and in the design and even from discovery forward, like, how we even structure the thing we’re building. 

I know we came up with a checklist, but, Amber, as the author of said checklist, do you want to talk about some of the things that we do? 

 >> AMBER: Yes, yes. This is what we call our shift left accessibility checklist. 

I’ll say, broadly, one of the things that we’ve done more.., and this has come into play in two fold. One, just because as we have moved into building more enterprise websites, we needed to have more attention to detail, but also because of accessibility, just in general, we’re creating more designs in Figma than we ever were. 

It used to be, you get a homepage, and a blog archive, and a blog post, and just an interior page, right? Or it’d be like four to seven designs per website, and now sometimes we have websites where there’s about 30 designs, and then if it’s like an application or something where we’re like, “Oh, and there’s going to be a modal, and here’s all of the possible options with a modal,” and I felt like while it does definitely increase the discovery and the design timeframe, and thus the budget for the client, from an accessibility standpoint and just a general, like, delivering a really high-quality website, I think having more designs and not leaving it up to developer has helped because we’re defining more. 

Our designer Jacob is great. We spent a lot of time talking to him about things, so when we’re talking about, you know, what’s in that checklist on content. There are some things that he just knows already. Like, he generally looks for color contrast as he’s designing, but I will look for it also, because every once in a while, he will miss something, and he’ll have… Not on the main, but it’ll be, like, “Oh, the hover state is orange on white,” and I’m, like, “Yes, that fails.” Right? So we need to come up with something else. Or sometimes he’ll miss the color alone, so I’ll spend time looking for that to make sure, like, are there not just a color change on links, but we have a state change too, so if the link was underlined, then in the design, we’re showing a hover, and we’re showing that the underline went away, and the color changed. 

So we’re doing a lot of that kind of stuff. I’ve been trying to get better about having him be consistent with his heading levels. I think that’s something that’s really hard, but then if he doesn’t, then I’m, like… One of the last, like, two projects I’ve actually gone through in Figma and put comments have been like, “H2, H3, H2, H3.” Right? Like, I would literally defined what they should be in code, because on a certain page, the sizing didn’t match, for whatever reason. Or if something’s really big, putting on the file that it’s not a heading just needs to be like large-size text or something using the WordPress large text sizing in the block editor.

So those are some of the things that I think we’ve been looking for before we even get to dev. Are there other things that I’m forgetting, Steve? 

 >> STEVE: No. I think those are some of the big things, and I think what’s good is we’re doing, like, intermittent dev checks of the design as well. Like, Amber will alert me to do a pass on the designs to make sure there’s nothing that kind of stands out from an accessibility standpoint, and even from a complexity standpoint, right? Or, you know, things don’t always translate. 

If you’re using a plugin to achieve like an Instagram output, and then the design has a kind of a design that was not achievable with that plugin, you know, kind of to comment on those things, and, like, you know, to have discussion about whether or not to use modals for everything, or accordions, tabs, like, should it really just be a link to another page? Because from an accessibility standpoint, the more dynamic components that you make like that, the more complexity you’re adding to your dev process. 

 >> AMBER: Yes, which means the budget have to be bigger for clients, so if you’re trying to keep your profit margin at a certain percent and make it feasible for certain client budgets, then sometimes you have to make choices to limit, and be, like, “OK, well, yes, we could design it this way, but maybe it’s not best.”

 >> STEVE: Yes, totally. I think the big things, like you said, are color contrast, heading sizes. I’m speaking from translating from design to development, and I think, a lot of times, that’s where our communication has probably broke down the most. It’s like on font sizes and headings. 

So I actually think, in the design, where you’ve gone through the design and put all the, “This is an H1, this is an H2,” right? Because a lot of developers that are inexperienced with accessibility will use the font size as the indicator of which one to use, not the structure of the page.

 >> AMBER: Yes. 

 >> STEVE: So now if you a developer that’s working on a project that has been through several projects with you and is very trained on this, they can make those decisions pretty good themselves, but I think it’s still good that we go through and we write it out exactly what it should be so there’s no question. 

 >> AMBER: Yes. I’m a little skipping ahead in our notes, but just thinking about this conversation about how we’re going to change, it might be useful to give our listeners a background on where we’ve been and some of the things we’ve tried, and on how to communicate about accessibility to developers.

This year has been sort of an interesting year for us because we’ve had more contractors work on websites, or new developers work on websites as we’ve grown the team than we have in the past. I was, like, I’ve been trying to refine, but it’s hard. 

Steve and I have been working together for seven years. 

 >> STEVE: Seven and a half years, yes. 

 >> AMBER: Yes, so things that I was just, like, “Oh, I don’t have to tell anyone this because it just happens that way.” [chuckles] 

 >> STEVE: Yes. 

 >> AMBER: But I realize, you know, sometimes, when I think it’s intuitive, it’s totally not, and that’s not on the person. That’s probably on me for just assuming it. Or it’s just you and me, like, having worked together, we just know. 

SPEAKER 1: This episode of “Accessibility Craft” is sponsored by Equalized 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 a 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 PPI 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 “EqualizedDigital.com/accessibility-checker.” Use coupon code “Accessibility Craft” to save 10% on any paid plan. 

 >> AMBER: We had Codable do some websites, and devs do Codable, and we love Codable, and with that, you have to submit, like, a brief in order to get your pricing, so I created this whole Google doc that was sort of like a template that we could modify, because I needed more characters than would fit in Codable’s little box, and we can maybe talk more about some of the things we have in there in a little bit, but then we have Dev Notes in Google Doc, because I had to do that in order to even get a quote on something that I was going to have a contractor build, but then for our in-house devs, it’s like, “Well, why is it in a Google doc?” 

So for a while, it was like in Basecamp on, like, Kanban tiles or to-dos, but then also, I’m going through the Figma file, and I’m putting comments on things in the Figma file, either using Figma comments, or sometimes I’ve put text box to the side and I’ve written notes there, so these are all these different places where I’ve tried to communicate how this design is supposed to be built, and some of the expected accessibility functionality, and I think that’s been a challenge for developers. 

 >> CHRIS: It’s a lot of information. It’s a lot of signal versus noise, and, “What should I focus on?”

 >> STEVE: And GitHub is a part of that too. Once devs starts moving, GitHub gets introduced, right? And we can comment on PRs inside of GitHub, so it’s like there’s a lot of areas where they can get notifications, or they have to keep up with notifications, right? Because even in a Google doc, you can add comments and stuff. I mean, that’s definitely been a challenge to try to find one project management workflow, and we’ve been trying new things out. 

 >> CHRIS: To that end, one thing that I know we were talking about even recently is, like, could we get almost everything into GitHub? But then it’s, like, but then what does the client see? Does the client have a GitHub account, right? And it’s like it’s this weird rock and a hard place that I feel like we’re caught between, where we need to honor our devs need to have as few channels as possible to monitor so that they can spend more time just building the thing, but we also need our customers to understand what progress is being made, and what we’re working on in the moment, so they don’t get weeks of silence and can’t check in. 

Yes, it’s a challenge, and I don’t know it’s a challenge that we’ve completely solved. 

 >> STEVE: Well, from the development side, we have our Accessibility Checker plugin, right? And that’s a piece of software that is worked on entirely almost in GitHub for the most part, right? And everything can happen there because, you know, you don’t have that client feedback. 

Websites are this massive thing of back and forth, multiple change requests, and questions on that, so it’s very difficult, but we’ve tried some tools out. 

Chris implemented some tools where the client can submit change requests right on the website, and it automatically creates a GitHub issue. Now that requires… 

 >> AMBER: So that was “Marker.io,” for people who are listening. 

I thought that worked well. Did you think that was OK?

 >> STEVE: It did. You give the customer a tool to use, and it’s very easy to use, so they just click right on the website where they went out of comment and they had a comment, right? And it goes right to GitHub. 

 >> AMBER: What I liked about that was it had a screenshot. It had their operating system, their browser, their, like, [Inaudible 00:23:41].

 >> CHRIS: Even the resolution. 

 >> AMBER: Yes, the resolution. They had to give their name and email address, so we had multiple people, so we had a lot more information than we normally have, because sometimes you have to go back and be, like, “Well, we’re not seeing this. What’s your browser? What’s your…” Right? So it did that by default.

 >> STEVE: So that did require a little bit of maybe unintended work on our end to then go through those from a project management standpoint and filter those out, like, what’s in scope, what’s not in scope. We created a Kanban board, where we could filter those out, and then we’d move things in progress that the… 

 >> AMBER: In GitHub, a Kanban board. Yes.

 >> STEVE: Yes, so another Kanban board inside of GitHub. 

 >> AMBER: Sever from our Basecamp Kanban board. [laughs] 

 >> STEVE: Yes, yes. 

 >> CHRIS: Yes. Which at that point, we were in QA, so everything in the Kanban board and Basecamp was linked in the “done column.” It’s like the Kanban moved somewhere else, which is weird, right? And it’s like, clearly, we’re constantly iterating and trying to find ways to make this more efficient. 

The other thing that was interesting with Marker, in like a crappy way, is when you have a customer with a team of five to six people entering issues. We had instances where five or six people entered the same issue, and so it’s like Amber’s having to go through, and Kolei [phonetic] would be, like, “Oh, this long list isn’t actually that long. It’s like a fifth of as long as it looks because there’s a shitload of duplicates.” Right? 

 >> AMBER: So for everyone who manages client feedback, here’s what I’m going to tell you. On this website, in round one, we got like 500 issues created with this tool, but I think about 390 of them were duplicates, and I was, like, “Oh, man.” Because, normally, of course multiple people from the company look at it, but if they’re giving you a Google doc or a spreadsheet, they can see what other people have entered, and they don’t want to enter the same thing, and I did, at one point when I saw so many duplicates coming in, I asked them, I was, like, “Do y’all have GitHub accounts? Because I want to invite you to this [Inaudible 00:25:43],” just so they can look at it, and they were, like, “No, we’ve never used that,” and I was, like, “Well, of course you don’t.” Actually, I don’t know why I asked that question. [chuckles]

 >> STEVE: Yes, yes. 

 >> CHRIS: Yes. We definitely had issues, too, where even one person would enter the same issue over and over that was like a template thing on different pages, but it was all the same. 

 >> AMBER: Yes. They didn’t realize they only had to report it one time. They didn’t have to report it every time they saw it on all the different pages. 

 >> CHRIS: And so some of this is, like, we tried out the tool for the first time, and we’re learning now how to communicate with the customer about that tool better, so I think next time the instructions will be beyond “Just click this button and then highlight your issue.” It’s going to be “Tell us about a problem once. If you see it again, don’t enter a new one.” Right? Like, there will be some additional instructions that get relayed for sure. 

 >> STEVE: Yes, and they don’t always understand that fixing this issue fixes it everywhere. 

 >> AMBER: Yes. They think it’s [Inaudible 00:26:43]. 

 >> CHRIS: Yes, it’s not their fault. It’s not their fault. It’s 100% our fault that we had that many issues and then only ended up with 20% of the total number after we cleared all the duplicates out. 

 >> AMBER: Yes. OK, wait, so we went on a little bit of a tangent, which is cool and fun, but let’s go back to Dev Notes. 


So I want to talk about this idea of what needs to be communicated upfront because this is a thing that we’ve learned. 

I’m just going to say this for everyone. I have a link in our show notes, which I can probably clean up and we can put in the show notes for the podcast for people to see the accessibility… I’ll just have the accessibility section for this, but I actually think it might be useful for us to literally go through this, and we can like round-robin it, like, point by point, because the accessibility section on this Dev Notes doc, it’s like things that we’ve added to every time we saw a problem, and I was, like, “I’m just going to tell people upfront about these” and be, like, “This is my baseline expectation.” 

Would it be weird if the three of us went through the main bullet points, and we just each read one until we get to the end of the list? So people who are listening know what are the baseline things that we tell a dev before they even start or even quote a project. Can we do that?

 >> CHRIS: Yes, and I’m cool that. I can start, and then we can just go to Steve, and then you, and then back to me, but I think I’ll start with the intro paragraph, which it just explains, “Accessibility is important to us and will be a big part of our test and debug process.” So right there, we’re giving them a heads up, right? 

We are going through the accessibility section, right, Amber? OK. “We’ll be looking at HTML output in your code. Make sure it’s semantic HTML. I’m being upfront about this because it would be ideal if you code with accessibility in mind from the beginning. That will reduce the need for us to have extra rounds of revision, or you needing to recode things after the fact to meet standards, which is frustrating for everyone.” 

So we’re being very upfront, saying we expect you to build things that output at semantic HTML. If you don’t do this, it is 100% coming up in subsequent phases, right? 

 >> STEVE: OK, so let’s read through the bullet points. I’ll take the first one. 

“Buttons will be coded as buttons, not divs, spans, or A tags.” 

 >> AMBER: Yes, so then the next one is.., and I might read two right here, just because I think they kind of go together, but it says, “Everything interactive will be keyboard focusable. The whole website needs to be usable with a keyboard alone. Use your tab key to check this,” and then, “Every focusable element needs a visible focus outline, and we a specify two-pixel solid with a two-pixel offset that sufficiently contrasts with the background.”

I’m giving Chris the hard one. 


 >> CHRIS: So the next bullet point is all about any sort of pop-up or modal, so “Lightboxes, pop-ups, and modals will manage focus well, i.e..,” and we’ve talked about this. I think we had a whole podcast episode about this, didn’t we? 

 >> AMBER: Yes. 

 >> CHRIS: So we should link to that in the show notes, but basically what we specify is that when opened, focus will move into the light box, pop-up, or modal. “There is no way to tab out of the lightbox, pop-up, or modal without closing it. After closing it, focus returns to the element that triggered it.” That’s a really common thing that people miss, which is returning focus to where they were before. “The ‘escape’ key should close the element when pressed.”

Man, I wish everybody did this, because it’s usually the first thing I try when I want to get rid of a modal, and it only works three out of 10 times, if that, and then “Screen readers should announce if a modal has been opened.” So those are our modal requirements. 

 >> STEVE: All right. “Any read-more link will have an ARIA label that includes the post title, i.e. ARIA-label equals “read more of post xyz.” 

 >> AMBER: Yes, and then we have some sub items under there. 

 >> STEVE: “This applies to all ambiguous links: “learn more,” “more,” “download,” et cetera. You can use the screen-reader text format plugin to add screen-reader text in the block editor for ambiguous links in blocks.”

So that’s an add-on, right? That’s a plugin in the plugin repository, screen reader text format. Is that the actual name of it? 

 >> AMBER: Yes, that’s the name of it. It comes from Reactive. It’s free. That’s always in our base installs that we have, so even when we go get a developer off Codable, they’re building in our base, and so we’re telling them, “In some scenarios, you don’t code this. You enter it in the editor.” Because a lot of developers maybe aren’t aware of that tool, and that’s a really great tool which we can definitely add to our podcast or our show notes for this, so this was a big one that has come up a lot. 

It’s funny, because this list we’re reading right now, everyone, we’ve added to this list every time we find problems. 

“There will be no empty links, buttons, or headings. If a button or a link contains an icon, the icon has to have proper alternative text. Or if it’s hidden from screen readers, then there has to be an ARIA label or a hidden screen-reader text communicating the button or link’s purpose. If you code a custom ACF Block to match the design, assume that any field could be left blank.”

This goes back to those empty headings. “As such, you have to use conditionals when fetching the meta or other information. Don’t output empty tags or a heading with no content following it, if the meta field is left empty in the admin.”

That surprises me so much, and we should take a brief break from reading this list, because, Steve, I’ve seen so many developers not make ACF Blocks or page templates with ACF with conditionals, and I don’t understand that. Why?

 >> STEVE: Well, it shows lack of experience. I mean, really, because you want to do a conditional check on those all the time, right? Because it could be an array, and it could be a group field that you’re saving as an array, where one of the values is filled in, but the other isn’t, right? So then you get an undefined index error, right? 

So I think it just comes back to experience. Like, they’re not running any kind of error handling. They don’t have query monitor running in their website that lets them know, “Hey, there’s an error here,” right? 

A lot of times when developers are building websites, like, they’re taking the content and they’re plugging it right in, so they’re almost evaluating a best case scenario right there. All the fields are filled in and it works, and then it gets to us and to the content people, and they actually use the block, and then there’s errors on the page or the block breaks, right? You get that nasty little warning in the block editor that the block is not working, and if it’s ACF, they’re probably just grabbing the field, right? They’re not doing a “if get field,” right? They’re not checking, and that just comes with experience. 

 >> AMBER: Yes. I think I’ve even seen that, too, even outside of the custom blocks scenario, like on custom post types, where you’re frequently adding… Like, even like a team, for example, and the design shows a fully filled out with, like, “This person has a phone number that’s visible, and this person has, you know, a link to Twitter,” and all these things or whatever, but then in reality, not all of the team members have all of the different pieces of meta. 

I’ve seen before where it’s just like.. 

 >> STEVE: Basing. 

 >> AMBER: Yes. There’s a literal link there with nothing in it, like, it’s an empty href that goes to Twitter. It’s still visible on the page, but it doesn’t go anywhere because they didn’t put, like, a Twitter handle in for that person or whatever, so yes. 

 >> STEVE: Yes, it comes with experience, and I think websites are kind of high pressure and fast moving, right? So sometimes, you know, corners are cut. 

If you’re building an application, you got a little bit more time, and there’s a little more thought process that goes into how this can be worked, and a lot of times, if you’re building a WordPress plugin, you don’t know how it’s going to be used, right? Like, you don’t have the perfect scenario, so you do consider those things more, but yes, I think it just comes with attention to detail and thinking forward, right? But this has definitely been a big issue for us, like, with some newer devs. 

 >> AMBER: And it’s interesting because it’s one of those things that you just don’t think about as much as causing accessibility issues, but it really can if you end up with empty heading tags, which aren’t even visible on the page, but then a screen-reader user comes along and they go to their headings list because they’re trying to figure out how to jump through, and there’s multiple H2s that have nothing in them, and that can really cause a problem. 

 >> STEVE: Yes, totally. Good code review probably can catch some of this stuff, right? But it just depends on how your company is working at that time, if somebody’s available for code review. 

To be honest, in a small company, sometimes.., sometimes I’m not always available for code review. Or I put trust in that developer to not require them to attach me to review it, right? And then sometimes we get down the road and we’re, like, “Oh, some things were missed.” 

 >> AMBER: Yes, so speaking of headings, that’s the next thing on this list. 

 >> CHRIS: So headings being used in the correct order, which we alluded to earlier in the design note portion. “We can provide a view of the design that indicates the expected heading levels if you need this,” and Amber is saying we often provide that upfront in our comments. It’s just sometimes I think it’s down to whether or not they see those comments, right? And you will likely need to style heading levels multiple ways to fit the design because we’re special and we’re fancy. 

 >> STEVE: Yes. 

 >> AMBER: Yes, so what’s next? I think we have three more. 

 >> STEVE: So I’m up? 

 >> AMBER: Yes. 

 >> CHRIS: Tables. Another podcast episode. 

 >> STEVE: Yes. 


It’s like a flashback. It’s like those old sitcoms where they would have the flashback episode. This is our flashback episode. 

 >> AMBER: Yes. 


Well, it’s good because this is going to come out at the end of the year. It’s like calling back to things we talked about this year, but also for all of our listeners, this is an inside at, “How Amber comes up with podcast topics.” 

 >> CHRIS: [crosstalk 00:38:16] What’s making Amber mad right now? 


 >> AMBER: “Things developers are doing wrong.” We’re going to talk about it on the podcast, and add it to this list. 

 >> STEVE: That’s right. There’s pesky developers.

“Any data table, pricing tables, information tables, et cetera need to be coded as actual HTML tables. It is almost never appropriate to use divs. If you want to use divs for a table, check with us first, and note that you’ll need to add ARIA attributes to indicate that it is a table.” 

 >> AMBER: Yes. There was a whole podcast episode on how mad I was about a table that was coded with divs. Go listen to that for more info. 

The next one is, “Groups of posts should be coded in unordered lists, not divs, and should contain article tags in the LI elements for each post.” 

You have something to say about that one, Steve? 

 >> STEVE: This was kind of a hard one for me. When we first started doing it, I was kind of like, “Really?” I needed to put a featured post or related post, right? 

 >> AMBER: Yes, related post section at the bottom. 

 >> STEVE: Yes. I was, like, “I really got to put that in a list?” But I guess it makes sense because it reads out how many there are, right? 

 >> AMBER: It also allows them to skip past them. 

 >> STEVE: Oh. 

 >> AMBER: Because you could get to a list, and instead of choosing to go through all, you could just go to the bottom of the list. 

 >> CHRIS: Yes. 

 >> AMBER: But if they’re not grouped in that way, you’re forced to go through… Which if there’s only three at the bottom of a post, maybe that’s not as big of a deal, but what if you’re on the homepage and there’s six? And you really just want to get further down the homepage? I mean, I don’t know. 

The reality sometimes is that screen-reader users don’t go top to bottom of every single page, right? Unless they’re having a hard time finding something. If they come to a website with a specific goal in mind, then they’re probably hearing all the headers first or that sort of thing, and then jumping to that section, and moving around. 

If you ever want to hear what Alex thinks about going top to bottom, you should ask Alex Stine that, because I test that way and he thinks it’s hilarious. [laughs] He’s, like, “Yes, no one goes top to bottom.”

That said, the benefit of a list is it allows people to skip and to know what to expect, which is important. 

 >> CHRIS: I was just going to say, it’s a total tangent, but the way that Alex sees code, pages just blows my mind. 

I listened to the testing episodes, which we put them out on the podcast, too, where it’s his screen reader going through things, and he always starts at his normal speed, and he slows it down, which I think is such an amazing flex on his part, like, just how fast he moves through stuff, and like, Steve, things you’ve told me about moving through the code base. 

I’ve actually been on sales calls with people who listen to our podcast, who are like, “I listened to the episode with this Alex guy, and that kid is a genius.” I’ve heard that from multiple people, but anyway, I’ll go to the last bullet point here. 

 >> STEVE: Yes. Alex’s ego doesn’t need to be [chuckles] stroked anymore. He knows we all love him, and he’s a genius. 

 >> AMBER: We do love Alex. 


 >> CHRIS: So, “When linking to a post with an image, heading, excerpt, et cetera, use one A tag wrapped around everything in the post block rather than multiple links on every element.”

I literally don’t understand that, so someone help. 


 >> AMBER: Well, good thing it’s notes for a developer, not notes for salesperson. 

 >> CHRIS: Yes. 

 >> STEVE: Do you understand that, Steve?

 >> STEVE: Yes, yes. If you have your latest post, you want the whole post wrapped in that link, right? 

 >> AMBER: In one link, yes, so it’s like a card style is kind of what we’re getting at, which maybe it would be more clear if I wrote that on there. Yes. 

So these are all the things that I feel like we’ve commonly come across, and I’ve just like collected them into a list that I’m, like, “I’m going to give these to developers up front.” 

I feel like, generally, it has helped, but not always. There’s been instances where they got it, and then we still saw these problems, and I don’t know if there’s any way to solve for that. Maybe we give them a quiz? 


 >> STEVE: I think we would take it a step further than this. The notes we’re looking at right now was a project that I ultimately ended up working on after we had tried it with another developer, but I think our notes will go to Basecamp, like, we’ll create like to-dos in our Kanban and Basecamp, and a lot of times, on those notes, especially if it’s a newer developer and it’s kind of a tricky. accessibility thing… Even if it’s not accessibility, but just functionality, we’ll add even more notes on how to do it, because most new developers that we work with have no idea about how to code a modal or accessible tabs, right? And we even put in links to examples, and it still comes back not quite there. There’s still a back and forth, but… 

 >> AMBER: You think the problem is that this is a Google doc, and then we also have the Basecamp Kanban where… The way we handle that in our dev is that we find the units of things, and it gets a little granular, like, “Register the post types, register the custom fields,” like, those are separate items, right? And then it’s like, you know, “Style the page,” and each page has its own thing and stuff. 

So it’s the problem that we have these here and not on that, and so if I want better results, I need to not have it in a Google doc, and I need to, on every single page that has a modal, pull in that expectation related to modals every time. That’s what’s hard for me. I’m, like, “I just want there to be one thing,” and you’ve reviewed that, and you’ve been told that, and you said, “OK, I got it,” and then you apply it to everything, but maybe that’s not the way a developer works when you’re in the flow. 

 >> STEVE: Yes. I think it’s hard, and I think every agency works differently, right? I think that developers that come into our agency definitely have a ramp up in the learning process. 

Like Amber stated, it’s been seven and a half years that we’ve been working together, right? And after all that time, when it’s a small team, you really do start to kind of be able to finish each other’s sentences per se, right? 

 >> CHRIS: Yes. 

 >> STEVE: And I used to always joke that when I started working with them, it was, like, a developer is trying to meet deadline, right? So there’s always this.., because you could spend forever developing anything to make it perfect, right? There’s always a drawback between the timeline and the time you have to do it, and the time in the day, and the requirement, right? 

So sometimes, you’re, like, “OK, well, I’ll just…” You know, that’s close enough, right? But the joke here is that, after some time working with Amber, in my mind, I had this little angel or devil, I don’t know which one it was sitting on my shoulder. 

 >> CHRIS: It was a little Amber. It was just a smaller Amber on your shoulder. 

 >> STEVE: It was a little Amber sitting on my shoulder. I knew if I didn’t, she’s going to find it. She’ll find it. She’ll find everything, right? It’s like, if I don’t do this right, she’s going to find it, and I’m going to have to redo it, right? 

So I think when we get new devs in, definitely, the first couple of projects, it’s learning. There’s a lot of learning, and a lot of people don’t take accessibility to the level that we take it, right? 

 >> AMBER: Hopefully, they will eventually. 

 >> STEVE: Right. We tried to with a 100% practice that if it’s not accessible, it’s broken, like, we’re not going to launch. I mean, accessibility is our company, right? It has to be accessible, but I think I have the time to catch on, yes. 

 >> AMBER: It’s funny you say that, that you visualize me. 

I did an interview for the WP Constellations podcast, which is StellarWP’s podcast with Michelle and Jeff, and Jeff said that he uses Accessibility Checker, and he’s, like, he just envisions that it’s me inside his website shouting at him, and I was, like, “That’s horrible. I was, like, maybe the cheerleader cheering you on when it gets one…” [laughs] 

 >> STEVE: That’s when you go, “It’s actually Steve’s code yelling at you.” 

 >> AMBER: Yes, “Steve is the one who’s yelling at you, not me.”


 >> STEVE: Or Matt, our other developer, but, yes.

 >> AMBER: Yes, Matt. 

 >> STEVE: Yes. 


 >> AMBER: I mean, we all work collaboratively on what the rules should be, and whether or not they worked. 

 >> STEVE: Oh, yes, totally. Yes. 

 >> AMBER: But also, let’s be real, some of those rules are just like it’s WCAG yelling at you. 

 >> STEVE: Yes, yes, yes. Well, OK, so yes, it is Amber. She makes sure those rules are pretty tight. 

 >> CHRIS: I was just going to close us on a thought because I know we’re getting close to time anyway. It’s a process, right? And so we’ve spent all this time listing through these requirements, and I’m just sitting here thinking about, like, I’ve had conversations with other developers who have worked for other agencies, and they have described to me, like, “This is so different,” right? Like, “What your process sounds like is so different.” This is the developer talking to me, and I’ve had several conversations like this.

It’s like I’m literally handed a design and nothing else, and told to go make it happen, right? And that’s the brief. That’s the requirements. I’m given nothing else, and so what I would say is… 

 >> AMBER: [jokingly] I’m a control freak.

 >> CHRIS: What I will say is.., and I’m not saying that’s a bad thing. I’m saying, for the agencies who operate in that way.., and I don’t know that it’s wrong to operate in that way. You just have to hire good and competent people who you really trust, right? But as you start to introduce these requirements, maybe do it gradually. Maybe have some conversations up front rather than dumping all this on someone. They might feel overwhelmed, especially if they’re used to just being handed a design and told “go.” Give them some context, give them some information, maybe drip it out to them gradually. 

I’m just advocating for progress over perfection, and I think that’s the name of the game, and that’s just based on me trying to be empathetic to other developers I’ve spoken with, where they’re just told to go create an outcome with no other strings attached, right? 

 >> AMBER: You know, I might play a little bit of devil’s advocate on that. 

I think at some point, especially if you’re an agency owner, or a project manager, or someone who’s responsible, if you’re deciding that accessibility is important, you have to draw a line in the sand, and you just pick a project, and ideally, you increase the budget on that project with the client, right? 

 >> STEVE: Yes. 

 >> AMBER: And it’s going to be accessible, and if you take this list, which we’ll put in our show notes, and we read out… If you aren’t visiting the show notes, you heard it, right? And this is like our baseline bottom expectations. 

As long as you figure out the right way to communicate that.., and obviously, as we’ve said, we’re still working on it, because I don’t know if the Google doc is the best way, and, like, I need to move it more into the other places where the developers are working because they maybe forget to reference it, but you have to, at some point, just say, “This is what we’re doing, and this is expected…” I mean, don’t tell them in the middle of the project. That’s when it sucks. No developer wants to hear, at the very end, “Oh, and this is accessible, right?” 

I mean, how many of us have heard horror stories where clients say that at the very end? 

 >> CHRIS: Those people end up being our clients.


 >> AMBER: Yes, but I think if you say it out at the beginning… I don’t think it’s, like, “Oh, on this project, we’re going to make sure there’s no ambiguous links, and then on the next project, we’ll make sure there’s alt text.” No, just decide. “This project is going to be an accessible project,” and I think you have to sort of be willing to learn and eat it a little bit. Totally true. I think we all did. We’ve all been there, right? Whether it’s on accessibility or something else, where we were, like, we didn’t do as well as we thought we would, or we maybe felt like we worked for $5 an hour by the time the project was done, right? But, you know, it didn’t happen again, and we learned stuff, and I think picking a project and doing that, and then figuring out how to communicate. 

The thing that I’ve been doing is having this centralized list that when I see a problem, I don’t just open the GitHub issue. I then go back to the list and I add it, because my idea is I want to make sure it doesn’t ever happen on any other future project, so having that set up that you’re constantly going back to what your dev notes are and updating them to meet the new standards, or to, like, “I never thought I had to tell a developer that all images should not be background images, but, hey, I did, so I’m just going to tell all developers that now,” and most of them are probably, like, “Why are you telling me that? This is dumb.” But I ran into someone where I had to say that, so yes. 

 >> STEVE: And I think it pushes accessibility forward. We’re training developers when we require these things, and we’re pushing them to be better, right? And I’m sure after, you know, if we just bring in a contractor to work one-off, after working with us a couple of times, they now have a skill set that they can take with them that they got through having to learn that, and I think it’s vital. 

The impact of whatever they touch in their career here or their career somewhere else should be about making the web more accessible. 

 >> AMBER: Yes. 

 >> CHRIS: I’m such an incrementalist, but you both may have convinced me that just going all in with both feet is the better option. I don’t know. I always get so empathetic of other people’s plights and struggles that I have trouble, but maybe jumping in is the right way to go.

 >> AMBER: Yes. Well, we’ll be back in two weeks with another conversation episode. 

In the meantime, if anyone has thoughts for us about how you write your dev briefs, I would love to hear from you. As we’ve said at the beginning of this episode, we’re trying to refine ours so they’re not in a million different places. You can reach us on Twitter or in the Facebook WordPress Accessibility group and let us know. 

 >> CHRIS: All right. Bye everybody. 

 >> STEVE: All right, see you. 

 >> AMBER: 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 help make thousands of WordPress websites more accessible at “EqualizeDigital.com.”