Ready to get started?Download WordPress

Make WordPress Accessible

Updates from Joe Dolson Toggle Comment Threads | Keyboard Shortcuts

  • Joe Dolson 9:02 pm on April 15, 2014 Permalink | Log in to leave a Comment
    Tags: ,   

    Update on accessibility-ready theme tag 

    We’re gradually working the kinks out of the process. There was an oversight in the automated process that added the accessibility-ready keyword to themes, so that only new themes were automatically getting the keyword, and not updated themes that added it. That’s been fixed, which will improve our ability to note themes that need to go through the review process.

    There’s a lot of support for the process, and the theme review team is invested in making this work, but I could use some backup in actually doing the reviews. Even if you don’t have the accessibility background, let me know if you’re interested: I’m happy to provide training to make sure you’ve got the knowledge it takes to do this review.

    • David A. Kennedy 4:00 pm on April 16, 2014 Permalink | Log in to Reply

      @joedolson I can help out with this once I finish up a few other projects. It’s a good place for me to contribute since it’s theme-centric. Feel free to reach out to me with details on how to get started.

  • Joe Dolson 11:14 pm on February 8, 2014 Permalink
    Tags: ,   

    Want to participate in reviewing WordPress themes for the accessibility-ready tag? There’s a trac keyword for that! Themes awaiting an accessibility-ready review.

  • Joe Dolson 8:01 pm on December 12, 2013 Permalink  

    Remove title attributes trac tickets 

    I’ve created all new tickets for each file referenced from the original remove title attributes trac ticket (http://core.trac.wordpress.org/ticket/24766). I originally split it up into 17 separate tickets, but closed 3 of them already, because they had already been committed into 3.8 or earlier.

    I’ve added comments and/or patches, as relevant, on all of the remaining tickets – so please chime in with opinions as relevant! Many of these incorporate situations where a 2nd opinion would be valuable, because the title attribute incorporates relevant information and some alternative handling may be necessary.



    http://core.trac.wordpress.org/ticket/26549 – 2nd opinion
    http://core.trac.wordpress.org/ticket/26550 – 2nd opinion
    http://core.trac.wordpress.org/ticket/26551 – 2nd opinion
    http://core.trac.wordpress.org/ticket/26552 – 2nd opinion
    http://core.trac.wordpress.org/ticket/26553 – 2nd opinion


    http://core.trac.wordpress.org/ticket/26555 – 2nd opinion


    http://core.trac.wordpress.org/ticket/26558 – 2nd opinion


    http://core.trac.wordpress.org/ticket/26560 – 2nd opinion
    http://core.trac.wordpress.org/ticket/26561 – 2nd opinion
    http://core.trac.wordpress.org/ticket/26562 – 2nd opinion

  • Joe Dolson 4:54 am on June 29, 2013 Permalink
    Tags: , , , media, plugins   

    Potentially useful accessibility plug-in I learned about today at WordCamp Chicago: http://wordpress.org/plugins/media-ally/

  • Joe Dolson 3:28 am on April 21, 2013 Permalink
    Tags: , , patch   

    Just submitted: http://core.trac.wordpress.org/ticket/24148. Comments welcome.

    • _Redd 12:13 pm on April 22, 2013 Permalink | Log in to Reply

      I never cease to be amazed, Joe, thank you–yet again.

      I looked briefly at the ticket, and I see obenland has the following question:

      Do we really need additional html elements for the ids? Can’t the labels or the p elements carry them with the same effect?

      My understanding is that ARIA is needed above and beyond simple form labeling and p elements due to the dynamic nature of WordPress. In other words, if a page is updated dynamically for whatever reason, the screen reader will only capture the “old” information in the buffer, without ARIA…

      Is the following a true and correct statement?

      To create a “live” region by which screenreaders may be able to access dynamically updated pages (such as those used in WordPress) using the aria-live property is necessary–simple form elements won’t do.

      Thanks for any input you may have, and thanks again, VERY much, for what you do.

      • Joe Dolson 2:07 pm on April 22, 2013 Permalink | Log in to Reply

        First, this is *not* creating a live region — the native comment form is not a dynamically updated region; although some themes may cause it to be. What this patch is about is incorporating the extra text statements that are contained within the comment form into the labels for the elements that they are associated with using ARIA, so that text is exposed to a screen reader without requiring a second pass through the form.

        The commenter is correct that an extra HTML element is not required in order to attach these IDs; and I was able to eliminate two of them, because the text they’re catching is already wrapped in entirety. A third span is required because the text I needed to catch is not already discretely wrapped by any element.

        Your statement is accurate, yes — but not actually relevant to this situation.

    • andyvaughn 9:02 pm on April 22, 2013 Permalink | Log in to Reply

      Thanks for the thorough look at this, Joe.
      Perhaps this is forest-questioning in a tree-analysis area…but, is it semantically appropriate to be using paragraph-tags for comment-form-email, comment-form-comment, and comment-notes? I always rewrite my comment templates to definition lists, with labels as definition-titles, and inputs/textareas as definition-descriptions, as I felt this was more semantically correct. Am I incorrect? Does this have a negative effect when read as a definition-list? It’s been a while since I’ve used a screen reader.
      Either way, thanks for the work Joe.

    • esmi 9:48 pm on April 22, 2013 Permalink | Log in to Reply

      I don’t think there’s a problem – semantically – with either approach and there are valid arguments for both. From a Real Life accessibility perspective, it might be worth bearing on mind that some (most?) screen reading software will announce content in definition lists in the same manner as content in paragraph tags. So from the user’s perspective, there’s no difference and your definition lists will still work just fine.

      • andyvaughn 9:52 pm on April 22, 2013 Permalink | Log in to Reply

        Thanks for the quick reply, Esmi. It helps to know I’m not causing screen-reader confusion with my preferred form markup.

    • Joe Dolson 9:52 pm on April 22, 2013 Permalink | Log in to Reply

      I’d agree with esmi on this; there may be some semantic value to considering these to be definition lists (although it’s debatable), but there is no accessibility value. It would just be a matter of your own judgement concerning whether the list of inputs should be considered a set of term/definition value pairs. My feeling is that the

      Either way, it doesn’t impact accessibility.

    • Anders Herning 11:16 am on April 24, 2013 Permalink | Log in to Reply

      Awesome work Joe! Really appriciate it! I know it’s not the right approach, but I gotta ask:
      I’ve been searching for the most “popular” accessibility theme for WordPress but can’t seem to find any.
      Do you have any advice on this?

  • Joe Dolson 6:28 pm on April 16, 2013 Permalink  

    Updated Theme Review Guidelines 

    I’ve updated the Theme Review guidelines for Accessibility again. This update takes into a consideration a number of suggestions and questions from Chip Bennett regarding the understanding of issues and how to resolve them.

    Among the changes:

    • Images now state that decorative images must be included with CSS.
    • Headings explicitly states that post and widget titles must be wrapped in headings, to draw the ‘reasonable headings’ guidelines into a context explicitly relevant to WordPress structure as defined by a theme.
    • Link text provides specific techniques for accomplishing the goal.
    • Keyboard navigation provides guidance on testing and specific mention of one of the most common failures for dropdown menus.
    • Contrast references tools for testing.
    • Skip links defines a conforming skip link.
    • Forms defines specific changes that can be made to defaults that would break accessibility.

    Your comments are welcome.

  • Joe Dolson 10:59 pm on March 28, 2013 Permalink
    Tags: , theme audit   

    I’ve been chatting with Chip Bennett via the Theme Review list about the Theme Audit guidelines. With his feedback (which was from the theme author and reviewer perspective, and very valuable) and the feedback from the comments on my previous post, I’ll be working on the next version with a variety of changes of various types. He’s going to be proposing some changes to the general guidelines that will obviate the need for a couple of the elements in the accessibility audit guidelines.

    • joe 2:26 am on April 1, 2013 Permalink | Log in to Reply

      I think it would be worthwhile to still mention the accessibility guidelines anyway, perhaps a cross reference or state that it also satisfies accessibility points.

  • Joe Dolson 3:15 pm on March 19, 2013 Permalink
    Tags: audit,   

    Theme accessibility audit guidelines update 

    Hey, all. I’ve updated the theme auditing guidelines and they have now been added to the theme reviewer’s documentation. Take a look at the requirements for the #accessibility-ready theme tag and comment back here with any suggestions or changes.

    Note that these guidelines are in addition to the rest of the theme guidelines, and there are many quality guidelines already established that don’t need to be part of the accessibility audit.

    • _Redd 5:49 pm on March 19, 2013 Permalink | Log in to Reply

      You ROCK! As do these guidelines!

      Do you think a requirement to have controls for audio, video be included in the guidelines?

    • Joe Dolson 5:55 pm on March 19, 2013 Permalink | Log in to Reply

      I’ll be honest, I find it extremely unlikely that a theme that had autoplaying video or audio with no controls available would ever be accepted to the theme directory. It’s also possible that including any kind of video/audio player crosses the Presentation/Functionality guideline, and wouldn’t be allowed regardless. I’ll check on that.

      • esmi 5:02 pm on March 20, 2013 Permalink | Log in to Reply

        What about sliders? Should they start automatically?

        • Joe Dolson 5:22 pm on March 20, 2013 Permalink | Log in to Reply

          Perhaps adding a generic statement addressing the behavior of media resources, to the effect that media resources should not, by default, auto start or change without user intervention. Would that cover these grounds effectively?

    • GrahamArmfield 6:32 pm on March 19, 2013 Permalink | Log in to Reply

      Nice piece of work Joe.

      I have a couple of comments:

      1. Re colour contrast… Would it be appropriate to reference a Colour Contrast Analyzer tool here? The contrast algorhythms are fairly complex and a tool such as the one from the Paciello Group is very easy to use.
      2. I’d say there are some situations where tabindex=0 would be allowed.

      Hope that helps.

      • esmi 5:03 pm on March 20, 2013 Permalink | Log in to Reply

        1. We’ve got a load of links here for useful tools, so perhaps a link back to the page on this blog would be the best way forward?

        2. Did you mean negative tabindexing?

        • Joe Dolson 5:25 pm on March 20, 2013 Permalink | Log in to Reply

          I think that a link back here for testing resources is a good plan, and I also agree that tabindex=0 should be allowed on non-focusable elements. Tabindex of -1 is already permitted.

    • Joe Dolson 10:06 pm on March 20, 2013 Permalink | Log in to Reply

      I’ve added comments regarding media resources behaviors, tabindex equals zero, and a link back to the Useful Tools page. That should cover everything discussed here; but let me know if you have more comments!

    • joe 10:45 pm on March 24, 2013 Permalink | Log in to Reply

      I love the accessibility-ready tag. Hits the right note and reminds the user that a11y is not a checkbox or developer only task. Should there be some ability to add specific alt text to a heading image, in particular if the theme supports multiple header images displayed randomly. not all images are decorative and empty alts on headers isn’t very a11y.

    • James Craig 6:52 pm on March 25, 2013 Permalink | Log in to Reply

      A few more pieces of feedback:

      1. A “skip link” should not be required if the author uses WAI-ARIA landmark roles.
      2. Forms section should require use of @required or @aria-required, and should encourage use of @aria-invalid while displaying field validation errors.

    • James Craig 6:57 pm on March 25, 2013 Permalink | Log in to Reply

      Looks like my first post didn’t go through. If you’re intending to use those bolded keywords as normative RFC-2119 requirements you need a few changes:

      1. Add a normative requirement section explaining that. e.g. http://www.w3.org/TR/wai-aria/normative
      2. Consistency case them. e.g. “MUST NOT” not “must NOT”
      3. Change the passive requirements to active ones clearly indicating to whom the requirement applies. e.g. “Theme authors MUST include alt values for images.” not “Images MUST have alt values.”

    • Léonie Watson 2:40 pm on March 26, 2013 Permalink | Log in to Reply

      Great to see accessibility in the theme guidelines Joe.

      I’d be inclined to rename the “Skip links” section to “Keyboard navigation”, and make the content less technique specific. For example:

      “Themes must include a mechanism that enables people to move to a particular area of the page using the keyboard. For example ARIA landmark roles or a skip link.

      ARIA landmark roles for banner, main, navigation, complimentary, search and contentinfo should be included. If the ARIA main landmark and navigation roles are used, a skip link need not be included.

      If a skip link is included it may be hidden off-screen initially, but must always be available to screen readers and must become visible onFocus for sighted keyboard users.”

    • Joe Dolson 3:15 pm on March 26, 2013 Permalink | Log in to Reply

      Hey, James and Leonie — I’m not sure I’m comfortable with removing the skip links requirement if WAI ARIA landmarks are provided. While WAI-ARIA landmarks are great for screen readers, they don’t provide any navigation benefit for sighted but keyboard-dependent navigators, that I know of. If there’s something I don’t know there, however, please do let me know!

      In terms of any RFC-2119 factors, I think that’s an issue for the WordPress documentation team to address — the entire document is quite inconsistent on all points, so it’s no great benefit to a single section conformant. But we can raise the question.

      The voice change is a good suggestion, however – thanks.

    • Rian Rietveld 9:02 am on March 27, 2013 Permalink | Log in to Reply

      Great work Joe!

      My comments:
      1. About the Headings: maybe replace “use a reasonable heading structure” for “use a semantic heading structure”.
      2. Add links to examples (like solutions of the read rome…” link or how place text offscreen), in stead of a link to a list of links that link to pages with links. Some developers (like me) are more comfortable with a quick example instead of reading though a lot of documentation first.
      3. About the Headings, maybe replace “use a reasonable heading structure” for “use a semantic heading structure”.
      4. I can see the HTML code for the abbr HTML also for CSS.
      5. I agree with your opinion: “I’m not sure I’m comfortable with removing the skip links requirement if WAI ARIA landmarks are provided”. Leave it to the user what way to navigate, not all users of screen readers use roles.
      6. Maybe add a requirement that inline style for mark-up should be avoided.

      • Joe Dolson 3:04 pm on March 27, 2013 Permalink | Log in to Reply

        We actually want to explicitly avoid requiring semantic heading structures, because the movable content model in many WordPress themes makes that almost impossible to guarantee — and the most important thing, ultimately, is having headings used correctly, rather than having a proper semantic structure to the headings. Developers are certainly encouraged to exceed the guidelines, but the guidelines are really intended to be fairly minimal.

        Adding links to examples in some cases is intended — but will be developed over time.

        I’ve noticed the HTML issue in the docs; it’s in markdown, and I’m not fully comfortable with what it supports yet…

        We feel that inline styles are ultimately a code quality guidelines, and should be dealt with in the ‘Code Quality’ portion of the theme review, rather than in the Accessibility guidelines. Inline styles are not, by themselves, an accessibility problem, as far as I understand.

  • Joe Dolson 2:52 pm on March 9, 2013 Permalink  

    If anybody has a chance to take a look at the progress on autosave and post locking that would be valuable – I have some concerns about whether the context changes when sessions have expired will be announced, but haven’t had time to test it at all. Ticket 23295

    • esmi 2:11 pm on March 14, 2013 Permalink | Log in to Reply

      Just lodged a general note of concern on the ticket. We really do need to test this out with our screen reader users.

    • Graham Armfield 7:01 am on March 16, 2013 Permalink | Log in to Reply

      I have made some comments on #23697 (Check and refresh post locks with heartbeat) also. There’s a proposal for a couple popup to be generated where locking conflict is occurring. I have asked @azaozz to confirm that focus will be moved into any popup that gets generated, and that focus goes somewhere sensible when a button is actioned.

  • Joe Dolson 11:12 pm on February 13, 2013 Permalink
    Tags: reviews,   

    Progress Report: Theme Review Guidelines for Accessibility 

    Per the most recent conversations about the accessibility-ready tag for the theme repository, I’ve been working on establishing some new classes for the Theme Check plug-in that can scan themes for accessibility issues.

    Because accessibility is not easily verified, particularly when you’re not working in an HTML context, most of these are relatively generalized, and work on the principle that I want to avoid false positives (accessibility issues detected that don’t actually exist), but am perfectly comfortable with false negatives. The reason for this is that these are only intended to be indicative flags; they aren’t intended to substitute for an actual reviewer going over the themes and judging it according to the theme accessibility audit guidelines.

    The idea is that any definite failures we can identify before engaging in a hands-on review are beneficial — and because theme authors have access to the Theme Check plug-in and can scan for these issues themselves, and learn of them before they submit.

    I’ve prepared six classes to extend the Theme Check plug-in, but they could all stand a review (and some creativity in reviewing other areas, if you’re comfortable enough with PHP).

    You can download my modified version of the Theme Check plug-in (six new files, one edited: new files in /checks/, prefixed with a11y; edited file is just the stylesheet, to add a color for the class .tc-accessibility.)

    Experiment with it, change it, let me know.

    Some of these are very superficial or crude checks; but if you have an idea how to improve them, share your wisdom! Keep in mind that all of these tests are performed on un-rendered code; so using a DOM parsing engine is not an option — we can use standard testing methods when it comes to reviewing the ultimate output of the theme.


    Any use of accesskey is a failure, so this class returns an error if any occurrence of the string ‘accesskey’ occurs anywhere in any theme PHP file.

    Form labeling

    Examines each PHP file individually. If any file contains input, textarea or select elements without also containing a label element, returns an error. This is superficial, as it doesn’t currently verify that there is any equivalency between inputs and labels, and doesn’t specifically exclude hidden inputs as an acceptable case.

    Image alt

    Examines each PHP file individually. If any file contains the string ‘<img’ but does not contain the string ‘alt=’ it returns an error. It’s crude, and this could definitely be improved.

    Empty links

    Examines each PHP file individually. Runs a regex to identify link text, returns errors for any link with no content. However, the actually cases within a theme are so diverse that there are *many* circumstances that this won’t pick up using the current rules, including link texts consisting only of white space characters, linked images with no alt attributes, or complex PHP concatenations.


    Just like the accesskey check. However, there are allowable cases for use of tabindex, and this class does not account for those at the moment.


    Scans the PHP files for occurrences of the strings ‘<h1′ and ‘<h2′. All it’s verifying is the presence of structural headings. If no structural headings are found anywhere in the code, it returns an error indicating a lack of HTML heading structure. Also very crude, but it will pick up the worst-case scenario.

    • esmi 10:46 am on February 14, 2013 Permalink | Log in to Reply

      Just grabbed a copy and will try running it on a few of my themes plus some random ones from the Theme Repo. Do you want any comments posted here or via email?

    • _Redd 2:38 pm on February 14, 2013 Permalink | Log in to Reply

      I’ve also grabbed a copy, and uploaded to a test prototype. I confess I’m not informed about features such as the access key, so I have a bit of a learning curve to deal with….but I am SO happy to see this! Just let us know where you want feedback—AND–where I can ask questions, please.

    • _Redd 2:41 pm on February 14, 2013 Permalink | Log in to Reply

      Doh! I should have checked first, but the prototype site I’m using for the plugin is a multi-site set up….does that matter?

    • Joe Dolson 3:34 pm on February 14, 2013 Permalink | Log in to Reply

      Comments here or through email are fine. Redd – it should be fine in multisite, but I haven’t tried it. Don’t see an obvious reason it would be a problem, though. It doesn’t run on the live theme specifically, just whatever you select from the drop down control.

    • Lance Willett 4:43 pm on February 14, 2013 Permalink | Log in to Reply

      This is amazing—looks like it’ll be very useful in theme development.

    • Joe Dolson 4:46 pm on February 14, 2013 Permalink | Log in to Reply

      Don’t get too excited; these accessibility checks are all pretty minimal — they’re really only going to catch pretty blatant issues.

    • Aaron Jorbin 6:49 pm on February 14, 2013 Permalink | Log in to Reply

      Any chance this can go up in github or some other public source control?

    • Joe Dolson 6:53 pm on February 14, 2013 Permalink | Log in to Reply

      It’s really just an extension of Otto’s Theme Check plug-in: http://wordpress.org/extend/plugins/theme-check/, and will ultimately be managed however he wants it to be – I can set up something, but I’d only do that for the 6 accessibility related classes.

    • _Redd 9:16 pm on February 15, 2013 Permalink | Log in to Reply

      @joedolson So far, so great! WordPress multisite 3.5.1

    • Chip Bennett 12:23 am on February 17, 2013 Permalink | Log in to Reply

      By chance, do you have a list of Accessibility criteria that we could add as draft/recommended to the Theme Review guidelines? For one, I would like to keep Theme-Check consistent with what\’s listed on the Theme Review Codex page, and for another, the sooner we can get more Developers hammering on them, thinking about them, and trying to implement them, the better.

      I\’m happy with escalating immediately to *RECOMMENDED* any guidelines the Accessibility team gives the Theme Review Team. Just let me know.

      • esmi 3:10 pm on February 18, 2013 Permalink | Log in to Reply

        I came up with the following that you might want to have a think about:
        Use a reasonable HTML heading structure — including the use of heading elements for page sub-sections. Heading markup should only be used for presentational purposes. (Note: the Information → Document Outline view in Firefox\’s Web Developer Toolbar is an excellent way to quickly check on this.)

        Provide visual keyboard focus highlighting in navigation menus and for form fields, submit buttons and text links. Navigation by keyboard should also be intuitive and effective,

        Theme Images
        Images added to the template markup should incorporate an appropriately populated alt attribute.

        Read more Links
        When creating read more links, authors should incorporate a unique fragment for each link to avoid multiple, identical, \”read more…\” links on a page. If possible, the unique fragment should prefix the link — eg: \”Puppy dogs – read more\” would be better than \”Read more on Puppy dogs\”; Hiding the unique link fragment from graphical browsers (using offscreen positioning) is fine.

        Aall background/foreground color contrasts should be within the level AA contrast ratio (4.5:1) specified in the Web Content Accessibility Guidelines (WCAG) 2.0 for color luminosity.

        Skip Links
        Include a mechanism that enables users to move straight to content or navigation on entering any given page. These links may be positioned offscreen initially but should be available to screen reader users and must be visible on focus for sighted keyboard navigators.

        Comment forms should have appropriate field labels and and all content within form tags should be explicitly associated to a form control — ideally via comment_form(). )Note: we need to check if there\’s a Trac ticket associated with the default output from comment_form() and, of not submit one).

        Forms that include a single input (such as a standard search form) may position the input label offscreen.

    • Joe Dolson 4:38 pm on February 17, 2013 Permalink | Log in to Reply

      We have an existing set of theme accessibility audit guidelines, intended as qualifications for the proposed \’accessibility-ready\’ theme repository tag, and could recommend all of those or a portion of them as things that we\’d love to see considered as recommended.

      There\’s very little within the accessibility guidelines that can readily be tested by the theme check plug-in.

      The theme accessibility guidelines are here: http://make.wordpress.org/accessibility/theme-accessibility-audit-draft-proposal/

      The purpose for the accessibility-ready tag is to assist in findability for accessible themes, which are otherwise very difficult to identify; but having a general improvement in the accessibility of themes would be amazing, too.

    • _Redd 2:41 pm on February 20, 2013 Permalink | Log in to Reply

      Joe, I have a test page up with forms. There’s a report from the Themecheck plugin as follows:

      ACCESSIBILITY: The theme contains form elements but does not contain label elements in the file page3.php.

      I used /”label for/” rather than /”label /”
      Does this mean I am doing it wrong?
      The page with the form may be seen at this linktest page for forms

      • Joe Dolson 5:00 pm on February 20, 2013 Permalink | Log in to Reply

        Yes, label is an element, you’re using it as an attribute.

      • _Redd 6:29 pm on February 20, 2013 Permalink | Log in to Reply

        Per esmi and Joe’s recommendation, I changed the code. Re-ran Themechecker plugin. The report cleared without a warning.

        So congratulations to the Themechecker theme, which proves to work on multisite 3.5.1.

        And, I’m going to incorporate this knowledge about labels in training….so you helped more than just me with this feedback! Woo woo!

    • esmi 4:45 pm on February 20, 2013 Permalink | Log in to Reply

      You need to be using something like:
      <input id="checkbox1" type="checkbox"" value="checkbox1" />
      <label for="checkbox1">Item One</label>

      • _Redd 4:48 pm on February 20, 2013 Permalink | Log in to Reply

        Thank you, I’ll get on it, fix it, and re-visit the report from Themechecker!

compose new post
next post/next comment
previous post/previous comment
show/hide comments
go to top
go to login
show/hide help
shift + esc