Lighthouse audit report for documentation pages

Addressing Lighthouse Audit results for MDN pages 🚧

• Performance
• Accessibility (100) 🏆
• Best Practices
• SEO

Using the automated tool Lighthouse for improving the quality of webpages (performance, SEO, accessibility, best practices), it uncovers some really “quick” fixes for accessibility & SEO, and potentially performance improvements. The audit lists some potential solutions for reducing DOM size etc, but that is where the fixes will become more complex.

I hope this thread will be helpful first step in beginning to improve overall page quality and chip away at potential fixes to get 100s across the board on Lighthouse audits. Achieving 100 performance might be unreasonable as the size of pages are quite big with many main-thread JS tasks happening (maybe a 10-15 point increase would be super) but the other categories we will be able to get perfect scores in.

Performance results

1. Avoid excessive DOM size - This would probably be the first priority, or atleast the start of a discussion regarding “windowing” some the elements with many repeated children like <ol> elements Maximum Child Elements | ol | 363. Lighthouse recommends using a “windowing” library like react-window to minimize the number of DOM nodes created if rendering many repeated elements on a page. Like what is happening with the child <li> elements within the ordered lists on some pages. Here is a post they lighthouse recommends on virtualizing large lists with react-window

Potentially using a “windowing” library like react-window to minimize the number of DOM nodes created if you are rendering many repeated elements on the page. Learn more. Also, minimize unnecessary re-renders using shouldComponentUpdate, PureComponent, or React.memo and skip effects only until certain dependencies have changed if you are using the Effect hook to improve runtime performance.

1. Minimize main-thread work - I’m not entirely sure how much can be reduced here, but the breakdown for the main-thread looks like this:

Accessibility

1. <frame> or <iframe> elements do not have a title attribute

(Fix pending in #4061) - “Provide unique and descriptive title attributes for all frame and iframe elements.” web.dev/frame-title/

Indeed the EmbedLiveSample() KS macro output doesn’t give the <iframe>'s a title attribute. Since the $0 arg in EmbedLiveSample.ejs represents the sampleId, I just used that value for the title and deslugified it along with adding “sample” to the end like <iframe class="example-outcome-frame" title="Comparison of HTML and SVG sample" ..> .

1. Heading elements are not in a sequentially-descending order

(Fix pending in #4107) - This is another relatively “quick” fix. The audit screenshot is a bit off, the <h4> shown below tag fails the heading levels audit. It fails because we skip from an <h2> to an <h4> in the aside element. I’m just spitballin here, but since it would be a pain to search through all pages and make sure the headings are properly ordered/structured, could we do something with internal utility for selecting all the heading elements on the page (or a more specific group for performance) and then check too see if the last two headings are mismatched, then perform a “fix” to make sure the last two heading elements are in sequentially descending order. Or we could see if changing the markup directly would resolve things, but I think it might be to unpredictable on what the 2nd to last heading before the last on each page will be to provide a blanket fix. Link heading-order

For example this is whats happening on https://developer.mozilla.org/en-US/docs/Web/CSS/flex to cause the headings level audit to fail ie ["h1", "h2", "h3", "h2", "h3", "h2", "h4"] and its clear as day the <h3> is skipped at the end of the list and the <h4> ends up being the next heading (also the last) in the “outline” of the page in terms of someone navigating the sections of a page with a screen reader.

Best practices

1. Registers a unload listener

SEO

1. Tap targets are not sized appropriately 87% appropriately sized tap targets - Targets that are smaller than 48 px by 48 px or closer than 8 px apart fail the audit. tap targets. This one will be an easy fix too!

With all of the above said/shown, I think there are some improvements we can quickly capitalize on to improve overall page quality. I’ve fixed almost all of these failed audits (besides the excessive DOM size perf audit) on my own site/projects so getting 100s in everything except performance should be obtainable relatively soon once we remedy these failed audits. And also this discussion brings to light potential areas of improvement for page performance. Hopefully this acts as a good starting point. Let the journey begin!

cc @peterbe @schalkneethling

[tannerdolby]

Update: July 14, 2021

Accessibility: 97 ➡️ 100 🏆

• <iframe> elements now have title attributes
• headings are all in sequentially-descending order

SEO: 98 ➡️ 99 (update: July 18)

Changes have landed. The score bumped up one point (as expected) since the .main-page-content ul li and .on-github ul li are now fixed 🎉

<strike>Waiting for PR to land, before changes are on live site.</strike> note: this won’t achieve 100 since its not including .social-icons (the last audit failure) in footer which are apart of redesign

• add appropriate 8px spacing between elements so they don’t overlap
• ensure that tap targets are atleast 48px by 48px

[tannerdolby]

Here is the up-to-date Lighthouse audit report (as of July 18, 2021)

Plan of action:

• I’m going to dive into the performance improvements next week.
• Regarding SEO: It’s giving a 92% size tap target failure for the <select id="language-selector"> element within .on-github container, it doesn’t seem to be overlapping so it must need to its tap target increased as 173x21 is not adhering to the 48px by 48px minimum tap size. After this is fixed, the only SEO audit failures are those related to .social-icon’s in the footer which are part of redesign and might be changing (which could resolve the tap target sizing and spacing in itself) to achieve a perfect score of 100 in SEO.
• Take a closer look at the best practices audit failure to see if there is any “low-hanging fruit”