Skip to Main Content
Go to Penn Libraries homepage   Go to Guides homepage

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:
  • 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.) footnote 1

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

Don't kill yourself. Keep it simple!

Chances are you'll never need H5 or H6.

Here's a screenshot showing excellent use of H-tags.


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 new Penn Libraries homepage. The left column shows the linking text.

Phew! It doesn't say "click here"!

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 ("Alternative Text") for images: 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

What to do when screen readers need more information.

Often screen readers need information that's obvious to sighted users. For example, a header may be obvious because of the layout ("Hey, here's a sidebar!"). You don't need to annoy your sighted users. You can present the header to screen readers only with class="visually-hidden":

Here's the code for class="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="">more...<span class=visually-hidden"> accessibility events</span></a>

  • Did you wonder about this one?

    (<a href="">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 1: What is CSS?

"CSS files" are often called "Stylesheets"

Here's a definition of CSS from the W3C Schools:

  • CSS stands for Cascading Style Sheets
  • CSS describes how HTML elements are to be displayed on screen, paper, or in other media
  • CSS...can control the layout of multiple web pages all at once

Usually, CSS is stored separately from HTML files. That way, a single CSS file can be called by multiple HTML files.


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

  1. Use Chrome
  2. Be sure you're in a live environment. For example, in Penn Libraries Guides, this will not work in the editor.
  3. Open Development Tools
    - Press Command+Option+C (Mac) or Control+Shift+C (Windows, Linux, ChromeOS).
  4. Click Console
  5. 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;
    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 ="");

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

Penn Libraries Home Franklin Home
(215) 898-7555