Skip to Main Content
It looks like you're using Internet Explorer 11 or older. This website works best with modern browsers such as the latest versions of Chrome, Firefox, Safari, and Edge. If you continue with this browser, you may see unexpected results.

Accessible Code for Content Providers

"I need that too."

"When you look at a web page, you see right away how it's divided and what's most important. I need that too." - Dave Simpson, programmer, musician and writer, who was blind from birth.

An H-tag Hierarchy: The #1 Priority

Think of h-tags as a hierarchy, not as a font size!

Screen readers are usually set to read the h-tag hierarchy for a quick outline of the page.

  • Do create a clear hierarchy of h-tags.
  • Do make the page title an h1-tag. Make it the only h1-tag and make the title unique. (Required for SEO too!)
  • Do write a header that can be understood in a list of headers, without context. Use the Accessibility Tree to read through your headers. It's explained here: https://guides.library.upenn.edu/alt-code/accessibility-tree
  • Do not throw in additional h1 tags because you like the way they look. In fact, don't throw in any h-tags that disrupt the hierarchy.
  • Do not leave holes in your outline. If sighted users don't need a header, you don't have to show it. Make it screen-reader only with a special class. See below for class="visually-hidden"
  • Do use CSS to make any h-tag any size you like!  (If you need help with styling h-tags, ask ALT.)

Coming soon in a lawsuit near you: A proper header structure will be required for ADA compliance.

ADA compliance is determined based on WCAG 2 guidelines.

Starting with WCAG 3, the guidelines will include a rating for headers. Using the chart below, a rating of 3.5 is required.

WCAG 3.0 ratings for headers

Rating 0: 25% or less of expected headings
Rating 1: 26-50% or less of expected headings
Rating 2: 51-80% or less of expected headings
Rating 3: 81-95% or less of expected headings
Rating 4: 96-100% or less of expected headings

Meaningful Linking Text: Priority #2

Not just "Click here, Click here, Click here."

Screen readers can be set to read the list of links on a page. If the linking text is meaningful, the links provide highlights and a networked context. For even more efficiency, the reader can jump to one of the links because they want that e-resource fast!

  • Do not write "Click here" or "Here."
  • Do not write "more..." or "more about this..." 
  • Do not write "More on this page" or "More on this website." 
  • Do not write "If you need help, ask ALT"! (help with what?)
  • Do provide full information about the link inside the a-tag. A quick solution is to move the beginning of the a-tag back so it includes the rest of the sentence.

Here's a list of about 300 links on the Penn Libraries homepage: https://guides.library.upenn.edu/ld.php?content_id=65627825

Imagine listening to "Click here" 300 times!

You don't have to show your sighted users the info you add for screen readers. Use class="visually-hidden" to make text screen-reader only. See below to get the css.

Alt Text (AKA "Alternative Text"): Priority #3

When you fail to add alt text, people who use screen readers know that information is missing and you have not made it available to them. 

When the screen reader comes to an image it says "Graphic." Then it reads the "alt text" inside the image tag. If you fail to add alt text, the screen reader will read the file name. Did you save the image as image.jpg? Horrors!

Rules for alt text

  • Do describe the image briefly. Just what you see. 150 characters is a good maximum.
  • If you want to cite the image source and give the date, do that in a caption. Alt text is the alternative for visible information.
  • Don't provide the same information in both caption and image. It takes long enough to listen to a screen reader. No one wants to hear the same thing twice.
  • Don't write "image" or "graphic." The screen reader will provide that information.

You may leave the alt text empty only if...

  • The caption truly describes what you see. 
  • The image is purely decorative - a scroll or curlicue

Wysiwygs are built to help you add alt text.

The alt field is highlighted. The Drupal image wysiwyg The alt field is highlighted. The LibGuides image wysiwyg

class="visually-hidden" because screen readers more need

Here's the CSS to set up "visually-hidden":

.visually-hidden:not(:focus) {
     position: absolute !important;
     white-space: nowrap;
     clip: rect(0 0 0 0);
     clip-path: inset(50%);
     padding: 0 !important;
     border: none !important;
     height: 1px !important;
     width: 1px !important;
     overflow: hidden;
}

You won't see the text because it gets clipped to a single pixel!

For example:

  • Your link can still say "more..." on the browser screen.
    Use class="visually-hidden" to hide the additional, accessible text:

     

    <a href="https://accessibility.web-resources.upenn.edu/events">more...<span class=visually-hidden"> accessibility events</span></a>

  • Did you wonder about this one?

    (<a href="mailto:ALT@upenn.libanswers.com?subject=coding">If you need help<span class="visually-hidden"> with styling h-tags</span>, ask ALT.</a>)

Guides Extra:

The class visually-hidden is already set up.

Footnote: How to extract a list of links from a webpage

  1. Use Chrome
  2. Open Development Tools
    - Press Command+Option+C (Mac) or Control+Shift+C (Windows, Linux, ChromeOS).
  3. Click Console
  4. At the bottom, after the arrow (>), paste in this code: var x = document.querySelectorAll("a");
    var myarray = []
    for (var i=0; i<x.length; i++){
    var nametext = x[i].textContent;
    var cleantext = nametext.replace(/\s+/g, ' ').trim();
    var cleanlink = x[i].href;
    myarray.push([cleantext,cleanlink]);
    };
    function make_table() {
        var table = '<table><thead><th>Name</th><th>Links</th></thead><tbody>';
       for (var i=0; i<myarray.length; i++) {
                table += '<tr><td>'+ myarray[i][0] + '</td><td>'+myarray[i][1]+'</td></tr>';
        };
     
        var w = window.open("");
    w.document.write(table); 
    }
    make_table()

With thanks to Cynthia Cronin-Kardon, who created the original version of this guide.