Intro to the Audit panel

Updated

Find and fix accessibility issues with Webflow’s Audit panel.

The Audit panel flags common accessibility-related issues so you can address them before going live with your site. Critical errors (Audit panel flags with a red square) represent issues where your users may miss out on critical site content, or where search performance may be degraded. Moderate errors (Audit panel flags with a yellow triangle) represent important issues, but are not critical to fix.

To learn more about accessibility, enroll in our accessibility course.

Important

The Audit panel does not check for accessibility issues within components. Please take care to manually identify and correct any accessibility issues within components. Learn more about components.

Identify accessibility issues

The Audit panel currently includes 4 high-impact accessibility checks so you can identify and fix common issues during the design process. It addresses: 

  1. Missing alt text
  2. Non-descriptive link content
  3. Skipped heading level
  4. Duplicate element IDs

As an added bonus, by using the Audit panel and learning from the issues it flags, you can become more practiced and aware of these considerations so they’re part of your design and development workflow instead of an afterthought.

You can access the Audit panel by clicking the Audit panel icon in the bottom left of the Designer.

Pro tip

Press Alt/Option + U on your keyboard to quickly expand or collapse all items in the Audit panel.

Pro tip

The Audit panel doesn’t include checks for text color contrast ratios, but Webflow has a built-in color contrast checker in the color picker for text elements to help you check your text’s accessibility as you design.

Missing alt text

Alt text describes the appearance or function of your image content for site visitors who are Blind, low vision, or have visual disabilities. It will also be displayed in place of an image if the image file hasn’t loaded or when a user has chosen not to view images. (It’s also great for SEO.)

Note

Good to know: A screen reader is assistive technology that renders text and image content as speech, and is used by Blind, low vision, or visually disabled people. It’s also useful for people who have cognitive or learning disabilities.

Learn how to fix missing alt text.

Why the Audit panel flags missing alt text

Missing alt text means you’ve included images without descriptive alt text or failed to mark that image as decorative. If an image conveys essential information not available anywhere else on the page, a person who can’t see the image will miss out on that information, and search engines are left guessing as to what your image content contains.

Important

The Audit panel does not check alt text for images inside Lightbox media elements. Additionally, the Audit panel does not check alt text for CMS-bound images. Please take care to ensure you’ve included alt text for any images inside Lightbox media elements and images you’ve connected to the CMS. Learn more about setting alt text on CMS-bound images.

Link text should be unique, make sense without the surrounding text, and tell readers what the purpose of the link is and where it will take them.

Learn how to fix non-descriptive link content.

Empty links are links with no meaningful text or image alt text and will confuse people using screen readers.

Keep in mind that rasterized text on an image (meaning the text is literally part of the image and not a standalone text element) is not interpretable by screen readers or search engines. Best practice is to ensure that any descriptive text used with an image is an actual text element.

Learn more about accessible typography

Skipped heading level

Headings give people a sense of a page’s organization and structure, like a table of contents. They let people quickly navigate the structure of your page and break up content to be easily scanned visually or with screen readers. Absent or poor heading structure forces visitors to work extra hard to find what they’re looking for.

Learn how to fix skipped heading levels.

Why the Audit panel flags skipped heading levels

Skipped heading levels mean your heading elements (H1, H2, etc.) don’t use proper heading hierarchy. H1 is considered the most important heading, H2 headings would group content underneath H1, H3 headings would land underneath H2 headings, and so on. 

The heading hierarchy breaks if you skip a heading level (e.g., you have H1 and H3 headings, but no H2 headings). This can be confusing for people with cognitive disabilities and people using screen readers.

Duplicate element IDs

Designers and developers use unique identifiers (IDs) to optimize sites for accessibility or to extend site functionality with custom code, including linking, scripting, or styling (with CSS). It’s considered best practice in web development to ensure that each ID is unique across an entire webpage (i.e., each ID is used to identify only a single element).

Why the Audit panel flags duplicate element IDs

Using the same ID on more than one element may cause custom code or screen readers to malfunction, as they’ll only target the first element with the shared ID. While modern browsers typically accept duplicate IDs, these still present an increased risk for site visitors to encounter bugs on the published site. 

With the Audit panel, you’ll be able to identify duplicate IDs on a page and act on them before issues occur, reducing the time spent debugging custom code and removing the risk of degrading the accessibility of your published sites.

Fix accessibility issues

In many cases, fixing accessibility issues involves adding the missing identification. We’ll cover: 

  1. How to fix missing alt text
  2. How to fix non-descriptive link content
  3. How to fix skipped heading levels
  4. How to fix duplicate element IDs

How to fix missing alt text

You can assign alt text to images from the Asset panel

Or, if an image isn’t meant to communicate semantic information and is only used decoratively, you can explicitly set the image as decorative so that screen readers skip it. 

Note

To decide if an image is decorative or informative, remove it from the page. If information is missing without the image, it’s informative and needs alt text. Images that are links, buttons, logos, or that contain important information always need alt text.

Important

The Audit panel does not check alt text for images inside Lightbox media elements. Additionally, the Audit panel does not check alt text for CMS-bound images. Please take care to ensure you’ve included alt text for any images inside Lightbox media elements and images you’ve connected to the CMS. Learn more about setting alt text on CMS-bound images.

The Audit panel categorizes images with missing alt text into 2 groups: 

Images with missing alt text under the Asset grouping

If the image is under the Asset grouping in the Audit panel, it means the canvas image is referencing the asset and the asset does not have alt text. 

To fix missing alt text on an Image element:

  1. Click on the target action arrow (this will take you to the asset’s settings in the Asset panel)
  2. Click “Find it for me” in the Missing alt text modal to automatically locate the image’s alt text settings in the Asset panel
  3. Add descriptive alt text or mark the image as decorative

Good to know

You can click and drag the informational modal to move it around the canvas.

If you want to override alt text set on images in the Asset panel, you can add custom alt text to individual images on the canvas.

To add custom alt text to Image elements on the canvas: 

  1. Select the Image element on the canvas 
  2. Click the “cog” icon to access the Image settings
  3. Choose “Custom description” from the Alt text dropdown menu and enter custom alt text for that image

Learn more about setting alt text on individual images.

Images with missing alt text under the Rich text grouping

If the image is under the Rich text grouping in the Audit panel, it means the canvas image in the rich text element does not have alt text. 

To fix missing alt text on an image in a rich text element: 

  1. Click the target action arrow to locate the rich text element on the canvas and open the Missing alt text modal
  2. Click “Find it for me” in the Missing alt text modal to automatically locate the image’s alt text settings in the Asset panel
  3. Add descriptive alt text or mark the image as decorative

If you want to override alt text set on images in the Asset panel, you can add custom alt text to individual images within rich text elements.

To add custom alt text to images in rich text elements: 

  1. Double click the image inside the rich text element on the Designer canvas
  2. Click the “wrench” icon
  3. Choose “Custom” from the Alt text dropdown menu and enter custom alt text for that image

Learn more about setting alt text on individual images.

Important

The Audit panel does not check alt text for images inside Lightbox media elements. Additionally, the Audit panel does not check alt text for CMS-bound images. Please take care to ensure you’ve included alt text for any images inside Lightbox media elements and images you’ve connected to the CMS. Learn more about setting alt text on CMS-bound images.

Tips for writing effective alt text

  1. Describe the intent, purpose, and meaning of the image
  2. Don’t repeat surrounding text (e.g., alt text isn’t needed if a caption fully describes a picture, alt text is redundant, or it repeats names of people in alt text for their bios. That is repetitive text and doesn't describe the picture or how they look.) 
  3. Use punctuation (to help screen readers describe the image with a more human-sounding approach)
  4. Write so Blind, low vision, and visually disabled visitors receive meaningful information about the image from alt text, and keep your description to 1 to 2 sentences of key information (don’t go overboard with your description)
  5. Avoid non-specific words like “chart,” “image,” or “diagram,” unless it adds meaningful context — instead describe the meaning or trends shown in the charts, diagrams, or images

Resources

To learn more about image alt text and screen readers, check out our Alt text lesson, along with How to Design Great Alt Text: An Introduction and Images must have alternate text from Deque University.

To fix this, make sure all the link elements on your page have meaningful, descriptive text inside. 

Avoid generic terms like “read more,” “link,” or “click here.” Though the Audit panel doesn’t provide guidance on generic terms, use clear, specific language about the action the link performs to make your link that much easier to use (e.g., “Download assets”).

You can also use assets that don’t have text rasterized with the image. Instead, place text elements over your image assets. 

Remember, if you have image links (like icon buttons), be sure to include alt text for those as well.  

Click the target action arrow (the arrow in the Audit panel next to your link), and then update the link by adding alt text for the image/icon (if the link contains an image).

You can make any alt text changes in your element settings (the settings for your image element) so that your alt text is more descriptive.

Resources

To learn more about how to set links and what options are available, check out our links article and the WCAG Link purpose criterion.

How to fix skipped heading levels

Headings should follow a logical, numerical order that reflects the structure of your content and clearly describes the contents of the section.

For example, the title of this lesson (Intro to the Audit panel) is the only level 1 heading (H1) on this page, the subheadings of this lesson are level 2 headings (H2), and any headings within those subheadings are further levels down (H3, H4, etc). The heading for this paragraph is a level 3 heading and clearly describes the content of this section. 

For example, using an <H2> element for a section title and then using <H4> elements for the section's subheadings will cause the audit to fail because the <H3> level is skipped. 

If the skipped heading was an accidental omission, you can set it to the correct heading type: 

  1. Select the Heading you want to change
  2. Open the Settings panel (D)
  3. Press the Heading type that was skipped (e.g., “H3”) 

Resources

To learn more about proper heading order and markup structure, check out the documentation on WebAIM’s site.

How to fix duplicate element IDs

Each element ID must be unique across an entire webpage (i.e., each ID is used to identify only a single element).

Using the same ID on more than one element will trigger an error message in the Settings panel when the ID is added and cause any subsequent site audits to fail. The Audit panel will identify all elements and component instances with duplicate IDs to allow you to quickly identify and resolve any duplicate IDs on your site.

To fix duplicate IDs: 

  1. Click the target action arrow next to the flagged ID in the Audit panel to show all elements and component instances with the duplicate ID 
  2. Click the “Show me” arrow next to the flagged elements (this will take you to the element settings in the Settings panel where the ID is set) 
  3. Edit or delete the duplicate ID
  4. Repeat the above steps for each element with the duplicate ID

Resources

To learn more, check out the MDN documentation on the ID attribute.

Ignore accessibility issues

In some instances, you might want to ignore a flagged issue in the Audit panel. For example, maybe your content requires a skip in the heading hierarchy. Or maybe you’re building on the fly and you choose to build your content out of order. 

To ignore the issue and temporarily (or permanently) dismiss the notification in the Audit panel:

  1. Open the Audit panel
  2. Hover over the issue you want to ignore and press the “silenced bell” icon 

Unignore accessibility issues

Most of the time ignoring an issue is a temporary solution while you build out your design. You can unignore the issue you temporarily dismissed, and re-flag it to be solved as you continue designing and developing. 

To unignore an issue:

  1. Open the Audit panel
  2. Press the disclosure arrow to the left of the issue you dismissed
  3. Hover over the ignored issue and press the “bell” icon

If you have feedback, issues to report, or questions about the Audit panel, let us know in the feedback thread on our forum.

Related reading: Make your site more accessible